Skip to content

Brand System

Ubuntu — “I am because we are.” Our design language reflects African heritage, community-first values, and technological ambition.

Our color palette is drawn from Africa’s mineral wealth. Each color has meaning. For canonical hex values, container colors, and usage notes, query brand_minerals directly — the database is the source of truth. This page describes what each colour means; the database describes what each colour is.

Source: Democratic Republic of Congo. Used for primary actions, links, and active states. The blue of the digital future, grounded in the mineral wealth of the Copperbelt.

Source: Merelani Hills, Tanzania (the only place on Earth where tanzanite is found). Used for purple accents, brand identity, and premium features. Rare, precious, and uniquely African.

Source: Congo Copper Belt. Used for success states, confirmations, and positive indicators. The green of growth and nature.

Source: Ghana, South Africa, Mali. Used for achievements, rewards, warmth, and premium badges. The material of honour across African cultures.

Source: Pan-African Sahel. Used for community features and warmth. The clay of home — grounding, tactile, shared.

All visual design values live in dedicated database tables under the brand_* prefix. Each table is the canonical source for its category. Run SELECT * FROM get_token_counts() to see the live row counts for every brand_* table.

  • brand_minerals — the five palette colours with light/dark/container/on-container values
  • brand_semantic_colors — semantic role mappings (foreground, background, border, ring, primary, accent, error, success, warning, info, and container variants), plus hc_light_value and hc_dark_value for high-contrast mode
  • brand_spacing — the spacing scale from 2px hairline to 128px page-hero
  • brand_typography — font families and type scale, with letter_spacing, fluid_min_px, fluid_max_px, and font_features columns for modern responsive typography
  • brand_radius — border-radius scale including the pill radius used for buttons, inputs, avatars, badges, and toggles
  • brand_shadow — compound shadows with light and dark variants
  • brand_motion — durations, easings, and stagger timings with reduced-motion fallbacks
  • brand_breakpoints — responsive breakpoints with max-content-width ceilings
  • brand_z_index — banded stacking scale across six categories
  • brand_icon_sizes — canonical icon dimensions from xs (12px) through xl (40px), default 20px
  • brand_touch_targets — accessibility tiers, each at or above the Bundu floor’s hit area (see Touch Targets), with WCAG, Apple HIG, and Material Design citations per row
  • brand_component_specs — per-component canonical heights, padding, variants, border-radius, and minimum touch targets for primitives like button, input, avatar, badge, card, dialog, toggle, checkbox, tabs
  • brand_density — three tiers (compact for desktop dashboards, comfortable as the Nyuchi default for mobile/tablet, spacious for hero and landing surfaces). Each tier references other token tables by name (spacing_component, touch_target, icon_size, body_type, heading_type, radius_card) rather than hardcoding numeric values
  • brand_density_breakpoint_map — viewport-to-default-density mapping that determines which tier loads at which screen size
  • brand_accessibility_checks — WCAG contrast ratios and color-blindness safety flags for every critical semantic-color pair, in both light and dark modes. Each row carries the contrast ratio, WCAG AA/AAA compliance booleans, and protanopia/deuteranopia/tritanopia/achromatopsia safety flags

Three SQL functions support contrast validation directly in the database:

  • hex_to_rgb(hex) — hex → (r, g, b) tuple
  • relative_luminance(hex) — WCAG relative luminance for a hex color
  • calculate_contrast_ratio(fg_hex, bg_hex) — WCAG 2.1 contrast ratio between two hex colors. WCAG AA requires 4.5 for normal text (3.0 for large), AAA requires 7.0 (4.5 for large)

A summary report is available via SELECT * FROM get_accessibility_summary().

This page deliberately does not duplicate the values from these tables, because two sources of truth inevitably drift. To see current token values, query the relevant table or use get_token_counts() for a summary.

Three font families, chosen for complete coverage of African scripts including Latin, Arabic, Ethiopic, Tifinagh, and Bamum:

  • Noto Serif — page titles, hero text, display headings. Editorial feel with full language coverage.
  • Noto Sans — body text, UI labels. Neutral, highly legible, same coverage as Noto Serif.
  • JetBrains Mono — code blocks, terminal output, technical content. Purpose-built for developer readability.

