@bongos/core 1.17.0

package/docs/design/vanilla-hall-ui-redesign-scope.md

@@ -0,0 +1,284 @@
+# Vanilla Hall UI — Redesign Scope
+
+**Surface:** the default UI every Cloud Bongos instance ships — the `hall-ui` module (`modules/hall-ui/public`) served at `builders.<apex>` → **builders.cloudbongos.com**.
+
+**What this fixes:** component **type, placement, and sizing**. It deliberately does **not** settle final visual design, colour, typography, or exact copy.
+
+**Status:** scope for hand-off. Owner to seed tasks from §12–§14.
+
+**Visual companion:** the annotated wireframes for every surface below are rendered as an interactive artifact — [Cloud Bongos — Vanilla UI Redesign Scope](https://claude.ai/code/artifact/b6992395-ff5b-4356-8acb-99908a574aa8).
+
+**Locked decisions (owner, 2026-07-02):**
+
+| Fork | Decision |
+|---|---|
+| Layout paradigm | **Dashboard shell** — persistent sidebar + top bar + focused content per view |
+| Scope breadth | **Landing + primary pages** — shell + Home, Work, Standing, Achievements, Leaderboard, Docs, Settings. Archon pages inherit the shell only. |
+| Voice / theming | **Neutralize to a clean default** — strip the "chronicles of the city" lore to neutral, professional labels |
+
+---
+
+## 0. Starting point — what exists today
+
+The current hall is **one long single-column page** (`index.html`, `<main>` capped at 1080px) styled as an illuminated "chronicles of the city" manuscript. `<main>` stacks eleven registry-driven widget "scrolls" in a fixed order; the header carries an epigraph + H1 + a stack of text nav-links; a sticky chip strip jumps between sections; depth lives on separate full pages behind those links.
+
+```
+┌────────────────────────────────────────────┐
+│ header — epigraph · H1 · welcome · 8 links   │
+│ sticky chip nav (jump-to-section)            │
+├────────────────────────────────────────────┤
+│ Welcome → Path → Standing → Honours → Karma  │
+│ → Acclaim → Works → Marks → Curve → Bounty   │
+│ → Roll → Goals            (11+ stacked)      │
+│ footer                                       │
+└────────────────────────────────────────────┘
+```
+
+The eleven core widgets (from `hall-widgets.js`, by mount order): **Welcome, Path (onboarding), Standing (profile), Honours (8 laurels), Karma, Acclaim, Works (ships), Marks (grades), Curve (analytics), Bounty (red-team rewards), Roll (leaderboard)** — plus a **Goals** widget (`goals.js`).
+
+Separate full pages behind header links: **Work Board, Primer, Diagrams, Repo Atlas, Ranks, Settings, Pair**, plus Archon-only **Watch, Harbor, Gate**.
+
+The data and the registry seam stay. The redesign changes the **frame** the widgets live in.
+
+---
+
+## 1. Principles — what "vanilla" has to mean
+
+This is the recommended base every project inherits and then customizes. It should read as neutral, obvious, and calm.
+
+- **Neutral first** — no theme baked into markup; character arrives through the brand pack.
+- **Scan, don't scroll** — persistent navigation replaces the long scroll; any surface is one click away.
+- **Frame > contents** — the redesign owns the shell and placement; widgets keep registering as they do now, so instances add/remove without touching the frame.
+- **Summary before detail** — headline numbers and state up top; tables and history below. State shows as form (pills, marks), not just text.
+
+---
+
+## 2. The shell — persistent frame
+
+One shell wraps every page, replacing both the header text-link stack and the per-page sticky chip nav.
+
+```
+┌──────┬────────────────────────────────┐
+│ LOGO │  top bar: title · search · user │
+│ ──── ├────────────────────────────────┤
+│ Home │  ┌─────┐┌─────┐┌─────┐┌─────┐   │
+│ Work │  │stat ││stat ││stat ││stat │   │
+│ Stnd │  └─────┘└─────┘└─────┘└─────┘   │
+│ Achv │  ┌────────────┐┌────────────┐   │
+│ Lead │  │  card      ││  card      │   │
+│ Docs │  └────────────┘└────────────┘   │
+│ Sett │  ┌──────────────────────────┐   │
+│ Admin│  │  table / main content    │   │
+│      │  └──────────────────────────┘   │
+└──────┴────────────────────────────────┘
+```
+
+| Region | Component type | Placement | Size | Behaviour |
+|---|---|---|---|---|
+| **Sidebar** | Vertical nav rail + brand mark | Fixed left, full height | 240px → 64px rail → drawer | 64px icon rail <1024, off-canvas drawer <768. Active item marked with accent inset. |
+| **Top bar** | Context bar: page title, search, notifications, user menu | Fixed top of content column | height 56px | Sticky. Holds the user chip (today in the header welcome line) + logout. |
+| **Content** | Scrollable view region | Right of sidebar, below top bar | max 1120px, gutter 24–32 | Only region that scrolls. One view at a time; centers past max. |
+| **Footer** | Minimal meta line | End of content flow | auto | Reduced to sign-out + instance name; no lore. |
+
+> **Seam preserved.** The shell is chrome only. The hall-widget registry (`dom-utils.js` · `contributeHallWidget`) and the `/api/gds/*` reads are unchanged — widgets mount into view containers instead of one `<main>`.
+
+---
+
+## 3. Navigation model — where the sidebar sends you
+
+Seven primary destinations plus a gated Admin group. Today's eleven scrolls collapse onto **Home, Standing, Achievements, Leaderboard**; the separate pages become sidebar entries.
+
+| Nav entry | Absorbs (today) | Type | Gate |
+|---|---|---|---|
+| **Home** | Welcome, Path (onboarding), Goals, quick stats, recent Works snippet | Dashboard view | signed-in |
+| **Work** | Work Board (WIP, Claimable, History) | Full page | signed-in |
+| **Standing** | Profile, Karma, Acclaim, Works, Marks, Curve, Bounty | Sectioned page | signed-in |
+| **Achievements** | Honours (laurel grid) | Grid view | signed-in |
+| **Leaderboard** | Roll of the Foremost | Table view | signed-in |
+| **Docs** | Primer, Diagrams/maps, Repo Atlas | Doc pages + TOC | signed-in |
+| **Settings** | Settings (all panels) | Sub-nav + panels | signed-in |
+| **Admin ▾** | Watch, Harbor, Gate | Grouped, collapsed | **Archon only** |
+
+> Rank/permission gating is **unchanged** — Xenos still don't see Work until graduation; Admin only unhides at `rank=archon`. The redesign moves *where* those links render (into the sidebar), not *whether* they gate.
+
+---
+
+## 4. Surface · Home — the landing dashboard
+
+Light and glanceable: a stat row, then a two-column band, then a compact recent-work list. Onboarding/welcome float above for pre-graduation members.
+
+| Component | Type | Placement | Size |
+|---|---|---|---|
+| Welcome / onboarding | Dismissable banner | Top, above stats | full-width · collapsible |
+| Quick stats | Stat-tile row (4) | Below banner | grid auto-fit · min 200px · h ~88 |
+| Standing summary | Card w/ link-out | Left of band | 50% · ≥320px |
+| Goals | Card / list | Right of band | 50% · ≥320px |
+| Recent work | Compact data table | Full-width, below band | 5 rows · row 44 |
+
+---
+
+## 5. Surface · Standing — everything about one member
+
+The heaviest consolidation: seven of today's scrolls become one page with an in-page section rail so it stays scannable.
+
+| Component | Type | Placement | Size |
+|---|---|---|---|
+| Profile header | Identity band (avatar, name, rank, key numbers) | Top, full-width | full · h ~120 |
+| Section rail | In-page anchor nav | Left, sticky | 150–180px |
+| Works | Filter bar + data table + pager | Panel 1 | fill · filters wrap |
+| Curve | Headline + metric grid + kind breakdown | Panel 2 | metrics auto-fit min 180 |
+| Marks / Karma / Acclaim | Ledger tables | Panels 3–5 | row 44 · sticky head |
+| Bounty | Reference table (reward schedule) | Panel 6 | compact |
+
+> On narrow viewports the in-page rail collapses to a horizontal chip strip — reusing the pattern the old sticky chip nav established.
+
+---
+
+## 6. Surface · Work — the Work Board
+
+Kept close to today's three-section structure (in-progress, claimable, history), reframed as filterable tables inside the shell.
+
+| Component | Type | Placement | Size |
+|---|---|---|---|
+| Board header | Count summary + filter bar | Top | full · filters wrap |
+| In progress | Data table (grouped) | Primary | full · row 44 |
+| Claimable | Data table w/ claim action | Below WIP | full · row 44 |
+| History | Collapsed table | Bottom | expandable |
+| Gate strip | Archon-only banner | Top when present | Archon |
+
+---
+
+## 7. Surface · Settings — grouped panels
+
+Settings has the most sections today (~15: connections, dev box, box app, craft, display name, wandering, render, art key, CLI, voices, sounds, event sounds…). It gets its own left sub-nav so each group is a focused panel.
+
+| Component | Type | Placement | Size |
+|---|---|---|---|
+| Settings sub-nav | Vertical group list | Left of panel | 170–200px |
+| Active panel | Grouped form / fields | Fill | max 720px reading col |
+| Voices | Data table (per-skill voice) | Within its panel | full · row 44 |
+| Panel footer | Save / action row | Bottom of panel | sticky-optional |
+
+> The exact grouping of the ~15 sections into ~6–7 sub-nav panels is an open question (§14). The placement pattern (sub-nav + one panel) holds regardless.
+
+---
+
+## 8. Surfaces · Docs · Achievements · Leaderboard — the lighter views
+
+- **Docs** — Primer already has a TOC aside; formalize it. Left TOC (200px, sticky) + centered reading column (max 68ch). Diagrams and Repo Atlas are sibling entries under Docs.
+- **Achievements** — the 8-laurel honours grid, kept as a grid: `auto-fill minmax(220px,1fr)`. Held vs. unearned distinguished by state, not a separate list. Full content width.
+- **Leaderboard** — full-width data table (place · member · rank · credits · karma), sortable headers preserved, pager below. Row height 44, sticky header on scroll.
+
+---
+
+## 9. Component taxonomy — the building blocks (types, not skins)
+
+The whole surface is composed from a small, reused kit. Fixing this list is most of the scope.
+
+| Block | Used for | Default size / rule |
+|---|---|---|
+| **App shell** | Sidebar + top bar + content frame | 240 / 56 / max 1120 |
+| **Nav rail item** | Sidebar + in-page section navs | h 36 · active accent inset |
+| **Stat tile** | Headline numbers (credits, shipped, karma, rank) | min 200 · h ~88 · tabular-nums |
+| **Card** | Grouped content (profile, goals, summaries) | radius 10 · pad 18–20 · hairline |
+| **Data table (ledger)** | Works, karma, acclaim, marks, leaderboard, voices | row 44 · sticky head · x-scroll wrap |
+| **Filter bar** | Works / Work Board filtering | wrap · label+select ~200 |
+| **Pager** | Long tables | prev · range · next |
+| **Badge grid** | Achievements / honours | auto-fill minmax(220,1fr) |
+| **Metric grid** | Dev curve | auto-fit minmax(180,1fr) |
+| **Banner** | Welcome, onboarding, Archon gate | full · dismissable/collapsible |
+| **Status pill / mark** | State (rank, grade, in/out) | h 20 · form-encoded state |
+| **Reading column** | Docs / primer | max 68ch · TOC 200 |
+
+---
+
+## 10. Sizing & responsive system — one scale, four breakpoints
+
+**Tokens**
+
+| Token | Value |
+|---|---|
+| Space scale | 4 · 8 · 12 · 16 · 24 · 32 · 48 |
+| Sidebar width | 240 → 64 → drawer |
+| Top bar height | 56 |
+| Content max-width | 1120 |
+| Reading column | ≤ 68ch |
+| Card radius / pad | 10 / 18–20 |
+| Table row height | 44 |
+| Stat tile min | 200 |
+
+**Breakpoints**
+
+| ≤ px | What changes |
+|---|---|
+| 1280 | Content stops growing; centers |
+| 1024 | Sidebar → 64px icon rail; 4→2 tile columns |
+| 768 | Sidebar → off-canvas drawer; two-col bands stack; in-page rails → chip strips |
+| 480 | Single column; tables scroll in their wrappers; filter bars stack |
+
+---
+
+## 11. Voice neutralization — themed → vanilla default
+
+Not layout, but it rides along. Most of this already flows through the brand pack (`brand-apply.js`, `copy.hallName`, `currency-label`) — neutralizing means shipping a neutral default pack **and** de-loring the hardcoded strings (ties to **idea [#351](https://example.com/builders#/idea/351)**, auth pages hardcoding OTB lore).
+
+| Today (themed) | Vanilla default | Source |
+|---|---|---|
+| "The Builders' Hall" · "chronicles of the city" epigraph | "Builders" · no epigraph | brand pack + markup |
+| "scroll" (section) | card / panel | markup + CSS class |
+| "Thy Standing in the City" | Standing / Profile | markup |
+| drachmae | credits (`currency-label`) | brand pack (already) |
+| Honours / laurels | Achievements | markup |
+| "Works Wrought by Thy Hand" | Your work | markup |
+| "Marks of the Inspector" | Reviews / quality marks | markup |
+| "Roll of the Foremost" | Leaderboard | markup |
+| "leave the hall" | Sign out | markup |
+| citizen | member / builder | markup + brand pack |
+| Xenos / Thetes / Metic / Archon | *rank names — deeper copy decision, see §14* | brand pack + access control |
+
+---
+
+## 12. Scope boundaries — in · deferred · out
+
+**In scope**
+- App shell (sidebar, top bar, content)
+- Home dashboard
+- Standing, Work, Achievements, Leaderboard, Settings, Docs layout
+- Component taxonomy + sizing system
+- Responsive behaviour
+- Neutral default voice
+
+**Deferred**
+- Archon pages — Watch, Harbor, Gate (inherit shell only; internal layout unchanged)
+- Rank-name copy decision
+- Public apex landing page (separate surface)
+
+**Out of scope**
+- Final colour / typography / visual identity
+- Exact copy wording
+- API / data-model changes
+- The `bongos-app` desktop tool (separate product)
+
+---
+
+## 13. Implementation seams — what the redesign must not break
+
+The hall has hard architectural constraints (see `modules/hall-ui/CLAUDE.md`). Placement changes are cheap only if they respect these.
+
+- **Widget registry is the source of truth.** A fitness check (`scripts/gds/fitness.js checkHallSectionRegistry`) reds the build if a `<section class="scroll">` is hardcoded into `<main>`. Views must mount registered widgets, not inline them.
+- **No framework, no build step.** Static HTML/CSS/JS polling `/api/gds/*`. The shell is hand-rolled CSS + a small amount of JS — no framework may be introduced.
+- **Dedicated serving block.** `src/bongos/serve-internal.js` serves this from `BUILDERS_DIR` with the subdomain rewrite shim, canonical redirects, page gates, and asset-stamping. New assets must carry the content-hash `?v=` stamp.
+- **Server-side gates stay authoritative.** Hiding a sidebar item is cosmetic; `requireArchonPage` and the sign-in redirects remain the real access control.
+- **Brand pack drives copy.** Neutralizing voice = a neutral default pack + removing hardcoded lore, not English strings baked into markup.
+- **Module-contributed widgets keep working.** The shell must give a stable mount point so a module's `hall-widget.js` lands in the right view (`injectModuleHallWidgets` seam).
+
+---
+
+## 14. Open questions — decide before build
+
+1. **Sidebar vs. top nav** as the primary — this scope assumes a left sidebar. Confirm before locking the shell.
+2. **Settings grouping** — the ~15 sections need a final grouping into ~6–7 sub-nav panels.
+3. **Standing consolidation depth** — one page with an in-page rail, or should Curve / Bounty split off?
+4. **Rank vocabulary** — keep Xenos/Thetes/Metic/Archon, or neutralize to plain tiers? Touches access-control copy, so flagged separately.
+5. **Where module hall-widgets land** in the new view structure (Home vs. their own view).
+6. **Desktop-first vs. mobile-usage** — how much the drawer/mobile path matters for the builder audience.

package/docs/design/world-map-scroll.md

@@ -0,0 +1,41 @@
+# World map — the "Sealed Ruins Chart" (diegetic artifact, V2)
+
+- **Task:** [#648](https://example.com/builders#/task/648) (V2 · product). Promoted from idea_inbox [#169](https://example.com/builders#/idea/169) (builder 25 art/design brief, 2026-06-04).
+- **Date:** 2026-06-18
+- **Status:** Art + design spec ready. Two follow-ups it implies are separate tasks: the **diegetic-item mechanic** (engineering) and **tile generation** (waits on the palette swap, [#640](https://example.com/builders#/task/640)/[ADR 0044](../adr/0044-mediterranean-palette-replacement.md)). See *Follow-ups* below.
+
+## Concept
+
+The world map is **not a UI overlay or menu** — it is a **diegetic in-game artifact**: an ancient sealed chart the player *discovers*. This reframes navigation from a game mechanic into a story beat. The in-world item name is the **"Sealed Ruins Chart"** — "sealed" is load-bearing: the map is a mystery; not everything is visible from the start.
+
+> Reference concept art (builder-25 planning input): `art/references/concept-art-original/world-map/Map Item Pop Up Concept.webp` + `Shipping container Concept.png`. **NB:** these planning images are not committed to the repo (the `art/references/concept-art-original/` tree is empty here); this written spec is the durable, self-contained source.
+
+## Behaviour (the "diegetic" part — engineering follow-up, not this art task)
+
+- The player does **not** open a menu. They find / are given the scroll — an inventory item, like the FireRed Town Map received from a character.
+- Examining it plays an **unroll animation**.
+- It is **progressive / fog-of-war**: sealed areas begin as blank parchment and fill in as the player explores. (This is the "sealed" mystery made mechanical.)
+
+## Scroll art spec (pixel art)
+
+- **Rollers (top + bottom):** dark mahogany brown, visible wood grain (2–3 horizontal pixel lines per plank); cylindrical implied by a lighter highlight strip along the top edge.
+- **Corner accents:** round emerald-green gemstone insets, 8×8px each, single light highlight pixel upper-left.
+- **Parchment:** aged warm tan, **not uniform** — subtle darker age/wear patches; slight edge vignette.
+- **Title banner:** a rectangular banner at the top, slightly darker parchment, **"SEALED RUINS CHART"** in a serif pixel font (dark brown, not black).
+- **Footer:** bottom roller repeats the title left + right with a centred **emblem** between — a 32×32 pixel creature (dragon / sea-monster), dark-outline style.
+
+### Map surface — the swirling currents (what makes it feel ancient)
+The parchment is densely covered in hand-drawn-style arrows + curved flowing lines — **ocean-current / wind notations**, the language of old nautical charts (NOT paths):
+- thin 1px dark-brown curved, directional lines; arrow tips = simple 2–3px chevrons;
+- density ≈ one arrow/curve segment per 16×16 area over **sea**; **land** areas sparser;
+- this texture — organic, dense, directional — is what reads as *ancient + discovered*, not *designed*.
+
+## Colour note (palette)
+The hexes in the source brief (mahogany, emerald, #D4A96A parchment) are **targets, not literals**: when generated, every pixel quantizes to the locked 64-colour palette — and that palette is being **replaced** ([#640](https://example.com/builders#/task/640) / [ADR 0044](../adr/0044-mediterranean-palette-replacement.md)). The replacement must carry warm-tan / mahogany / emerald steps for this artifact; flag if it doesn't. This is a UI/item artifact (not a world ground tile), so it is less palette-constrained than terrain, but it should still read in-world.
+
+## Mood target
+The player should feel they found something they were **not supposed to find** — a real object from another time, not a game menu. First unroll = one of the most memorable moments in the game.
+
+## Follow-ups (separate tasks, not this art spec)
+1. **Diegetic-item mechanic** (engineering): inventory item + examine→unroll animation + progressive fog-of-war reveal keyed to discovered areas. File when the inventory/item system exists (relates to the V3 purchase-loop / bag work, e.g. [#635](https://example.com/builders#/task/635)).
+2. **Scroll tile/sprite generation** (art pipeline): produce the scroll frame + parchment + emblem assets — **after** the palette swap ([#640](https://example.com/builders#/task/640)) so it isn't re-quantized + redone.

package/docs/design-contract.md

@@ -0,0 +1,320 @@
+# Design contract — neutral adapter interface
+
+**Status:** Accepted · authored by [task 1377](https://example.com/builders#/task/1377) · governed by [ADR 0081](adr/<redacted>.md)
+
+The repo is the single source of truth for design. Every design tool is a swappable adapter that reads from and writes to this contract — it does not own the source. This file is the contract every adapter must conform to. The minimal validator (`scripts/gds/validate-design.js`) enforces the machine-checkable parts.
+
+---
+
+## 1. Design tokens
+
+### 1.1 What tokens are
+
+Design tokens are the atomic design decisions an instance publishes as named values (colors, type ramps, spacing, motion). They are the presentation layer that adapters read when importing a design system into a tool, and the target a tool change must produce when exporting back to the repo.
+
+### 1.2 File locations
+
+| File | Role |
+|---|---|
+| `config/design-tokens.neutral.json` | Baseline — every instance resolves over this |
+| `config/design-tokens.json` | Instance pack — overrides the baseline (absent = baseline only) |
+| `config/design-tokens.schema.json` | JSON Schema for both files |
+
+Resolution order (highest wins):
+
+```
+env override → config/design-tokens.json → config/design-tokens.neutral.json
+```
+
+The validator merges both files (deep-merge, instance wins) and validates the result against the schema. An absent instance pack is valid — the neutral baseline is always present.
+
+### 1.3 Relationship to config/branding.json
+
+`config/branding.json` carries *identity* (product name, domains, currency, tracks). Design tokens carry *presentation* (colors, type, spacing). The two files are siblings; neither owns the other. Where both define overlapping values (e.g. `branding.json theme.ui.colors` and `design-tokens.json colors`), **design-tokens.json is authoritative at render time**. The `src/branding.js` resolver will be updated (task 1377) to expose resolved tokens alongside identity — adapters use `branding.resolveDesignTokens()`.
+
+### 1.4 Token schema overview
+
+See `config/design-tokens.schema.json` for the full machine-readable schema. Summary:
+
+| Group | Required | Description |
+|---|---|---|
+| `colors` | yes | Surface + semantic colors (`bg`, `bgCard`, `ink`, `accent`, …) |
+| `fonts` | yes | CSS font-family stacks (`display`, `body`) + optional `mono` + `links` (external stylesheets) |
+| `scale` | no | Spacing / sizing scale (`xs` … `2xl`, CSS lengths) |
+| `radius` | no | Border-radius tokens (`sm`, `md`, `lg`, `pill`) |
+| `motion` | no | Duration + easing tokens (`fast`, `normal`, `slow`, `easing`) |
+
+All color values are CSS color strings (hex, `rgb()`, `hsl()`, `color-mix()`, etc.). All length values are valid CSS lengths (`px`, `rem`, `em`).
+
+### 1.5 Extending tokens
+
+An instance may add new tokens inside any group — the schema uses `additionalProperties: false` on the top-level groups to prevent misspellings of the canonical keys, but accepts that an instance may grow additional groups over time. Add a new group by proposing a schema addition via a GDS task before committing it to the instance pack.
+
+---
+
+## 2. Component code and assets
+
+### 2.1 Component code
+
+UI components live under `src/ui/<surface>/`. A surface is any discrete piece of UI that can be independently authored and reviewed — a page, a panel, a design-system library.
+
+```
+src/ui/
+  <surface>/           e.g. builders-hall, landing, status-dashboard
+    index.js           entry point (may re-export sub-components)
+    <Component>.js     sub-components (no subdirectory required for flat surfaces)
+    <Component>.css    co-located styles (optional; token refs use CSS vars)
+    CLAUDE.md          surface-scoped context (required for surfaces > ~200 LoC)
+```
+
+Rules:
+- Component code imports tokens as CSS custom properties, resolved from design tokens at boot. It must not hardcode token values.
+- A surface directory is the unit a design adapter targets — an adapter imports or exports an entire surface, not individual files.
+- Generated code (output of a Claude Design or Figma adapter run) lands in the same directory as hand-written code; origin is tracked in `config/design-sources.json`, not in file naming.
+
+### 2.2 Exported assets
+
+Assets that cannot round-trip as code (raster images, SVG illustrations, icon sets, video) live under `assets/ui/<surface>/`.
+
+```
+assets/ui/
+  <surface>/
+    <filename>.<ext>   SVG, PNG, WEBP, MP4, …
+```
+
+Rules:
+- Every file in `assets/ui/` is a **committed binary or SVG** — generated by a tool and committed; it is not re-generated on deploy.
+- Adapters that emit assets (e.g. Figma exporting SVG icons) write to this directory.
+- Asset files are referenced from component code by relative import or by the static-asset path — never by absolute URL.
+
+### 2.3 Surface categories
+
+| Category | Code location | Asset location | Round-trip mode |
+|---|---|---|---|
+| Structured UI (components, layouts, design-system) | `src/ui/<surface>/` | — | Code-canonical (default) |
+| Icon / illustration set | — | `assets/ui/<surface>/` | Asset |
+| Freeform canvas art | — | `assets/ui/<surface>/` | Asset |
+| Pixel-art game tiles | see `art/` pipeline | — | Art pipeline (not this contract) |
+
+Pixel-art game tiles (world tiles, characters, objects) are out of scope for this contract — they are governed by the `art/` pipeline and [ADR 0088](adr/<redacted>.md).
+
+---
+
+## 3. Design source pointer
+
+### 3.1 Purpose
+
+The design source pointer records which tool authored a surface and where its editable source lives. It is the metadata layer that lets an adapter know whether it is the authoritative tool for a given surface, and lets a human know where to open a surface to make a manual edit.
+
+### 3.2 File: config/design-sources.json
+
+```json
+{
+  "surfaces": {
+    "<surface-id>": {
+      "tool": "claude-design | figma | hand | asset",
+      "sourceUrl": "https://…",
+      "lastSyncedAt": "2026-06-21T14:00:00.000Z",
+      "notes": "optional free-text"
+    }
+  }
+}
+```
+
+Field definitions:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `tool` | enum | yes | `claude-design` — authored by Claude Design; `figma` — authored in Figma; `hand` — written by a builder directly; `asset` — binary/SVG asset, no round-trip source |
+| `sourceUrl` | string (URI) | when tool ≠ hand, asset | URL to the editable source in the design tool |
+| `lastSyncedAt` | string (ISO 8601) | no | Written by the adapter after each import or export round-trip |
+| `notes` | string | no | Human commentary |
+
+### 3.3 Authoring rules
+
+- A surface absent from `design-sources.json` is implicitly `tool: "hand"` — no entry is required for hand-written UI.
+- When an adapter creates or updates a surface, it must upsert its entry in `design-sources.json` (update `lastSyncedAt`).
+- A surface may only have **one** `tool` at a time. Changing tool (e.g. migrating a surface from `claude-design` to `figma`) requires updating the entry and ensuring the new tool's adapter has imported the current repo state before the first export.
+- `tool: "asset"` surfaces have no `sourceUrl` — they are committed artifacts with no live design-tool source.
+
+### 3.4 Code-canonical vs. Figma-canonical
+
+Code-canonical is the **default**: the repo (committed code + tokens) is authoritative; a Figma file is a downstream view. The Figma adapter syncs *from* the repo into Figma before a designer opens it, and syncs changes *back* as a committed diff.
+
+A surface may be declared **Figma-canonical** as an explicit exception — set `"figmaCanonical": true` in its entry. In this mode the Figma file is the source; the adapter's export direction generates code/tokens from Figma. The honest cost: round-trip fidelity is limited to what Code Connect / the Figma MCP can extract; arbitrary canvas art becomes an asset, not code.
+
+Figma-canonical is appropriate for design-system foundations that a dedicated designer actively iterates on in Figma. All other surfaces default to code-canonical.
+
+---
+
+## 4. Adapter interface
+
+Each design tool that integrates with this contract must provide an adapter module. An adapter lives at:
+
+```
+src/ui/adapters/<id>/index.js   (e.g. claude-design, figma)
+```
+
+### 4.1 Required exports
+
+```js
+module.exports = {
+  // Stable identifier. Must match the `tool` enum value in design-sources.json.
+  id: 'claude-design',   // or 'figma', etc.
+
+  // Direction 1: repo → tool.
+  // Export the repo's current design system INTO the tool so the tool has
+  // up-to-date context before a designer opens it.
+  async import(opts) { /* ImportOpts → ImportResult */ },
+
+  // Direction 2: tool → repo.
+  // Receive a tool's output (HTML/CSS/JS code from Claude Design, or a Figma
+  // MCP diff from Figma) and emit it as a committed-ready diff.
+  async export(opts) { /* ExportOpts → ExportResult */ },
+};
+```
+
+### 4.2 ImportOpts
+
+```ts
+{
+  repoRoot: string;           // absolute path to the repo root
+  tokens: <redacted>;     // branding.resolveDesignTokens() output
+  surfaces: SurfaceManifest[]; // list of surfaces in src/ui/ + assets/ui/
+  targetSurface?: string;     // if set, import only this surface; else all
+}
+```
+
+`ResolvedTokens` is the deep-merged `design-tokens.neutral.json + design-tokens.json` result, validated against the schema.
+
+`SurfaceManifest`:
+```ts
+{
+  id: string;       // surface directory name
+  path: string;     // absolute path to src/ui/<id>/
+  tool?: string;    // current tool from design-sources.json (undefined = 'hand')
+  sourceUrl?: string;
+}
+```
+
+### 4.3 ImportResult
+
+```ts
+{
+  toolUrl?: string;   // URL where the tool opened or created the design project
+  surfaceIds: string[]; // surfaces successfully imported
+  summary: string;    // human-readable log line
+}
+```
+
+### 4.4 ExportOpts
+
+```ts
+{
+  repoRoot: string;         // absolute path to the repo root
+  surfaceId: string;        // which surface this export targets
+  toolOutput: unknown;      // adapter-specific; see per-adapter docs
+  taskId?: string;          // GDS task to associate the commit with
+  authorName?: string;      // git author name (defaults to GDS builder identity)
+}
+```
+
+`toolOutput` is intentionally `unknown` at the contract level — each adapter interprets its own tool's output format. Claude Design hands over HTML/CSS/JS strings; the Figma adapter hands over a Figma MCP snapshot or Code Connect output.
+
+### 4.5 ExportResult
+
+```ts
+{
+  filePaths: string[];    // repo-relative paths written by this export
+  diff: string;           // unified diff (for grader + PR description)
+  commitMessage: string;  // suggested commit message
+  designSourcesUpdated: boolean; // whether config/design-sources.json was updated
+  warnings: string[];     // non-fatal issues (e.g. tokens that had no match)
+}
+```
+
+### 4.6 Adapter registration
+
+Adapters are discovered by the design subsystem at runtime. No static registry — the loader walks `src/ui/adapters/*/index.js` and requires each, verifying the `id` field is present. A missing or broken adapter is a non-fatal warning; the unaffected adapters continue loading.
+
+### 4.7 Adapter error contract
+
+- `import()` must throw a descriptive `Error` if it cannot reach the tool or the tool rejects the import.
+- `export()` must throw if `toolOutput` is missing or malformed (validated by the adapter before writing files).
+- Neither method may write files outside `src/ui/<surfaceId>/`, `assets/ui/<surfaceId>/`, or `config/design-sources.json`. A path-escape attempt must throw.
+- Both methods must be idempotent: running the same call twice must produce the same repo state (adapters check current file content before overwriting).
+
+---
+
+## 5. CSS variable injection at runtime
+
+The design system renders as CSS custom properties injected into the document at boot, consistent with the existing `themeMarkup` pattern in `src/branding.js`. The naming convention:
+
+```css
+--dt-color-bg:          /* tokens.colors.bg */
+--dt-color-bg-card:     /* tokens.colors.bgCard */
+--dt-color-ink:         /* tokens.colors.ink */
+--dt-color-accent:      /* tokens.colors.accent */
+/* … etc., camelCase → kebab-case with --dt- prefix */
+
+--dt-font-display:      /* tokens.fonts.display */
+--dt-font-body:         /* tokens.fonts.body */
+--dt-font-mono:         /* tokens.fonts.mono */
+
+--dt-scale-xs:          /* tokens.scale.xs */
+/* … */
+
+--dt-radius-md:         /* tokens.radius.md */
+/* … */
+
+--dt-motion-normal:     /* tokens.motion.normal */
+--dt-motion-easing:     /* tokens.motion.easing */
+/* … */
+```
+
+Component code uses these variables. Adapters generating CSS must use them; hardcoded hex values in generated component code are a validator warning.
+
+The `--dt-` prefix is reserved for this design system. Adapters must not emit CSS variables with this prefix whose names conflict with the canonical token names.
+
+---
+
+## 6. Validator
+
+`scripts/gds/validate-design.js` is the minimal validator for this contract. It checks:
+
+1. `config/design-tokens.neutral.json` exists and validates against the schema.
+2. If `config/design-tokens.json` exists, it validates against the schema.
+3. The deep-merged token set satisfies all required fields.
+4. `config/design-sources.json` is valid JSON and every surface entry has a `tool` field from the allowed enum.
+5. Every `sourceUrl` in `design-sources.json` is a valid URI string.
+6. Every `surfaceId` key in `design-sources.json` has a matching directory under `src/ui/` or `assets/ui/` (if any such directory exists — the file may precede the directories for a new instance).
+7. If `src/ui/adapters/` exists, each adapter directory has an `index.js` that exports `id`, `import`, and `export`.
+
+Usage:
+
+```
+node scripts/gds/validate-design.js           # exits 0 on pass, 1 on failure
+node scripts/gds/validate-design.js --json    # machine-readable report
+node scripts/gds/validate-design.js --strict  # fail on warnings too
+```
+
+The validator is hooked into `scripts/gds/fitness.js` as an opt-in check (enabled once the first adapter is committed — task 1378 or 1379).
+
+---
+
+## 7. What adapters must NOT do
+
+- Write outside `src/ui/<surfaceId>/`, `assets/ui/<surfaceId>/`, or `config/design-sources.json`.
+- Read or modify `config/branding.json` — tokens are the design layer; identity is the branding layer.
+- Contact external services from within `export()` — the tool interaction is upstream; `export()` receives already-resolved output.
+- Embed tool-specific metadata in component code (no "generated by Figma" comments in `.js` files — that belongs in `design-sources.json`).
+- Override `--dt-*` CSS variables in component-level style blocks — components consume them, they do not redefine them.
+
+---
+
+## 8. Adding a new adapter
+
+1. Create `src/ui/adapters/<id>/index.js` exporting `{ id, import, export }`.
+2. Add a `<surface-id>` entry to `config/design-sources.json` with `"tool": "<id>"`.
+3. Write a task for the adapter (it unblocks from [task 1377](https://example.com/builders#/task/1377)) and ship it under a claimed GDS task.
+4. The validator discovers the adapter automatically on the next run.