# The Kiduna Ally System

## 1. Core model

### Source

The real person. The Source owns their identity, choices, permissions, and representation.

### Ally

The Source’s persistent visual identity inside Kiduna. An Ally is not a bot, synthetic replacement, digital twin, or claim about the Source’s legal identity. It is a recognizable, Source-approved representation used across Kiduna applications.

### State

A temporary visual expression of the Ally’s current mode. State may change pose, gaze, expression, cheek sigil, and medallion field. It must not change who the Ally is.

### Relationship

The default model is one Source → one canonical Ally → several states. An Ally should remain recognizable across every Kiduna surface and state.

## 2. Design principles

1. **Recognition before decoration.** Face shape, age, skin tone, hairstyle, and distinctive features must survive at small sizes.
2. **Warm eyes.** Allies should feel available to relationship. Even focused and dreaming states keep the eyes visible.
3. **Identity is stable; state is fluid.** State changes are deliberately limited to expression and symbolic context.
4. **Caricature with dignity.** Exaggerate a few memorable features without ridicule, infantilization, or stereotype.
5. **Kiduna-native.** Use the canonical palette and sun, moon, orbit, node, and constellation vocabulary.
6. **Source-controlled.** The Source approves the canonical Ally and may revise, freeze, hide, or retire it.
7. **Readable without lore.** The portrait works as a profile picture even when the viewer does not know the state system.

## 3. Celestial Enamel visual grammar

Each production Ally is a circular enamel portrait medallion inside a square asset.

### Fixed identity layer

These properties remain consistent across states:

- facial proportions and distinguishing features
- skin tone
- apparent age
- hair shape, texture, and primary color
- facial hair
- body and shoulder silhouette
- one or two signature adornments
- core clothing silhouette and main colors
- line weight, enamel material, and gold rim treatment

### Variable state layer

Only these properties normally change:

- head angle within a restrained range
- eye direction
- brow and mouth expression
- cheek sigil
- background celestial geometry
- local balance of approved palette colors
- subtle lighting emphasis

### Composition

- Head and shoulders; face occupies most of the medallion.
- Frontal or gentle three-quarter views are preferred.
- Full profiles are reserved for exceptional narrative uses, not routine profile pictures.
- Keep both eyes visible whenever practical.
- Use one clear silhouette and little background clutter.
- The circular rim must remain legible at 40 px.

### Palette

| Role | Color | Hex |
| --- | --- | --- |
| Deep field | Deep umber | `#120C07` |
| Primary ground | Umber | `#1C140D` |
| Surface | Warm brown | `#271B11` |
| Action/light | Sky | `#03CCD9` |
| Solar accent | Sun gold | `#EAAA00` |
| Lunar light | Moon cream | `#FFF6D5` |
| Human warmth | Camel | `#C19A6B` |
| Secondary ground | Aubergine | `#2A1A2B` |
| Rare magic | Mint | `#8FE6C6` |

Do not introduce a dominant color outside this palette. Mint is rare. Sky identifies active or relational energy; it should not flood every surface.

## 4. Canonical state vocabulary

### OPEN

**Meaning:** available, welcoming, present. This is the default neutral state.

- Pose: frontal or gentle three-quarter
- Gaze: direct eye contact
- Expression: relaxed, subtle individual smile
- Cheek sigil: open ring or radiant four-point spark
- Field: sunrise discs, cream space, sky arcs, sparse gold rays

### ENGAGED

**Meaning:** actively conversing, collaborating, or responding.

- Pose: lively three-quarter, never facing away
- Gaze: active direct eye contact
- Expression: lifted brows and conversational warmth
- Cheek sigil: linked nodes or a small relational constellation
- Field: paired nodes, orbit lines, and connected constellations

### FOCUSED

**Meaning:** deliberately working, reviewing, or making.

- Pose: near-frontal or restrained three-quarter
- Gaze: slightly beside the viewer toward an implied task
- Expression: composed and attentive, not stern
- Cheek sigil: diamond compass or four-axis mark
- Field: concentric rings, compass points, disciplined radial geometry

### DREAMING

**Meaning:** imagining, incubating, reflecting, or exploring possibility.

- Pose: near-frontal or gentle three-quarter
- Gaze: slightly upward, eyes still visible
- Expression: softened brows and faint private warmth
- Cheek sigil: crescent cradling a star or seed-light
- Field: open constellations, crescents, floating nodes, rare mint spark

## 5. State behavior in products

- **OPEN** is the fallback when no meaningful state is available.
- A Source may explicitly select a state. Explicit selection outranks automation.
- Product-driven state changes must describe real in-product context, not infer emotion from a camera, face, demographic information, or private behavior.
- Use **ENGAGED** during an active shared exchange, **FOCUSED** during a clearly initiated work mode, and **DREAMING** during a clearly labeled ideation or incubation mode.
- Do not change states rapidly. Use a minimum dwell time and avoid animation that makes the identity feel unstable.
- A state is expressive product language, not a claim about the Source’s actual mental or emotional condition.
- Never imply presence, endorsement, or activity when the Source is not actually present or has not authorized an automated representation.

## 6. Accessibility

- Never communicate status through the avatar alone.
- Pair the avatar with a text status, tooltip, accessible name, or nearby status control where the state matters.
- Suggested accessible name: `Ally for [display name], [state]`.
- Maintain a visible boundary against both dark and light surfaces.
- Test at 32, 40, 64, 128, and 256 px.
- Avoid relying on subtle facial expression as the sole state cue. The cheek sigil and field grammar provide redundant cues.
- Respect reduced-motion preferences. State transitions should default to a short crossfade or no motion.

## 7. Representation and governance

- Obtain the Source’s informed permission before using their photos to generate an Ally.
- Show the Source the canonical master before producing state variants.
- The Source may reject caricature choices, adornments, cultural references, age presentation, or gender presentation.
- Do not infer or invent religion, ethnicity, disability, profession, rank, or cultural identity from appearance.
- Do not lighten or darken skin, change apparent age, alter gender presentation, or remove identity-defining features without explicit direction.
- Do not add crowns, uniforms, weapons, luxury signals, or status markers by default.
- Store Source reference photos separately from shipped Ally assets. Follow the product’s privacy and retention rules; do not expose source photos to clients.
- Record the approved canonical revision. Every generated state must name the canonical revision from which it was derived.
- Material identity revisions require Source review. Routine state rendering does not, provided it remains within the approved grammar.
- Provide a non-portrait fallback for Sources who do not want a generated likeness: a Source-approved celestial monogram or abstract medallion.

## 8. Anti-patterns

- Six different faces presented as “states” of one person
- Full profiles that hide engagement in routine UI
- Generic corporate vector portraits
- Generic NFT rarity traits or randomized status accessories
- Anime, chibi, toy, emoji, or photoreal styles
- Unapproved cultural costuming
- State inferred from surveillance or biometric analysis
- Mood labels baked into individual production avatar images
- Uncontrolled regeneration that gradually changes identity
