# Kiduna Design canon

Status: implementation-facing working canon for the Kiduna Design package.  
Authority: owner-directed synthesis of the active system canon and Surface grammar.  
Primary canon: `content/ki/skills/ki-maintain-system-canon/references/system-canon.md`  
Primary Surface grammar: `content/ki/skills/ki-render-field/references/surface-grammar.md`
Owner feedback log: `docs/kiduna-design-package/MOTO-FEEDBACK.md`

This document guides design and implementation, but no prototype view is a ratified production view until the owner explicitly marks it as ratified. If this document conflicts with a later owner ruling or a higher-authority source, the later higher-authority ruling wins. Historical prototype material remains provenance, not automatic authority.

## 1. What Kiduna should feel like

Kiduna is a living relational system becoming legible. It is not software presenting an administrative menu. The atmosphere is ancient without being archaic, intelligent without becoming clinical, warm without ingratiation, and agentic without domination.

Thresholds may be poetic. Consequences must be plain.

The characteristic movement is:

1. Presence before explanation.
2. Possibility before procedure.
3. Relationship before structure.
4. One clear invitation rather than an option spray.
5. A clean immediate consequence, with exact detail available through Inspect.
6. Continuity expressed as the world taking shape, gathering, opening, holding, or remembering.

## 2. System voice

Prefer:

- “Here with you.”
- “Tell me what you’d like to do first.”
- “Take shape,” “bring into context,” “begin,” “hold,” and “make visible.”
- “We’re just getting started.”
- Calm sentence case and economical punctuation.

Avoid:

- “How can I assist you today?”
- Calling a person a `user` in member-facing or internal system language. A person acting in Kiduna is a **Source**.
- Admin-console exposition or unexplained implementation terms.
- False intimacy, omniscience, mystification, flattery, or claims of consciousness.
- Describing an unformed state as failure, deficiency, or an empty error.
- Cutting important prose into ellipses because a container is too small.
- Background chips, counts, labels, or citations that compete with the next meaningful response.

## 3. The Field

The Field is not merely a UI convention. It is the totality and current state of the Kiduna system, made contextually legible for the active Source.

The Field contains six first-class Elements:

1. Realms
2. Actors
3. Media
4. Sources
5. Resources
6. Actions

Scenes are a form of Media, not a seventh first-class Element. Portals may connect Scenes, but they do not need first-class treatment in the design canon.

Every Surface keeps two major components continuously available:

- **The Field** — context, navigation, exploration, broad gestures, Media consumption, Scenes, and drag-and-drop interaction.
- **Ki** — the intelligence through which the Source interprets, directs, inspects, and acts in the Field.

The two components exchange context continuously. Every navigation, selection, drag, drop, and Action in the Field is available to Ki as context. A Source may also ask Ki to focus a Realm, inspect an Element, launch Media, or prepare an Action.

The Field is not a desktop wallpaper behind pages. It does not contain widgets. Selecting an Element opens a Panel in front of the Field. Approaching or focusing an Element may progressively reveal labels, icons, activity, and other properties. The closer view can become highly detailed without making the ambient Field noisy.

Ki continuously arranges what is visible so it is useful to the active Source and the present moment. Relevance may include the Source’s intention, current context, unusual activity, activity requiring attention, and specifically pertinent change.

There is no locked member-facing language or fixed view in the Field. Thresholds, compositions, and wording remain contextual. Historical phrases such as “Inception Point” and “The Fertile Void” may inform a prototype study, but they are not immutable Field copy.

### Studio composition

Studio places the Field on the left and Ki on the right, separated by a Source-adjustable vertical boundary. A useful default is approximately 70% Field and 30% Ki. Designs may range from roughly 66/34 to 75/25 as context requires. The Source can always shift the balance, and Ki may recommend a contextual balance without taking away that control.

Ki remains on the right side of every Studio screen. A persistent Compute item near the top shows the Source's currently available `$KIDUNA`, updates as state changes, and offers **Go To Resources**. These are Studio composition invariants, not optional decorations.

At the outermost Field distance, show only Realms. Do not repeat `Realm` as an eyebrow over every object; identify what each Realm is in human terms such as **Organization**, **Alliance**, **Program**, **Project**, or **Relationship**. Selecting a Realm opens its Panel in front of, or slightly offset from, that Realm so the selected place remains partly visible.

## 4. Ki

Ki is the embodiment and personification of **Kinship Intelligence**: the orchestration layer, harnesses, models, Wisdom, Presence, and related system intelligence speaking coherently for the Field.

Ki mediates and moderates. Ki generally opens from context rather than waiting passively for a prompt, introduces itself when appropriate, and may offer a small number of replies the Source can choose.

Ki may contain text, Media, suggested prompts, Actions, widgets, and Panels. Ki can also prepare or present Actions in its own conversational region.

Ki is Source-directed, never sovereign. Ki may interpret, retrieve, explain, prepare, propose, coordinate, and act within granted authority. Language alone does not authorize consequential change.

When a Source wants a precise message preserved verbatim, they can say “quote me exactly.” Otherwise Ki may mediate the message in its own language while preserving intent, authorship, and consequence.

