diff --git a/docs/internal/design/oobe/CHECKLIST.md b/docs/internal/design/oobe/CHECKLIST.md index 77570a971e5..7c53a6044cb 100644 --- a/docs/internal/design/oobe/CHECKLIST.md +++ b/docs/internal/design/oobe/CHECKLIST.md @@ -12,8 +12,8 @@ Legend: `[ ]` not started · `[~]` in progress · `[x]` done. Every code box imp - [x] Branch merged up to date with `main` (post-#6918 family-folder reorg); the `AUTOMATION-TASKS-CONTRACT.md` moved into `docs/design/oobe/`. - [ ] **Carousel gate (D-F5)** — *deferred to the implementation PR:* when the carousel is (re)built, it must not return `MOCK_COMPLETED_TASKS` to real users (behind DEV/flag or an empty real projection). - [x] Contract reconciled to the post-#6918 family-folder names (`ironclaw_event_log` + `ironclaw_event_store` under `crates/events/`; facade `RebornServicesApi` in `ironclaw_assistant`; `src/webui_v2/` confirmed current). -- [ ] Decision round #1 recorded (PROPOSAL §10 items 2, 4, 5). -- [ ] (If approved) first-draft `DESIGN.md` seeded with v2 tokens + card taxonomy (D-F6). +- [ ] Decision round #1 recorded (PROPOSAL §10 items 2 and 4; item 5 settled 2026-08-21). +- [x] D-F6 settled — `DESIGN.md`, tokens and the workbench are owned by [`docs/internal/reborn/design-system/`](../../reborn/design-system/README.md); no local seed is landed here (PROPOSAL §5.6). ## F1 — Automation-task backend (D-F1) @@ -52,10 +52,12 @@ Legend: `[ ]` not started · `[~]` in progress · `[x]` done. Every code box imp - [ ] Carousel gate (D-F5) retired — projection is the source of truth. - [ ] Foundational demoable end-to-end on a fresh account. -## F5 — Design track (D-F6) — optional, parallel +## F5 — Design track pilot (D-F6) — optional, parallel -- [ ] `DESIGN.md` finalized (principles · theming · typography · a11y floors · card taxonomy · REJECT list). -- [ ] (Optional) Storybook workbench for card / action-bar / drawer / mode-pill: smoke play test + token/CSS check + one story per state. +*✎ 2026-08-21: `DESIGN.md`, tokens and the workbench are owned by [`docs/internal/reborn/design-system/`](../../reborn/design-system/README.md) (PR #7257) — OOBE contributes the pilot, not the governance (PROPOSAL §5.6).* + +- [ ] OOBE card taxonomy + a11y floors contributed **into** that program's `DESIGN.md` (Phase-2 work, issue #7042 under Epic #7781) — no parallel constitution seeded here. +- [ ] Card / action-bar / drawer / mode-pill stories added to the Phase-1 catalog (#7750) once it lands: smoke play test + token/CSS check + one story per state. - [ ] Design validation gate passes on the OOBE components (1:1 parity vs. mockup; tokens; light+dark; a11y). ## Foundational exit gate diff --git a/docs/internal/design/oobe/PLAN.md b/docs/internal/design/oobe/PLAN.md index 4a3d8b28cda..74e8f718686 100644 --- a/docs/internal/design/oobe/PLAN.md +++ b/docs/internal/design/oobe/PLAN.md @@ -18,10 +18,10 @@ 1. **D-F5 carousel gate** ⚠ — the guard for when the carousel returns. Gate the landing carousel behind DEV / a feature flag (or an empty-projection read) so it never exposes mock "done for you" cards to real users. The earlier prototype's *ungated* mock path is exactly what got it rolled back — the first implementation PR that re-adds the carousel must ship it gated. 2. **Contract reconciliation — ✅ done in this PR.** [AUTOMATION-TASKS-CONTRACT.md](AUTOMATION-TASKS-CONTRACT.md) now reflects the post-#6918 family-folder names: event log `ironclaw_event_log` + durable store `ironclaw_event_store` under `crates/events/`; facade `RebornServicesApi` in `crates/product/ironclaw_assistant`; routes in `crates/product/ironclaw_webui/src/webui_v2/` (confirmed current). Docs-only. -3. **Decision round #1** `[decision]` — close PROPOSAL §10 items 2 (suggestion producer), 4 (carousel gating), 5 (DESIGN.md pilot). One thread each. -4. **(Optional) D-F6 seed** — land a first-draft `DESIGN.md` capturing the v2 token system + card taxonomy, if the pilot is approved. Docs-only, unblocks design review of later phases. +3. **Decision round #1** `[decision]` — close PROPOSAL §10 items 2 (suggestion producer) and 4 (carousel gating). One thread each. *(Item 5, the DESIGN.md pilot, is settled — see below.)* +4. **D-F6 — nothing to seed here.** `DESIGN.md` and the workbench are owned by [`docs/internal/reborn/design-system/`](../../reborn/design-system/README.md) (PROPOSAL §5.6); OOBE's contribution is its card taxonomy + a11y floors, offered into that program's `DESIGN.md` (the Phase-2 work tracked by issue #7042, under Epic #7781) rather than a local draft. -*Exit criteria: the carousel-gate approach decided; contract reconciled (done); §10.2/§10.4/§10.5 decided. (Implementation is landing behind an off-by-default flag; the docs remain mergeable.)* +*Exit criteria: the carousel-gate approach decided; contract reconciled (done); §10.2/§10.4 decided (§10.5 settled — governance owned elsewhere). (Implementation is landing behind an off-by-default flag; the docs remain mergeable.)* ## Phase F1 — Automation-task backend (D-F1) — the leverage phase @@ -53,12 +53,12 @@ - Add the **first-run onboarding CUJ** (PROPOSAL §8.4) to the regression baseline: fresh user → cards → connect → approve → card flips to done → appears in `/automations`. - **Milestone:** Foundational is feature-complete and demoable on a fresh account; the carousel gate (D-F5) is retired — the projection is the truth. -## Phase F5 — Design track productionization (D-F6) — optional, parallel +## Phase F5 — Design track pilot (D-F6) — optional, parallel -*Runs alongside F1–F4 if the pilot is approved (§10.5).* +*Runs alongside F1–F4. ✎ **2026-08-21:** `DESIGN.md`, tokens and the Storybook workbench are **not** built here — they are owned by [`docs/internal/reborn/design-system/`](../../reborn/design-system/README.md) (PR #7257; Phase 1 under Epic #7038 as PR #7750 · Phases 2–3 under Epic #7781, issue #7042 tracking the Phase-2 `DESIGN.md` work). What is left in F5 is OOBE's pilot contribution (PROPOSAL §5.6).* -- Finalize `DESIGN.md` (principles, theming, typography, a11y floors, card component taxonomy, REJECT list). -- Optionally stand up a Storybook workbench for the pure Tier-2/3 card components (card, action bar, drawer, mode pill): smoke play test + token/CSS check + one story per state (PROPOSAL §8.3). +- Contribute the OOBE card taxonomy + a11y floors **into** that program's `DESIGN.md` rather than seeding a parallel one. +- Add stories for the pure Tier-2/3 card components (card, action bar, drawer, mode pill) to the Phase-1 catalog once it lands: smoke play test + token/CSS check + one story per state (PROPOSAL §8.3). - **Milestone:** the OOBE component family is the design-governance pilot; the validation gate is enforceable on future card work. --- diff --git a/docs/internal/design/oobe/PROPOSAL.md b/docs/internal/design/oobe/PROPOSAL.md index 206a980f1e4..da5ccd2b66c 100644 --- a/docs/internal/design/oobe/PROPOSAL.md +++ b/docs/internal/design/oobe/PROPOSAL.md @@ -160,7 +160,9 @@ Each dependency states *what it needs* and *how to build it*; the PLAN sequences ### 5.6 D-F6 — DESIGN.md + design tokens (cross-cutting, APDD design track) -*Needs:* IronClaw has no root `DESIGN.md` and no component workbench; the OOBE cards are a greenfield component family — the natural pilot to seed the APDD design governance track (see the prior APDD kit evaluation, `docs/plans/apdd-governance-kit/`). *Approach:* seed a `DESIGN.md` capturing the v2 token system, theming, a11y floors, and the card component taxonomy; optionally stand up a Storybook workbench for the card/drawer/action-bar components (they are pure Tier-2/3 presentational components — ideal isolation candidates). Deferrable, but cheapest to do while the components are being productionized. +> ✎ **Governance ownership moved (2026-08-21).** The `DESIGN.md` constitution, the `--v2-*` token architecture, and the Storybook workbench are owned by the WebUI design-system program — [`docs/internal/reborn/design-system/`](../../reborn/design-system/README.md) (PR #7257; Phase 1 under Epic #7038, shipping as PR #7750 · Phases 2–3 under Epic #7781, with issue #7042 tracking the Phase-2 `DESIGN.md` governance work specifically), whose [PROPOSAL §9](../../reborn/design-system/PROPOSAL.md#9-ownership-boundary-one-canonical-governance-record) records the boundary. **D-F6 no longer stands any of that up.** What survives is its *pilot* half: the OOBE card/drawer/action-bar family is catalogued and judged **through** that system — stories in the Phase-1 catalog, conformance against the Phase-2 `DESIGN.md`. If the cards productionize before Phase 1 lands, they ship as ordinary token-driven components and their stories follow in its wake; they do not fork a second workbench. The original text below is **historical** — kept as the record of why this dependency was raised, superseded in full by the note above. + +> *Historical (pre-2026-08-21):* *Needs:* IronClaw has no root `DESIGN.md` and no component workbench; the OOBE cards are a greenfield component family — the natural pilot to seed the APDD design governance track (see the prior APDD kit evaluation, `docs/internal/apdd-governance-kit/` — [PR #7255](https://github.com/nearai/ironclaw/pull/7255), not yet on `main`). *Approach:* seed a `DESIGN.md` capturing the v2 token system, theming, a11y floors, and the card component taxonomy; optionally stand up a Storybook workbench for the card/drawer/action-bar components (they are pure Tier-2/3 presentational components — ideal isolation candidates). Deferrable, but cheapest to do while the components are being productionized. ### 5.7 D-V1 — Cold-start queued OAuth orchestration @@ -222,7 +224,7 @@ Following `.claude/rules/testing.md` (integration-first; test through the caller - **8.1 Backend (integration-first).** Each new event: persistence / replay / projection-visibility / redaction / ordering / transport-serialization tests. The projection: the cross-user isolation test (§7). Each route/facade method: a Reborn integration test through the harness asserting at a seam — not `wait_for_status(Completed)` alone. The `auto`/`bypass` gate-suppression paths: explicit privilege-escalation tests + audit-trail assertions. Modify-rerun: a test that an automated-task modify re-executes and returns fresh evidence. - **8.2 Frontend.** The prototype already ships `automation-tasks.test.ts` + VM-sandbox stubs (1032 tests green). Add: seam contract tests (the `fetch` shapes match the route DTOs), drawer state-machine tests, connect-flow wiring test (the card's connect calls the shared resolver with the right `extension_name`). -- **8.3 Design validation gate (APDD).** If D-F6 is adopted: `DESIGN.md` conformance (tokens, theming, a11y floors — contrast, focus rings, state-not-by-color-alone), 1:1 parity against the mockup, and — if Storybook is stood up — smoke play test + token/CSS check + one story per card state. +- **8.3 Design validation gate (APDD).** Judged against the design-system program's `DESIGN.md` once it lands (§5.6; Phase 2 sits under Epic #7781 and is tracked by issue #7042): `DESIGN.md` conformance (tokens, theming, a11y floors — contrast, focus rings, state-not-by-color-alone), 1:1 parity against the mockup, and — once the Phase-1 Storybook catalog lands (#7750) — smoke play test + token/CSS check + one story per card state. - **8.4 CUJ.** Add a first-run onboarding Critical User Journey (fresh user → cards appear → connect a tool → approve → card flips to done → appears in `/automations`) to the regression baseline once Foundational lands. ## 9. Risks @@ -242,14 +244,14 @@ Following `.claude/rules/testing.md` (integration-first; test through the caller 2. **[OPEN]** D-F2 suggestion producer — deterministic starter set (recommended) vs. triggers-hosted suggester vs. agent-driven? Bounds the first-run feed. 3. **[OPEN]** D-F4 `auto` semantics — exact definition/bounds of "approved task types" (per-tool, per-action, spend/impact caps)? 4. **[OPEN]** D-F5 — real projection now, or DEV/flag gate first, to unblock PR #6994? -5. **[OPEN]** D-F6 — adopt the APDD design track (DESIGN.md + tokens now, Storybook later) with the OOBE cards as pilot? +5. **[RESOLVED 2026-08-21]** D-F6 — design governance is owned by [`docs/internal/reborn/design-system/`](../../reborn/design-system/README.md) (PR #7257, §9); OOBE contributes the card family as a pilot and stands up no `DESIGN.md`, tokens, or workbench of its own (§5.6). 6. **[OPEN]** D-V5 — username-derivation precedence when several sources resolve; fallback when none. 7. **[OPEN]** Enterprise tool config — does the admin-whitelisted set surface to the user as read-only "connected by your workspace," or invisibly? ## 11. How the two reference frameworks are applied - **PR #6918 (target-architecture) framing** — this package mirrors #6918's document set: an executive **README** (overview + reviewer decisions + doc index), an evidence-backed **PROPOSAL** (this file), a sequenced **PLAN** (waves/gates/PR-sizing), and a **CHECKLIST** (definition of done). It borrows #6918's execution discipline: move-only/behavior-free PRs kept separate from semantic changes, guidance travels with the change, deletions use the un-masking discipline, and `main` stays shippable after every PR (PLAN). -- **APDD kit (product/design governance)** — this package follows the kit's **docs-first feature workflow**: spec → team review (this §10 stays open until folded in) → plan → test plan, with the binding anchors present (*Feedback & Decisions* §10, *Regression Tests* §8, and a *Critical Bug Fix Log* below per Rule 2). The **design track** (D-F6) proposes seeding `DESIGN.md` + tokens + a Storybook workbench for the new component family, exactly the kit's core design governance. The kit's evaluation for IronClaw is recorded at `docs/plans/apdd-governance-kit/`. +- **APDD kit (product/design governance)** — this package follows the kit's **docs-first feature workflow**: spec → team review (this §10 stays open until folded in) → plan → test plan, with the binding anchors present (*Feedback & Decisions* §10, *Regression Tests* §8, and a *Critical Bug Fix Log* below per Rule 2). The **design track** is not ours to seed: `DESIGN.md` + tokens + the Storybook workbench are owned by [`docs/internal/reborn/design-system/`](../../reborn/design-system/README.md) (PR #7257), and D-F6 contributes the card family as its pilot (§5.6). The kit's evaluation for IronClaw is proposed at `docs/internal/apdd-governance-kit/` ([PR #7255](https://github.com/nearai/ironclaw/pull/7255) — open, not yet on `main`). **Human-review artifact.** A self-contained visual review aid — the 5-layer integration schematic, the dependency graph, the phase timeline, and the shipped-vs-net-new map — lives in this package as [integration-review.html](integration-review.html) ([rendered preview](https://html-preview.github.io/?url=https://github.com/nearai/ironclaw/blob/feat/oobe-chat-automations/docs/design/oobe/integration-review.html)). It renders §3, §5, and §6 for reviewers who prefer the visual. diff --git a/docs/internal/design/oobe/README.md b/docs/internal/design/oobe/README.md index c519b9a1c29..3782c5f509a 100644 --- a/docs/internal/design/oobe/README.md +++ b/docs/internal/design/oobe/README.md @@ -86,7 +86,7 @@ Every dependency has an implementation approach in [PLAN.md](PLAN.md); the full - **D-F3 — Connect wiring:** route each card's connect through the shared `extension_name` resolver + existing OAuth path (no new auth path — CLAUDE.md invariant). - **D-F4 — Agent-mode persistence + gate semantics:** contract §7; `auto` is the typed generalization of `global_auto_approve`. - **D-F5 — Carousel de-risk / gating:** the current draft blocker — the landing carousel shows mock cards to *all* users; must read the real projection (empty until tasks exist). -- **D-F6 — DESIGN.md + tokens (cross-cutting):** IronClaw has no `DESIGN.md` yet; the OOBE cards are the natural pilot to seed the APDD design track. +- **D-F6 — DESIGN.md + tokens (cross-cutting):** ✎ *governance ownership moved (2026-08-21)* — `DESIGN.md`, tokens and the Storybook workbench belong to [`docs/internal/reborn/design-system/`](../../reborn/design-system/README.md) (PR #7257); OOBE contributes the card family as its **pilot** and stands up none of that itself (PROPOSAL §5.6). **Vision (additional):** - **D-V1** cold-start queued OAuth orchestration · **D-V2** reveal-animation infra (`prefers-reduced-motion`) · **D-V3** anticipatory / "no automations yet" projection states (#6993) · **D-V4** composer-docked drawer component · **D-V5** username-derivation source (open decision). @@ -97,7 +97,7 @@ Every dependency has an implementation approach in [PLAN.md](PLAN.md); the full 2. **The suggestion producer (D-F2)** — first-login trigger vs. deterministic starter set gated on connected extensions vs. an agent-driven suggester. This is the one genuinely new mechanism and the biggest open design question. (PROPOSAL §5.2) 3. **Agent-mode gate semantics (D-F4)** — `auto` skips the per-action gate for approved task *types*; confirm the typed generalization of `global_auto_approve` and its audit-trail requirements. (PROPOSAL §7) 4. **Carousel gating (D-F5)** — the merge blocker on PR #6994: real projection now, or DEV/flag gate first? (PROPOSAL §5.5) -5. **DESIGN.md pilot (D-F6)** — adopt the APDD design track here (seed `DESIGN.md`, tokens, and — later — a Storybook workbench for the card components), or defer. (PROPOSAL §8.3) +5. ~~**DESIGN.md pilot (D-F6)**~~ — *settled 2026-08-21:* design governance is owned by [`docs/internal/reborn/design-system/`](../../reborn/design-system/README.md); OOBE's part is the pilot card family, catalogued through it. (PROPOSAL §5.6, §8.3) ## How to review diff --git a/docs/internal/reborn/design-system/CHECKLIST.md b/docs/internal/reborn/design-system/CHECKLIST.md new file mode 100644 index 00000000000..f837e28a3b1 --- /dev/null +++ b/docs/internal/reborn/design-system/CHECKLIST.md @@ -0,0 +1,59 @@ +# Design System — Completion Checklist + +**Status:** Proposal, under review · **Authored against:** `origin/main` @ `d3791e0f8` · **Tracks:** three Epics — [ownership table](README.md#epic-ownership-canonical) + +**Definition of done:** when every box below is checked, the governed, agentic-first WebUI design system is fully realized. A checked box means **landed on `main`**, with the landing PR named inline. `⚠` marks a blocking prerequisite; `[decision]` marks an item gated on a named human call. + +> **Epic ownership** lives in one place: the canonical table in +> [README.md](README.md#epic-ownership-canonical). Every `Epic #NNNN` label below is a +> **link into that table**, not a restatement of it — this document holds no second copy +> of the mapping, so an ownership change is one edit, in the README. + +## WS1 — Storybook integration (Phase 1) · [Epic #7038](README.md#epic-ownership-canonical) +- [ ] Storybook 10 (`@storybook/react-vite`, pnpm) wired to `app.css` + light/dark toolbar — **Ships with #7750** +- [ ] ~33 stories in five categories (Primitives / Components / Composites / Icons / Tokens) — **#7750** +- [ ] Vitest split: `pnpm test` node-only, `pnpm test:storybook` in headless Chromium — **#7750** +- [ ] `@storybook/addon-mcp` available for agent access — **#7750** + +## WS2 — DESIGN.md governance (Phase 2) · [Epic #7781](README.md#epic-ownership-canonical) · tracked by #7042 +- [ ] `crates/product/ironclaw_webui/frontend/DESIGN.md` (M3X spec + IronClaw governance appendix) — **changeset preserved from closed #7043; fresh PR off `main`** +- [ ] Storybook `Design/Guidelines` docs page (`Design` sorts first) — **#7042** +- [ ] `.claude/rules/design-system.md` + `CLAUDE.md` Module Specs pointer + DS README link, all written as **supplements to `AGENTS.md`** — the canonical tool-neutral contract stays the entry point and the Claude files add no rule it does not carry — **#7042** +- [ ] ⚠ Merge #7750, then land the Phase-2 changeset as a fresh PR off `main` (PROPOSAL §7.6) + +## WS3 — Theme foundation & reskin (Phase 3) · [Epic #7781](README.md#epic-ownership-canonical) +- [ ] Dark-palette values derived for every token (`:root[data-theme="dark"]`) (PROPOSAL §7.3) +- [ ] WCAG AA contrast validated for all text/token pairings; `Tokens/Colors` story asserts it — invariant §3.4, carried inside the dark-palette dependency (§7.3), not owned separately +- [ ] Fonts vendored: Roboto Flex + Roboto Mono (OFL) under `/vendor/fonts` — **[decision]** Google Sans substitute (§7.4) +- [ ] M3 → `--v2-*` token *values* land in `app.css` (light + dark) +- [ ] ⚠ Token values land **before** any component restyle +- [ ] Primitives/composites reskinned against new tokens; each story + `CssCheck` + a11y green +- [ ] **Invariant 2 gap closed** (PROPOSAL §3.1) — the **345 occurrences of arbitrary pixel classes across 91 files** migrated to the type/space/radius scales and the **10 hardcoded six-digit hex values in 3 `.tsx` files** retired; `design-system/` (38 occurrences in 8 files) and the OOBE pilot card go first, and a lint or grep gate keeps the count from regrowing +- [ ] **Safeguards (§7.0)** — fonts self-hosted with a tested system-fallback stack + `font-display: swap`; token *names* unchanged (values only); the whole phase revertable by a single PR revert with no residue + +## WS4 — Agentic components & interactions (Phase 4) · [Epic #7782](README.md#epic-ownership-canonical) +- [ ] Animation approach chosen + wired behind a `prefers-reduced-motion` gate (PROPOSAL §7.5) +- [ ] MSW added for network-backed story happy-paths (PairingWebCodePanel, TeeShield) (§7.2) +- [ ] Agentic components built + catalogued (composer toolbar, FAB speed-dial, chat bubbles, agent-activity/reasoning cards, branded progress, connected button groups) — each with stories + play coverage +- [ ] **Safeguards (§7.0)** — production artifact asserted to contain neither `mockServiceWorker.js` nor an `msw` chunk, the worker generated into a Storybook-only static dir and never `frontend/public/` (§7.2); a missing handler degrades to the existing limited/error state +- [ ] **Motion kill switch (§7.5)** — one shared disabled-motion signal behind both `prefers-reduced-motion` and the app switch, read by CSS *and* every JS caller; a running spring cancels its RAF loop and writes the static end-state; a rejected dynamic motion chunk renders the static baseline; asserted by caller-level tests, not helper-level +- [ ] ⚠ Depends on WS3 tokens + +## WS5 — Information architecture (Phase 5) · [Epic #7782](README.md#epic-ownership-canonical) +- [ ] Navigation/routes/page structure reshaped — `src/app/routes.ts`, `src/pages/`, the sidebar, `src/layout/gateway-layout.tsx` (relative to `crates/product/ironclaw_webui/frontend/`) +- [ ] M3X navigation-rail pattern adopted where it fits; multi-channel parity preserved +- [ ] Critical user journeys (chat, approvals, projects, settings) verified unbroken + +## WS6 — Enforcement & CI (cross-cutting) +- [ ] `.claude/rules/design-system.md` governance kept current with each phase, and each update preserves the precedence: `AGENTS.md` canonical and tool-neutral, the Claude rule supplementary +- [ ] **[decision]** Optional CI job runs `playwright install chromium` + `pnpm test:storybook`; promote to a required gate only once stable (PROPOSAL §7.1) — **safeguards:** path-filtered to WebUI changes, non-blocking, and deletable without affecting any other lane +- [ ] `pnpm typecheck` + `pnpm lint:conventions` + `pnpm build-storybook` stay green each phase +- [ ] **Owners named before each gating phase opens** (PROPOSAL §7 accountability rule): a dependency sub-issue cut and assigned on the owning Epic for §7.1–§7.6, and every **[decision]** recorded with its caller on that Epic +- [ ] Design governance stays single-owner: no second `DESIGN.md`, token set, or Storybook workbench proposed outside this package (PROPOSAL §9) + +## WS7 — Final verification gate (the 100% gate) +- [ ] Every primitive/composite/component with meaningful states has a story; `pnpm test:storybook` green +- [ ] Light + dark parity and WCAG AA contrast hold across the reskin +- [ ] The WebUI's theming, assets, interactions, and IA reflect the agentic-first principles in `DESIGN.md` +- [ ] `DESIGN.md` + the Storybook catalog are the demonstrated source of truth (new UI built through them) +- [ ] Each phase landed under [its owning Epic](README.md#epic-ownership-canonical) diff --git a/docs/internal/reborn/design-system/PLAN.md b/docs/internal/reborn/design-system/PLAN.md new file mode 100644 index 00000000000..527c110ae8b --- /dev/null +++ b/docs/internal/reborn/design-system/PLAN.md @@ -0,0 +1,72 @@ +# Design System — Execution Plan (Phased) + +**Status:** Proposal, under review · **Authored against:** `origin/main` @ `d3791e0f8` · **Tracks:** three Epics — [ownership table](README.md#epic-ownership-canonical) + +This is the **when and how**; [CHECKLIST.md](CHECKLIST.md) is the **what** (definition of done); [PROPOSAL.md](PROPOSAL.md) is the frozen decision record. The five phases are **predefined** and executed in order; each phase heading links its owning Epic into the canonical table in [README.md](README.md#epic-ownership-canonical). Nothing here is sacred except the ordering constraints marked **⚠**. + +> **Epic ownership** lives in one place: the canonical table in +> [README.md](README.md#epic-ownership-canonical). Every `Epic #NNNN` label below is a +> **link into that table**, not a restatement of it — this document holds no second copy +> of the mapping, so an ownership change is one edit, in the README. + +**Operating principles:** +1. **Docs first** — each phase updates `DESIGN.md` / this package before or with the code (APDD Rule 1). +2. **Token values before component restyle** — Phase 3 lands tokens, validated in Storybook, before any primitive is reskinned. +3. **A story travels with every component change**; `pnpm test:storybook` stays green. +4. **`main` stays shippable** — phases land as reviewable PRs, stacked only where necessary. + +```mermaid +flowchart LR + P1["Phase 1 · Storybook · #7750"] --> P2["Phase 2 · DESIGN.md · #7042"] --> P3["Phase 3 · Theme & reskin"] --> P4["Phase 4 · Interactions"] --> P5["Phase 5 · IA"] +``` + +*The diagram shows sequencing only. Which Epic carries which phase is in the +[canonical table](README.md#epic-ownership-canonical) — it is deliberately not +redrawn here, so the grouping cannot drift out of step with it.* + +## Phase 1 — Storybook integration (PR #7750 — in review) · [Epic #7038](README.md#epic-ownership-canonical) +*Stand up the workbench + catalog.* Storybook 10 (react-vite, pnpm), wired to `app.css` + light/dark toolbar; ~33 stories in five categories; vitest split (`pnpm test` node-only, `pnpm test:storybook` in Chromium); addon-mcp. +**Milestone:** catalog live; story + node suites green at the `crates/product/ironclaw_webui/frontend` path (103 story tests · 1355 node tests on #7750). +**Note:** originally PR #7039 — closed and recreated as **#7750**, clean and non-stacked off current `main`. + +## Phase 2 — DESIGN.md governance & guidelines (issue #7042) · [Epic #7781](README.md#epic-ownership-canonical) +*Make the design system governed.* `DESIGN.md` (M3X spec + IronClaw appendix) and a Storybook `Design/Guidelines` page. **Precedence:** `AGENTS.md` is the canonical, tool-neutral agent contract — `DESIGN.md` is reachable from it, and `.claude/rules/design-system.md` plus the `CLAUDE.md` Module Specs pointer are Claude-specific adapters that *supplement* it, never replace or restate it. +**Milestone:** source of truth + agent rules in place; build-storybook green. +**⚠ Ordering:** the original #7043 was stacked on #7039; both were closed for the resulting merge tangle. Merge **#7750** first, then land the Phase-2 changeset as a fresh PR off `main` (PROPOSAL §7.6). + +## Phase 3 — Theme update & UI reskin · [Epic #7781](README.md#epic-ownership-canonical) +*Change token values + assets to the M3X look; validate in Storybook.* +- Resolve the Phase-3 dependencies first — there are **two**, not three: **dark-palette derivation with WCAG AA contrast validation** (§7.3 — contrast is a standing invariant carried inside the palette work, not a separately-ownable dependency) and **fonts/licensing** (§7.4). Expressive motion is §7.5 and gates Phase 4, not this one. +- Land M3 → `--v2-*` token *values* (light + dark) in `app.css`; refresh color/type/space/radius scales; vendor fonts. +- Reskin primitives/composites against the new tokens; every change validated by its story + `CssCheck` + a11y. +- **Close the invariant-2 gap** (PROPOSAL §3.1): migrate the **345 occurrences of arbitrary pixel classes across 91 files** to the new type/space/radius scales, starting with the 38 occurrences in `design-system/`'s 8 files and the OOBE pilot card, and retire the **10 hardcoded six-digit hex values in 3 `.tsx` files**. +**Milestone:** new palette live in both themes, all `Tokens/*` stories pass contrast, primitives reskinned with green story tests, and `design-system/` free of arbitrary px/hex. +**Exit criteria (safeguards, PROPOSAL §7.0):** token *names* unchanged; fonts self-hosted with a tested fallback stack; the phase revertable by a single PR revert with no residue. +**⚠ Ordering:** Phase 2 lands **before** Phase 3 (DESIGN.md is the spec the token values are judged against, and both phases sit under the same Epic — see the [ownership table](README.md#epic-ownership-canonical)); token values land **before** component restyle; Phase 3 branches off `main` after #7750 and the Phase-2 PR merge. + +## Phase 4 — Interaction & component updates (agentic-first) · [Epic #7782](README.md#epic-ownership-canonical) +*Add the expressive, agent-first interactions + new components.* +- Resolve the **animation approach** (reduced-motion-gated) and **MSW** for network-story happy-paths (PROPOSAL §7.2, §7.5). +- Build the agentic components (composer toolbar, FAB speed-dial, chat bubbles, agent-activity/reasoning cards, branded progress, connected button groups); each ships with stories + play coverage. +**Milestone:** agentic component set catalogued + story-tested; motion honors `prefers-reduced-motion`. +**Exit criteria (safeguards, PROPOSAL §7.0):** the production artifact asserted to contain neither `mockServiceWorker.js` nor an `msw` chunk (the worker never enters `public/` — PROPOSAL §7.2); motion opt-in per component, off via the single shared disabled-motion signal specified in PROPOSAL §7.5 — which cancels JS RAF loops, not just CSS — with the static baseline covered by caller-level tests. +**⚠ Ordering:** depends on Phase 3 tokens. + +## Phase 5 — Information architecture · [Epic #7782](README.md#epic-ownership-canonical) +*Reshape navigation/routes/page structure to foreground agentic workflows.* +- Revisit `src/app/routes.ts`, `src/pages/`, the sidebar and `src/layout/gateway-layout.tsx` (paths relative to `crates/product/ironclaw_webui/frontend/`); adopt the M3X navigation-rail pattern where it fits; ensure multi-channel parity. +**Milestone:** IA restructured; CUJs (chat, approvals, projects, settings) verified unbroken. + +## Suggested next PRs (concrete, in order) +1. **Merge #7750** — that closes Phase 1. Then land the Phase-2 (#7042) changeset as a fresh PR off `main`, opening Phase 2. +2. **Before Phase 3a opens — name the owners:** cut the dependency sub-issues on #7781 (dark palette + contrast, fonts/licensing **[decision]**) and assign them; PROPOSAL §7's accountability rule is what makes the gates real. +3. **Phase 3a — token foundation:** dark-palette + contrast + font vendoring in `app.css` (+ updated `Tokens/*` stories). No component restyle yet. +4. **Phase 3b — primitive reskin:** restyle `design-system/` primitives against the new tokens, story-by-story. +5. **Phase 4a — motion foundation:** choose + wire the animation approach behind the reduced-motion gate; add MSW. +6. **Phase 4b — first agentic component:** composer toolbar or agent-activity card, fully catalogued. + +## Coordination notes +- This is a **docs-only** PR; it changes no code. It references the open Phase-1/2 PRs by number, and adds one cross-link to the OOBE package (PROPOSAL §9). +- **Design governance has one owner: this package** (PROPOSAL §9). OOBE's D-F6 contributes its card family as a pilot; it does not stand up a second `DESIGN.md`, token set, or workbench. +- Each phase is tracked under [its owning Epic](README.md#epic-ownership-canonical), with per-phase sub-issues (e.g. #7042) spun up as work starts. The closed Epic #7733 is recorded as superseded in that table. +- The APDD-kit evaluation (`docs/internal/apdd-governance-kit/`, [PR #7255](https://github.com/nearai/ironclaw/pull/7255) — open, not yet on `main`) is a sibling initiative that motivated this design-governance track; the two do not depend on each other. diff --git a/docs/internal/reborn/design-system/PROPOSAL.md b/docs/internal/reborn/design-system/PROPOSAL.md new file mode 100644 index 00000000000..4030e1e906c --- /dev/null +++ b/docs/internal/reborn/design-system/PROPOSAL.md @@ -0,0 +1,207 @@ +# Proposed: Storybook + Design-System Catalog for the IronClaw WebUI + +**Status:** Proposal, under review · **Authored against:** `origin/main` @ `d3791e0f8` · **Tracks:** three Epics — [ownership table](README.md#epic-ownership-canonical) · **Benchmarks:** the APDD governance kit (external, not vendored — evaluated in-repo at [`docs/internal/apdd-governance-kit/`](https://github.com/nearai/ironclaw/pull/7255), PR #7255, *not yet on `main`*) · [`docs/internal/reborn/target-architecture/`](../target-architecture/PROPOSAL.md) (PR #6918) + +## 1. Executive decision + +Adopt a **governed, catalogued design system** for the IronClaw WebUI and evolve it toward an **AI/agentic-first UX** in five predefined phases. Realize the design language — **Material 3 Expressive (M3X)** — **natively** with the existing React 19 + Tailwind v4 primitives; do **not** adopt Material Web components or a parallel/third-party design-system framework. `DESIGN.md` and the Storybook catalog are the source of truth; the token architecture (`data-theme` + `--v2-*`) is kept. + +Phases 1–2 are in flight (PR #7750 in review; the Phase-2 changeset preserved on #7042). Ownership of each phase is the [canonical table in README.md](README.md#epic-ownership-canonical). This proposal freezes the framing, records the decisions, and — most importantly — **names the dependencies of Phases 3–5 with a proposed implementation for each** (§7). + +## 2. Current-state evidence + +### 2.1 Frontend stack (`CURRENT`, measured against `origin/main`) +- **React 19.2 + TypeScript** SPA under `crates/product/ironclaw_webui/frontend`, built with **Vite + Tailwind v4** (CSS-first: no `tailwind.config.ts`; tokens live in `src/styles/app.css` under `@theme` + `:root[data-theme=…]`). +- Package manager **pnpm**; fonts self-vendored via `/vendor/fonts` (Geist / Geist Mono). +- A deliberate **static-motion policy** in `app.css` (`* { animation: none !important }`) with **five standing exceptions**, not one: `.v2-marquee…-track` (`v2-marquee-scroll`, hover-only), `.v2-spin`, `.near-process.is-busy .near-process-icon` (`near-pulse`) and its `.near-comet` (`near-chase`), and `.oobe-card-reveal` (`v2-page-in`). Each follows the same discipline, and it is the discipline Phase 4 extends rather than replaces: the exception is declared `!important` so it outranks the universal rule, and it is **individually re-suppressed** in the `@media (prefers-reduced-motion: reduce)` block. No exception is ad-hoc. + +### 2.2 Existing design surface (`CURRENT`) +- `src/design-system/` — atomic **primitives** (Button, Badge, Input, Card, Switch, Spinner, Modal, ConfirmDialog, SelectMenu, Icon) + **composites** in `primitives.tsx` (StatCard, Panel, FlowList, EmptyPanel, SectionHeader, SubLabel). +- `src/components/` + `src/layout/` — shared composites and the app shell. +- Tokens are already token-driven via `--v2-*`; light + dark both defined. + +### 2.3 Foundations in flight (not yet on `main`) + +Phases 1–2 are *built but unmerged*. Nothing in this section can be verified by checking out `main`; each item's home path is created by the PR or tracked issue named beside it — and Phase 2 has an issue, not yet a PR. + +- **Phase 1 — `IN REVIEW` (PR #7750, supersedes closed #7039):** Storybook 10 (`@storybook/react-vite`, pnpm) wired to the real `app.css` + a light/dark toolbar; **~33 stories** in five sidebar categories (Primitives / Components / Composites / Icons / Tokens); a vitest split (`pnpm test` node-only, `pnpm test:storybook` in headless Chromium); `@storybook/addon-mcp` for agent access. On `main` today: no `.storybook/` directory, no stories. +- **Phase 2 — `PREPARED`, no open PR (issue #7042, changeset preserved from closed #7043):** `crates/product/ironclaw_webui/frontend/DESIGN.md` (M3X spec + an IronClaw implementation/governance appendix), a Storybook `Design/Guidelines` docs page, and `.claude/rules/design-system.md` agent governance. On `main` today: none of those three files exists. + +### 2.4 Current-state conclusion +The workbench, catalog, governance doc, and agent rules are **written and reviewable, but not merged** — Phase 1 in review, Phase 2 awaiting its fresh PR (§7.6). Read every `DESIGN.md` / Storybook / `.claude/rules/design-system.md` reference in this package as *the artifact those two phases land*, not as something present on `main`. What remains after them is the **visual/interaction transformation** (Phases 3–5) — which is where the dependencies and risk concentrate. + +## 3. Non-negotiable invariants + +**These are the target state, and the bar for new and touched code from now on — not a description of the tree today.** Two of them are already met (1, 5); invariant 2 is not, and the gap is measured in §3.1 rather than asserted away. Nothing here may be relaxed to accommodate the gap; the gap is closed by the phase named against it. + +1. **Native M3X** — realized with React + Tailwind + `--v2-*`; never `` Lit web components or a parallel framework. *(Holds today.)* +2. **Token-driven** — no hardcoded hex/px in components; add tokens (light **and** dark) in `app.css`. *(**Not met today** — see §3.1. Binding on new and touched components immediately; the existing backlog migrates in Phase 3.)* +3. **Story-per-component** — every primitive/composite/component with meaningful states has a colocated `*.stories.tsx`; changes are reviewed in Storybook and covered by `pnpm test:storybook`. +4. **Accessibility bar** — WCAG AA contrast, preserved `aria-*`, keyboard/focus, light+dark parity. +5. **Motion policy** — expressive motion is opt-in and `prefers-reduced-motion`-gated. *(Holds today — the five standing exceptions in §2.1 are each reduced-motion-suppressed.)* + +### 3.1 The token invariant's current gap (`CURRENT`, measured against `origin/main`) + +Invariant 2 is stated as a target because the tree does not meet it. Measured under `crates/product/ironclaw_webui/frontend/src/`, **production components only — `*.test.*` excluded**, since the invariant governs components rather than fixtures. Every row gives files *and* occurrences in the same unit: + +| Violation | Files | Occurrences | +|---|---:|---:| +| Arbitrary pixel classes (`text-[13px]`, `rounded-[13px]`, …) | **91** | **345** | +| …of which inside `design-system/` — the primitive layer the invariant most directly governs | **8** | **38** | +| Hardcoded 6-digit hex in `.tsx` | **3** | **10** | + +*(Counting test files too would read 93/347 and 4/13; the migration targets production components, so the table states those.)* + +This includes the component family this package names as the governance pilot: `pages/chat/components/suggested-task-card.tsx` carries 5 arbitrary pixel classes (`rounded-[13px]`, `rounded-[6px]`, `text-[13px]`, `text-[11px]`, `text-[10.5px]`). It is *colour*-conformant already — every colour on it is a `var(--v2-*)` reference — so the gap is dimensional, not chromatic, which is why Phase 3's type/space/radius scales are what close it. + +**Consequence for the pilot claim:** the OOBE card family is the pilot *subject*, not a conformant exemplar. It demonstrates the governance loop (catalogued, story-tested, judged against `DESIGN.md`); it does not yet demonstrate invariant 2, and this package does not claim it does. Migration is Phase 3 work, tracked in CHECKLIST WS3. + +## 4. Alternatives considered + +- **Material Web Components (``, Lit) — rejected.** Introduces a second component runtime into a React app; violates the program's "no parallel framework" non-goal (carried by all three Epics) and the `--v2-*` token architecture. The supplied agent instructions assumed this stack; it does not fit. +- **A third-party React DS (MUI/Radix/shadcn adoption wholesale) — rejected.** We already have a coherent primitive layer; swapping frameworks is a rebuild, not a reskin. +- **Native M3X on React + Tailwind — recommended.** Adopt M3X as the *design language*, applied to our own primitives and tokens. Preserves logic, `aria-*`, and the token mechanism; changes values/assets/interactions, not architecture. + +## 5. The design system, as governed + +`DESIGN.md` is the constitution; it maps cleanly onto the APDD-kit 5-tier taxonomy. **Every home below is relative to `crates/product/ironclaw_webui/frontend/src/`**: + +| APDD tier | IronClaw home | +|---|---| +| Tier 1 — Tokens | `styles/app.css` (`@theme` + `--v2-*`) | +| Tier 2 — Elements (primitives) | `design-system/` atomics | +| Tier 3 — Components (pure compositions) | `design-system/primitives.tsx` composites + `components/` | +| Tier 4 — Patterns (state-bound) | `pages/**` feature views | +| Tier 5 — Layouts | `layout/` | + +## 6. Storybook as workbench + test-harness + agent MCP + +Per the APDD design-governance guide, Storybook is three things: a **workbench** (the catalog), a **test harness** (`test:storybook` runs stories in Chromium with a11y + a `CssCheck` that fails if the stylesheet didn't load), and an **agent MCP** (`@storybook/addon-mcp`, registered local-scope, so an agent can query component docs before using them). All three arrive with Phases 1–2 — built and reviewable today (#7750 / #7042), on `main` only once those land (§2.3). + +## 7. Dependencies and their implementation proposals + +The remaining phases carry six dependencies. Each is stated with a **proposed implementation**, the phase it gates, and an **owner**. + +**Accountability rule.** A dependency's owner is the Epic that carries its gating phase. The *accountable individual* is the assignee of that Epic's dependency sub-issue, which must be **cut and assigned before the gating phase's first PR opens**; items marked **[decision]** additionally need a named human call recorded on the owning Epic. A dependency with no assignee, or a `[decision]` with no named caller, leaves its phase gate **closed** — it does not default open. + +> ⚠ **State as of this proposal: no dependency has a named individual yet, so every gate below is closed.** The `Assignee` column records what has actually been assigned, not an intention — it reads `— none` on every row, and that is the honest current state of the program, not an oversight in this table. Cutting and assigning these six sub-issues is itself a prerequisite, tracked as a box in CHECKLIST WS6; the table is updated in place as each is assigned. Nothing in Phases 3–5 may open while its row is still `— none`. + +| # | Dependency | Gates | Owning Epic | Sub-issue | Assignee | Gate | +|---|---|---|---|---|---|---| +| 7.1 | CI Playwright/Chromium for `test:storybook` | cross-cutting | [#7038](https://github.com/nearai/ironclaw/issues/7038) | not yet cut | — none | 🔒 closed · **[decision]**: promotion to a required gate needs a named caller | +| 7.2 | MSW for network-backed stories | Phase 4 happy-paths | [#7782](https://github.com/nearai/ironclaw/issues/7782) | not yet cut | — none | 🔒 closed | +| 7.3 | Dark palette derivation (+ the §3.4 contrast invariant) | Phase 3 | [#7781](https://github.com/nearai/ironclaw/issues/7781) | not yet cut | — none | 🔒 closed | +| 7.4 | Fonts + licensing | Phase 3 | [#7781](https://github.com/nearai/ironclaw/issues/7781) | not yet cut | — none | 🔒 closed · **[decision]**: Google Sans substitute needs a named caller | +| 7.5 | Expressive motion | Phase 4 | [#7782](https://github.com/nearai/ironclaw/issues/7782) | not yet cut | — none | 🔒 closed · **[decision]**: animation mechanism needs a named caller | +| 7.6 | Merge order / stacked PRs | Phase 1→2 landing | [#7038](https://github.com/nearai/ironclaw/issues/7038) → [#7781](https://github.com/nearai/ironclaw/issues/7781) | [#7042](https://github.com/nearai/ironclaw/issues/7042) | — none | 🔒 closed — Phase 1 lands via [#7750](https://github.com/nearai/ironclaw/pull/7750) | + +WCAG AA contrast validation is not a seventh line: it is a **standing invariant** (§3.4) enforced inside 7.3 by the same owner, not a separately-ownable dependency. + +### 7.0 Operational safeguards every dependency must carry + +Each proposal below adds a dependency, a CI lane, or a runtime behavior to a shipping frontend, so each states how it is **contained, reverted, and degraded** — not only how it is installed. These are exit criteria for the phase that lands them (PLAN Phases 3–4; CHECKLIST WS3/WS4/WS6), not aspirations: + +| Safeguard | What it must be true of | +|---|---| +| **Isolation** | A dev/test-only dependency must be provably absent from the production bundle — not merely unused in it. | +| **Fallback** | Any asset or capability that can fail to load (font, motion mechanism, mock worker) has a defined, tested degraded state. | +| **Rollback** | Every item is revertable by a single PR revert, with no persisted state or generated artifact left behind that a revert would not remove. | +| **Compatibility** | No change to the `--v2-*` token *contract* (names, semantics) without updating every consumer in the same PR; token *values* may change freely. | + +```mermaid +flowchart LR + DARK["Dark palette derivation"] + CONTRAST["WCAG AA contrast validation"] + FONTS["Fonts: vendor Roboto Flex/Mono; drop Google Sans"] + TOKENS["Phase 3: M3 to --v2-* token values"] + MOTION["Animation approach + reduced-motion"] + COMPS["Phase 4: agentic components + interactions"] + CI["CI: Playwright/Chromium for test:storybook"] + MSW["MSW for network-backed stories"] + DARK --> TOKENS + CONTRAST --> TOKENS + FONTS --> TOKENS + TOKENS --> COMPS + MOTION --> COMPS + CI -. gates .-> COMPS + MSW -. enables .-> COMPS +``` + +**7.1 CI: Playwright/Chromium for `test:storybook`.** *Gates: cross-cutting.* *Owner: Epic #7038 → the CI-lane owner named on it; promotion to a required gate is a **[decision]**.* The story suite runs in headless Chromium; CI runners don't install it today (the vitest split keeps `pnpm test` node-only, so nothing breaks now). **Proposal:** add an *optional, non-blocking* CI job that runs `pnpm exec playwright install chromium` + `pnpm test:storybook`; promote to a required gate only after it's proven stable. Documented in CHECKLIST WS6. *Safeguards:* **isolation** — the job runs only on WebUI-path changes and installs Chromium into the runner, touching no other lane; **fallback** — the vitest split keeps `pnpm test` node-only, so a Chromium failure never blocks the node suite; **rollback** — deleting the job restores today's behavior exactly, since nothing depends on its result while it is non-blocking; **compatibility** — it stays non-required until it has been green for a full release cycle, and the promotion is the **[decision]** above. + +**7.2 MSW for network-backed stories.** *Gates: Phase 4 happy-paths.* *Owner: Epic #7782 → the Phase-4 sub-issue assignee.* Two components (PairingWebCodePanel, TeeShield) render limited/error states in Storybook because they hit the network / are host-gated. **Proposal:** add `msw` + `msw-storybook-addon` and handlers for only those endpoints, keeping deterministic cache-seeding for everything react-query-based (the pattern already used in Phase 1). + +> ⚠ **The worker must not be generated into `frontend/public/`** — the obvious default, and wrong here. `vite.config.ts` sets `publicDir: "public"`, so everything in it is copied into `dist/`; `crates/product/ironclaw_webui/build.rs` then walks `dist/` recursively (`collect()`, skipping only `.vite`) and embeds **every** file into the shipping binary. A worker dropped in `public/` would be compiled into production and served by the real WebUI, `devDependency` or not. Generate it into a **Storybook-only static directory** wired through Storybook's `staticDirs`, so it never enters the Vite production input. *Safeguards:* **isolation** — `msw` and `msw-storybook-addon` are `devDependencies`, the worker lives in a Storybook-only static dir (never `public/`) and is registered from Storybook's preview only, and a build assertion proves the production artifact contains **neither `mockServiceWorker.js` nor any `msw` chunk** — asserted against `dist/` before `build.rs` embeds it, since a `devDependency` alone guarantees nothing once a file is in `public/`; **fallback** — a component whose handler is missing renders its existing limited/error state rather than hanging; **rollback** — removing the addon and the generated worker from the Storybook static dir is the whole revert; **compatibility** — handlers are added only for the two named endpoints, so no existing story changes behavior. + +**7.3 Dark palette derivation.** *Gates: Phase 3.* *Owner: Epic #7781 → the Phase-3a token-foundation PR author; carries the §3.4 WCAG AA invariant with it.* The supplied M3 palette is light-only; the app is dark-default and dual-theme. **Proposal:** derive dark values per token (tonal shift, not literal inversion) in `app.css :root[data-theme="dark"]`; validate each pair in the `Tokens/Colors` story before adoption. *Safeguards:* **compatibility** — token *names* and semantics are unchanged, only values, so no consumer needs editing; **rollback** — the previous values are one revert away and no state persists; **fallback** — a token that fails contrast blocks adoption rather than shipping with a note. + +**7.4 Fonts + licensing.** *Gates: Phase 3.* *Owner: Epic #7781; the Google Sans substitute is a **[decision]** that must be called on #7781 before Phase 3a opens.* Spec wants Roboto Flex / Google Sans / Roboto Mono; app ships Geist. **Proposal:** vendor **Roboto Flex + Roboto Mono** (OFL) under `/vendor/fonts`; **drop Google Sans** (not freely redistributable) — use Roboto Flex for the emphasized-headline role, or confirm a licensed source before shipping. *Safeguards:* **isolation** — fonts are self-hosted under `/vendor/fonts`, so no third-party request is introduced; **fallback** — every face declares a real system fallback stack and `font-display: swap`, so a failed font load degrades to readable text rather than invisible text; **rollback** — reverting the `@font-face` block and the vendored files restores Geist; **compatibility** — metric-compatible sizing is verified in the `Tokens/Type` story before the swap lands. + +**7.5 Expressive motion.** *Gates: Phase 4.* *Owner: Epic #7782; the animation mechanism is a **[decision]** that must be called on #7782 before Phase 4a opens.* Spring physics / shape-morph / speed-dial unfurl require an animation mechanism; none is installed, and the static-motion policy is in force. **Proposal:** evaluate a small JS spring lib (e.g. `motion`) vs. spring→cubic-bezier CSS approximations; whichever is chosen, all expressive motion is **opt-in and `prefers-reduced-motion`-gated**, introduced behind the policy rather than ad-hoc keyframes. *Safeguards:* **isolation** — motion is opt-in per component, so the static-motion policy remains the default for everything untouched; **fallback** — reduced-motion and a failed library load both resolve to the current static presentation, which is the tested baseline; **compatibility** — no component's logic, `aria-*`, or focus behavior changes when motion is disabled. + +**The kill switch must be a shared signal, not the CSS line.** `* { animation: none !important }` stops CSS animations and transitions; it cannot stop a JavaScript spring's `requestAnimationFrame` loop or the inline `transform`/`style` writes it makes, so treating the `app.css` rule as the off-switch would be a guardrail promise the code does not keep. The mechanism, specified once here and referenced (not restated) by PLAN Phase 4 and CHECKLIST WS4: + +- **One disabled-motion signal** that both `prefers-reduced-motion` and the app-level kill switch resolve into — read by CSS *and* by every JS animation caller. A spring that is running cancels its RAF loop and writes the static end-state; it never merely stops mid-transform. +- **Dynamic loading fails closed.** If the motion module is imported dynamically, a rejected chunk is caught and the component renders the static baseline. A failed *static* import stays a build failure — it is not something to paper over at runtime. +- **Tested at the caller.** Coverage asserts the disabled path at the component that animates, not only on the helper: signal on → no RAF scheduled, no inline transform written, static end-state rendered. + +**7.6 Merge-order / stacked PRs.** *Gates: Phase 1→2 landing.* *Owner: #7750's author for Phase 1; the Phase-2 fresh-PR author for #7042.* The original Phase-2 PR #7043 was stacked on Phase-1 #7039; both were closed after the stack became an unmergeable merge-commit tangle. **Proposal:** merge the recreated, non-stacked **#7750** first, then land the preserved Phase-2 changeset (#7042) as a fresh PR off `main`; Phase 3 branches off `main` after both land. + +## 8. Alignment with the governance benchmarks + +- **APDD kit:** we produce the kit's design-governance artifacts — `DESIGN.md` (constitution + taxonomy + REJECT gate), path-scoped `.claude/rules/design-system.md`, Storybook-as-workbench/test/MCP, and a validation gate — and honor its spine (docs are source of truth; fixes update docs + add a test). This proposal package is the kit's "epic gets a committed plan" case. +- **PR #6918:** we mirror the doc shape (this README/PROPOSAL/PLAN/CHECKLIST + an interactive artifact) and conventions (provenance shas; phased waves with quantified milestones; `⚠` ordering constraints; "Landed with #NNNN"; a PR-body `| File | Role |` table). + +## 9. Ownership boundary: one canonical governance record + +There must be exactly one owner for the shared `DESIGN.md`, token, and Storybook-governance decisions. **This package is that owner.** Everything else that needs design governance consumes it rather than re-proposing it. + +```mermaid +flowchart LR + DS["docs/internal/reborn/design-system/
(this package) — Epics #7038 · #7781 · #7782"] + GOV["DESIGN.md + --v2-* tokens + Storybook governance
(single source of truth)"] + OOBE["docs/internal/design/oobe/ — D-F6
OOBE card family"] + OTHER["any other feature package
needing new UI"] + DS -->|owns and defines| GOV + OOBE -->|consumes: pilot component family| GOV + OTHER -->|consumes| GOV +``` + +**What this package owns.** The `DESIGN.md` constitution and its taxonomy, the `--v2-*` token architecture and its values, the Storybook catalog/test-harness/MCP setup, `.claude/rules/design-system.md`, and the phase sequencing that lands all of it (Phases 1–5, Epics #7038 / #7781 / #7782). + +**What it does not own.** Any individual feature's component work. Feature packages specify *their* components and states; they do not stand up parallel governance. + +**Specifically, OOBE D-F6.** [`docs/internal/design/oobe/PROPOSAL.md` §5.6](../../design/oobe/PROPOSAL.md) proposes seeding a `DESIGN.md` plus "optionally a Storybook workbench" for the OOBE card family. That is the *same* governance work this package's Phases 1–2 land. The boundary, effective with this proposal: + +- **D-F6 does not stand up `DESIGN.md`, tokens, or Storybook.** Phase 1 (#7750) delivers the workbench; Phase 2 (#7042) delivers `DESIGN.md` + the agent rules. D-F6's governance half is **subsumed**, not duplicated. +- **What survives of D-F6 is its pilot role**: the OOBE card/drawer/action-bar family is a Tier-2/3 component family that gets catalogued *through* this system — stories in the Phase-1 catalog, conformance judged against the Phase-2 `DESIGN.md`. +- **Sequencing:** if OOBE productionizes its cards before #7750 lands, it ships them as ordinary token-driven components and their stories follow in the Phase-1/2 wake — it does not fork a workbench to get there. +- **The OOBE package's D-F6 section carries a pointer to this section** so the two records cannot drift into competing plans (that pointer is part of this PR's diff). + +If a reviewer would rather the OOBE track own design governance instead, that is a legitimate call — but it has to be *one* of the two, and this package should then be retired into a link to that owner. What is not acceptable is both records proposing the same `DESIGN.md`. + +## 10. Risks & open questions + +- **Reskin scope creep** — an M3X reskin can balloon. Mitigation: token values land first (Phase 3) and are validated in Storybook before any component restyle. +- **Motion vs. the static-motion policy** — reversing it broadly risks a11y regressions. Mitigation: opt-in + reduced-motion gate, per-component. +- **CI cost** — running Chromium story tests in CI adds minutes. Mitigation: optional job first; make required only if stable. +- **[decision]** Font substitute for Google Sans — needs a named call (Roboto Flex only, or a licensed alternative). +- **[decision]** Whether `test:storybook` becomes a required merge gate. + +## 11. References + +Every path below is stated with where it actually resolves, so nothing in this package points at a file a reader cannot open. + +**Resolvable in this repo, on `main`:** +- Benchmark package: [`docs/internal/reborn/target-architecture/`](../target-architecture/README.md) (PR #6918). +- Sibling design record whose governance half this package subsumes (§9): [`docs/internal/design/oobe/`](../../design/oobe/README.md). + +**Not in this repo:** +- The **APDD governance kit** itself (`guides/design-ux-governance.md`, `templates/DESIGN.template.md`) is an external kit reviewed from a working copy alongside the IronClaw checkout. It is **not vendored here**, so this package quotes and paraphrases it rather than linking to it. Its IronClaw evaluation *is* in-repo — see below. + +**Proposed, not yet on `main` (open PRs / future phases):** +- APDD-kit evaluation: `docs/internal/apdd-governance-kit/` — [PR #7255](https://github.com/nearai/ironclaw/pull/7255), open. +- Phase 1 artifacts (Storybook config + ~33 stories under `crates/product/ironclaw_webui/frontend/`) — [PR #7750](https://github.com/nearai/ironclaw/pull/7750), open. +- Phase 2 artifacts — `crates/product/ironclaw_webui/frontend/DESIGN.md`, `.claude/rules/design-system.md`, and a `crates/product/ironclaw_webui/frontend/src/design-system/README.md` pointer — [issue #7042](https://github.com/nearai/ironclaw/issues/7042); changeset preserved from closed #7043, fresh PR to follow #7750. + +**Tracking:** three Epics — the phase→Epic mapping is the [canonical table in README.md](README.md#epic-ownership-canonical) and is not restated here. This package is PR #7257. Closed and superseded: PRs #7039, #7043; Epic #7733 (→ #7781). diff --git a/docs/internal/reborn/design-system/README.md b/docs/internal/reborn/design-system/README.md new file mode 100644 index 00000000000..5091fd0c7b8 --- /dev/null +++ b/docs/internal/reborn/design-system/README.md @@ -0,0 +1,93 @@ +# IronClaw WebUI Design System — Storybook + Catalog (Executive Overview) + +**Status:** Proposal, under review · **Authored against:** `origin/main` @ `d3791e0f8` · **Tracks:** three Epics — see [Epic ownership](#epic-ownership-canonical) below + +**Documents:** [PROPOSAL.md](PROPOSAL.md) — the case, decisions & dependencies · [PLAN.md](PLAN.md) — phased execution · [CHECKLIST.md](CHECKLIST.md) — definition of done · [explorer.html](explorer.html) — self-contained interactive review aid (schematics + phase map; also published as a [claude.ai artifact](https://claude.ai/code/artifact/371a2622-054c-404a-8992-f110e1fa3d5a)) + +> **North star:** a *governed, catalogued* WebUI design system that carries IronClaw to an AI/agentic-first UX — realized **natively** on our React 19 + Tailwind v4 stack, reviewed and regression-tested through **Storybook**, and evolved in **five predefined phases**. + +## Epic ownership (canonical) + +This table is the **single source** for phase→Epic ownership across this package. [PLAN.md](PLAN.md), [CHECKLIST.md](CHECKLIST.md) and [explorer.html](explorer.html) name the owning Epic inline per phase/workstream and point back here rather than restating the mapping — when ownership changes, this table is the one edit. The program is tracked across three Epics (the original #7038 was split, then Phase 2 folded in with Phase 3): + +| Epic | Phases | Scope | +|---|---|---| +| [#7038](https://github.com/nearai/ironclaw/issues/7038) | 1 | Storybook integration & design-system catalog — PR #7750 | +| [#7781](https://github.com/nearai/ironclaw/issues/7781) | 2–3 | `DESIGN.md` governance & documentation (#7042) · theme update & UI reskin — supersedes the closed #7733 | +| [#7782](https://github.com/nearai/ironclaw/issues/7782) | 4–5 | Agentic interactions & components · Information architecture | + +## What this proposes + +Formalize the design-system work already underway (Storybook integration + a catalogued primitive/component library) into a **benchmarked, phased program** to redefine the WebUI's theming, visual assets, interactions, and information architecture around an agent-first experience. Phases 1–2 are in flight — Phase 1 as PR [#7750](https://github.com/nearai/ironclaw/pull/7750) (recreated non-stacked off current `main`; supersedes the closed #7039) and Phase 2 as issue [#7042](https://github.com/nearai/ironclaw/issues/7042) (the closed #7043's changeset preserved, fresh PR to follow). **Neither is on `main` yet** — every `DESIGN.md` / Storybook / `.claude/rules/design-system.md` reference in this package describes what those two phases *land*, not what a reader can check out today ([PROPOSAL §2.3](PROPOSAL.md#23-foundations-in-flight-not-yet-on-main)). This package is the north-star that frames every phase and the dependencies they carry. + +It deliberately follows two benchmarks: the **APDD governance kit** (an *external* kit — not vendored into this repo; docs-are-source-of-truth, a `DESIGN.md` constitution, Storybook-as-workbench/test/MCP, a design validation gate — its IronClaw evaluation is proposed at `docs/internal/apdd-governance-kit/` on [PR #7255](https://github.com/nearai/ironclaw/pull/7255), not yet on `main`) and the **target-crate-architecture package** ([`docs/internal/reborn/target-architecture/`](../target-architecture/README.md), PR #6918 — README/PROPOSAL/PLAN/CHECKLIST + interactive explorer). Reference paths and where each resolves: [PROPOSAL §11](PROPOSAL.md#11-references). + +## Why this shape + +1. **The work is already phased and partly shipped** — a north-star doc set makes the sequence, dependencies, and done-ness legible to reviewers instead of living only in an Epic checklist. +2. **Docs are the source of truth** (APDD Rule 1). `DESIGN.md` + the Storybook catalog govern how UI is built; this package records *why* and *in what order*. +3. **The riskiest work is ahead** (theme reskin, expressive motion, IA). Naming the dependencies now — and proposing how each is met — de-risks Phases 3–5. + +## The layer map + +Where the design system sits in the frontend, and what governs/catalogs it. **The five stacked nodes are relative to `crates/product/ironclaw_webui/frontend/src/`**; the two governance/catalog nodes are not paths under it — `DESIGN.md` lands at `crates/product/ironclaw_webui/frontend/DESIGN.md`, `.claude/rules/design-system.md` at the repository root, and the Storybook node names catalog sections rather than a directory: + +```mermaid +flowchart TD + P["pages/ — feature views (chat, settings, admin…)"] + L["layout/ — app shell (gateway-layout)"] + C["components/ — shared composites (sidebar, command palette, page header…)"] + DS["design-system/ — primitives (Button, Input, Modal, SelectMenu…) + composites (primitives.tsx)"] + T["styles/app.css — @theme + --v2-* tokens · data-theme light/dark"] + P --> L --> C --> DS --> T + GOV["DESIGN.md + .claude/rules/design-system.md — governance"] + SB["Storybook catalog + story tests — Design / Primitives / Composites / Components / Icons / Tokens"] + GOV -. governs .-> DS + GOV -. governs .-> T + SB -. catalogs & regression-tests .-> DS + SB -. catalogs & regression-tests .-> C +``` + +## The five phases + +*Scope and delivery state only — which Epic carries which phase is the [table above](#epic-ownership-canonical), the one place that mapping is written down.* + +| Phase | Scope | Status | Ships as | +|---|---|---|---| +| **1** | Storybook integration + design-system catalog | In review | PR [#7750](https://github.com/nearai/ironclaw/pull/7750) (supersedes closed #7039) | +| **2** | `DESIGN.md` governance & guidelines | Ready, PR to follow #7750 | Issue [#7042](https://github.com/nearai/ironclaw/issues/7042) (old PR #7043 closed) | +| **3** | Theme update & UI reskin (tokens + assets) | Planned | — | +| **4** | Interaction & component updates (agentic-first) | Planned | — | +| **5** | Information architecture | Planned | — | + +## Ownership boundary + +This package is the **canonical design-system governance record**: it owns `DESIGN.md`, the `--v2-*` token architecture, the Storybook catalog/test-harness/MCP, and `.claude/rules/design-system.md`. Feature packages *consume* that governance instead of re-proposing it — including the OOBE package, whose D-F6 "DESIGN.md + design tokens" item is **subsumed** here, keeping only its pilot role (the OOBE card family is catalogued through this system). Full boundary, with the alternative call spelled out: [PROPOSAL §9](PROPOSAL.md#9-ownership-boundary-one-canonical-governance-record). + +## Dependencies at a glance + +The reskin/interaction phases carry hard prerequisites. Each has a proposed implementation **and a named owner** in [PROPOSAL §7](PROPOSAL.md#7-dependencies-and-their-implementation-proposals). The Epic on each line below is that *dependency's* owner, derived from its gating phase via the [ownership table](#epic-ownership-canonical) — it is a per-dependency attribution, not a second copy of the phase mapping — the owner is the Epic carrying the gating phase, made individual by a dependency sub-issue that must be cut and assigned before that phase's first PR opens: + +- **Dark palette derivation** — the supplied M3 palette is light-only; the app is dark-default and dual-theme. *(gates Phase 3 · Epic #7781)* +- **WCAG AA contrast validation** for the high-chroma tokens — a standing invariant carried inside the palette work. *(gates Phase 3 · Epic #7781)* +- **Fonts** — vendor Roboto Flex/Mono (OFL); drop/replace Google Sans (not freely redistributable). *(gates Phase 3 · Epic #7781 · **[decision]**)* +- **Animation approach** — a spring/motion mechanism gated on `prefers-reduced-motion`; none installed today. *(gates Phase 4 · Epic #7782 · **[decision]**)* +- **CI: Playwright/Chromium** for `pnpm test:storybook` if story tests run in CI. *(cross-cutting · Epic #7038 · promotion to required is a **[decision]**)* +- **MSW** for network-backed component stories' happy paths. *(cross-cutting · Epic #7782)* + +## How this aligns with the governance benchmarks + +- **APDD kit** (external, not vendored) → this initiative *is* the kit's design-governance track: `DESIGN.md` (constitution + 5-tier taxonomy), path-scoped `.claude/rules/design-system.md`, Storybook as workbench + test-harness + agent-MCP, and a validation/REJECT gate. See [PROPOSAL §8](PROPOSAL.md#8-alignment-with-the-governance-benchmarks). +- **PR #6918** → this package copies its doc shape (README/PROPOSAL/PLAN/CHECKLIST + interactive artifact + a PR-body file table) and its conventions (provenance shas, phased waves with milestones, `⚠` ordering constraints, "Landed with #NNNN"). + +## What is explicitly *not* decided here + +- Exact **token values**, the **animation library**, the **font substitute** for Google Sans, and the **IA/navigation** redesign — each is owned by its phase and resolved against `DESIGN.md` before it lands. +- Whether story tests become a **required CI gate** (proposed, not yet mandated — see PROPOSAL §7.1). + +## How to review + +1. Skim this README for the shape and the phase table. +2. Read [PROPOSAL.md](PROPOSAL.md) §1–§4 (decision + alternatives) and **§7 (dependencies)** — that's where the real risk lives. +3. Open [explorer.html](explorer.html) for the schematics and phase map — a self-contained page (no build step); render it in-browser via [html-preview](https://html-preview.github.io/?url=https://github.com/nearai/ironclaw/blob/docs/design-system-proposal/docs/internal/reborn/design-system/explorer.html) if you don't want to clone. +4. Challenge [CHECKLIST.md](CHECKLIST.md) (is this the right definition of done?) and argue [PLAN.md](PLAN.md) sequencing. diff --git a/docs/internal/reborn/design-system/explorer.html b/docs/internal/reborn/design-system/explorer.html new file mode 100644 index 00000000000..6a834e5135f --- /dev/null +++ b/docs/internal/reborn/design-system/explorer.html @@ -0,0 +1,384 @@ + + + + + +WebUI Design System — Proposal Review + + + +
+ +
+ +
+

Proposal · Review aid · WebUI design-system program

+

WebUI Design System — Storybook & Catalog

+

A governed, catalogued design system that carries IronClaw to an AI/agentic-first UX — realized natively on React 19 + Tailwind v4, reviewed and regression-tested through Storybook, and delivered in five predefined phases.

+
+ Docs-only proposal + authored against origin/main @ d3791e0f8 + · + benchmarks: APDD kit (external) + PR #6918 +
+
+ Read this page as a review aid, not a record. Phase→Epic ownership is defined once, in + README.md; the pills below only echo it. + And Phases 1–2 are not on main — Phase 1 is in review (PR #7750), Phase 2 is prepared + but has no open PR (#7042), so every DESIGN.md / Storybook reference here describes what those phases land. +
+
+ +
+

What this follows — the two benchmarks

+
+
+
APDD governance kit — external, not vendored
+

How it should be governed

+
    +
  • Docs are the source of truth — DESIGN.md + the catalog govern how UI is built.
    • +
  • DESIGN.md constitution + a 5-tier taxonomy (Tokens → Elements → Components → Patterns → Layouts).
    • +
  • Storybook = workbench + test-harness + agent MCP.
    • +
  • Path-scoped agent rules and a design validation / REJECT gate.
    • +
+
+
+
PR #6918 — target architecture
+

How it should be framed

+
    +
  • README / PROPOSAL / PLAN / CHECKLIST quartet + this interactive explorer.
    • +
  • Provenance shas, phased waves with milestones, ⚠ ordering constraints.
    • +
  • "Landed with #NNNN" on completed checklist items.
    • +
  • A PR body with a File → Role index table.
    • +
+
+
+
+ +
+

Where the design system lives

+

Every rung is relative to crates/product/ironclaw_webui/frontend/src/. The governance notes beside it are not: DESIGN.md lands at crates/product/ironclaw_webui/frontend/DESIGN.md and .claude/rules/design-system.md at the repository root.

+
+
+
+
pages/ — feature views
+
↓ depends on
+
layout/ — app shell
+
↓
+
components/ — shared composites
+
↓
+
design-system/ — primitives + composites
+
↓
+
styles/app.css — @theme + --v2-* · data-theme light/dark
+
+ +
+
+

Native M3X: the language is applied to our own React/Tailwind primitives and --v2-* tokens — no Material Web <md-*> components, no parallel framework.

+
+ +
+

The five phases

+
+
+ 1 · Storybook→ + 2 · DESIGN.md→ + 3 · Theme & reskin→ + 4 · Interactions→ + 5 · IA +
+
+
+ + + +
+
4
+

Interaction & component updates

+

Agentic components + expressive, reduced-motion-gated interactions.

+ Epic #7782 · Planned +
+
+
5
+

Information architecture

+

Navigation / routes / page structure foregrounding agentic workflows.

+ Epic #7782 · Planned +
+
+
+ +
+

Dependencies & how we meet them

+
+
+
+
Dark palette
+
WCAG contrast
+
Fonts / licensing
+
+ → +
Phase 3
token values
+ → +
+
Phase 4
agentic components
+
↑ Animation + reduced-motion
+
+
+
Cross-cutting: CI Playwright/Chromium (test:storybook) · MSW for network stories
+
Accountability rule. A dependency's owner is the Epic carrying its gating phase; the accountable individual is the assignee of that Epic's dependency sub-issue, which must be cut and assigned before the gating phase's first PR opens. Every [decision] needs a named caller recorded on the owning Epic. See PROPOSAL §7.
+
+
+

Dark palette derivation

Gates Phase 3
+

Proposal: derive dark values per token by tonal shift (not inversion) in :root[data-theme="dark"]; validate in the Tokens/Colors story.

Owner: Epic #7781 · Phase-3a token-foundation PR author

+

WCAG AA contrast

Gates Phase 3
+

Proposal: validate every text/token pairing for the high-chroma palette; the Tokens story asserts computed contrast before adoption.

Owner: Epic #7781 · standing invariant, carried by the palette owner

+

Fonts & licensing

Gates Phase 3
+

Proposal: vendor Roboto Flex + Roboto Mono (OFL); drop Google Sans (not freely redistributable) — [decision] needed on the substitute.

Owner: Epic #7781 · [decision] — substitute called on #7781 before Phase 3a

+

Expressive motion

Gates Phase 4
+

Proposal: a small spring lib or spring→bezier CSS, always opt-in and prefers-reduced-motion-gated — never bypassing the static-motion policy.

Owner: Epic #7782 · [decision] — mechanism called on #7782 before Phase 4a

+

CI: Playwright/Chromium

Cross-cutting
+

Proposal: an optional, non-blocking CI job runs playwright install chromium + test:storybook; promote to required only once stable.

Owner: Epic #7038 · CI-lane owner; [decision] to promote to required

+

MSW for network stories

Cross-cutting
+

Proposal: add msw + msw-storybook-addon for the two network-backed components' happy paths; keep deterministic cache-seeding elsewhere.

Owner: Epic #7782 · Phase-4 sub-issue assignee

+
+
+ +
+

Ownership boundary

+

Design governance has exactly one owner. This package is it.

+
+ This package owns DESIGN.md, the --v2-* token architecture, the Storybook + catalog / test-harness / MCP, and .claude/rules/design-system.md. Feature packages + consume that governance rather than re-proposing it — including + docs/internal/design/oobe/, whose D-F6 “DESIGN.md + design tokens” item is + subsumed here and keeps only its pilot role: the OOBE card family is catalogued + through this system. Full boundary, including the alternative call: + PROPOSAL §9. +
+
+ +
+

Document map & how to review

+
+ + + + + + + + +
FileRole
README.mdExecutive north-star — shape, phase table, how to review.
PROPOSAL.mdThe case, invariants, alternatives, and §7 dependencies with implementation proposals.
PLAN.mdThe five phases as waves — intent, milestones, ⚠ ordering, next PRs.
CHECKLIST.mdDefinition of done — workstreams WS1–WS7, "Landed with #NNNN", final gate.
+
+
    +
  1. Skim the README for the shape and the phase table.
    2. +
  2. Read PROPOSAL §1–§4 (decision + alternatives) and §7 (dependencies) — that's where the risk lives.
    3. +
  3. Use this page for the schematics and phase map.
    4. +
  4. Challenge the CHECKLIST (right definition of done?) and argue PLAN sequencing.
    5. +
+
+ +
+ docs/internal/reborn/design-system/ · phase→Epic ownership: the canonical table in README.md · Phase 1 PR #7750 (in review) · Phase 2 #7042 (prepared) · benchmarks: the APDD kit (external, not vendored — in-repo evaluation proposed on PR #7255) and docs/internal/reborn/target-architecture (PR #6918) +
+ +
+ + + +