[blafourcade]

🎯 What & why

Second PR of the aidd-ui rework. The 01-system skill lays a design system on a blank or existing project, whatever its platforms. It extracts the norm from the code and carries a token or component change to its new versions. 01-hello goes away.

🛠️ How it works

• One norm, platform agnostic. aidd_docs/ui/ is the project's norm. An existing design system in the code is matter for extraction, then only an implementation the norm is checked against.

  • system.md ties each code root to a platform: code-roots: [web=apps/web/src, mobile=apps/mobile/src].
  • A record lists its platforms, all of them when absent.
  • code is one link per platform with the version it implements: [apps/web/Button.tsx#Button@2, apps/mobile/Button.tsx#Button@1]. implemented-version is gone.

• Responsibilities.

  • Engine hooks/aidd-ui.cjs: every rule and every deterministic write.
  • Hook hooks/ui-hook.cjs: an adapter only.
  • Skill: decides, passes inputs, reads outputs, judges.

  The engine stays in hooks/ because the CLI ships only that folder at plugin level, and later skills call it too.

• Engine commands.

  • validate.
  • tokens writes aidd_docs/ui/tokens.css.
  • extract reads the code's token files (CSS custom properties of :root, [data-theme] and @media, JS or TS literal objects) and writes tokens.json and the theme, breakpoint and platform files. It keeps every CSS name, lists what it leaves, and writes the same bytes on every run.
  • impact reports what a change reaches, plus the tokens holding the same value without aliasing it.
  • bump applies the version rules to what impact reaches, once per task.

• Themes, breakpoints and platforms are DTCG Resolver modifiers, combined by resolutionOrder.

  • A render sets data-theme and data-platform on <html> only, which V9 checks.
  • Every custom property therefore lives on the root, so each var() computes against the final values.
  • The generator writes one block per combination.

• Version guard (H8). A validated element whose text, render or token values differ from HEAD must raise its version.

• Colour literals (C4). They are found in any text file under a code root, except documents, data and images; a techno with no reader is read in its strings.

  • In a file identical to HEAD, a literal is a warning: existing debt.
  • In a changed or new file, it is an error.

• Skill in the lean format. Three phase actions, prepare, write, conclude, a single sequence for setup and change. What the model needs lives in five references, as tables.

Choices worth a veto:

• C4's severity by file state.
• Components validated by hand until the review page exists (PR 3).
• A value-only token change raising every validated element it reaches.
• Theme and platform set on <html> only.

🧪 How to verify

• node scripts/check-tests-leave-git-alone.js -- node --test 'scripts/__tests__/**/*.test.js': 1384 pass, 0 fail.
• Rules and limits: plugins/aidd-ui/README.md. Skill: SKILL.md.

Evidence:

Check	Result
Stylesheet in headless Chrome, against an independent Resolver	200 seeds × 6 resolution orders × 3 widths × 8 theme and platform combinations: 0 mismatch in 230,400 comparisons; the old generator gave 1661 mismatches on 50 seeds
Real Codex, flat install, and Haiku in Claude Code, on a web plus mobile project with a responsive web type scale, a dark theme and mobile values	extraction then a token change, 0 errors for both; their tokens.json, theme and platform files are identical
Real Codex, blank web project	setup and token change end VALID, about 30k tokens each
Gouvernail and Kairos copies, earlier skill text	0 errors (Kairos: 153 committed colour literals as warnings); impact matches a transitive grep

⚠️ Heads-up

• Gouvernail and Kairos ran an earlier skill text. They used the six-action text and had no extract or bump. Only the synthetic web plus mobile project ran the final text.
• Hook feedback on Codex is not proven. Codex writes through shell commands, which the hook does not see. No host was run on Copilot, Cursor, Kilo or OpenCode: only their flat layout was checked.
• Screens, journeys and reviews are proven by scripted tests only.
• H8 and C4 read HEAD. Committing an unraised edit or a new literal hides it from a later validate.
• Overlapping breakpoint queries stay a limit, and so does a native-only behaviour such as haptics, which no render shows.
• The other limits are written in the README.

✅ I certify

• I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XeK3mD4irAZumku9bknHhD