From d3308602eef08b93e6e754e5a6d6adf68bae9f34 Mon Sep 17 00:00:00 2001 From: scotttong Date: Mon, 6 Jul 2026 21:58:39 -0700 Subject: [PATCH] docs: move design-process artifacts to doc/design/ DESIGN.md stays at root (AGENTS.md links it); audit reports, decision sheet, prior art, and run prompts move out of the repo root. Co-Authored-By: Claude Fable 5 --- .claude/agents/codemod-runner.md | 2 +- .claude/agents/token-auditor.md | 4 ++-- DESIGN.md | 4 ++-- COMPONENT-INVENTORY.md => doc/design/COMPONENT-INVENTORY.md | 0 DECISION-SHEET.md => doc/design/DECISION-SHEET.md | 0 GOAL-PROMPT.md => doc/design/GOAL-PROMPT.md | 0 KNOWN-DUPLICATES.md => doc/design/KNOWN-DUPLICATES.md | 0 PRIOR-ART.md => doc/design/PRIOR-ART.md | 0 TOKEN-AUDIT.md => doc/design/TOKEN-AUDIT.md | 0 9 files changed, 5 insertions(+), 5 deletions(-) rename COMPONENT-INVENTORY.md => doc/design/COMPONENT-INVENTORY.md (100%) rename DECISION-SHEET.md => doc/design/DECISION-SHEET.md (100%) rename GOAL-PROMPT.md => doc/design/GOAL-PROMPT.md (100%) rename KNOWN-DUPLICATES.md => doc/design/KNOWN-DUPLICATES.md (100%) rename PRIOR-ART.md => doc/design/PRIOR-ART.md (100%) rename TOKEN-AUDIT.md => doc/design/TOKEN-AUDIT.md (100%) diff --git a/.claude/agents/codemod-runner.md b/.claude/agents/codemod-runner.md index 66fa7c4be0..3fafe19b69 100644 --- a/.claude/agents/codemod-runner.md +++ b/.claude/agents/codemod-runner.md @@ -14,4 +14,4 @@ Rules: - Every rewrite happens through a codemod script committed to scripts/ before it is run. Scripts must be idempotent and reviewable. - Third-party style overrides that cannot use tokens go on a documented allowlist in the token source, each with an inline comment saying why. - Verify after every script run: rg gates (zero hardcoded hex, zero arbitrary px/bracket values in ui/src/components/** and ui/src/pages/** outside the allowlist), pnpm typecheck, and the Storybook snapshot suite. Snapshots must match the Phase 0 baseline exactly. -- If a replacement cannot be made without visual change, skip it and record it in TOKEN-AUDIT.md under "Needs human decision". +- If a replacement cannot be made without visual change, skip it and record it in doc/design/TOKEN-AUDIT.md under "Needs human decision". diff --git a/.claude/agents/token-auditor.md b/.claude/agents/token-auditor.md index e2c0922aaa..07561c8052 100644 --- a/.claude/agents/token-auditor.md +++ b/.claude/agents/token-auditor.md @@ -1,11 +1,11 @@ --- name: token-auditor -description: Scans ui/src/ for hardcoded visual values, duplicate components, and shadcn replacement candidates; produces TOKEN-AUDIT.md and COMPONENT-INVENTORY.md. Read-only on source — never modifies component files. Use for Phase 1 of the design simplification run. +description: Scans ui/src/ for hardcoded visual values, duplicate components, and shadcn replacement candidates; produces doc/design/TOKEN-AUDIT.md and doc/design/COMPONENT-INVENTORY.md. Read-only on source — never modifies component files. Use for Phase 1 of the design simplification run. tools: Read, Grep, Glob, Bash model: sonnet --- -You inventory design-system debt in this repository. Follow DESIGN.md at the repo root; read PRIOR-ART.md first — a previous audit found only 6 of ~220 drift sites were exact-value-mappable to existing tokens, so expect most hardcoded values to need new verbatim tokens. +You inventory design-system debt in this repository. Follow DESIGN.md at the repo root; read doc/design/PRIOR-ART.md first — a previous audit found only 6 of ~220 drift sites were exact-value-mappable to existing tokens, so expect most hardcoded values to need new verbatim tokens. Your outputs (written to the repo root): diff --git a/DESIGN.md b/DESIGN.md index 4e5609fc90..8ff8a57852 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -27,7 +27,7 @@ Existing tiers already in index.css (~80+ tokens) — extraction maps to these o ## Principles 1. **One way to say each thing.** One component per job. One Button, one Card, one Badge, one Table, one EmptyState. Variants are props, not new components. Before creating a component, prove no existing one covers the job. -2. **Tokens are the only source of visual values.** All color, spacing, radius, type size/weight, shadow, and motion values come from the token layer. No hex, no raw px, no ad-hoc Tailwind arbitrary values (`p-[13px]`) in components. If a needed value doesn't exist, add a token — don't inline it. Tailwind palette classes (`bg-red-500`, `text-zinc-400`, etc.) ARE hardcoded values in spirit: they name a literal color, not a semantic role. They are in-scope debt scheduled for a dedicated future run (Run 4, cluster-by-cluster mapping to semantic tokens per DECISION-SHEET.md B2) and are not currently gated by check-token-gates. Exception (DECISION-SHEET.md B1 user ruling): first-party intentional one-off decoration on demo/UX-lab surfaces stays inline and allowlisted rather than minted as singleton tokens. +2. **Tokens are the only source of visual values.** All color, spacing, radius, type size/weight, shadow, and motion values come from the token layer. No hex, no raw px, no ad-hoc Tailwind arbitrary values (`p-[13px]`) in components. If a needed value doesn't exist, add a token — don't inline it. Tailwind palette classes (`bg-red-500`, `text-zinc-400`, etc.) ARE hardcoded values in spirit: they name a literal color, not a semantic role. They are in-scope debt scheduled for a dedicated future run (Run 4, cluster-by-cluster mapping to semantic tokens per doc/design/DECISION-SHEET.md B2) and are not currently gated by check-token-gates. Exception (doc/design/DECISION-SHEET.md B1 user ruling): first-party intentional one-off decoration on demo/UX-lab surfaces stays inline and allowlisted rather than minted as singleton tokens. 3. **Spacing routes through tokens; the scale comes later.** During simplification, extract every spacing and radius value verbatim into tokens — do not normalize, round, or invent a scale. The final scale is a design decision made by a human after reviewing the token audit. Structural rules apply now: vertical rhythm within a container uses one gap value, not per-element margins, and siblings never carry both margin and gap. 4. **Hierarchy through structure, not decoration.** Prefer position, size, and weight over borders, backgrounds, and dividers. Every border, divider, and background fill must justify itself; when in doubt, remove it. A screen should survive the removal of one visual layer. 5. **Status is systematic.** States like running / paused / blocked / awaiting-approval / over-budget map to a single semantic status token set used identically everywhere (badge, row, chart, log). An operator learns the vocabulary once. @@ -53,4 +53,4 @@ No visual redesign, no new colors or typefaces, no layout restructuring, no new ## Prior art (read before auditing) -See `PRIOR-ART.md` — a previous audit pass (PAP-280/283/284, on the `PAP-282-playground` branch, NOT on master) found that of ~220 hardcoded drift sites, only 6 were exact-value-mappable to existing tokens; expect the verbatim extraction to mint many new tokens that the human scale-collapse step later merges. It also drafted usage rules (radius tiers, CTA tiers, named type styles) that are good candidates for the post-audit scale decision. +See `doc/design/PRIOR-ART.md` — a previous audit pass (PAP-280/283/284, on the `PAP-282-playground` branch, NOT on master) found that of ~220 hardcoded drift sites, only 6 were exact-value-mappable to existing tokens; expect the verbatim extraction to mint many new tokens that the human scale-collapse step later merges. It also drafted usage rules (radius tiers, CTA tiers, named type styles) that are good candidates for the post-audit scale decision. diff --git a/COMPONENT-INVENTORY.md b/doc/design/COMPONENT-INVENTORY.md similarity index 100% rename from COMPONENT-INVENTORY.md rename to doc/design/COMPONENT-INVENTORY.md diff --git a/DECISION-SHEET.md b/doc/design/DECISION-SHEET.md similarity index 100% rename from DECISION-SHEET.md rename to doc/design/DECISION-SHEET.md diff --git a/GOAL-PROMPT.md b/doc/design/GOAL-PROMPT.md similarity index 100% rename from GOAL-PROMPT.md rename to doc/design/GOAL-PROMPT.md diff --git a/KNOWN-DUPLICATES.md b/doc/design/KNOWN-DUPLICATES.md similarity index 100% rename from KNOWN-DUPLICATES.md rename to doc/design/KNOWN-DUPLICATES.md diff --git a/PRIOR-ART.md b/doc/design/PRIOR-ART.md similarity index 100% rename from PRIOR-ART.md rename to doc/design/PRIOR-ART.md diff --git a/TOKEN-AUDIT.md b/doc/design/TOKEN-AUDIT.md similarity index 100% rename from TOKEN-AUDIT.md rename to doc/design/TOKEN-AUDIT.md