The type scale runs from Display (72px serif) through Display Small (60px serif), H1-H6 (48-16px mixing serif and sans), Body Large/Body/Body Small (18-14px sans), Caption (14px sans, the Bundu floor minimum for captions and secondary labels), and Code (14px mono). Display sizes carry fluid_min_px/fluid_max_px so they scale responsively rather than breaking to one word per line on phones. Display through H4 carry negative letter-spacing for typographic refinement; Caption carries small positive tracking; Code carries tabular-nums so numbers align in tables.

Wordmarks are always lowercase: mukoko, nyuchi, shamwari, bundu. This is a brand decision, not a typography accident.

The Bundu floor sets the minimums that no screen in the ecosystem can go under. Version 1.1.0 is the current floor, published at standards.bundu.org/bundu-floor, which is the only place its text is published.

  • Hit area: 45px on touch, and 24px with a fine pointer.
  • Control heights: 33px for small controls and 41px for large ones.
  • Spacing: 7px from label to field (5px dense), and 14px between list items (7px dense).
  • Unchanged: 7:1 body contrast, and 17px body text on touch (15px with a fine pointer).

The Nyuchi comfortable and generous tiers in brand_touch_targets sit above this floor, and no tier, brand pack or density setting may go below it. The floor takes the nearest allowed value at or above WCAG 2.2 and Apple’s 44pt, so 44 becomes 45.

Three tiers in brand_density:

  • Compact — desktop dashboards, admin tables, power-user tools
  • Comfortable (Nyuchi default) — phones, tablets, general consumer surfaces
  • Spacious — landing pages, marketing surfaces, onboarding, long-form reading

Each tier composes other tokens by reference rather than duplicating values. The brand_density_breakpoint_map table maps viewport sizes to default density tiers so the right tier loads automatically.

All motion respects prefers-reduced-motion. Every row in brand_motion carries a reduced_motion_fallback value that components must honour when the user has requested reduced motion. Four duration tiers (quick 100ms, standard 200ms, emphasis 350ms, dramatic 500ms) and four easing curves (entrance, exit, standard, spring) cover the full motion language.

brand_semantic_colors carries hc_light_value and hc_dark_value columns alongside the standard light_value and dark_value. When high-contrast mode is active, the design system reads from the HC columns. NULL means “fall back to the standard value.” Every populated HC value has been verified to meet WCAG AAA (7:1 contrast) against typical backgrounds.

Every critical foreground-on-background pair is tracked in brand_accessibility_checks. Pairs with luminance contrast ≥ 7:1 are universally safe because they rely on lightness, not hue, to remain distinguishable. Pairs that depend on hue discrimination — particularly red/green semantic states (error vs success) — must be paired with an icon or label so colour is not the sole channel conveying meaning.

Components must use logical CSS properties (margin-inline-start, padding-inline-end, inset-inline-start, border-inline-end) instead of physical (margin-left, padding-right, left, border-right). Text alignment uses start/end, not left/right. Directional icons (arrows, chevrons, undo/redo) should be marked data-rtl-mirror="true" so they flip in RTL contexts. The rtl-conformity-check Layer 8 component validates these rules at runtime and reports violations.

Certain components carry brand-identity decisions that are non-negotiable. These live in brand_component_specs and include the pill-shaping rule: buttons, inputs, avatars, badges, and toggles always use borderRadius 9999. Query that table before creating new components that resemble these categories, so the brand identity is preserved.

The system runs a daily accessibility audit that validates every non-exempt pair in brand_accessibility_checks under four color-blindness simulations. Regressions are surfaced via the N8 assurance surface so the palette is continuously validated rather than checked once at release time.

The audit is registered as the N8 component accessibility-audit and runs via pg_cron job nyuchi-accessibility-audit-daily at 02:00 UTC.

To run the audit on-demand:

SELECT * FROM run_accessibility_audit();

To preview how a specific colour appears under a specific condition:

SELECT simulate_color_blindness('#0047AB', 'deuteranopia');

Decorative pairs can be exempted by setting audit_exempt = TRUE with a reason, following the WCAG 1.4.11 (Non-Text Contrast) exemption for borders that do not convey state or meaning.