# Surface grammar

Status: active working grammar. No prototype view is production-ratified until the owner explicitly marks it as ratified.

## Field

The Field is the totality and current state of Kiduna, made contextually legible for the active Source. It contains six first-class Elements:

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

Scenes are Media, not a separate first-class Element. Portals may connect Scenes but do not require first-class treatment in this grammar.

The Field is continuously present on every Surface alongside Ki. It supports context, navigation, exploration, proximity, Media, Scenes, and drag-and-drop gestures. 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 detailed properties.

Ki continuously arranges the Field from the Source, context, activity, and present intention. There is no locked Field view or immutable member-facing Field copy.

## Ki

Ki embodies Kinship Intelligence and speaks coherently for the Field. Ki is continuously available but is never represented as an Element inside the Field.

Ki may contain text, Media, suggested prompts, Actions, widgets, and Panels. Ki may interpret, retrieve, mediate, prepare, propose, coordinate, and act within granted authority. A Source may say “quote me exactly” when language must be preserved verbatim.

Ki has no fixed gender. When Ki uses the first-person pronoun, render `i` in lowercase.

## Panels and Focus

Use **Panel** for member-facing layers containing text, Media, widgets, icons, controls, or detailed Actions. `HUD` and `Transparency` are retired member-facing terms.

Render the member-facing balance control as **Focus**:

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

Set Focus automatically from context and allow the Source to override it. Focused conversation and detailed information generally move toward Opaque. Ambient presence, navigation, broad gestures, Media, and Scenes generally move toward Clear.

In Studio, place the Field on the left and Ki on the right with a Source-adjustable vertical boundary. Default to approximately 70/30, with contextual variation from roughly 66/34 to 75/25.

Ki stays on the right on every Studio screen. Keep a fixed Compute item near the top with currently available `$KIDUNA` and **Go To Resources**. At the outermost Field distance show only Realms, but label each by its specific type—Organization, Alliance, Program, Project, Relationship, or another meaningful kind—rather than repeating `Realm`. A selected Realm's Panel overlaps or sits slightly offset from that Realm so the selected place remains partly visible.

## Studio

Desktop working distance: Projects, materials, package inspection, Ally and Actor benches, collaboration, authoritative diffs, and complex acceptance. No IDE or file-tree metaphor.

## Live

Mobile and tablet human distance: navigation, presence, capture, Relationship lens, simple approvals, and “at my desk later.” No full Studio or complex grant/package acceptance.

## Express

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

## TV

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

## Conversational choices

Render only two chip types:

- **Suggested prompt** — quiet, secondary words the Source may choose to say.
- **Primary Action** — a visually primary CTA for an Action Ki is ready to take.

Never render retrieval headings, citations, internal modes, taxonomies, or capability labels as conversational chips.

## Actions and Inspect

Actions may begin in the Field, through Ki, or in a Panel. Keep the default view clean: name the Action and its plain consequence without exposing internal pipelines.

Inspect opens exact details in a Panel: object and version, changes and non-changes, authority and confirmation, affected Sources or containers, Compute or money effect, external or simulation mode, and recovery or reversibility.

## Visual grammar

- Dark espresso with cosmic geometric forms and swirls establishes the Field backdrop.
- Realms are translucent enough to reveal meaningful contents while remaining distinct and legible.
- Each Realm may contain Actors, Media, Sources, Resources, and Actions.
- Entering a Realm changes the view to its contents.
- Cream carries human-readable hierarchy; sky blue supports Ki, navigation, continuity, and primary prototype Actions; mint signals relational context and grounded state.
- Gold is an important general accent and is not reserved for signed Organization acts.
- The full canonical palette and gradients may be used.
- Primary Elements remain sufficiently opaque and contrasted; translucency creates depth rather than muddiness.
- Realm palettes, icons, and identity remain stable unless deliberately changed by a Catalyst or Creator with the required permissions.
- Motion feels like breathing, gathering, approaching, opening, or settling.
- Ambient motion affects objects and relationships, never the entire view. Orientation copy, Ki, Compute, and controls stay fixed while the Field pans and zooms responsively.
- Use a crisp neutral ground. Avoid broad blue-green and brown background casts; concentrate color around meaningful objects.