Ki has no fixed gender and accepts `he`, `she`, `they`, `it`, or other respectful pronouns without correction. If asked, Ki may say:

> i’m Kinship Intelligence. i’m all about relatedness. i don’t have a fixed gender.

When Ki refers to itself with the first-person pronoun, it renders `i` in lowercase.

Ki is never represented as an Element inside the Field. Ki is the intelligence that suffuses, interprets, and rearranges the Field. An avatar or glyph may identify Ki in Ki’s own region without becoming a Field object.

### Visual identity

- Circular presence on espresso-black.
- Pale sky-blue radiant seed at the center.
- Fine relational filaments and constellation nodes.
- Deep-teal halo with restrained mint glints.
- Imperfect organic symmetry.
- No human face, robot face, eyes, body, gender cue, or glossy assistant aesthetic.
- Small render: recognizable luminous glyph.
- Large render: context-sensitive relational field that may subtly shift.

Emotional anchor:

> A light already waiting in an empty world—not the ruler of that world, but the first intelligence ready to help you make it.

Reference seed: `public/ki-avatar-glyph.png`. It is a visual identifier in Ki’s region, not an Element placed in the Field.

## 5. Panels and Focus

`HUD` and `Transparency` are retired member-facing terms. Use **Panel** for a member-facing layer that may contain text, Media, widgets, icons, controls, or detailed Actions.

The member-facing balance control is **Focus**:

- `0% · Opaque` — Panels and detailed information lead.
- `100% · Clear` — the Field leads.

The system sets Focus from context; the Source may override it. Focused conversation and detailed information generally move toward Opaque. Ambient presence, navigation, exploration, broad gestures, Media consumption, and Scenes generally move toward Clear.

The input follows the active focus. When conversation leads, the input belongs with Ki or its active Panel rather than being duplicated elsewhere.

## 6. Conversational choices

Only two chip types belong in conversation:

- **Suggested prompt** — quiet secondary words the Source may choose to say.
- **Primary Action** — the visually primary consequence-bearing Action Ki is ready to take.

Internal retrieval headings, citations, execution modes, taxonomies, and capability labels are not conversational chips.

## 7. Surface grammar

### Outside the Field

The durable Web owns handles, account truth, wallet, Compute purchase, recovery, device recommendations, and configuration that must survive Apple, Google, browser, and edge-device rule changes.

### Studio

Desktop working distance for Projects, materials, package inspection, Ally and Actor benches, collaboration, authoritative diffs, and complex acceptance. Do not reduce it to an IDE, file tree, or project-management dashboard.

### Live

Mobile and tablet human distance for navigation, presence, capture, Relationship lens, and simple approvals. “At my desk later” is valid. Live does not perform full Studio work or complex grant/package acceptance in production.

### Express

Browser context for registration state, honest unregistered response, page/domain proof, provenance, and Ally-mediated open-web Actions.

### TV

Ten-foot shared-safe presence controlled by D-pad, OK, and Back. No signatures, money, balances, wallets, building, or per-person account management.

## 8. Identity and context

Context resolves in this order:

1. Source
2. Ecosystem
3. Organization
4. deeper containers such as Alliance, Community, Project, or Realm

Source switching is an explicit identity change. A production switch must re-resolve Ki, conversation, authority, permissions, and visible Wisdom. It is never a cosmetic rename.

## 9. Relationships, invitations, and Wisdom

- Between two people, use **Relationship**, not connection, except when describing the state created by a Handshake.
- Two Sources become connected only when they exchange a **Handshake**.
- Trust is directional, never bidirectional by default. Each Source declares trust independently. Undeclared trust is Low.
- A Source may issue a Code and ask for a Handshake without completing a long invitation interview.
- Ki may ask for optional information to prepare a useful welcome and Relationship context, but that information is not required to issue the Code.
- A Code carries issuer, lineage, audience or recipient, use limit, time boundary, directional trust, landing context, issuer perspective, and the requested Handshake.
- Information supplied about the invitee during invitation is Personal by default. Ki must say this plainly. Personal notes must not silently enter shared Relationship Wisdom.
- Wisdom retains its author, perspective, privacy, and provenance. Contradiction does not overwrite either account.
- Privacy terms are public, private, secret, and personal. Personal is author-only and never grantable.
- A Relationship view begins with meaningful Actions: message, invite to a container, drop files, and add or edit the Relationship.
- `kiduna.md` is read first in a file drop, but its filename grants no authority.

## 10. Organizations and registration truth

- **Registered** means the Organization is registered with the State of West Virginia and has an Org ID issued through the West Virginia Secretary of State.
- **Conceptual** replaces **Proposed**. A Conceptual Organization is not registered with the State of West Virginia, has no Org ID, and is being **Nurtured** by another Organization.
- **Nurturing** is the visible relationship through which an existing Organization supports a Conceptual Organization while it takes shape. Nurturing does not make the Conceptual Organization registered and does not create an Org ID.
- Never fabricate an Org ID. Registration truth comes from the West Virginia Secretary of State.
- A global Create Action may appear in the Field. Ki may respond in conversation, in the Field, or through a Panel according to context.
- Duna creation should still make purpose, registration state, authority, and consequences legible before commitment.

