# Kiduna Design System

A focused, opinionated design system for **Kiduna** — a living ecosystem where people and their allies organize around shared purpose, form relationships, build institutions and movements, and govern what they create together.

Kiduna takes shape through the **Field**: a dynamic, spatial interface in which people, intelligent agents, communities, organizations, projects, conversations, agreements, resources, and decisions remain present and connected.

Organizations here are not static structures assembled from predefined charts and forms. They emerge through participation. People and their allies establish purpose, define roles, make decisions, allocate resources, coordinate action, resolve tensions, and adapt their rules as circumstances change. The system supports governance without requiring centralized control and self-regulation without reducing collective life to scores, rankings, or rigid automation.

The design language should feel alive but grounded, intelligent but human. Dark-UI native. Serif display, sans body. Sky blue carries action and possibility across a deep-umber ground. Sun gold and moon cream connect the system to the Kiduna mark; camel and chocolate add warmth, materiality, and depth; mint signals growth, intelligence, and emergence.

### Foundational Brand Structure

**The ecosystem** is the whole living system.\
**The Field** is how that system is perceived and navigated.\
**People and their allies** are the participants through whom it thinks, organizes, and acts.

### Tag Line

> *Where people and their allies organize what comes next.*

---

## Orientation

This is a **living design system** captured as a single CSS file + a folder of HTML preview cards. It is not a component library you install — it is a reference you read, copy from, and extend. If you are building a new Kiduna surface (a landing page, a dashboard, a proposal, a slide deck, a prototype), start by reading this file and linking `colors_and_type.css`.

**Files at a glance**

- [`colors_and_type.css`](./colors_and_type.css) — tokens + base styles. Import this into everything.
- [`UI Kit.html`](./UI%20Kit.html) — a full worked example: nav, hero, stat strip, capability cards, delivery feed, engagement tiers.
- [`preview/`](./preview) — one HTML card per design-system concept (colors, type, spacing, components, logos). These are the review artifacts.
- [`assets/`](./assets) — the Kiduna sun/moon logos (`kiduna-logo-linear-skyblue.svg`, `kiduna-logo-stacked-gold.svg`, `kiduna-mark.svg`), the extra-wide `kidunaverse-banner.svg`, and favicon set (`favicon.svg`, `favicon-32.png`, `apple-touch-icon.png`), plus legacy Kinship lockups and the fawn symbol (`fawn-symbol-*.svg`).
- [`fonts/`](./fonts) — Goudy Heavyface + Avenir (Light / Book / Regular / Heavy / Black).
- [`SKILL.md`](./SKILL.md) — the skill prompt: *how to design in the Kidunaverse idiom*.

---

## Visual foundations

### The three-word aesthetic

**Deep. Warm. Alive.** Kiduna begins on a near-black deep umber (`#1C140D`), with sky blue (`#03CCD9`) carrying the clear current of action, navigation, continuity, and Ki’s presence. Camel (`#C19A6B`) and chocolate (`#6F4A2E`) give the Field material warmth; aubergine (`#2A1A2B`) opens a deeper, more imaginative alternate ground. Sun gold (`#EAAA00`) and moon cream (`#FFF6D5`) come directly from the Kiduna mark, bringing light, significance, and human-readable contrast to the dark.

**Kiduna never uses pure white.** Wherever an interface, document, illustration, or brand application would ordinarily call for white (`#FFFFFF`), use **cream white (`#FFFFE6`)** instead. It is the system’s neutral light: softer against the Field, warmer beside the earth tones, and more coherent with Kiduna’s material character. Moon cream remains a distinct, more golden brand color for lunar light, highlights, and symbolic emphasis; cream white performs the everyday role of white.

From this warm foundation, a broader spectrum brings the ecosystem to life. Violet grows out of aubergine, with violet bright (`#9D7BE8`) illuminating alliances, intelligent actors, and emerging constellations. Jade (`#57C08F`) gives communities, participation, and collective growth a vivid presence, while mint (`#8FE6C6`) marks relationship, availability, and grounded living state. Apricot (`#F0A85C`) extends the earth and sun colors into something more open and inviting—a warm accent for projects, invitations, highlights, and moments of emergence. These colors are not ornamental additions to an umber-and-sky interface; they help people perceive the different forms, relationships, and possibilities taking shape across the Field.

