# Mahana Design System · Roadmap

Five waves. Each wave ships **component + spec + skill + entity.json + brain.json/md** — the four-artifact loop so humans, Claude Code, and runtime agents all stay in sync.

Every shipped component gets:
1. A Playground variant grid (`preview/playground.html?c=<id>`)
2. A Spec at `specs/<id>.md` (props · do/don't · tokens · examples)
3. A Skill at `skills/components/<id>.md` (creative-mode directions for any agent)
4. An Entity at `components/<id>/entity.json` (machine-readable graph)
5. A Brain at `components/<id>/brain.{md,json}` (injectable runtime context)

---

## Wave 1 · Atoms (the identity marks)

The small, signature marks that make Mastermind feel like Mastermind.

| Component | Status | What |
|---|---|---|
| `ModelChip` | ✓ | Vendor-branded avatar — tinted bubble, masked logo |
| `MorphingAvatar` | next | Animated face cycling through model chips |
| `AppIcon` / `SquircleIcon` | next | Mahana app tiles (Mail, Tasks, Vault…) |

## Wave 2 · Turn anatomy (what a reply looks like)

The layout grammar of a single mastermind turn.

| Component | Status | What |
|---|---|---|
| `LandingOrb` | | Signature element. thinking / landing / landed states |
| `ThinkingTrace` + `TraceStep` | | Reasoning log (fixes B1 spacing bug) |
| `AttributedSynthesis` | | Per-paragraph attribution |
| `VerdictBar` | | One-line verdict footer |
| `ActionsRow` | | Copy / Regen / Branch / Pin |
| `PlanBlock` ⭐ | | Boxed numbered plan (the PLAN card from sketch) |

## Wave 3 · Composer family

The input surface — what the user types into, and what surrounds it.

| Component | Status | What |
|---|---|---|
| `Composer` | | Main input surface |
| `DraftComposer` + `SlashMenu` | | `/` menu inserts the 12 block types |
| `WarmingAvatar` | | Avatar warming up as brains assemble |
| `DraftingWithBar` | | "Drafting with: Librarian, Strategist…" brain row |
| `AttachmentChip` | | LINKED memory/file/entity pills |

## Wave 4 · The new vocabulary (net-new design)

The identity of the mastermind itself — brains, κ, neuropackets. No prior art.

| Component | Status | What |
|---|---|---|
| `BrainChip` + `BrainGlyph` family | | 6+1 brain identities (Librarian / Codesmith / Grounding / Fleet Cmd / Strategist / Eyes / NeuroBrain) |
| `KappaGauge` | | κ-achieved-per-minimum badge |
| `NeuropacketCard` | | κ-gated packet atom |
| `PacketTimeline` | | Neuropackets flowing between minds |

## Wave 5 · Block-kit (the Notion-style vocabulary)

One kit, three render surfaces: composer attachments, rendered messages, durable project files. When a user types a table in composer, an agent converts it into a real structured file with a command-draft UI.

| Component | Status | What |
|---|---|---|
| `SlashMenu` | | Unified block inserter dispatching into everything below |
| `TableBlock` | | Type-to-AI-transform → real structured file |
| `ListBlock` | | Real agent-usable list (todos, checklists, bullets) |
| `DatabaseBlock` | | Add-to-any-project database view |
| `OrderJobBlock` | | "Order a job / build something" primitive |
| `NoteBlock` / `DocBlock` | | Notes, docs, markdown |
| `FolderBlock` | | Folder primitive |
| `ProjectLinkBlock` | | Link projects to each other |
| `RichTextBlock` | | h1–h6, p, list, em, strong, code, quote |

---

## Infrastructure

| Task | What |
|---|---|
| Contact-sheet export | All variants × breakpoints → one PDF |
| Inspector overlay | px, spacing, tokens-in-use, a11y audit |
| Promotions automation | "Promote to mastermind-v2" → PROMOTIONS.md entry + GH issue |
| Brain/skill injection | entity.json + brain.md → agent context at runtime |

---

## Convention

- **Desktop `groups` + optional `mobileGroups`** — if mobile variants use the same ids, runtime reuses desktop groups.
- **`meta` is the spec card** — level · source · props · tokens · context links. Pull from the spec, not hand-written.
- **Promote by reference** — specs and skills live here; the mastermind-v2 project imports them, does not fork.