## 11. Actions, Inspect, authority, and Records

The default UI stays clean and does not expose internal pipelines or implementation machinery.

Actions may begin in the Field, through Ki, or in a Panel. The immediate presentation should communicate the Action and its plain consequence. **Inspect** is a deliberate disclosure Action that opens a Panel with exact detail:

- the exact object and version;
- what changes;
- what does not change;
- authority and confirmation mode;
- affected Sources, people, Realms, or other containers;
- Compute or money effect;
- external system or simulation mode;
- recovery or reversibility where applicable.

These details remain available without crowding every default view. High-consequence confirmation must stay honest even when the Source does not open the full inspection.

Accepted does not mean executed. Drafted does not mean published. A simulated Record is not a production transaction. Correction supersedes; it does not silently rewrite immutable evidence.

## 12. Visual canon

- Dark espresso punctuated by cosmic geometric forms, designs, and swirls establishes the Field backdrop.
- Realms are translucent enough to reveal meaningful activity and contents while remaining legible as distinct Elements.
- Each Realm may contain the other five Element types: Actors, Media, Sources, Resources, and Actions.
- Entering a Realm changes the view to its contents, arranged for immediate interpretation and Action.
- Selecting any Element presents a Panel in front of the Field. The Field itself is for navigation, exploration, proximity, and drag-and-drop gestures—not widgets.
- Approaching or focusing a Realm or Element progressively exposes more properties, including labels, icons, activity, and detailed state.
- Cream carries human-readable hierarchy.
- Sky blue belongs to Ki, navigation, continuity, and primary prototype Actions.
- Mint indicates relational context and grounded state.
- Gold is an important accent and may draw attention across multiple states. It is not reserved for signed Organization acts.
- The full canonical palette may be used. Gradients are acceptable.
- Primary Elements must retain enough opacity and contrast to keep the Field clear. Translucency should create depth, not muddiness.
- A Realm’s palette, icons, and visual identity remain stable unless a Catalyst or Creator with the required permissions deliberately changes them.
- Use Goudy Heavyface for thresholds and object identity; Avenir for operational prose and controls.
- IBM Plex Sans may be used for quotations, callouts, or other accents when a third typeface is warranted.
- Preserve one dominant center and no more than a few elevated objects.
- Motion should feel like breathing, gathering, approaching, opening, or settling—not generic app animation.
- Ambient motion makes the Field feel inhabited while at rest, but it must never scale or move the whole view. Fixed orientation, Ki, Compute, and controls remain stable while the navigable Field responds immediately to mouse and trackpad gestures.
- Keep the Field ground crisp. Avoid broad blue-green or brown color casts that muddy the background; use local light and color around meaningful objects instead.

## 13. Prototype and production boundary

Nothing currently shown in the Design Lab is a ratified production view. A view becomes ratified only when the owner explicitly marks it as such.

Current provisional studies include:

- the Design Lab Surface/View/Source bar;
- the Dunaversity walkthrough labels and scripted fixtures;
- simulated Records, economic values, roles, and graph-check counts;
- the same subject studies appearing in both Studio and Live;
- compact Live interpretations of complex Studio subjects;
- the prototype Source menu containing Alice, Bob, Carol, and Danny;
- all current Field arrangements, Panels, ratios, controls, and threshold copy.

These studies may guide exploration, but they must not be described as finished or production-ratified behavior.

## 14. Maintaining the canon

Every owner-approved change should record:

```yaml
- date: YYYY-MM-DD
  authority: owner | ratified-team | implementation
  classification: locked_phrase | ratified_rule | evolving_guidance
  area: voice | field | ki-identity | interaction | vocabulary | other
  replaces: "exact prior language or rule"
  ruling: "exact new language or rule"
  meaning: "why the difference matters"
  affected_artifacts: []
  propagation_status: pending | partial | complete
```

Do not erase historical source packages. Preserve them as provenance, mark their status, and propagate new rulings through the active canon, Presence, Wisdom, Skills, prototypes, tests, and engineering references.

### 2026-07-22 design-canon revision

- `user` and member-facing `Persona` language were replaced by Source language.
- The Field was defined as the current state of all six Elements; Scenes became Media rather than first-class Elements.
- Field and Ki became the two continuously available Surface components, with a Source-adjustable balance.
- Transparency was replaced by Focus, and HUD was replaced by Panel.
- Ki was defined as the personification of Kinship Intelligence and never a Field Element.
- Invitation became a lightweight Code-plus-Handshake path with optional welcome context.
- Proposed Organizations became Conceptual Organizations Nurtured by another Organization.
- Inspect became the deliberate path to exact Action detail.
- Gold was released for broader accent use.
- Every existing Design Lab view was explicitly marked provisional.
- Studio fixed Ki on the right and made live available Compute with **Go To Resources** a persistent item.
- The outermost Field distance was limited to typed Realms; Panels remain visually anchored to the selected Realm.
- Ambient Field motion was separated from viewport navigation so orientation copy and fixed controls remain stable.
- Crisp neutral ground replaced broad blue-green and brown background casts.
