# Design System Optimization Roadmap — 2026-06-08

> Source: a 6-agent parallel, evidence-grounded analysis of the whole repo (process/governance,
> capability coverage, code architecture, sync/audit pipeline, repo hygiene, external benchmark).
> Driver: owner's recurring complaint — AI tools "已读不执行 / 直接跳过 / 流程连接不上".
> Principle applied: 稳健 / 真源 / 高可信 / 不猜测; uncertain items deferred, not forced.

---

## 0. Core diagnosis (one paragraph)

The failure mode is **not missing rules — it's rule sprawl + enforcement that fires only at
commit-time (or not at all) + SoT docs that contradict each other**. ~8,700 lines of mandatory
prose rules, a first-read entry doc (`STATUS.md`) that is physically un-readable in one pass
(80 KB; line 3 alone = 63 KB; a full `Read` exceeds the 25k-token cap), an onboarding gate whose
own step-count says 5/6/7 across four files, and stale/contradictory state (AGENTS.md & PROJECT_MAP.md
frozen at "2026-04-28 / v0.1" vs actual v0.7.0; FIGMA_AS_SOURCE_OF_TRUTH says the verification
manifest is "待建" when it exists at 3.3 MB). The benchmark of mature design systems (Carbon, Polaris,
Material, Changesets, Style Dictionary) gives the cure in one line: **turn rules into machine-checkable
gates — the only kind AI agents reliably respect.** Every prose rule the agent is asked to "remember"
is a coin-flip; every CI gate is deterministic.

---

## 1. ✅ Executed this turn (certain, safe, committed)

| # | Fix | Evidence it was a real defect |
|---|---|---|
| 1 | `audit:status-consistency` false-positive unblocked (STATUS.md:88 reworded so a v1.0.0-checklist row referencing "v0.7.0" + 🟡 no longer trips the stale-prep-marker regex) | The gate `process.exit(1)`s — a release cut today would have FAILED CI |
| 2 | AGENTS.md §当前阶段定位 frozen "2026-04-28 / v0.1" block → pointer to STATUS.md | Frozen ~7 versions behind reality |
| 3 | PROJECT_MAP.md §7 frozen "2026-04-28 / phase 6.2" block → pointer to STATUS.md | Same; two more drifted copies of phase state |
| 4 | FIGMA_AS_SOURCE_OF_TRUTH.md: manifest "（待建）" → "✅ 已建 (908 entries)" + link | Highest-priority doc was wrong about its own core mechanism |
| 5 | AGENTS.md onboarding gate: removed the hard-coded "5 个 todo" count (→ "每个必读项各建 1 个 todo") | Contradicted "6-step" in the same file; the count is the drift source |
| 6 | 3 fake gates made real (exit 1 on findings): `audit:icon-fill-currentcolor`, `audit:component-no-inline-svg`, `audit:tokenized-diff` | All 3 are in `prepublishOnly` but hard-coded `exit 0` → couldn't fail despite `severity:"error"` findings. Verified 0 current findings → no spurious breakage |
| 7 | Stale `Alert` divergence marked resolved (`divergences-decisions.json` + `divergences.md`) | Alert component was deleted (CANONICAL-030) but the entry still said "exists in code, pending designer confirmation" |

All gates re-verified green: status-consistency exit 0, the 3 hardened gates exit 0, translation-completeness exit 0, design-system exit 0.

---

## 2. Prioritized roadmap (needs owner direction OR multi-hour — NOT executed)

Ranked by impact-vs-effort. Each tagged with the agent evidence and a decision the owner should make.

### P0 — Structural, highest leverage

**P0-1. Split STATUS.md.** Move the 63 KB line-3 changelog blob into an append-only
`docs/internal/STATUS-CHANGELOG.md`; keep STATUS.md < ~400 lines (current version + roadmap
buckets + Active + read-chain + wrap-up + latest 1–2 entries). *Why:* it's the #1 mandatory read
and is structurally impossible to read whole → the literal mechanism behind "已读不执行".
*Owner decision:* approve the split shape (it changes the wrap-up append target).