The extended palette is organized in dark-to-light ranges: deep tones establish atmosphere and surfaces, core tones provide identity and structure, bright tones remain legible on dark, and pale tints create moments of openness and illumination. Sky remains the unmistakable signal for action. Gold is used deliberately where organizational or record-level significance warrants it. Violet, jade, apricot, and their related ranges supply identity, life, and invitation without turning the Field into visual noise.

Avoid pure white, cold greys, flat pastel fields, decorative gradients, and color without meaning. Use richer color confidently but purposefully, paired with form, icon, language, and context. The result should feel less like a dark interface with occasional accents and more like a living ecosystem—warmly grounded, visibly diverse, and quietly luminous.

### Typography

Goudy Heavyface (display) + Avenir (body) + IBM Plex Sans (callouts). Goudy has a tall x-height and heavy stroke — it carries every headline. Avenir is the quiet, humanist counterpoint that handles everything else. Callouts — pull-quotes, asides, highlighted notes — are set in IBM Plex Sans via `--font-callout` / `.kin-callout` (loaded from Google Fonts).

**The signature move: `em.kin-emph`** — one italic Goudy Heavyface phrase, set in the brand sky blue, inside a display headline. *One phrase per headline, never two.* Examples in `preview/type-emphasis.html`.

### Rhythm

- 4pt spacing grid; 8/12/16/20/24 do most of the work.
- Pill-shaped nav and badges (`--radius-pill`); **buttons are squared with a slight radius** (`--radius-xs`, 4px). Cards use `--radius-lg` (14px).
- Shadows are cool and dim on dark surfaces — never bright. `--shadow-glow-accent` and `--shadow-glow-sky` are reserved for *one* hero CTA per screen.

---

## Content fundamentals

**Voice.** Warm, direct, profound. Short sentences. We write *to* the reader, not around them. We use "you" freely. We talk about *agents*, *organizations*, *ecosystems*, *members* — plainly, never in buzzwords.

**Headline pattern.** A complete thought, then an Goudy Heavyface phrase that reframes it in gold. The house tagline is the north star:

- *"Where people and their allies organize what comes next."*
- *"The agentic internet starts here."*
- *"A new architecture for agentic civilization."*

**Avoid.** Buzzwords (*synergy*, *leverage*, *disrupt*), hollow CTAs (*Learn more*), stacked emoji, jargon that isn't load-bearing. If we say "agentic" or "cloud-native," it has to mean something in the sentence.

**Numbers.** Always display in Goudy Heavyface. Round to three significant figures in dense UI (`99.98%`, `3,400`). Use full precision in detail views.

---

## Iconography

Kiduna uses a layered visual language. Each family has a distinct job: **icons support actions, crests identify Realms, Talismans carry meaning, connectors describe relationships, Allies represent people, and the Kiduna mark signs the brand.** Never substitute one family for another.

### Functional icons

Kiduna ships a focused set of Lucide-compatible line icons in `assets/icons/`, covering navigation, actions, system concepts, and Kiduna-specific functions.

Icons use a **24px grid**, **1.75px stroke**, round caps and joins, no fill, and `currentColor`. The default rendered size is **20px**; use 16px in dense controls, 24px for standard emphasis, and 32px only when additional prominence is needed.

Use color semantically:

- Muted foreground for ordinary controls.

- Sky blue for the active, linked, or consequence-bearing action.

- Camel for quiet supporting or atmospheric use.

- Mint only for rare moments of intelligence, emergence, or “magic.”

Do not give every icon an accent color. Do not mix filled, sharp-cornered, or differently weighted icon styles. Additional Lucide icons may extend the set when necessary, using the same construction rules. If no suitable glyph exists, use a clear placeholder until a canonical icon is drawn.

Text arrows (`→`, `↗`, `←`) remain the preferred continuation and direction glyphs in written CTAs. Use icons when they improve recognition, not as decoration or a substitute for a label.