**P0-2. Move per-component status OUT of the single hot doc → component frontmatter → generated
dashboard.** (Carbon/Polaris/USWDS pattern.) Eliminates the merge-contention chokepoint that makes
STATUS.md grow forever. Pairs with P0-1.

### P1 — Make process self-enforcing (the benchmark's core insight)

**P1-3. Require a Changeset per change (CI-enforced).** Auto changelog/versioning AND a forcing
function an agent's PR can't skip. (changesets/changesets.) Low effort, high impact.

**P1-4. ✅ SHIPPED (2026-06-09, owner chose "complete the pipeline").** `generate-tokens.mjs` rewritten
to a 3-tier in-place sync: refreshes the 54 Figma **primitive** tokens in `variables.css` (dark+light)
from `variables.json` and **preserves** the ~236 hand-authored semantic/component tokens verbatim
(was a foot-gun: old generator emitted ~80 tokens and would wipe the rest). Honest header. New
`audit:token-contract` gate (variables.css primitive tier == Figma) wired into `prepublishOnly` +
sync pipeline **Step 2.5 (generate-tokens) + Step 8.5 (contract)** — closes the previously-missing
`variables.json → variables.css` link. Verified byte-identical token values (only the header changed),
idempotent, contract PASS, vitest 219 / vue-tsc 0. *Note: runtime "lazy-load tokens by component" is
not applicable for a CSS-variable system (single `variables.css` import; vars cascade from `:root`);
the valuable "categorize by component" already exists via the file's section grouping.*

**P1-5. Bring the render-drift gate to everyday CI (Gitea), not just release (GitHub).** Today a
commit with real Figma↔code drift passes Gitea CI and is only caught at publish (possibly weeks later).
The numeric verifier is environment-independent by design → a containerized Gitea job is feasible.

**P1-6. Add the pre-commit-only gates to `prepublishOnly`** (`export-coverage`, `hard-rule-compliance`,
`icon-canonical-names`, `component-affordances`) so CI backstops them unconditionally (today they're
skippable via `--no-verify` / a non-matching staged path / a clone without husky).

**P1-7. Lightweight RFC/ADR gate for "substantial" changes** (new prop / new component / token rename /
new convention). (Carbon RFC pattern.) Make it a markdown file the change must include → machine-checkable,
so agents physically can't skip the decision step. This is the structural cure for STATUS.md line-3.

### P2 — Capability / docs role-coverage (PROJECT_GOAL commitments not yet built)

**P2-8. Docs-site QA "Status Matrix" rollout** — present in 1 of 31 pages; the state data already
renders, so it's mostly template propagation. Low effort.

**P2-9. Docs-site PM "Use Cases" segment** — 0 of 31 pages; PROJECT_GOAL §3 promised it. Needs
business-scenario content (authoring decision).

**P2-10. Surface the a11y report in main nav** — currently reachable only via shift+click on the
version chip; it's the only QA reader-surface and is undiscoverable. Trivial.

**P2-11. Add T4b manifest fields** (`directions`, `compositionSupport`) to `components.manifest.json`
— composition rules already exist in `component-affordances.md`; this makes page-level AI composition
machine-readable. Safe data enrichment (file via versioned executor prompt per the collaboration loop).

**P2-12. Code Connect strategy under Figma Professional.** Only 1 `.figma.ts` exists (placeholder URL).
Publish is plan-blocked, but *authoring* local `.figma.ts` + `reverseGenerationHints` is not — it unlocks
traceability (capability 5) and the future code→figma generator (capability 3). **Owner decision:** author
all 34 now vs defer to a plan upgrade.

**P2-13. Reconcile PROJECT_GOAL with the skills layer.** The 12 `skills/*` deliver 7 of the owner's 9
role dimensions (persona testing, design QA, PM/PRD, discovery…) but PROJECT_GOAL doesn't mention them —
a new agent reading only PROJECT_GOAL would wrongly conclude those capabilities are missing.

### P3 — Hygiene / debt (mostly archive, not delete)