### Realm and organization symbols

Realm emblems are identity objects, not interface icons. The seven Realm types—**Organization, Alliance, Program, Project, Relationship, Community, and Conceptual**—each have a supplied custom crest whose structure communicates its type before color does.

Every Realm emblem shares a celestial-enamel chassis: circular silhouette, double warm-metal rim, cardinal anchor studs, dark lacquer core, orbit track, constellation nodes, and moon-cream highlight. Preserve the defining geometry and semantic hue of every type. At small sizes, remove engraving and secondary detail before changing the silhouette or crest.

Never replace a Realm crest with Lucide, emoji, a font icon, or a generic outline symbol.

Organizations use the Organization chassis with a persistent, bounded identity system: a canonical central crest, exactly two approved deep-enamel colors, a deterministic star signature, an orbit engraving, and one or two emphasized anchors. These differences must remain recognizable at 40px and must never imply rank, rarity, or prestige.

### Talismans

Talismans are portable symbols of meaning:

- **Compass** — orientation

- **Moon** — reflection

- **Sprout** — cultivation

- **Tide** — flow

- **Summit** — purpose

- **Vessel** — stewardship

A Talisman may mark a ritual or value, accompany an invitation, belong to a Realm, or serve as a navigational landmark. It is not a Realm type, user identity, decorative badge, collectible, or status marker.

Use at most one dominant Talisman in a local composition. Preserve its canonical enamel colors and generous clear space; never recolor it to match its surroundings. Connectors attach at visible studs or orbit nodes, never through the central symbol. Always pair a meaningful Talisman with its accessible name and context.

### Connectors

Connections are semantic objects. They show how the Field belongs, relates, gathers, exchanges, and changes.

The primary forms are:

- **Orbit** — belonging

- **Tether** — direct relationship

- **Braid** — reciprocity

- **Confluence** — gathering

- **Anchor** — commitment

- **Crossing** — exchange

- **Threshold** — entry

Secondary forms include constellations, threshold arcs, and historical echoes.

At rest, connectors are quiet warm-gold or camel hairlines. Increased opacity, resolved endpoints, moon-cream cues, or a brief enamel light indicate relevance and activity. Attach every connection to a visible stud or node and route it behind labels and object faces. Use a star glint only when a crossing itself has meaning.

Do not animate the whole Field. Motion should communicate a real transfer, change, or newly active relationship, then settle. Prefer fewer legible connections to a complete but noisy graph, and provide an equivalent static state when reduced motion is requested.

### Allies

An **Ally** is the Source-approved visual identity of a person inside Kiduna. It is not a bot, digital twin, legal identity, or generic avatar.

Allies use circular celestial-enamel portrait medallions. Recognition comes first: facial structure, skin tone, apparent age, hair, distinctive features, adornments, clothing silhouette, and crop remain stable across every state.

The canonical states are:

- **Open** — available and present

- **Engaged** — actively collaborating

- **Focused** — deliberately working

- **Dreaming** — imagining or reflecting

A state may change expression, gaze, cheek sigil, and background geometry, but never the identity of the person. Open is the fallback. Explicit Source choice always outranks an automated state, and states must describe real product context—not inferred mood, biometric analysis, or private activity.

Never communicate presence or state through the portrait alone. Pair it with text, a tooltip, or an accessible name such as `Ally for [display name], [state]`. Use a Source-approved celestial monogram or abstract medallion when a person does not want a generated likeness.

### The Kiduna mark

The Kiduna sun-and-moon mark (preview/symbol-mark.html, assets/kiduna-mark.svg) is the standalone brand symbol—a quiet signature, not a general-purpose icon. Use it sparingly: as the favicon, one hero or section watermark, a loading or empty state, or the back of a card.

Use no more than one mark per surface. Never tile it, turn it into a bullet, recolor it, or substitute it for a Realm crest, Talisman, Ally, or action icon.

---

## Components (preview index)