**P3-14. Compact hand-offs:** 30 `next-session-pickup-*.md` at top level (only the newest is live;
7 already in `_plans/archived/`). Move the ~22 superseded ones to `archived/` (precedent exists),
update STATUS.md's 8 inbound links. **Archive, not delete** (history-bearing, cross-referenced).

**P3-15. Compaction policy for `_prompts/` (144 files / 1.9 MB) and one-shot drafts** — long-merged
executor prompts → `_prompts/archived/`. Not script-referenced (safe), but cross-linked from plans →
move, don't delete.

**P3-16. Consolidate the two icon taxonomies** (`src/icons/generated` eager vs `src/icons/catalog`
lazy; 10 overlapping categories, both ship SVG bytes). **Owner decision:** pick the authoritative one
(likely catalog — newer, lazy) and trim the other to a documented core; confirm external consumers of
`IconAdd`-style exports first.

**P3-17. Local junk** (gitignored, repo-neutral): `*.tgz` (1.4 MB), 20×`.DS_Store`, optional 262 MB
`figma-data/mockup/` cache (regenerable, re-fetched on next sync). Working tree is otherwise clean of
committed strays; `Select.vue` is a LIVE import — do NOT delete.

---

## 3. Adopt-from-mature-systems shortlist (benchmark, cited)

1. **DTCG/W3C design-token format** as the on-disk intermediate (stable since 2025-10), built by
   **Style Dictionary v4** — replaces ad-hoc extract. (Adobe/Google/Shopify-backed.)
2. **3-tier token taxonomy** primitive → semantic → component (add the explicit component tier so AI
   binds components to component tokens, never raw primitives).
3. **Playwright VRT gate on every component story** (plan-independent; the highest-leverage drift guard).
4. **Component lifecycle** experimental → stable → deprecated, "stable" gated by audit + VRT + a11y
   (gives agents a concrete "done"). (Carbon.)
5. **Per-component docs sections**: Best-practices/Do-Don't + Accessibility (keyboard+ARIA) + status badge
   (serves design/PM/QA on the same page). (Polaris/Carbon.)
6. **Lintable API contract**: no boolean-prop sprawl (compose instead), no `is/has` prefixes,
   `on[Subject]Verb` events, identical Figma↔code names. (Statically checkable in Vue `emits`/`props`.)

**Cross-cutting theme:** for a solo+AI shop, the systems that scale aren't the ones with the most rules
— they're the ones that convert rules into CI gates. That turns "agents skip process" from a
documentation problem into a CI problem, which is the only kind agents reliably respect.

---

## 4. Evidence index (for re-verification)

- Process: `docs/STATUS.md:3` (63 KB line), `AGENTS.md:58/67` (step-count), `.claude/hooks/onboarding-checklist.sh` (omits FIGMA_SOT step 0), `docs/internal/retrospection/2026-06-01-rule-execution-discipline-gap.md` (37.5% rule-execution rate).
- Gates: `figma-sync/audit-{icon-fill-currentcolor,component-no-inline-svg,no-hardcoded-design-tokens,component-token-linkage,tokenized-diff}.mjs` (exit-0 hard-codes), `.gitea/workflows/pr-checks.yml` vs `.github/.../publish.yml` (render-gate only at release), `figma-sync/generate-tokens.mjs` (54 vs 290 tokens).
- Capability: `playground/docs/pages/*` (Status Matrix in 1/31, Use Cases 0/31), `playground/docs/navigation.ts` (a11y hidden), `src/components/Badge/Badge.figma.ts` (sole Code Connect, placeholder URL), `figma-data/normalized/components.manifest.json` (no `directions`/`compositionSupport`).
- Architecture: `src/index.ts` + `src/canonical/*` (dual-source clean), `src/canonical/index.ts` (drifted barrel), `src/icons/{generated,catalog/generated}` (two taxonomies).
- Hygiene: `docs/internal/_plans/*` (30 pickups), `docs/internal/_prompts/*` (144), `src/components/Select/Select.vue` (LIVE — Pagination/App import it).