| Concept | Card |
| --- | --- |
| Brand palette | [`preview/colors-brand.html`](./preview/colors-brand.html) |
| Accent + feedback colors | [`preview/colors-accents.html`](./preview/colors-accents.html) |
| Semantic tokens (dark) | [`preview/colors-semantic.html`](./preview/colors-semantic.html) |
| Display type (Goudy) | [`preview/type-display.html`](./preview/type-display.html) |
| Body type (Avenir) + Callout (IBM Plex Sans) | [`preview/type-body.html`](./preview/type-body.html) |
| The signature emphasis | [`preview/type-emphasis.html`](./preview/type-emphasis.html) |
| Spacing · Radius · Elevation | [`preview/spacing.html`](./preview/spacing.html) |
| Buttons | [`preview/buttons.html`](./preview/buttons.html) |
| Inputs | [`preview/inputs.html`](./preview/inputs.html) |
| Cards | [`preview/cards.html`](./preview/cards.html) |
| Badges + chips | [`preview/badges.html`](./preview/badges.html) |
| Logo — primary | [`preview/logo-primary.html`](./preview/logo-primary.html) |
| Logo — lockups | [`preview/logo-lockups.html`](./preview/logo-lockups.html) |
| Logo — banner (extra wide) | [`preview/logo-banner.html`](./preview/logo-banner.html) |
| Favicon — Kiduna mark | [`preview/favicon.html`](./preview/favicon.html) |
| Symbol — Kiduna mark | [`preview/symbol-mark.html`](./preview/symbol-mark.html) |
| Meta / Open Graph cards | [`preview/og-cards.html`](./preview/og-cards.html) |
| Extended color ranges | [`preview/colors-extended.html`](./preview/colors-extended.html) |
| Icons | [`preview/icons.html`](./preview/icons.html) |
| Light & Magic — gradients, auras, bursts, orbits | [`preview/effects.html`](./preview/effects.html) |
| Kiduna Allies — Celestial Enamel avatars | [`preview/allies.html`](./preview/allies.html) |
| Studio — Field taxonomy & Realm anatomy | [`preview/studio-taxonomy.html`](./preview/studio-taxonomy.html) |
| Studio — Field ground & ambient motion | [`preview/studio-field-ground.html`](./preview/studio-field-ground.html) |
| Studio — Ki panel kit | [`preview/studio-ki-panel.html`](./preview/studio-ki-panel.html) |
| Studio — Panels & Focus | [`preview/studio-panels-focus.html`](./preview/studio-panels-focus.html) |
| Studio — Realms | [`preview/studio-realms.html`](./preview/studio-realms.html) |
| Studio — Enamel states & celestial geometry | [`preview/studio-enamel-states.html`](./preview/studio-enamel-states.html) |
| Studio — Connection grammar | [`preview/studio-connections.html`](./preview/studio-connections.html) |
| Studio — Realm emblems & Organization identity | [`preview/studio-emblems.html`](./preview/studio-emblems.html) |
| Studio — Talismans | [`preview/studio-talismans.html`](./preview/studio-talismans.html) |
| Kiduna Live — glyphs, images & connectors | [`preview/live-glyphs.html`](./preview/live-glyphs.html) |
| Kiduna Live — Mobile | [`preview/live-mobile.html`](./preview/live-mobile.html) |
| Kiduna Live — Tablet | [`preview/live-tablet.html`](./preview/live-tablet.html) |

---

## How to use

```html
<link rel="stylesheet" href="/path/to/colors_and_type.css">
```

Then use tokens everywhere:

```css
.hero {
  background: linear-gradient(135deg, var(--surface-elev), var(--bg));
  color: var(--fg);
  border-radius: var(--radius-xl);
  padding: var(--space-16) var(--space-12);
  box-shadow: var(--shadow-lg);
}

.hero h1 {
  font-family: var(--font-display);
  font-size: var(--fs-5xl);
}

.hero h1 em { /* the signature move */
  font-family: var(--font-display);
  color: var(--accent);
}
```

For a full worked example, open `UI Kit.html`.

## Icons

`assets/icons/` — 27 Lucide-style line icons (24px grid, stroke 1.75, round caps, currentColor, never filled). Preview: `preview/icons.html`. Any Lucide icon at stroke 1.75 extends the set.
