From fca1cebdc03f5a6b48b46dd947a108baf3e954eb Mon Sep 17 00:00:00 2001
From: Baptiste LAFOURCADE
Date: Fri, 30 Oct 2026 12:15:02 +0100
Subject: [PATCH 01/26] docs(aidd-ui): frame the ui plugin rework
Co-Authored-By: Claude Opus 5.5
---
.../2026_10_30_aidd-ui-rework/brainstorm.md | 71 +++++++++++++++++++
1 file changed, 71 insertions(+)
create mode 100644 aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/brainstorm.md
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/brainstorm.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/brainstorm.md
new file mode 100644
index 000000000..128dd1f7e
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/brainstorm.md
@@ -0,0 +1,71 @@
+---
+status: approved
+---
+
+# aidd-ui : un design system qui vit avec le code
+
+Pour un dev qui conçoit l'UI avec une IA : le plugin crée, fait évoluer et versionne un design system, et le relie aux écrans et au code, pour que chaque changement soit tracé et propagé sans travail manuel.
+
+## Clair
+
+### Périmètre
+
+- Tout est dans le périmètre de la première version, versionnage par élément compris. Les étapes forment une seule chaîne, pas des outils séparés.
+- La chaîne : marque et identité (projet, utilisateurs, domaine, plateformes), tokens, atomes, molécules, compositions, parcours et wireframes, écrans finis, code.
+- La marque part du contexte réel (utilisateurs, domaine, plateformes), pas d'un style par défaut.
+- Deux points de départ : un projet vierge, où le DS est construit, et un projet existant, où le DS est extrait du code.
+- Les skills suivent le format lean de brainstorm, plan et implement : chaque mot a sa place.
+
+### Emplacement
+
+- Tout vit dans `aidd_docs/ui/`, un dossier dédié avec un fichier par élément. Les parcours vont dans `ui/journeys/`. Rien n'est posé à côté du code.
+- L'IA écrit les fiches, chacune suivant son template : token, atome, molécule, composition, écran, parcours.
+- Les artefacts ne dépendent d'aucune techno. Les tokens suivent le format W3C DTCG 2025.10. Figma et Claude Design se branchent, le contrat du projet fait foi.
+
+### Lien
+
+- Le lien entre le design system, les écrans et le code est le cœur du plugin. On relie composants et écrans, pas chaque token.
+- Chaque élément correspond à un seul fichier de code, identifié par son chemin et le nom du composant.
+- Les usages se lisent dans les compositions du DS, et le rapport d'impact remonte cet arbre.
+
+### Feature
+
+- Chaque feature a son `ui.md`, le contrat UI de la feature. Une fois la feature implémentée, le code est vérifié contre ce contrat et l'index est mis à jour.
+- Quand un élément change : rapport d'impact, validation, régénération de ce qui est touché, nouvelle validation si besoin, puis nouvelle version du DS.
+
+### Vitrine
+
+- Un script génère la vitrine à partir des fiches et de templates HTML fixes, sans IA : le rendu est identique à chaque fois et se régénère à volonté.
+- Elle montre les éléments, leurs liens et l'endroit où chacun est utilisé.
+- Les écrans y apparaissent dans leur version validée, la maquette HTML créée par l'IA avec les vrais tokens, et chacun porte un lien vers le réel (route ou fichier).
+
+### Vérifications
+
+- Des scripts Node déterministes, qui tournent partout sans IA, vérifient le format de chaque fichier généré (écrans HTML compris), un lien vers un fichier absent, un fichier UI absent de l'index, une composition qui utilise un élément inexistant, et une valeur en dur dans le code.
+- Une fiche mal formée bloque la construction de la vitrine.
+- Des hooks (`SessionStart`, `PostToolUse` sur `aidd_docs/ui/`) lancent ces scripts. Ce sont les mêmes scripts qu'on lance à la main, donc ils marchent aussi dans les outils sans hooks.
+- L'IA juge le sens : le code fait-il ce que dit le `ui.md` ?
+
+### Audit et review
+
+- L'audit UI appartient au plugin. Il constate et ne corrige rien. Il compare le validé et le réel : capture d'écran sur le web, fiche contre code ailleurs. Le volet UI de l'audit dev est retiré une fois cet audit en place.
+- La review design se fait dans une page HTML interactive : OK ou pas OK par écran, avec un commentaire, et les verdicts sont enregistrés dans un fichier du projet. Quand l'utilisateur dit qu'il a fini, l'IA lit le fichier et continue.
+- La review code reste dans dev. L'accessibilité fait partie du plugin.
+
+### Signal de réussite
+
+Sur un projet vierge comme sur un projet existant :
+
+- le flow complet passe de bout en bout jusqu'à tous les écrans voulus ;
+- les features générées ensuite sont liées, sans dérive, et testées ;
+- les mises à jour et le cycle de vie s'enchaînent de façon cohérente.
+
+## Supposé
+
+- On repart de zéro et l'ancienne PR aidd-ui est fermée. Seules ses idées sont gardées : boucle delta, ordre de priorité entre sources, classes de dérive.
+- La vitrine s'inspire d'un outil propriétaire vu en démo : DS, liens et usages visibles, tout normé et vérifié par script.
+- Le réel n'est rendu que sur le web. Ailleurs, l'audit compare la fiche au code.
+
+## Ouvert
+
+- Projet pilote : Gouvernail ou Keros pour le cas vierge. Le cas existant demande un projet qui a déjà du code UI.
From 67b659c55665dcecb1a9ee22794aba45f6183492 Mon Sep 17 00:00:00 2001
From: Baptiste LAFOURCADE
Date: Fri, 30 Oct 2026 14:39:03 +0100
Subject: [PATCH 02/26] docs(aidd-ui): specify the ui plugin rework and its
roadmap
Co-Authored-By: Claude Opus 5.5
Claude-Session: https://claude.ai/code/session_01XeK3mD4irAZumku9bknHhD
---
.../2026_10_30_aidd-ui-rework/roadmap.md | 33 ++++
.../2026_10/2026_10_30_aidd-ui-rework/spec.md | 147 ++++++++++++++++++
2 files changed, 180 insertions(+)
create mode 100644 aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/roadmap.md
create mode 100644 aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/spec.md
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/roadmap.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/roadmap.md
new file mode 100644
index 000000000..4a1410d59
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/roadmap.md
@@ -0,0 +1,33 @@
+# aidd-ui : feuille de route
+
+Cinq pull requests empilées, chacune planifiée, codée et revue à son tour. Le contrat est dans [spec.md](./spec.md).
+
+## Skills
+
+| Skill | Fait | Produit |
+| --- | --- | --- |
+| `01-system` | pose la marque, les tokens, les assets et les composants, depuis rien ou en les extrayant du code ; conduit un changement de l'impact jusqu'aux nouvelles versions | `system.md`, `brand.md`, `tokens.json`, `assets/`, `components/` |
+| `02-screens` | dessine les parcours, les wireframes puis les écrans avec leurs états | `journeys/`, `screens/` |
+| `03-review` | ouvre la page de review et reprend à partir des verdicts | `reviews/` |
+| `04-feature` | écrit le `ui.md` d'une feature, puis vérifie son code et met à jour les liens | `ui.md` dans le dossier de la tâche |
+| `05-audit` | constate les écarts sans rien corriger | un rapport |
+
+Un skill ne nomme jamais un autre skill.
+
+La vérification est un hook, déclenché à chaque écriture dans `aidd_docs/ui/` : chaque skill en hérite et voit l'erreur pendant qu'il travaille. Elle se lance aussi à la main. Chaque skill porte ses propres scripts de génération : `tokens.css` pour `01-system`, la vitrine pour `02-screens`, la page de review pour `03-review`.
+
+`01-hello` disparaît avec la PR 2.
+
+## Pull requests
+
+| # | Contenu | Fini quand |
+| --- | --- | --- |
+| 1 | Socle : règles de chaque fiche, vérification complète en hook et à la main | chaque règle de la spec a un cas qui la fait échouer ; un projet exemple complet passe |
+| 2 | `01-system` : marque, tokens, assets, composants, extraction depuis le code, génération de `tokens.css`, flux de changement | sur le pilote vierge, puis sur Gouvernail et Kairos, le design system est posé, puis un changement de token produit son impact et ses versions |
+| 3 | `02-screens`, `03-review`, vitrine | sur le pilote vierge, tous les écrans voulus sont validés en review, vitrine générée deux fois identique |
+| 4 | `04-feature`, et la lecture du `ui.md` par le plan et l'implémentation | une feature du pilote passe du `ui.md` au code vérifié, liens à jour |
+| 5 | `05-audit`, retrait du volet UI de l'audit dev | l'audit du pilote signale chaque écart semé exprès, et rien d'autre |
+
+## Limites connues
+
+- Le retour du hook à l'agent est garanti sur Claude Code. Codex ne lance le hook qu'une fois approuvé ; Kilo et opencode perdent sa sortie ; Cursor et Copilot le lancent sur chaque outil. Ailleurs, la commande à la main est la garantie.
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/spec.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/spec.md
new file mode 100644
index 000000000..8a39fb546
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/spec.md
@@ -0,0 +1,147 @@
+# aidd-ui : un design system qui vit avec le code
+
+## Target
+
+Dans un projet, un dev qui conçoit l'UI avec une IA obtient un design system versionné, relié à ses écrans et à son code, dont chaque changement est tracé, propagé et vérifiable sans IA.
+
+## Hard constraints
+
+### Arborescence
+
+Tout le design system vit dans `aidd_docs/ui/`, un fichier par élément, rien à côté du code.
+
+```txt
+aidd_docs/ui/
+├── system.md racine du design system
+├── brand.md identité de marque
+├── tokens.json tokens, format W3C DTCG 2025.10
+├── tokens.css généré depuis tokens.json, jamais écrit à la main
+├── assets/.md icône, image, illustration, avec son fichier à côté
+├── components/.md atome, molécule ou composition
+├── components/.html rendu du composant, toutes variantes et tous états
+├── screens/.md écran
+├── screens/.html maquette de l'écran, tous ses états dans un seul fichier
+├── journeys/.md parcours utilisateur
+├── reviews/.md verdicts d'une review du design system
+└── showcase/ vitrine générée, jamais écrite à la main, ignorée par git
+```
+
+Le contrat UI d'une feature, `ui.md`, vit dans le dossier de sa tâche, à côté du plan. Il n'est jamais versé dans `aidd_docs/ui/`.
+
+### Fiches
+
+Chaque fiche porte en tête : `id` (égal au nom du fichier, unique), `kind`, `status`, `version`.
+
+| Fiche | Contient en plus |
+| --- | --- |
+| `system.md` | version du design system, plateformes, breakpoints, thèmes, langues et sens d'écriture, dossiers UI du code, chemins ignorés, librairies de composants utilisées |
+| `brand.md` | projet, utilisateurs, domaine, plateformes, personnalité et ton, charte imposée s'il y en a une, références et anti-références |
+| asset | type (icône, image, illustration), fichier, texte alternatif attendu |
+| atome, molécule, composition | éléments utilisés, tokens utilisés, variantes, états (au moins défaut, survol, focus, désactivé, et chargement ou erreur quand ils existent), comportement clavier et rôle accessible, lien vers le code |
+| écran | éléments utilisés, états (au moins défaut, vide, chargement, erreur, sans droits quand ils existent), breakpoints couverts, route ou fichier réel, lien vers le code |
+| parcours | persona, étapes ordonnées, chaque étape un écran et l'action qui mène à la suivante |
+| review | écrans revus, verdict OK ou pas OK par écran et par état, commentaire, écrans restants |
+
+### Cycle de vie
+
+- `proposé` : créé, pas encore validé.
+- `validé` : rendu approuvé en review.
+- `codé` : un lien vers le code existe et le validateur le confirme.
+- `déprécié` : ne doit plus être utilisé, nomme son remplaçant ou dit pourquoi il n'en a pas.
+- Le lien vers le code est obligatoire à `codé`, facultatif avant.
+- Modifier un élément `codé` le repasse à `proposé` le temps de la review ; il redevient `codé` quand le code suit sa nouvelle version.
+- Un élément non déprécié n'utilise jamais un élément déprécié.
+
+### Lien avec le code
+
+- Un élément correspond à un seul fichier de code, identifié par son chemin et le nom du composant exporté.
+- Un composant de librairie est lié à son paquet et à son nom exporté.
+- Chaque fichier sous un dossier UI déclaré est lié à une fiche ou couvert par un chemin ignoré.
+- Les usages se lisent dans les fiches : un token mène aux composants qui le déclarent, un composant aux compositions et écrans qui l'utilisent, un écran aux parcours, chaque élément à son fichier de code. Le rapport d'impact suit ce chemin.
+
+### Versions et historique
+
+- Chaque élément a une version entière et un historique : une ligne par version, avec le changement, s'il est cassant, et la tâche qui l'a fait.
+- Est cassant : retirer une variante, un état ou une propriété, renommer ou supprimer un token, déprécier un élément.
+- Le design system a sa propre version dans `system.md` : un changement cassant monte la majeure, un autre la mineure.
+- Deux lignes d'historique qui revendiquent la même version d'un élément sont signalées, pour que la personne tranche, comme un conflit git.
+
+### Changements
+
+- Un changement produit d'abord un rapport d'impact : éléments, écrans, parcours et fichiers de code touchés.
+- Après validation, les rendus HTML touchés sont régénérés, revus si leur aspect change, puis versions et historiques sont mis à jour.
+- Le code suit dans la feature qui porte le changement, jamais en dehors.
+
+### Feature
+
+- Une feature qui touche l'UI a son `ui.md` : écrans et éléments réutilisés, créés ou modifiés, et ce que le code doit respecter.
+- Une feature sans UI n'en a pas, et rien ne se déclenche.
+- Une feature qui ne fait que réutiliser ne change aucune version.
+- Une fois la feature implémentée, son code est vérifié contre son `ui.md` et les liens vers le code sont mis à jour.
+
+### Rendus
+
+- Écrans et composants sont rendus en HTML avec les vrais tokens, sans valeur en dur.
+- Un écran montre tous ses états dans un seul fichier, avec un sélecteur d'état.
+- La vitrine est générée sans IA, à partir des fiches et de gabarits fixes : identique à chaque génération, elle montre chaque élément, ses variantes, ses états, ses usages et son lien vers le réel.
+- La vitrine affiche la version validée d'un écran et un lien vers le réel.
+
+### Review
+
+- La review design se fait dans une page HTML : OK ou pas OK par écran et par état, avec un commentaire.
+- Les verdicts sont enregistrés dans une fiche review, qui vit avec ce qu'elle revoit : `aidd_docs/ui/reviews/` pour une review du design system, le dossier de la tâche pour une review de feature. Quand la personne dit qu'elle a fini, l'IA lit la fiche et continue.
+- Une review partielle garde les écrans restants, et l'IA reprend là où elle s'est arrêtée.
+
+### i18n et accessibilité
+
+- `system.md` déclare les langues et les sens d'écriture.
+- Les rendus utilisent des propriétés logiques plutôt que physiques quand un sens droite-gauche est déclaré, et aucune largeur fixe sur du texte.
+- Dates et nombres suivent la langue.
+- Base d'accessibilité : WCAG 2.2 AA, mobile d'abord, tailles en `rem`, aucun comportement qui n'existe qu'au survol sur écran tactile.
+
+### Vérification
+
+- La structure se vérifie à chaque écriture dans le design system, quel que soit le skill qui écrit, et à la main, par des scripts déterministes, sans IA, qui tournent sur toute machine où tourne Node :
+ - format de chaque fiche et du fichier de tokens ;
+ - éléments utilisés et alias de tokens qui existent ;
+ - cycle de vie respecté ;
+ - liens vers le code valides, couverture des dossiers UI ;
+ - aucune valeur en dur dans les rendus ni dans le code ;
+ - versions en double dans un historique ;
+ - propriétés physiques quand un sens droite-gauche est déclaré.
+- L'IA juge le sens : le code fait-il ce que disent `ui.md` et les fiches ?
+- L'audit UI constate et ne corrige rien : élément sans code, code sans élément, écart entre le validé et le réel, doublons proches, textes trop longs dans la langue la plus longue, accessibilité.
+
+### Format
+
+- Les skills suivent le format lean de brainstorm, plan et implement.
+- Les artefacts ne dépendent d'aucune techno ; Figma et Claude Design se branchent, le contrat du projet fait foi.
+
+## Non-goals
+
+- Plusieurs design systems dans un projet, ou une app web et une app mobile avec deux systèmes.
+- Un composant réparti sur plusieurs fichiers.
+- Synchronisation dans les deux sens avec Figma ou Claude Design, et import de maquettes existantes.
+- Retour à une version précédente du design system.
+- Travail à plusieurs, et parcours pour un designer qui ne code pas.
+- Rendu du réel hors web.
+- Détection des valeurs en dur dans du code non web.
+
+## Done-when
+
+- Sur un projet vierge puis sur un projet existant, le flow passe de la marque jusqu'à tous les écrans voulus, chacun validé en review.
+- Les features générées ensuite sont liées au design system, sans dérive, et leur code est vérifié.
+- Un changement de token, de composant et d'écran produit chacun son rapport d'impact, ses régénérations et ses nouvelles versions, sans élément oublié.
+- Deux features parallèles sur le même élément aboutissent à une version en double signalée.
+- La vitrine générée deux fois de suite est identique.
+- Chaque règle de vérification a un cas qui la fait échouer.
+- Sur Gouvernail et Kairos, le design system est extrait du code existant.
+
+## Open Questions
+
+- TBD: quel projet pilote pour le cas vierge, sachant que Gouvernail et Kairos, pilotes du cas existant, ont déjà une identité ?
+
+## Context
+
+- Brief approuvé : [brainstorm.md](./brainstorm.md).
+- Découpage en pull requests : [roadmap.md](./roadmap.md).
From 9db5c887bc58093237dd16c9aa5fb6707b2a36d6 Mon Sep 17 00:00:00 2001
From: Baptiste LAFOURCADE
Date: Fri, 30 Oct 2026 14:50:05 +0100
Subject: [PATCH 03/26] docs(aidd-ui): plan the ui foundation validator
Co-Authored-By: Claude Opus 5.5
Claude-Session: https://claude.ai/code/session_01XeK3mD4irAZumku9bknHhD
---
.../2026_10_30_aidd-ui-foundation/phase-1.md | 122 ++++++++++++++++++
.../2026_10_30_aidd-ui-foundation/phase-2.md | 77 +++++++++++
.../2026_10_30_aidd-ui-foundation/phase-3.md | 64 +++++++++
.../2026_10_30_aidd-ui-foundation/phase-4.md | 88 +++++++++++++
.../2026_10_30_aidd-ui-foundation/plan.md | 56 ++++++++
5 files changed, 407 insertions(+)
create mode 100644 aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-1.md
create mode 100644 aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-2.md
create mode 100644 aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-3.md
create mode 100644 aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-4.md
create mode 100644 aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/plan.md
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-1.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-1.md
new file mode 100644
index 000000000..c760e59ce
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-1.md
@@ -0,0 +1,122 @@
+---
+status: pending
+---
+
+# Instruction: Records and history
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+.
+├── plugins/aidd-ui/hooks/lib/
+│ ├── markdown.cjs ✅
+│ ├── project.cjs ✅
+│ ├── records.cjs ✅
+│ └── history.cjs ✅
+└── scripts/__tests__/
+ ├── aidd-ui-records.test.js ✅
+ └── fixtures/
+ ├── README.md ✏️
+ └── aidd-ui/
+ └── project.js ✅
+```
+
+## Test Scope
+
+| Scenario | Action | Observable outcome | Actor |
+| ------------ | ----------------------- | -------------------- | ------------------------------- |
+| Setup | `writeProject(tmp)` from `fixtures/aidd-ui/project.js` | a complete valid project: every record kind, tokens, renders, code under `src/ui/` | system |
+| Happy path | `records.check(load(tmp))` and `history.check(load(tmp))` | both return `[]` | system |
+| Edge case | R1: a record without front matter, or a line that is neither `key: value` nor `key: [a, b]` | one problem naming the file and the line | system |
+| Edge case | R2: `kind: widget`, or an atom under `screens/` | one problem: unknown kind, or kind outside its folder | system |
+| Edge case | R3: a required key removed, per kind; `status: done`; `interactive: maybe`; asset `type: photo` | one problem naming the missing key or the bad value | system |
+| Edge case | R4: `id` differs from the file name; two records with the same `id` | one problem each | system |
+| Edge case | R5: `version: 0` or `v2` on an element; `version: 1.0` on `system.md` | one problem each: element integer from 1, system semver | system |
+| Edge case | R6: `uses` names an absent id; an atom uses an atom; a molecule uses a composition; a screen uses a screen | one problem each | system |
+| Edge case | R7: an interactive component without `hover`, `focus` or `disabled`; a component without `default`; a screen without `default`; an interactive component without `## Keyboard` | one problem each | system |
+| Edge case | R8: `status: coded` without `code` | one problem | system |
+| Edge case | R9: `deprecated` without `replaced-by`; `replaced-by` absent or deprecated; `replaced-by: none` without `## Deprecation` | one problem each | system |
+| Edge case | R10: a non-deprecated record uses a deprecated one | one problem naming both | system |
+| Edge case | R11: a screen breakpoint missing from `system.md` | one problem | system |
+| Edge case | R12: a journey step naming an absent screen | one problem | system |
+| Edge case | R13: a review missing a row for one screen state; `Verdict` not `ok`, `ko` or `pending` | one problem each | system |
+| Edge case | R14: `brand.md` without one of its seven headings | one problem naming the heading | system |
+| Edge case | R16: `system.md`, `brand.md` or a review with `status: coded` or `deprecated` | one problem: only `proposed` or `validated` | system |
+| Edge case | R15: an asset whose `file` is absent | one problem | system |
+| Edge case | H1: a versioned record without `## History` | one problem | system |
+| Edge case | H2: two rows for version 2, as after a merge of two branches | one problem: two changes claim version 2, renumber | system |
+| Edge case | H3: front matter `version` not the highest row; a gap from 1 to 3 | one problem each | system |
+| Edge case | H4: `Breaking` neither `yes` nor `no` | one problem | system |
+| Edge case | H5: a task with a breaking element row and no major bump in `system.md`; a task with only non-breaking rows whose `system.md` row raises nothing; a task in an element history with no `system.md` row | one problem each, naming the task | system |
+| Edge case | H6: a `deprecated` record whose last history row says `Breaking: no` | one problem | system |
+| Teardown | remove `tmp` | no file left | system |
+
+## Tasks to do
+
+### `1)` Fixture project
+
+> One complete valid project every phase mutates.
+
+1. Export `writeProject(dir)` writing:
+ - Every record holds `id`, `kind`, `status`, `version` and a `## History` table (Version, Change, Breaking, Task); every element's first row is task `ds-init`.
+ - `aidd_docs/ui/system.md`: `id: system`, `kind: system`, `status: validated`, `version: 2.0.0`, `platforms: [web]`, `breakpoints: [mobile, desktop]`, `themes: [light, dark]`, `locales: [fr, ar]`, `directions: [ltr, rtl]`, `code-roots: [src/ui]`, `ignore: [src/ui/tokens.css]`, `libraries: [@radix-ui/react-dialog]`; a `## Breakpoints` table; `## History` rows `1.0.0` for task `ds-init`, `2.0.0` for task `retire-old-button`.
+ - `aidd_docs/ui/brand.md`: `id: brand`, `kind: brand`, `status: validated`, `version: 1`; headings `## Project`, `## Users`, `## Domain`, `## Platforms`, `## Personality and tone`, `## References`, `## Anti-references`, optional `## Imposed charter`.
+ - `aidd_docs/ui/tokens.json`: `color.brand.primary` (srgb, dark theme extension), `color.text.default` aliasing it, `space.md` (rem), `border.thin` (`0.0625rem`), `motion.fast` (ms), `font.body` (family list), `font.weight.bold` (700).
+ - `aidd_docs/ui/assets/icon-search.md` with `icon-search.svg`.
+ - `aidd_docs/ui/components/`, each with `tokens`, `variants`, `states`, `role` and its `.html` render carrying a `data-variant` per variant, a `data-state` per state, tokens through `var(--...)` only, logical properties only:
+ - atom `button`: interactive, `role: button`, coded `src/ui/Button.tsx#Button`, variants `primary`, `secondary`, states `default`, `hover`, `focus`, `disabled`, `## Keyboard`.
+ - molecule `search-field`: interactive, `role: search`, validated, uses `button`, `icon-search`, no code, variants `default`, states `default`, `hover`, `focus`, `disabled`, `## Keyboard`.
+ - composition `dialog`: interactive, `role: dialog`, coded `package:@radix-ui/react-dialog#Root`, uses `button`, variants `default`, states `default`, `hover`, `focus`, `disabled`, `## Keyboard`.
+ - atom `old-button`: not interactive, `role: button`, variants `default`, states `default`, deprecated, `replaced-by: button`, history row 2 `Breaking: yes` for task `retire-old-button`.
+ - `aidd_docs/ui/screens/home.md` (coded, `src/ui/HomePage.tsx#HomePage`, states `default`, `empty`, `loading`, `error`, breakpoints `mobile`, `desktop`, route `/`) with `home.html`.
+ - `aidd_docs/ui/journeys/onboarding.md` (`## Steps` table: Screen, Action).
+ - `aidd_docs/ui/reviews/first-pass.md` (`status: proposed`, `scope: system`, `screens: [home]`, `## Verdicts` table: Screen, State, Verdict, Comment, one row per state, one `pending`: the remaining screens are the `pending` rows).
+ - `src/ui/Button.tsx`, `src/ui/HomePage.tsx`, `src/ui/tokens.css` (ignored, holds hex values).
+2. Add the fixture to `scripts/__tests__/fixtures/README.md`.
+
+### `2)` Markdown reading
+
+> Records read the same way everywhere.
+
+1. `markdown.cjs`: front matter between the first two `---` lines into `{key: string | string[]}`, a problem per malformed line; `## ` headings into sections; a section's first table into rows keyed by header.
+
+### `3)` Project loading
+
+> One read of the tree every check shares.
+
+1. `project.cjs`: `load(root)` returns `null` without `aidd_docs/ui/`, else every record with its file, folder, front matter and sections, the raw `tokens.json` text, and the render paths.
+
+### `4)` Record rules
+
+> R1 to R16 hold.
+
+1. `records.cjs`: `check(project)` returns `{file, message}` per broken rule, in rule order.
+2. Required keys: every record `id`, `kind`, `status`, `version`; `system.md` `platforms`, `breakpoints`, `themes`, `locales`, `directions`, `code-roots`, `ignore`, `libraries`; component `uses`, `tokens`, `variants`, `states`, `interactive`, `role`; screen `uses`, `states`, `breakpoints`, `route`; journey `persona`; asset `type`, `file`, `alt`; review `scope`, `screens`; `code` only when `coded`; `replaced-by` only when `deprecated`.
+3. Folders: `components/` holds atom, molecule, composition; `screens/` screen; `journeys/` journey; `assets/` asset; `reviews/` review; the root holds `system.md`, `brand.md`.
+
+### `5)` History rules
+
+> H1 to H6 hold.
+
+1. `history.cjs`: `check(project)` reads each `## History` table (Version, Change, Breaking, Task) and returns `{file, message}` per broken rule.
+2. Bumps: the system row of a task raises the major version over the previous row when any element row of that task says `yes`, else at least the minor.
+3. A `deprecated` record's last row says `Breaking: yes`.
+
+### `6)` Tests
+
+> Each rule has the mutation that turns its test red.
+
+1. `aidd-ui-records.test.js`: the Happy path, then one test per Edge case row, each asserting its own message.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | -------------------------------- |
+| 1 | `writeProject` output passes both checks; the fixture README lists it |
+| 2 | a malformed front matter line comes back as a problem with its line |
+| 3 | `load` returns `null` without `aidd_docs/ui/` and every record otherwise |
+| 4 | each of R1 to R16 has its own message |
+| 5 | each of H1 to H6 has its own message, H2 naming the claimed version |
+| 6 | reverting any one rule turns exactly its test red |
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-2.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-2.md
new file mode 100644
index 000000000..4fb53fa02
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-2.md
@@ -0,0 +1,77 @@
+---
+status: pending
+---
+
+# Instruction: Tokens and renders
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+.
+├── plugins/aidd-ui/hooks/lib/
+│ ├── tokens.cjs ✅
+│ └── renders.cjs ✅
+└── scripts/__tests__/
+ └── aidd-ui-tokens-renders.test.js ✅
+```
+
+## Test Scope
+
+| Scenario | Action | Observable outcome | Actor |
+| ------------ | ----------------------- | -------------------- | ------------------------------- |
+| Setup | `writeProject(tmp)` | the valid project | system |
+| Happy path | `tokens.check(load(tmp))`, `renders.check(load(tmp))` | both `[]` | system |
+| Edge case | T1: `tokens.json` not JSON | one problem | system |
+| Edge case | T2: a name starting with `$` that is not a reserved key; a name holding `.` | one problem each | system |
+| Edge case | T3: a token without `$value`; without any `$type`; with `$type: colour` | one problem each | system |
+| Edge case | T4: color `colorSpace: cmyk`; color with two components; `hex: #fff`; dimension `unit: em`; duration `unit: min`; fontWeight `1200`; cubicBezier x `1.5` | one problem each | system |
+| Edge case | T5: `{color.missing}`; `{color.brand}` naming a group | one problem each | system |
+| Edge case | T6: theme `sepia` absent from `system.md`; a theme value of the wrong shape | one problem each | system |
+| Edge case | T7: a component `tokens` entry naming no token | one problem | system |
+| Edge case | T8: a dimension token in `px` | one problem: sizes are in `rem` | system |
+| Edge case | V1: a component or screen without its `.html` | one problem | system |
+| Edge case | V2: a declared variant or state with no `data-variant` or `data-state` in the render | one problem each | system |
+| Edge case | V3: `var(--color-missing)` in a render | one problem | system |
+| Edge case | V4: `#336699`, `rgb(`, `hsl(` in a render | one problem each, with its line | system |
+| Edge case | V6: `16px`, `1.5rem` or `200ms` written in a render | one problem each: only tokens carry values | system |
+| Edge case | V5: `margin-left` in a render while `system.md` declares `rtl`; the same with only `ltr` | one problem; none | system |
+| Teardown | remove `tmp` | no file left | system |
+
+## Tasks to do
+
+### `1)` Token rules
+
+> T1 to T8 hold.
+
+1. `tokens.cjs`: walk the tree; a key starting with `$` is a property, any other is a group or a token, a token being an object with `$value`.
+2. Resolve `$type`: own, else the aliased token's, else the closest group's.
+3. Check primitive shapes per the 2025.10 module; for composite types, check only that `$value` exists.
+4. Read themes from `$extensions["dev.ai-driven.themes"]`; check names against `system.md` `themes`, values against the token's type.
+5. Require `rem` on every dimension token.
+6. Export the set of token paths and their CSS names for renders.
+
+### `2)` Render rules
+
+> V1 to V6 hold.
+
+1. `renders.cjs`: require `.html` beside each component and screen record.
+2. Find `data-variant="x"` and `data-state="x"` for each declared variant and state.
+3. Flag each `var(--x)` with no token, each colour literal (`#` with 3, 4, 6 or 8 hex digits, `rgb(`, `rgba(`, `hsl(`, `hsla(`) with its line, and, when `rtl` is declared, each `margin-left`, `margin-right`, `padding-left`, `padding-right`, `border-left`, `border-right`, `left:`, `right:`, `text-align: left`, `text-align: right`, `float: left`, `float: right`.
+4. Flag each number followed by `px`, `rem`, `em`, `ms` or `s` outside `var(...)`; `0` alone passes.
+5. Export the colour, unit and physical-property patterns for the code checks.
+
+### `3)` Tests
+
+> Each rule has its mutation.
+
+1. `aidd-ui-tokens-renders.test.js`: the Happy path, then one test per Edge case row.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | -------------------------------- |
+| 1 | each of T1 to T8 has its own message |
+| 2 | each of V1 to V6 has its own message; `ltr` alone allows physical properties |
+| 3 | reverting any one rule turns exactly its test red |
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-3.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-3.md
new file mode 100644
index 000000000..ba863f296
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-3.md
@@ -0,0 +1,64 @@
+---
+status: pending
+---
+
+# Instruction: Code link
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+.
+├── plugins/aidd-ui/hooks/lib/
+│ └── code.cjs ✅
+└── scripts/__tests__/
+ └── aidd-ui-code.test.js ✅
+```
+
+## Test Scope
+
+| Scenario | Action | Observable outcome | Actor |
+| ------------ | ----------------------- | -------------------- | ------------------------------- |
+| Setup | `writeProject(tmp)` | the valid project | system |
+| Happy path | `code.check(load(tmp))` | `[]` | system |
+| Edge case | C1: `code` path absent; export name absent from the file; `code` without `#` | one problem each | system |
+| Edge case | C2: `package:left-pad#Pad` not in `libraries` | one problem | system |
+| Edge case | C3: `src/ui/Orphan.tsx` linked by no record and under no `ignore` | one problem naming the file | system |
+| Edge case | C3: a `proposed` record whose `code` points at an existing file | no problem: the link is optional before `coded`, valid when present | system |
+| Edge case | C4: `color: #ff0000` in `src/ui/Button.tsx`; the same in `src/ui/tokens.css` | one problem with its line; none, the file is ignored | system |
+| Edge case | C4: `padding: 16px` in a `.css` file under `src/ui/`; the same in a `.tsx` file | one problem; none, units in script files are a stated limit | system |
+| Edge case | C5: two records with the same `code` | one problem naming both | system |
+| Edge case | C6: `margin-left` in a `.css` file under `src/ui/` while `rtl` is declared | one problem | system |
+| Teardown | remove `tmp` | no file left | system |
+
+## Tasks to do
+
+### `1)` Link rules
+
+> C1 and C2 hold.
+
+1. `code.cjs`: split `code` on its last `#`; a `package:` link needs its name in `system.md` `libraries`; any other needs the file under the project root and the export as a whole word in it.
+
+### `2)` Coverage and literals
+
+> C3 to C6 hold.
+
+1. Walk each `code-roots` prefix; flag each file no `code` names and no `ignore` prefix covers.
+2. In files with extension `.css`, `.scss`, `.js`, `.jsx`, `.ts`, `.tsx`, `.vue`, `.svelte`, `.html`, outside `ignore`, flag colour literals with their line, with the render pattern.
+3. In `.css` and `.scss` files only, flag unit literals and, when `rtl` is declared, physical properties, with the render patterns.
+4. Flag two records sharing one `code`.
+
+### `3)` Tests
+
+> Each rule has its mutation.
+
+1. `aidd-ui-code.test.js`: the Happy path, then one test per Edge case row.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | -------------------------------- |
+| 1 | an absent file, an absent export, a malformed link and an undeclared package each have their own message |
+| 2 | an orphan file, a colour literal, a unit literal, a shared link and a physical property each have their own message; an ignored file and a unit in a script file have none |
+| 3 | reverting any one rule turns exactly its test red |
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-4.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-4.md
new file mode 100644
index 000000000..b35d036fc
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-4.md
@@ -0,0 +1,88 @@
+---
+status: pending
+---
+
+# Instruction: Entry, hook and docs
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+.
+├── docs/
+│ └── CATALOG.md ✏️
+├── plugins/aidd-ui/
+│ ├── CATALOG.md ✏️
+│ ├── README.md ✏️
+│ └── hooks/
+│ ├── hooks.json ✅
+│ ├── ui-hook.cjs ✅
+│ └── validate-ui.cjs ✅
+└── scripts/__tests__/
+ └── aidd-ui-validate.test.js ✅
+```
+
+## Test Scope
+
+| Scenario | Action | Observable outcome | Actor |
+| ------------ | ----------------------- | -------------------- | ------------------------------- |
+| Setup | `writeProject(tmp)` | the valid project | system |
+| Happy path | `node plugins/aidd-ui/hooks/validate-ui.cjs tmp` | `VALID`, exit 0 | cli |
+| Edge case | E1: the same on a project without `aidd_docs/ui/` | nothing printed, exit 0 | cli |
+| Edge case | E2: one mutation from each of phases 1, 2 and 3 | one `✗ : ` line each, exit 1 | cli |
+| Edge case | E3: `ui-hook.cjs` with a PostToolUse payload, `cwd` = `tmp`, `tool_input.file_path` under `aidd_docs/ui/`, after a mutation | the `✗` lines on stderr, exit 2 | system |
+| Edge case | E3: the same with `file_path` under `src/ui/` | the `✗` lines on stderr, exit 2 | system |
+| Edge case | E3: the same with `file_path` outside `aidd_docs/ui/` and every code root | silent, exit 0 | system |
+| Edge case | E3: the same on a valid project | silent, exit 0 | system |
+| Edge case | E4: SessionStart payload on a project with failures | stdout: the count then the `✗` lines, exit 0 | system |
+| Edge case | E4: SessionStart on a project without `aidd_docs/ui/` | silent, exit 0 | system |
+| Edge case | E5: PostToolUse payload without `tool_input.file_path`, as a host without matcher sends; empty or non-JSON stdin | silent, exit 0 | system |
+| Teardown | remove `tmp` | no file left | system |
+
+## Tasks to do
+
+### `1)` Manual entry
+
+> One command runs every check.
+
+1. `validate-ui.cjs`: root from the argument, else the working directory; `load`; nothing and exit 0 when `null`; else run `records`, `history`, `tokens`, `renders`, `code` in that order; print `VALID` or one `✗ : ` per problem; exit 1 on any; export `validate(root)` returning the problems.
+
+### `2)` Hook entry
+
+> The same checks on every write and at session start.
+
+1. `ui-hook.cjs`: read stdin JSON; anything else exits 0 silently; root from `cwd`.
+2. PostToolUse: run `validate(root)` only when `tool_input.file_path` is under `aidd_docs/ui/` or a `code-roots` prefix; on problems write the `✗` lines to stderr and exit 2.
+3. SessionStart: on problems write `aidd-ui: problems` then the `✗` lines to stdout; always exit 0.
+4. Any thrown error exits 0 silently: a broken check never blocks a session.
+5. `hooks.json`: `SessionStart` and `PostToolUse` matching `Write|Edit|MultiEdit`, each `node ${CLAUDE_PLUGIN_ROOT}/hooks/ui-hook.cjs`.
+
+### `3)` Tests
+
+> Each entry has its mutation.
+
+1. `aidd-ui-validate.test.js`: one test per Test Scope row, spawning `node` with the payload on stdin.
+
+### `4)` Docs
+
+> The README and catalogs match the tree.
+
+1. `plugins/aidd-ui/README.md`: status from `plugin.json`'s version; the `aidd_docs/ui/` tree and each record's keys; the hand command `node /hooks/validate-ui.cjs`; the limits: no `node`, no feedback in the turn outside Claude Code, Codex runs the hook once trusted, no composite token shape, no non-web code literal, no unit literal in script files, a word of hex letters after `#` counts as a colour; fixed widths on text and long translations are for the audit.
+2. Run `node scripts/sync-generated-docs.mjs` and `sh scripts/summarize-plugin-catalogs.sh`.
+
+### `5)` Contributor checks
+
+> The tree passes what a pull request requires.
+
+1. Run `make check` (`CONTRIBUTING.md`) and `node scripts/check-tests-leave-git-alone.js -- node --test 'scripts/__tests__/**/*.test.js'` (`aidd_docs/memory/testing.md`); fix until both exit 0.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | -------------------------------- |
+| 1 | the valid project prints `VALID`; each phase's mutation prints its line and exits 1 |
+| 2 | each Test Scope hook row gives its exit code and output |
+| 3 | reverting the path filter, the exit 2 or the silent catch turns its own test red |
+| 4 | the README holds the tree, the command and every limit; `docs/CATALOG.md` lists `hooks/ui-hook.cjs` under `SessionStart` and `PostToolUse`; `plugins/aidd-ui/CATALOG.md` lists the hook files |
+| 5 | both commands exit 0 |
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/plan.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/plan.md
new file mode 100644
index 000000000..c57f7a0da
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/plan.md
@@ -0,0 +1,56 @@
+---
+objective: "A deterministic validator, run by hand and by an aidd-ui hook on every write, rejects any UI record, token, render or code link that breaks the spec."
+status: pending
+---
+
+# Plan: aidd-ui foundation, every record and its validator
+
+Source: aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/spec.md, pull request 1 of aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-rework/roadmap.md.
+
+## Phases
+
+| # | Phase | File | Depends on |
+| --- | ------------ | ---------------------------- | ---------- |
+| 1 | Records and history | [`phase-1.md`](./phase-1.md) | none |
+| 2 | Tokens and renders | [`phase-2.md`](./phase-2.md) | 1 |
+| 3 | Code link | [`phase-3.md`](./phase-3.md) | 1 |
+| 4 | Entry, hook and docs | [`phase-4.md`](./phase-4.md) | 2, 3 |
+
+## External sources
+
+| URL | What it settled |
+| ----- | ----------------- |
+| https://www.designtokens.org/tr/2025.10/format/ | types: color, dimension, fontFamily, fontWeight, duration, cubicBezier, number, and composites strokeStyle, border, transition, shadow, gradient, typography; dimension `{value, unit: px or rem}`, duration `{value, unit: ms or s}`, fontWeight 1 to 1000 or a keyword, cubicBezier four numbers with x in 0..1; `$type` from the token, else the referenced token, else the closest parent group, else invalid; names never start with `$` nor hold `{`, `}`, `.`; a `{a.b}` alias targets a token, never a group; `$extensions` keys in reverse-domain notation; `$deprecated` true, false or a string; themes are not in the format module |
+| https://www.designtokens.org/tr/2025.10/color/ | color `$value` is `{colorSpace, components, alpha?, hex?}`, `colorSpace` one of srgb, srgb-linear, hsl, hwb, lab, lch, oklab, oklch, display-p3, a98-rgb, prophoto-rgb, rec2020, xyz-d65, xyz-d50, `components` three numbers or `none`, `hex` six digits |
+| https://code.claude.com/docs/en/hooks#posttooluse | PostToolUse reads `tool_input.file_path` on stdin; exit 2 hands stderr back to the agent |
+
+## Impact
+
+| Category | Verdict and evidence | Handled in |
+| -------------------------------------------------- | -------------------- | ------------------ |
+| runtime | the hook runs on the user's `node` with built-ins only: plugins ship without `node_modules` (`plugins/aidd-context/hooks/update_memory.js`). Kilo and opencode replay only `node ${CLAUDE_PLUGIN_ROOT}/hooks/` (`cli/src/contexts/tools/domain/profiles/kilo/kilo-hooks-bridge.ts:27`) and drop the hook's output (`:77`); Cursor and Copilot drop the matcher (`cli/src/contexts/tools/domain/formats/flat-hooks-merge.ts:109`); Codex runs a hook once trusted (`cli/src/contexts/tools/domain/profiles/codex/profile.ts:54`); a sibling `require` survives every translation (`plugins/aidd-telemetry/hooks/catch-up.cjs:2`). Tool names on hosts other than Claude Code: unverified, stated as a limit | 4 |
+| regression | low: no existing file changes behaviour; `01-hello` stays; golden snapshots read `cli/tests/fixtures/framework-real` (`cli/tests/golden/framework-build-golden.e2e.test.ts:17`). Safety-net phase: no | none |
+| architecture | aidd-ui gains its first hooks, `hooks/hooks.json` discovered without a manifest key (`plugins/aidd-context/.claude-plugin/plugin.json`). No skill reaches the validator by path: the hook runs it on every write | 4 |
+| documentation | `docs/CATALOG.md` hooks block and `plugins/aidd-ui/CATALOG.md` are regenerated at pre-commit (`scripts/sync-generated-docs.mjs:49`, `scripts/summarize-plugin-catalogs.sh`), checked by `scripts/__tests__/architecture-doc-matches-the-tree.test.js`; `plugins/aidd-ui/README.md` says `0.1.0-alpha.0`, `plugin.json` holds `0.2.1-alpha.0`; `scripts/__tests__/fixtures/README.md` lists every fixture | 1, 4 |
+
+## Rules
+
+| Rule | Why it applies |
+| ------ | -------------- |
+| A guard ships with the mutation that proves it (`aidd_docs/memory/coding-assertions.md`) | every rule below has one test that its one mutation turns red |
+| No code for an input never observed in real data (`aidd_docs/memory/coding-assertions.md`) | composite token values, alias cycles, globs and non-web code are stated limits, not code |
+| A plugin never holds its own tests (`aidd_docs/memory/testing.md`) | tests and their fixture go in `scripts/__tests__/` |
+| Run the scripts suite wrapped (`aidd_docs/memory/testing.md`) | `node scripts/check-tests-leave-git-alone.js -- node --test ...` |
+| A skill never links outside itself (`aidd_docs/memory/architecture.md`) | the validator lives in `hooks/`, reached by the hook, never by a skill path |
+| Bundled hooks run Node (`aidd_docs/memory/architecture.md`) | without `node` the hook is silent, stated in the README |
+
+## Decisions
+
+| Decision | Why |
+| ---------- | --- |
+| Front matter is flat: `key: value` or `key: [a, b]`, nothing nested; tables in the body carry what has rows | parses with built-ins, no YAML dependency, same reading for an agent and a script |
+| Keys and values are English; the spec's states map to `proposed`, `validated`, `coded`, `deprecated` | the plugin and its users' records share the repository's language |
+| Themes are a token extension `"$extensions": {"dev.ai-driven.themes": {"": }}` | the 2025.10 format module defines no themes; extensions are its sanctioned, preserved escape |
+| A token's CSS name is `--` plus its path joined by `-` | one rule both renders and the later `tokens.css` generator follow |
+| A code link is `path#Export` or `package:#Export` | one file and one export per element, a library component by its package |
+| The validator is `hooks/validate-ui.cjs` over modules in `hooks/lib/`, built one module per phase; `hooks/ui-hook.cjs` runs it for PostToolUse and SessionStart | one source of rules for the hand, the hook and every skill that writes |
From 4c350902c0ed231bdfdd6de4df71799d9c5c6a37 Mon Sep 17 00:00:00 2001
From: Baptiste LAFOURCADE
Date: Fri, 30 Oct 2026 15:15:59 +0100
Subject: [PATCH 04/26] feat(aidd-ui): validate ui records, tokens, renders and
code links on every write
Co-Authored-By: Claude Opus 5.5
Claude-Session: https://claude.ai/code/session_01XeK3mD4irAZumku9bknHhD
---
README.md | 2 +-
.../2026_10_30_aidd-ui-foundation/phase-1.md | 2 +-
.../2026_10_30_aidd-ui-foundation/phase-2.md | 2 +-
.../2026_10_30_aidd-ui-foundation/phase-3.md | 2 +-
.../2026_10_30_aidd-ui-foundation/phase-4.md | 2 +-
.../2026_10_30_aidd-ui-foundation/plan.md | 2 +-
.../2026_10_30_aidd-ui-foundation/run.md | 27 ++
docs/CATALOG.md | 11 +
plugins/aidd-ui/CATALOG.md | 7 +
plugins/aidd-ui/README.md | 61 +++-
plugins/aidd-ui/hooks/hooks.json | 27 ++
plugins/aidd-ui/hooks/lib/code.cjs | 114 ++++++
plugins/aidd-ui/hooks/lib/history.cjs | 138 +++++++
plugins/aidd-ui/hooks/lib/markdown.cjs | 94 +++++
plugins/aidd-ui/hooks/lib/project.cjs | 54 +++
plugins/aidd-ui/hooks/lib/records.cjs | 272 ++++++++++++++
plugins/aidd-ui/hooks/lib/renders.cjs | 95 +++++
plugins/aidd-ui/hooks/lib/tokens.cjs | 230 ++++++++++++
plugins/aidd-ui/hooks/ui-hook.cjs | 68 ++++
plugins/aidd-ui/hooks/validate-ui.cjs | 39 ++
scripts/__tests__/aidd-ui-code.test.js | 133 +++++++
scripts/__tests__/aidd-ui-records.test.js | 336 ++++++++++++++++++
.../__tests__/aidd-ui-tokens-renders.test.js | 208 +++++++++++
scripts/__tests__/aidd-ui-validate.test.js | 130 +++++++
scripts/__tests__/fixtures/README.md | 2 +
scripts/__tests__/fixtures/aidd-ui/project.js | 286 +++++++++++++++
26 files changed, 2337 insertions(+), 7 deletions(-)
create mode 100644 aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/run.md
create mode 100644 plugins/aidd-ui/hooks/hooks.json
create mode 100644 plugins/aidd-ui/hooks/lib/code.cjs
create mode 100644 plugins/aidd-ui/hooks/lib/history.cjs
create mode 100644 plugins/aidd-ui/hooks/lib/markdown.cjs
create mode 100644 plugins/aidd-ui/hooks/lib/project.cjs
create mode 100644 plugins/aidd-ui/hooks/lib/records.cjs
create mode 100644 plugins/aidd-ui/hooks/lib/renders.cjs
create mode 100644 plugins/aidd-ui/hooks/lib/tokens.cjs
create mode 100644 plugins/aidd-ui/hooks/ui-hook.cjs
create mode 100644 plugins/aidd-ui/hooks/validate-ui.cjs
create mode 100644 scripts/__tests__/aidd-ui-code.test.js
create mode 100644 scripts/__tests__/aidd-ui-records.test.js
create mode 100644 scripts/__tests__/aidd-ui-tokens-renders.test.js
create mode 100644 scripts/__tests__/aidd-ui-validate.test.js
create mode 100644 scripts/__tests__/fixtures/aidd-ui/project.js
diff --git a/README.md b/README.md
index 7868fb461..437922b16 100644
--- a/README.md
+++ b/README.md
@@ -185,7 +185,7 @@ Feature flow, issue-to-PR automation, backlog
🎨 aidd-ui
-1 skill
+1 skill · 2 hooks
UI and UX design, smoke test only
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-1.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-1.md
index c760e59ce..e0d25f365 100644
--- a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-1.md
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-1.md
@@ -1,5 +1,5 @@
---
-status: pending
+status: done
---
# Instruction: Records and history
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-2.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-2.md
index 4fb53fa02..7007d5ce8 100644
--- a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-2.md
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-2.md
@@ -1,5 +1,5 @@
---
-status: pending
+status: done
---
# Instruction: Tokens and renders
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-3.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-3.md
index ba863f296..0e0aa2099 100644
--- a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-3.md
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-3.md
@@ -1,5 +1,5 @@
---
-status: pending
+status: done
---
# Instruction: Code link
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-4.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-4.md
index b35d036fc..9eb94de74 100644
--- a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-4.md
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/phase-4.md
@@ -1,5 +1,5 @@
---
-status: pending
+status: done
---
# Instruction: Entry, hook and docs
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/plan.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/plan.md
index c57f7a0da..ab342b4be 100644
--- a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/plan.md
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/plan.md
@@ -1,6 +1,6 @@
---
objective: "A deterministic validator, run by hand and by an aidd-ui hook on every write, rejects any UI record, token, render or code link that breaks the spec."
-status: pending
+status: implemented
---
# Plan: aidd-ui foundation, every record and its validator
diff --git a/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/run.md b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/run.md
new file mode 100644
index 000000000..a086e34a5
--- /dev/null
+++ b/aidd_docs/tasks/2026_10/2026_10_30_aidd-ui-foundation/run.md
@@ -0,0 +1,27 @@
+# Run
+
+## Run 1
+
+Head: 9db5c887bc58093237dd16c9aa5fb6707b2a36d6
+
+| Task | Validation | Result |
+| ---- | ---------- | ------ |
+| 1.1 | Happy path: `writeProject` passes records and history, `node scripts/check-tests-leave-git-alone.js -- node --test scripts/__tests__/aidd-ui-records.test.js` | 54 of 54 pass |
+| 1.2 | R1: a malformed front matter line, same command | one problem naming line 7 |
+| 1.3 | `load` without `aidd_docs/ui/`, and on the fixture, same command | `null`; 10 records |
+| 1.4 | R1 to R16, one mutation each, same command | one message per rule |
+| 1.5 | H1 to H6, one mutation each, same command | one message per rule; H2 names version 2 |
+| 1.6 | each rule dropped from `RULES` in turn, then the file rerun | only that rule's tests red, 22 of 22 rules |
+| 2.1 | T1 to T8, `node scripts/check-tests-leave-git-alone.js -- node --test scripts/__tests__/aidd-ui-tokens-renders.test.js` | one message per rule, 33 of 33 pass |
+| 2.2 | V1 to V6, same command | one message per rule; `ltr` alone allows `margin-left` |
+| 2.3 | each rule dropped in turn, then the file rerun | only that rule's tests red, 14 of 14 rules |
+| 3.1 | C1 and C2, `node scripts/check-tests-leave-git-alone.js -- node --test scripts/__tests__/aidd-ui-code.test.js` | absent file, absent export, malformed link and undeclared package each named, 14 of 14 pass |
+| 3.2 | C3 to C6, same command | orphan, colour, unit, shared link and physical property named; ignored file and script units silent |
+| 3.3 | each rule dropped in turn, then the file rerun | only that rule's tests red, 7 of 7 rules |
+| 4.1 | `node plugins/aidd-ui/hooks/validate-ui.cjs `, `node scripts/check-tests-leave-git-alone.js -- node --test scripts/__tests__/aidd-ui-validate.test.js` | `VALID` exit 0; one line per family, exit 1; nothing without `aidd_docs/ui/` |
+| 4.2 | E3 to E5 hook payloads on stdin, same command | exit 2 with the lines on stderr under `aidd_docs/ui/` and `src/ui/`; silent elsewhere; SessionStart prints the count; silent on bad stdin and on a throw |
+| 4.3 | path filter, exit 2, silent catch and each check reverted in turn | each turns its own test red, 13 of 13 pass restored |
+| 4.4 | `node scripts/sync-generated-docs.mjs --check`, `sh scripts/summarize-plugin-catalogs.sh` | in sync; `docs/CATALOG.md` lists `hooks/ui-hook.cjs` under both events |
+| 4.5 | `make check`; `pnpm exec lefthook run pre-commit --all-files --force`; `node scripts/check-tests-leave-git-alone.js -- node --test 'scripts/__tests__/**/*.test.js'` | `make check` exit 0, every job skipped with nothing staged; whole tree: 870 of 871 pass, the one failure names untracked `hooks/ui-hook.cjs`, and it passes with the new files tracked in a scratch index |
+
+Left: nothing committed (commit strategy `never`); `comments-name-files-that-exist` stays red until `plugins/aidd-ui/hooks/` is tracked; `plugins/aidd-ui/CATALOG.md` lists `hooks.json` only, because its generator skips `.cjs` files, as for `aidd-telemetry`.
diff --git a/docs/CATALOG.md b/docs/CATALOG.md
index b7a04036b..ff09f767e 100644
--- a/docs/CATALOG.md
+++ b/docs/CATALOG.md
@@ -135,6 +135,17 @@ Runs synchronous feature delivery, optional async issue automation, and the prod
| ---------- | ----------------------------------------- | ---------- |
| `01-hello` | Smoke-test that confirms the plugin loads | `01-greet` |
+
+
+**Hooks**
+
+| Event | Runs |
+| --- | --- |
+| `SessionStart` | `hooks/ui-hook.cjs` |
+| `PostToolUse` | `hooks/ui-hook.cjs` |
+
+
+
## 📈 aidd-telemetry
🧪 **Beta.** Measurement: counts the tokens of Claude Code and Codex sessions, per person, session, model, agent, tool, day, repository, task and ticket, and keeps everything on your machine.
diff --git a/plugins/aidd-ui/CATALOG.md b/plugins/aidd-ui/CATALOG.md
index 73912f57f..13965a09b 100644
--- a/plugins/aidd-ui/CATALOG.md
+++ b/plugins/aidd-ui/CATALOG.md
@@ -7,6 +7,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
## Table of Contents
- [`.claude-plugin`](#claude-plugin)
+- [`hooks`](#hooks)
- [`skills`](#skills)
- [`skills/01-hello`](#skills01-hello)
@@ -18,6 +19,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
|------|
| [plugin.json](.claude-plugin/plugin.json) |
+### `hooks`
+
+| File |
+|------|
+| [hooks.json](hooks/hooks.json) |
+
### `skills`
#### `skills/01-hello`
diff --git a/plugins/aidd-ui/README.md b/plugins/aidd-ui/README.md
index 097fb8ab8..5cae57deb 100644
--- a/plugins/aidd-ui/README.md
+++ b/plugins/aidd-ui/README.md
@@ -6,7 +6,7 @@ UI and UX design.
| | |
| --- | --- |
-| Status | alpha (`0.1.0-alpha.0`) |
+| Status | alpha |
| Install | `/plugin install aidd-ui@aidd-framework` |
| Start with | `/aidd-ui:01-hello` |
| Skills, agents, hooks | [Catalog](../../docs/CATALOG.md#-aidd-ui) |
@@ -15,6 +15,65 @@ UI and UX design.
> Not ready for use.
> Skills and names may change or disappear without notice.
+## Design system
+
+One file per element, under `aidd_docs/ui/`.
+
+```txt
+aidd_docs/ui/
+├── system.md the design system
+├── brand.md the brand
+├── tokens.json tokens, DTCG 2025.10
+├── assets/.md an icon, image or illustration, its file beside it
+├── components/.md an atom, molecule or composition
+├── components/.html its render: every variant and state
+├── screens/.md a screen
+├── screens/.html its render: every state
+├── journeys/.md a user journey
+└── reviews/.md the verdicts of a review
+```
+
+Every record opens with flat front matter, `key: value` or `key: [a, b]`, and closes with a `## History` table: Version, Change, Breaking (`yes` or `no`), Task.
+
+| Record | Front matter | Body |
+| --- | --- | --- |
+| every one | `id` (the file name), `kind`, `status` (`proposed`, `validated`, `coded`, `deprecated`), `version` | `## History` |
+| `system.md` | `version` in semver, `platforms`, `breakpoints`, `themes`, `locales`, `directions`, `code-roots`, `ignore`, `libraries` | |
+| `brand.md` | | `## Project`, `## Users`, `## Domain`, `## Platforms`, `## Personality and tone`, `## References`, `## Anti-references` |
+| atom, molecule, composition | `uses`, `tokens`, `variants`, `states`, `interactive` (`yes` or `no`), `role`, `code` | `## Keyboard` when interactive |
+| screen | `uses`, `states`, `breakpoints`, `route`, `code` | |
+| journey | `persona` | `## Steps`: Screen, Action |
+| asset | `type` (`icon`, `image`, `illustration`), `file`, `alt` | |
+| review | `scope`, `screens` | `## Verdicts`: Screen, State, Verdict (`ok`, `ko`, `pending`), Comment |
+
+- `code` is `path#Export`, or `package:#Export` for a library component; required once `coded`.
+- A deprecated element names `replaced-by: `, or `replaced-by: none` with a `## Deprecation` section.
+- A theme value is a token extension: `"$extensions": {"dev.ai-driven.themes": {"dark": }}`.
+- A token's CSS name is `--` plus its path joined by `-`.
+
+## Validation
+
+A hook checks the design system after every write under `aidd_docs/ui/` or a code root, and at session start. By hand:
+
+```sh
+node /hooks/validate-ui.cjs [project-root]
+```
+
+It prints `VALID`, or one `✗ : ` line per problem and exits 1.
+
+## Limits
+
+- Without `node` on `PATH`, the hook does nothing.
+- Outside Claude Code, a problem does not come back in the same turn.
+- Codex runs the hook only once you trust it.
+- The write matcher uses Claude Code's tool names; other hosts are unverified.
+- Composite tokens are checked for a `$value`, not for its shape.
+- Alias cycles are not detected.
+- `code-roots` and `ignore` are path prefixes, not globs.
+- Literals are found in web code only, and units in stylesheets only, not in script files.
+- A word of hex letters after `#`, such as `#add`, counts as a colour.
+- Fixed widths on text and long translations are left to the UI audit.
+
## Try it from a checkout
| Scope | Run |
diff --git a/plugins/aidd-ui/hooks/hooks.json b/plugins/aidd-ui/hooks/hooks.json
new file mode 100644
index 000000000..f2653fed7
--- /dev/null
+++ b/plugins/aidd-ui/hooks/hooks.json
@@ -0,0 +1,27 @@
+{
+ "hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ui-hook.cjs",
+ "timeout": 30
+ }
+ ]
+ }
+ ],
+ "PostToolUse": [
+ {
+ "matcher": "Write|Edit|MultiEdit",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ui-hook.cjs",
+ "timeout": 30
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/plugins/aidd-ui/hooks/lib/code.cjs b/plugins/aidd-ui/hooks/lib/code.cjs
new file mode 100644
index 000000000..8390c253b
--- /dev/null
+++ b/plugins/aidd-ui/hooks/lib/code.cjs
@@ -0,0 +1,114 @@
+// C1 to C6: each code link resolves, every file under a code root is linked or ignored, and UI
+// code holds no literal a token should carry. Non-web code is a stated limit.
+const fs = require("node:fs");
+const path = require("node:path");
+const { list } = require("./markdown.cjs");
+const { placed, systemOf, isElement } = require("./records.cjs");
+const { PATTERNS, findLiterals, declaresRightToLeft } = require("./renders.cjs");
+
+const EXPORT_SEPARATOR = "#";
+const PACKAGE_PREFIX = "package:";
+const PATH_SEPARATOR = "/";
+const SCANNED_EXTENSIONS = [".css", ".scss", ".js", ".jsx", ".ts", ".tsx", ".vue", ".svelte", ".html"];
+const STYLESHEET_EXTENSIONS = [".css", ".scss"]; // units in script files are a stated limit
+
+const REGEX_SPECIALS = /[.*+?^${}()|[\]\\]/g;
+
+const fm = (record) => record.frontMatter;
+const posix = (file) => file.split(path.sep).join(PATH_SEPARATOR);
+
+/** A `code` value as `{target, name}`, `target` being a path or `package:`; null when malformed. */
+function parseLink(value) {
+ if (typeof value !== "string") return null;
+ const at = value.lastIndexOf(EXPORT_SEPARATOR);
+ if (at <= 0 || at === value.length - 1) return null;
+ const target = value.slice(0, at);
+ return { target, name: value.slice(at + 1), library: target.startsWith(PACKAGE_PREFIX) ? target.slice(PACKAGE_PREFIX.length) : null };
+}
+
+/** Elements with a `code` value, each with its parsed link. */
+const linked = (project) =>
+ placed(project)
+ .filter((record) => isElement(record) && "code" in fm(record))
+ .map((record) => ({ record, value: fm(record).code, link: parseLink(fm(record).code) }));
+
+const hasWord = (text, word) => new RegExp(`(?
+ list(systemOf(project)?.frontMatter.ignore).some((prefix) => file === prefix || file.startsWith(`${prefix.replace(/\/$/, "")}${PATH_SEPARATOR}`));
+
+function walk(dir) {
+ if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return [];
+ return fs
+ .readdirSync(dir, { withFileTypes: true })
+ .sort((a, b) => a.name.localeCompare(b.name))
+ .flatMap((entry) => (entry.isDirectory() ? walk(path.join(dir, entry.name)) : [path.join(dir, entry.name)]));
+}
+
+/** Every file under a `code-roots` prefix, relative to the project root. */
+function codeFiles(project) {
+ const roots = list(systemOf(project)?.frontMatter["code-roots"]);
+ return [...new Set(roots.flatMap((root) => walk(path.join(project.root, root)).map((file) => posix(path.relative(project.root, file)))))];
+}
+
+const scanned = (project, extensions) =>
+ codeFiles(project).filter((file) => extensions.includes(path.extname(file)) && !isIgnored(project, file));
+
+function linkProblems(project) {
+ return linked(project).flatMap(({ record, value, link }) => {
+ if (!link) return [{ file: record.file, message: `code "${value}" must be path#Export or package:#Export` }];
+ if (link.library !== null) return [];
+ const full = path.join(project.root, link.target);
+ if (!fs.existsSync(full) || !fs.statSync(full).isFile()) return [{ file: record.file, message: `code file "${link.target}" does not exist` }];
+ return hasWord(fs.readFileSync(full, "utf8"), link.name) ? [] : [{ file: record.file, message: `export "${link.name}" is not in ${link.target}` }];
+ });
+}
+
+function libraryProblems(project) {
+ const libraries = list(systemOf(project)?.frontMatter.libraries);
+ return linked(project)
+ .filter(({ link }) => link && link.library !== null && !libraries.includes(link.library))
+ .map(({ record, link }) => ({ file: record.file, message: `package "${link.library}" is not in system.md libraries` }));
+}
+
+function coverageProblems(project) {
+ const targets = new Set(linked(project).flatMap(({ link }) => (link && link.library === null ? [link.target] : [])));
+ return codeFiles(project)
+ .filter((file) => !targets.has(file) && !isIgnored(project, file))
+ .map((file) => ({ file, message: "no record links it and no ignore covers it" }));
+}
+
+const literalProblems = (pattern, extensions, applies = () => true) => (project) =>
+ applies(project)
+ ? scanned(project, extensions).flatMap((file) =>
+ findLiterals(fs.readFileSync(path.join(project.root, file), "utf8"), pattern).map(({ message }) => ({ file, message }))
+ )
+ : [];
+
+function sharedLinkProblems(project) {
+ const owners = new Map();
+ return linked(project).flatMap(({ record, value }) => {
+ const owner = owners.get(value);
+ if (!owner) {
+ owners.set(value, record);
+ return [];
+ }
+ return [{ file: record.file, message: `code "${value}" is also ${owner.file}'s` }];
+ });
+}
+
+const RULES = [
+ linkProblems, // C1
+ libraryProblems, // C2
+ coverageProblems, // C3
+ literalProblems(PATTERNS.colour, SCANNED_EXTENSIONS), // C4
+ literalProblems(PATTERNS.unit, STYLESHEET_EXTENSIONS), // C4
+ sharedLinkProblems, // C5
+ literalProblems(PATTERNS.physical, STYLESHEET_EXTENSIONS, declaresRightToLeft), // C6
+];
+
+/** Every broken code rule, as `{file, message}`, in rule order. */
+const check = (project) => RULES.flatMap((rule) => rule(project));
+
+module.exports = { check, codeRoots: (project) => list(systemOf(project)?.frontMatter["code-roots"]) };
diff --git a/plugins/aidd-ui/hooks/lib/history.cjs b/plugins/aidd-ui/hooks/lib/history.cjs
new file mode 100644
index 000000000..7a54b8fb7
--- /dev/null
+++ b/plugins/aidd-ui/hooks/lib/history.cjs
@@ -0,0 +1,138 @@
+// H1 to H6: each versioned record's history, and the system version its tasks raise.
+const { table } = require("./markdown.cjs");
+const { placed, systemOf, isElement } = require("./records.cjs");
+
+const HISTORY_SECTION = "History";
+const BREAKING_VALUES = ["yes", "no"];
+const BREAKING = "yes";
+const SYSTEM_KIND = "system";
+
+const INTEGER_VERSION = /^[1-9]\d*$/;
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+
+const problem = (record, message) => ({ file: record.file, message });
+const fm = (record) => record.frontMatter;
+const isSystem = (record) => fm(record).kind === SYSTEM_KIND;
+const rowsOf = (record) => table(record.sections[HISTORY_SECTION]);
+
+/** A version as comparable numbers: [n] for an element, [major, minor, patch] for the system. */
+function parts(version, system) {
+ if (system) {
+ const match = SEMVER.exec(version ?? "");
+ return match ? match.slice(1).map(Number) : null;
+ }
+ return INTEGER_VERSION.test(version ?? "") ? [Number(version)] : null;
+}
+
+function compare(a, b) {
+ for (let index = 0; index < a.length; index += 1) if (a[index] !== b[index]) return a[index] - b[index];
+ return 0;
+}
+
+/** Records that carry a version, which every history rule reads. */
+const versioned = (project) => placed(project).filter((record) => "version" in fm(record));
+
+function presenceProblems(project) {
+ return versioned(project)
+ .filter((record) => rowsOf(record).length === 0)
+ .map((record) => problem(record, `no "## ${HISTORY_SECTION}" table`));
+}
+
+function duplicateProblems(project) {
+ return versioned(project).flatMap((record) => {
+ const seen = new Set();
+ const claimed = new Set();
+ for (const row of rowsOf(record)) (seen.has(row.Version) ? claimed : seen).add(row.Version);
+ return [...claimed].map((version) => problem(record, `two changes claim version ${version}, renumber one`));
+ });
+}
+
+function currentProblems(project) {
+ return versioned(project).flatMap((record) => {
+ const system = isSystem(record);
+ const current = parts(fm(record).version, system);
+ const rows = rowsOf(record)
+ .map((row) => ({ version: row.Version, parts: parts(row.Version, system) }))
+ .filter((row) => row.parts)
+ .sort((a, b) => compare(a.parts, b.parts));
+ if (!current || !rows.length) return [];
+ const highest = rows.at(-1);
+ const problems = compare(current, highest.parts) === 0 ? [] : [`version ${fm(record).version} is not the highest history row, ${highest.version}`];
+ if (!system) {
+ for (let index = 1; index < rows.length; index += 1) {
+ const step = rows[index].parts[0] - rows[index - 1].parts[0];
+ if (step > 1) problems.push(`history jumps from ${rows[index - 1].version} to ${rows[index].version}`);
+ }
+ }
+ return problems.map((message) => problem(record, message));
+ });
+}
+
+function breakingProblems(project) {
+ return versioned(project).flatMap((record) =>
+ rowsOf(record)
+ .filter((row) => !BREAKING_VALUES.includes(row.Breaking))
+ .map((row) => problem(record, `breaking "${row.Breaking}" in version ${row.Version} must be yes or no`))
+ );
+}
+
+/** For each element task, whether any of its rows breaks, and which records it touches. */
+function elementTasks(project) {
+ const tasks = new Map();
+ for (const record of versioned(project).filter((candidate) => !isSystem(candidate))) {
+ for (const row of rowsOf(record)) {
+ const task = tasks.get(row.Task) ?? { breaking: false, records: [] };
+ task.breaking ||= row.Breaking === BREAKING;
+ if (!task.records.includes(record)) task.records.push(record);
+ tasks.set(row.Task, task);
+ }
+ }
+ return tasks;
+}
+
+/** The system row a task raised, with the row before it; null when the task has none. */
+function systemRow(rows, task) {
+ const index = rows.findIndex((row) => row.Task === task);
+ return index < 0 ? null : { row: rows[index], previous: rows[index - 1] };
+}
+
+function bumpProblems(project) {
+ const system = systemOf(project);
+ const rows = system ? rowsOf(system) : [];
+ return [...elementTasks(project)].flatMap(([task, { breaking, records }]) => {
+ const found = systemRow(rows, task);
+ if (!found) return records.map((record) => problem(record, `task "${task}" has no row in system.md`));
+ if (!found.previous) return [];
+ const now = parts(found.row.Version, true);
+ const before = parts(found.previous.Version, true);
+ if (!now || !before) return [];
+ if (breaking && now[0] <= before[0]) {
+ return [problem(system, `task "${task}" breaks an element, yet system.md ${found.row.Version} raises no major version`)];
+ }
+ if (!breaking && compare(now.slice(0, 2), before.slice(0, 2)) <= 0) {
+ return [problem(system, `task "${task}" changes an element, yet system.md ${found.row.Version} raises neither major nor minor`)];
+ }
+ return [];
+ });
+}
+
+function deprecationProblems(project) {
+ return versioned(project)
+ .filter((record) => isElement(record) && fm(record).status === "deprecated")
+ .filter((record) => rowsOf(record).length && rowsOf(record).at(-1).Breaking !== BREAKING)
+ .map((record) => problem(record, "deprecated, yet its last history row is not breaking"));
+}
+
+const RULES = [
+ presenceProblems, // H1
+ duplicateProblems, // H2
+ currentProblems, // H3
+ breakingProblems, // H4
+ bumpProblems, // H5
+ deprecationProblems, // H6
+];
+
+/** Every broken history rule, as `{file, message}`, in rule order. */
+const check = (project) => RULES.flatMap((rule) => rule(project));
+
+module.exports = { check };
diff --git a/plugins/aidd-ui/hooks/lib/markdown.cjs b/plugins/aidd-ui/hooks/lib/markdown.cjs
new file mode 100644
index 000000000..b73eddf28
--- /dev/null
+++ b/plugins/aidd-ui/hooks/lib/markdown.cjs
@@ -0,0 +1,94 @@
+// Reads a UI record: flat front matter, `## ` sections, and a section's first table.
+
+const LINE_BREAK = "\n";
+const FENCE = "---";
+const SECTION_PREFIX = "## ";
+const TABLE_CELL_SEPARATOR = "|";
+const LIST_SEPARATOR = ",";
+
+const WINDOWS_LINE_ENDING = /\r\n/g;
+const ENTRY = /^([a-z][a-z0-9-]*):[ \t]*(\S.*)$/;
+const LIST = /^\[(.*)\]$/;
+const TABLE_SEPARATOR_ROW = /^\|[\s:|-]+\|$/;
+
+const NO_FRONT_MATTER = "no front matter, open and close it with a --- line";
+
+/** A front matter value: `[a, b]` as a list, anything else as trimmed text. */
+function parseValue(raw) {
+ const list = raw.trim().match(LIST);
+ if (!list) return raw.trim();
+ return list[1]
+ .split(LIST_SEPARATOR)
+ .map((item) => item.trim())
+ .filter(Boolean);
+}
+
+/** Front matter between the first two `---` lines, with one problem per line that is neither
+ * `key: value` nor `key: [a, b]`. Lines are numbered as in the file. */
+function parseFrontMatter(lines) {
+ const close = lines.indexOf(FENCE, 1);
+ if (lines[0] !== FENCE || close < 0) return { found: false, values: {}, end: 0, problems: [{ line: 1, message: NO_FRONT_MATTER }] };
+ const values = {};
+ const problems = [];
+ for (let index = 1; index < close; index += 1) {
+ const line = lines[index];
+ if (!line.trim()) continue;
+ const entry = line.match(ENTRY);
+ if (entry) values[entry[1]] = parseValue(entry[2]);
+ else problems.push({ line: index + 1, message: `expected "key: value" or "key: [a, b]", got "${line.trim()}"` });
+ }
+ return { found: true, values, end: close + 1, problems };
+}
+
+/** The body's `## ` sections by name, each with its first line number and its lines. */
+function parseSections(lines, start) {
+ const sections = {};
+ let current;
+ for (let index = start; index < lines.length; index += 1) {
+ const line = lines[index];
+ if (line.startsWith(SECTION_PREFIX)) {
+ current = { line: index + 1, lines: [] };
+ sections[line.slice(SECTION_PREFIX.length).trim()] = current;
+ } else if (current) current.lines.push(line);
+ }
+ return sections;
+}
+
+const cells = (line) => line.split(TABLE_CELL_SEPARATOR).slice(1, -1).map((cell) => cell.trim());
+
+/** The section's first table as rows keyed by its header; [] when it has none. */
+function table(section) {
+ if (!section) return [];
+ const start = section.lines.findIndex((line) => line.trim().startsWith(TABLE_CELL_SEPARATOR));
+ if (start < 0) return [];
+ const block = [];
+ for (const line of section.lines.slice(start)) {
+ if (!line.trim().startsWith(TABLE_CELL_SEPARATOR)) break;
+ block.push(line.trim());
+ }
+ const header = cells(block[0]);
+ return block
+ .slice(1)
+ .filter((line) => !TABLE_SEPARATOR_ROW.test(line))
+ .map((line) => Object.fromEntries(cells(line).map((cell, index) => [header[index], cell])));
+}
+
+/** A record's front matter, its problems, and its sections. */
+function parseRecord(text) {
+ const lines = text.replace(WINDOWS_LINE_ENDING, LINE_BREAK).split(LINE_BREAK);
+ const frontMatter = parseFrontMatter(lines);
+ return {
+ hasFrontMatter: frontMatter.found,
+ frontMatter: frontMatter.values,
+ problems: frontMatter.problems,
+ sections: parseSections(lines, frontMatter.end),
+ };
+}
+
+/** A front matter value as a list: a lone value is a list of one, an absent one is empty. */
+function list(value) {
+ if (value === undefined) return [];
+ return Array.isArray(value) ? value : [value];
+}
+
+module.exports = { parseRecord, table, list };
diff --git a/plugins/aidd-ui/hooks/lib/project.cjs b/plugins/aidd-ui/hooks/lib/project.cjs
new file mode 100644
index 000000000..3d9ce75a4
--- /dev/null
+++ b/plugins/aidd-ui/hooks/lib/project.cjs
@@ -0,0 +1,54 @@
+// One read of a project's design system, shared by every check.
+const fs = require("node:fs");
+const path = require("node:path");
+const { parseRecord } = require("./markdown.cjs");
+
+const UI_DIR = "aidd_docs/ui";
+const TOKENS_FILE = "tokens.json";
+const SHOWCASE_DIR = "showcase";
+const RECORD_EXTENSION = ".md";
+const RENDER_EXTENSION = ".html";
+const ROOT_FOLDER = "";
+
+/** A path relative to the project root, with forward slashes on every platform. */
+const relative = (root, file) => path.relative(root, file).split(path.sep).join("/");
+
+/** Every file under `dir`, sorted, skipping the generated showcase. */
+function walk(dir, top = dir) {
+ return fs
+ .readdirSync(dir, { withFileTypes: true })
+ .sort((a, b) => a.name.localeCompare(b.name))
+ .flatMap((entry) => {
+ const full = path.join(dir, entry.name);
+ if (entry.isDirectory()) return dir === top && entry.name === SHOWCASE_DIR ? [] : walk(full, top);
+ return [full];
+ });
+}
+
+/** A record with its file, folder under `aidd_docs/ui/`, name, front matter and sections. */
+function readRecord(root, uiDir, full) {
+ const folder = path.relative(uiDir, path.dirname(full)).split(path.sep).join("/");
+ return {
+ file: relative(root, full),
+ folder: folder || ROOT_FOLDER,
+ name: path.basename(full, RECORD_EXTENSION),
+ ...parseRecord(fs.readFileSync(full, "utf8")),
+ };
+}
+
+/** The design system under `root`, or null when the project has none. */
+function load(root) {
+ const uiDir = path.join(root, UI_DIR);
+ if (!fs.existsSync(uiDir) || !fs.statSync(uiDir).isDirectory()) return null;
+ const files = walk(uiDir);
+ const tokensPath = path.join(uiDir, TOKENS_FILE);
+ return {
+ root,
+ records: files.filter((file) => file.endsWith(RECORD_EXTENSION)).map((file) => readRecord(root, uiDir, file)),
+ tokensFile: relative(root, tokensPath),
+ tokens: fs.existsSync(tokensPath) ? fs.readFileSync(tokensPath, "utf8") : null,
+ renders: files.filter((file) => file.endsWith(RENDER_EXTENSION)).map((file) => relative(root, file)),
+ };
+}
+
+module.exports = { load, UI_DIR };
diff --git a/plugins/aidd-ui/hooks/lib/records.cjs b/plugins/aidd-ui/hooks/lib/records.cjs
new file mode 100644
index 000000000..e0e956425
--- /dev/null
+++ b/plugins/aidd-ui/hooks/lib/records.cjs
@@ -0,0 +1,272 @@
+// R1 to R16: the shape of each record and how records point at one another.
+const fs = require("node:fs");
+const path = require("node:path");
+const { list, table } = require("./markdown.cjs");
+
+const STATUSES = ["proposed", "validated", "coded", "deprecated"];
+const DESIGN_STATUSES = ["proposed", "validated"]; // R16: system, brand and reviews are never coded
+const YES_NO = ["yes", "no"];
+const ASSET_TYPES = ["icon", "image", "illustration"];
+const VERDICTS = ["ok", "ko", "pending"];
+const NO_REPLACEMENT = "none";
+const DEFAULT_STATE = "default";
+const INTERACTIVE_STATES = ["hover", "focus", "disabled"];
+const KEYBOARD_SECTION = "Keyboard";
+const DEPRECATION_SECTION = "Deprecation";
+const STEPS_SECTION = "Steps";
+const VERDICTS_SECTION = "Verdicts";
+const BRAND_HEADINGS = ["Project", "Users", "Domain", "Platforms", "Personality and tone", "References", "Anti-references"];
+const SYSTEM_ID = "system";
+
+const COMMON_KEYS = ["id", "kind", "status", "version"];
+const COMPONENT_KEYS = ["uses", "tokens", "variants", "states", "interactive", "role"];
+const KIND_KEYS = {
+ system: ["platforms", "breakpoints", "themes", "locales", "directions", "code-roots", "ignore", "libraries"],
+ brand: [],
+ atom: COMPONENT_KEYS,
+ molecule: COMPONENT_KEYS,
+ composition: COMPONENT_KEYS,
+ screen: ["uses", "states", "breakpoints", "route"],
+ journey: ["persona"],
+ asset: ["type", "file", "alt"],
+ review: ["scope", "screens"],
+};
+const FOLDER_KINDS = {
+ "": ["system", "brand"],
+ components: ["atom", "molecule", "composition"],
+ screens: ["screen"],
+ journeys: ["journey"],
+ assets: ["asset"],
+ reviews: ["review"],
+};
+const COMPONENT_KINDS = FOLDER_KINDS.components;
+const DESIGN_KINDS = ["system", "brand", "review"];
+const LEVELS = { asset: 0, atom: 1, molecule: 2, composition: 3, screen: 4 }; // an element uses only lower levels
+
+const INTEGER_VERSION = /^[1-9]\d*$/;
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+const listWithOr = (values) => `${values.slice(0, -1).join(", ")} or ${values.at(-1)}`;
+const problem = (record, message) => ({ file: record.file, message });
+const fm = (record) => record.frontMatter;
+const isElement = (record) => fm(record).kind in LEVELS;
+const isComponent = (record) => COMPONENT_KINDS.includes(fm(record).kind);
+const isDeprecated = (record) => fm(record).status === "deprecated";
+const folderLabel = (folder) => (folder ? `${folder}/` : "aidd_docs/ui/");
+
+/** The records the other rules can read: a file without front matter is R1's alone. */
+const readable = (project) => project.records.filter((record) => record.hasFrontMatter);
+
+/** Readable records whose kind is known and in its folder: kind rules read only those. */
+const placed = (project) => readable(project).filter((record) => FOLDER_KINDS[record.folder]?.includes(fm(record).kind));
+
+/** The first record holding each id, in load order. */
+function byId(project) {
+ const index = new Map();
+ for (const record of readable(project)) if (fm(record).id && !index.has(fm(record).id)) index.set(fm(record).id, record);
+ return index;
+}
+
+const systemOf = (project) => readable(project).find((record) => fm(record).kind === SYSTEM_ID);
+
+function frontMatterProblems(project) {
+ return project.records.flatMap((record) => record.problems.map((parse) => problem(record, `line ${parse.line}: ${parse.message}`)));
+}
+
+function kindProblems(project) {
+ return readable(project).flatMap((record) => {
+ const kind = fm(record).kind;
+ if (kind === undefined) return [];
+ if (!(kind in KIND_KEYS)) return [problem(record, `unknown kind "${kind}"`)];
+ if (FOLDER_KINDS[record.folder]?.includes(kind)) return [];
+ return [problem(record, `kind "${kind}" does not belong in ${folderLabel(record.folder)}`)];
+ });
+}
+
+function valueProblems(record) {
+ const { status, interactive, type, kind } = fm(record);
+ return [
+ ...(status !== undefined && !STATUSES.includes(status) ? [`status "${status}" must be ${listWithOr(STATUSES)}`] : []),
+ ...(COMPONENT_KINDS.includes(kind) && interactive !== undefined && !YES_NO.includes(interactive) ? [`interactive "${interactive}" must be ${listWithOr(YES_NO)}`] : []),
+ ...(kind === "asset" && type !== undefined && !ASSET_TYPES.includes(type) ? [`type "${type}" must be ${listWithOr(ASSET_TYPES)}`] : []),
+ ].map((message) => problem(record, message));
+}
+
+function requiredKeyProblems(project) {
+ const placedRecords = new Set(placed(project));
+ return readable(project).flatMap((record) => {
+ const keys = [...COMMON_KEYS, ...(placedRecords.has(record) ? KIND_KEYS[fm(record).kind] : [])];
+ const missing = keys.filter((key) => !(key in fm(record))).map((key) => problem(record, `missing key "${key}"`));
+ return [...missing, ...(placedRecords.has(record) ? valueProblems(record) : [])];
+ });
+}
+
+function identityProblems(project) {
+ const index = byId(project);
+ return readable(project).flatMap((record) => {
+ const id = fm(record).id;
+ if (id === undefined) return [];
+ if (id !== record.name) return [problem(record, `id "${id}" differs from the file name "${record.name}"`)];
+ const owner = index.get(id);
+ return owner === record ? [] : [problem(record, `id "${id}" already belongs to ${owner.file}`)];
+ });
+}
+
+function versionProblems(project) {
+ return placed(project).flatMap((record) => {
+ const version = fm(record).version;
+ if (version === undefined) return [];
+ if (fm(record).kind === SYSTEM_ID) return SEMVER.test(version) ? [] : [problem(record, `version "${version}" must be semver, such as 2.0.0`)];
+ return INTEGER_VERSION.test(version) ? [] : [problem(record, `version "${version}" must be an integer from 1`)];
+ });
+}
+
+function usesProblems(project) {
+ const index = byId(project);
+ return placed(project)
+ .filter(isElement)
+ .flatMap((record) =>
+ list(fm(record).uses).flatMap((id) => {
+ const used = index.get(id);
+ if (!used) return [problem(record, `uses "${id}", which no record has`)];
+ const kind = fm(record).kind;
+ const usedKind = fm(used).kind;
+ return LEVELS[usedKind] < LEVELS[kind] ? [] : [problem(record, `${kind} cannot use ${usedKind} "${id}"`)];
+ })
+ );
+}
+
+function stateProblems(project) {
+ return placed(project).flatMap((record) => {
+ const states = list(fm(record).states);
+ if (fm(record).kind === "screen") return states.includes(DEFAULT_STATE) ? [] : [problem(record, `screen lacks state "${DEFAULT_STATE}"`)];
+ if (!isComponent(record)) return [];
+ const interactive = fm(record).interactive === "yes";
+ return [
+ ...(states.includes(DEFAULT_STATE) ? [] : [`component lacks state "${DEFAULT_STATE}"`]),
+ ...(interactive ? INTERACTIVE_STATES.filter((state) => !states.includes(state)).map((state) => `interactive component lacks state "${state}"`) : []),
+ ...(interactive && !(KEYBOARD_SECTION in record.sections) ? [`interactive component lacks a "## ${KEYBOARD_SECTION}" section`] : []),
+ ].map((message) => problem(record, message));
+ });
+}
+
+function codedProblems(project) {
+ return placed(project)
+ .filter((record) => isElement(record) && fm(record).status === "coded" && !("code" in fm(record)))
+ .map((record) => problem(record, 'status coded needs "code"'));
+}
+
+function deprecatedProblems(project) {
+ const index = byId(project);
+ return placed(project)
+ .filter((record) => isElement(record) && isDeprecated(record))
+ .flatMap((record) => {
+ const replacement = fm(record)["replaced-by"];
+ if (replacement === undefined) return [problem(record, 'status deprecated needs "replaced-by"')];
+ if (replacement === NO_REPLACEMENT) {
+ return DEPRECATION_SECTION in record.sections ? [] : [problem(record, `replaced-by none needs a "## ${DEPRECATION_SECTION}" section saying why`)];
+ }
+ const target = index.get(replacement);
+ if (!target) return [problem(record, `replaced-by "${replacement}", which no record has`)];
+ return isDeprecated(target) ? [problem(record, `replaced-by "${replacement}" is deprecated too`)] : [];
+ });
+}
+
+function deprecatedUseProblems(project) {
+ const index = byId(project);
+ return placed(project)
+ .filter((record) => isElement(record) && !isDeprecated(record))
+ .flatMap((record) =>
+ list(fm(record).uses)
+ .filter((id) => index.get(id) && isDeprecated(index.get(id)))
+ .map((id) => problem(record, `uses "${id}", which is deprecated`))
+ );
+}
+
+function breakpointProblems(project) {
+ const system = systemOf(project);
+ if (!system) return [];
+ const declared = list(fm(system).breakpoints);
+ return placed(project)
+ .filter((record) => fm(record).kind === "screen")
+ .flatMap((record) =>
+ list(fm(record).breakpoints)
+ .filter((breakpoint) => !declared.includes(breakpoint))
+ .map((breakpoint) => problem(record, `breakpoint "${breakpoint}" is not in system.md`))
+ );
+}
+
+const screenIds = (project) => new Set(placed(project).filter((record) => fm(record).kind === "screen").map((record) => fm(record).id));
+
+function journeyProblems(project) {
+ const screens = screenIds(project);
+ return placed(project)
+ .filter((record) => fm(record).kind === "journey")
+ .flatMap((record) =>
+ table(record.sections[STEPS_SECTION]).flatMap((row, index) =>
+ screens.has(row.Screen) ? [] : [problem(record, `step ${index + 1} names screen "${row.Screen}", which no screen has`)]
+ )
+ );
+}
+
+function reviewProblems(project) {
+ const index = byId(project);
+ return placed(project)
+ .filter((record) => fm(record).kind === "review")
+ .flatMap((record) => {
+ const rows = table(record.sections[VERDICTS_SECTION]);
+ const missing = list(fm(record).screens).flatMap((id) =>
+ list(index.get(id) && fm(index.get(id)).states)
+ .filter((state) => !rows.some((row) => row.Screen === id && row.State === state))
+ .map((state) => `no verdict row for ${id} / ${state}`)
+ );
+ const verdicts = rows
+ .filter((row) => !VERDICTS.includes(row.Verdict))
+ .map((row) => `verdict "${row.Verdict}" for ${row.Screen} / ${row.State} must be ${listWithOr(VERDICTS)}`);
+ return [...missing, ...verdicts].map((message) => problem(record, message));
+ });
+}
+
+function brandProblems(project) {
+ return placed(project)
+ .filter((record) => fm(record).kind === "brand")
+ .flatMap((record) => BRAND_HEADINGS.filter((heading) => !(heading in record.sections)).map((heading) => problem(record, `lacks "## ${heading}"`)));
+}
+
+function assetProblems(project) {
+ return placed(project)
+ .filter((record) => fm(record).kind === "asset" && typeof fm(record).file === "string")
+ .filter((record) => !fs.existsSync(path.join(project.root, path.dirname(record.file), fm(record).file)))
+ .map((record) => problem(record, `file "${fm(record).file}" does not exist beside it`));
+}
+
+function designStatusProblems(project) {
+ return placed(project)
+ .filter((record) => DESIGN_KINDS.includes(fm(record).kind))
+ .filter((record) => STATUSES.includes(fm(record).status) && !DESIGN_STATUSES.includes(fm(record).status))
+ .map((record) => problem(record, `status "${fm(record).status}" is for elements: system, brand and reviews are ${listWithOr(DESIGN_STATUSES)}`));
+}
+
+const RULES = [
+ frontMatterProblems, // R1
+ kindProblems, // R2
+ requiredKeyProblems, // R3
+ identityProblems, // R4
+ versionProblems, // R5
+ usesProblems, // R6
+ stateProblems, // R7
+ codedProblems, // R8
+ deprecatedProblems, // R9
+ deprecatedUseProblems, // R10
+ breakpointProblems, // R11
+ journeyProblems, // R12
+ reviewProblems, // R13
+ brandProblems, // R14
+ assetProblems, // R15
+ designStatusProblems, // R16
+];
+
+/** Every broken record rule, as `{file, message}`, in rule order. */
+const check = (project) => RULES.flatMap((rule) => rule(project));
+
+module.exports = { check, readable, placed, byId, systemOf, isElement };
diff --git a/plugins/aidd-ui/hooks/lib/renders.cjs b/plugins/aidd-ui/hooks/lib/renders.cjs
new file mode 100644
index 000000000..1d4d7f7f9
--- /dev/null
+++ b/plugins/aidd-ui/hooks/lib/renders.cjs
@@ -0,0 +1,95 @@
+// V1 to V6: each component and screen has its HTML render, showing every variant and state
+// through tokens alone.
+const fs = require("node:fs");
+const path = require("node:path");
+const { list } = require("./markdown.cjs");
+const { placed, systemOf } = require("./records.cjs");
+const { cssNames } = require("./tokens.cjs");
+
+const RENDERED_KINDS = ["atom", "molecule", "composition", "screen"];
+const RENDER_EXTENSION = ".html";
+const RIGHT_TO_LEFT = "rtl";
+const LINE_BREAK = "\n";
+
+const CUSTOM_PROPERTY = /var\(\s*(--[\w-]+)/g;
+const VAR_CALL = /var\([^()]*\)/g; // a fallback inside var() is the token's, not a literal
+
+/** Literals a render or UI code must not hold, each with the message it earns. */
+const PATTERNS = {
+ colour: {
+ regex: /(? `colour literal "${found}", use a token`,
+ },
+ unit: {
+ regex: /(? `literal "${found}", only tokens carry values`,
+ strip: VAR_CALL,
+ },
+ physical: {
+ regex: /\b(?:margin|padding|border)-(?:left|right)\b|(? `physical property "${found}", use its logical form`,
+ },
+};
+
+/** Each match of `pattern` in `text`, as `{line, message}`, lines numbered from 1. */
+function findLiterals(text, pattern) {
+ return text.split(LINE_BREAK).flatMap((line, index) => {
+ const searched = pattern.strip ? line.replace(pattern.strip, "") : line;
+ return [...searched.matchAll(pattern.regex)].map((match) => ({ line: index + 1, message: `line ${index + 1}: ${pattern.message(match[0])}` }));
+ });
+}
+
+/** Whether the design system declares a right-to-left direction. */
+const declaresRightToLeft = (project) => list(systemOf(project)?.frontMatter.directions).includes(RIGHT_TO_LEFT);
+
+const renderOf = (record) => `${path.dirname(record.file)}/${record.frontMatter.id}${RENDER_EXTENSION}`;
+const rendered = (project) => placed(project).filter((record) => RENDERED_KINDS.includes(record.frontMatter.kind) && record.frontMatter.id === record.name);
+const readRender = (project, file) => fs.readFileSync(path.join(project.root, file), "utf8");
+
+function presenceProblems(project) {
+ return rendered(project)
+ .filter((record) => !project.renders.includes(renderOf(record)))
+ .map((record) => ({ file: record.file, message: `no render beside it, expected ${path.basename(renderOf(record))}` }));
+}
+
+function coverageProblems(project) {
+ return rendered(project)
+ .filter((record) => project.renders.includes(renderOf(record)))
+ .flatMap((record) => {
+ const html = readRender(project, renderOf(record));
+ const wanted = [...list(record.frontMatter.variants).map((value) => `data-variant="${value}"`), ...list(record.frontMatter.states).map((value) => `data-state="${value}"`)];
+ return wanted.filter((attribute) => !html.includes(attribute)).map((attribute) => ({ file: renderOf(record), message: `no ${attribute}` }));
+ });
+}
+
+function referenceProblems(project) {
+ const names = cssNames(project);
+ if (names === null) return [];
+ const defined = new Set(names.values());
+ return project.renders.flatMap((file) =>
+ readRender(project, file)
+ .split(LINE_BREAK)
+ .flatMap((line, index) =>
+ [...line.matchAll(CUSTOM_PROPERTY)]
+ .filter((match) => !defined.has(match[1]))
+ .map((match) => ({ file, message: `line ${index + 1}: var(${match[1]}) names no token` }))
+ )
+ );
+}
+
+const literalProblems = (pattern, applies = () => true) => (project) =>
+ applies(project) ? project.renders.flatMap((file) => findLiterals(readRender(project, file), pattern).map(({ message }) => ({ file, message }))) : [];
+
+const RULES = [
+ presenceProblems, // V1
+ coverageProblems, // V2
+ referenceProblems, // V3
+ literalProblems(PATTERNS.colour), // V4
+ literalProblems(PATTERNS.physical, declaresRightToLeft), // V5
+ literalProblems(PATTERNS.unit), // V6
+];
+
+/** Every broken render rule, as `{file, message}`, in rule order. */
+const check = (project) => RULES.flatMap((rule) => rule(project));
+
+module.exports = { check, PATTERNS, findLiterals, declaresRightToLeft };
diff --git a/plugins/aidd-ui/hooks/lib/tokens.cjs b/plugins/aidd-ui/hooks/lib/tokens.cjs
new file mode 100644
index 000000000..7d875b662
--- /dev/null
+++ b/plugins/aidd-ui/hooks/lib/tokens.cjs
@@ -0,0 +1,230 @@
+// T1 to T8: tokens.json against the DTCG 2025.10 format and color modules, plus this plugin's
+// themes extension and its rem rule. Composite values are checked for presence only.
+const { list } = require("./markdown.cjs");
+const { placed, systemOf } = require("./records.cjs");
+
+const RESERVED_KEYS = ["$value", "$type", "$description", "$extensions", "$deprecated", "$extends", "$schema", "$root"];
+const PROPERTY_PREFIX = "$";
+const PATH_SEPARATOR = ".";
+const CSS_PREFIX = "--";
+const CSS_SEPARATOR = "-";
+const THEMES_EXTENSION = "dev.ai-driven.themes";
+const COMPONENT_KINDS = ["atom", "molecule", "composition"];
+
+const PRIMITIVE_TYPES = ["color", "dimension", "fontFamily", "fontWeight", "duration", "cubicBezier", "number"];
+const COMPOSITE_TYPES = ["strokeStyle", "border", "transition", "shadow", "gradient", "typography"];
+const TYPES = [...PRIMITIVE_TYPES, ...COMPOSITE_TYPES];
+const COLOR_SPACES = ["srgb", "srgb-linear", "hsl", "hwb", "lab", "lch", "oklab", "oklch", "display-p3", "a98-rgb", "prophoto-rgb", "rec2020", "xyz-d65", "xyz-d50"];
+const COLOR_COMPONENTS = 3;
+const NO_COMPONENT = "none";
+const DIMENSION_UNITS = ["px", "rem"];
+const DURATION_UNITS = ["ms", "s"];
+const SIZE_UNIT = "rem";
+const PIXEL_UNIT = "px";
+const FONT_WEIGHT_MIN = 1;
+const FONT_WEIGHT_MAX = 1000;
+const FONT_WEIGHT_KEYWORDS = ["thin", "hairline", "extra-light", "ultra-light", "light", "normal", "regular", "book", "medium", "semi-bold", "demi-bold", "bold", "extra-bold", "ultra-bold", "black", "heavy", "extra-black", "ultra-black"];
+const BEZIER_POINTS = 4;
+const BEZIER_X_INDEXES = [0, 2];
+const MAX_ALIAS_DEPTH = 32; // alias cycles are a stated limit; this only stops the walk
+
+const FORBIDDEN_IN_NAME = /[{}.]/;
+const ALIAS = /^\{([^{}]+)\}$/;
+const HEX = /^#[0-9a-fA-F]{6}$/;
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const childKeys = (node) => Object.keys(node).filter((key) => !key.startsWith(PROPERTY_PREFIX));
+const aliasOf = (value) => (typeof value === "string" ? ALIAS.exec(value)?.[1] : undefined);
+
+/** Every token and group of the tree, each with its path and the closest group `$type`. */
+function walk(node, path, groupType, found) {
+ for (const key of Object.keys(node)) {
+ const child = node[key];
+ const childPath = [...path, key];
+ if (key.startsWith(PROPERTY_PREFIX)) {
+ if (!RESERVED_KEYS.includes(key)) found.badNames.push({ path: childPath.join(PATH_SEPARATOR), message: `"${key}" is not a reserved key` });
+ continue;
+ }
+ if (FORBIDDEN_IN_NAME.test(key)) found.badNames.push({ path: childPath.join(PATH_SEPARATOR), message: 'a name never holds ".", "{" or "}"' });
+ if (!isObject(child)) continue;
+ const name = childPath.join(PATH_SEPARATOR);
+ if ("$value" in child || childKeys(child).length === 0) found.tokens.set(name, { path: childPath, node: child, groupType });
+ else {
+ found.groups.add(name);
+ walk(child, childPath, child.$type ?? groupType, found);
+ }
+ }
+ return found;
+}
+
+/** The tree read once: its parse error, or its tokens, groups and bad names. */
+function read(project) {
+ if (project.tokens === null) return { missing: true, tokens: new Map(), groups: new Set(), badNames: [] };
+ let tree;
+ try {
+ tree = JSON.parse(project.tokens);
+ } catch {
+ return { invalid: true, tokens: new Map(), groups: new Set(), badNames: [] };
+ }
+ if (!isObject(tree)) return { invalid: true, tokens: new Map(), groups: new Set(), badNames: [] };
+ return walk(tree, [], tree.$type, { tokens: new Map(), groups: new Set(), badNames: [] });
+}
+
+/** A token's `$type`: its own, else its alias target's, else its closest group's. */
+function typeOf(tree, token, depth = 0) {
+ if (token.node.$type !== undefined) return token.node.$type;
+ const target = tree.tokens.get(aliasOf(token.node.$value));
+ if (target && depth < MAX_ALIAS_DEPTH) return typeOf(tree, target, depth + 1);
+ return token.groupType;
+}
+
+function colorProblem(value) {
+ if (!isObject(value)) return "a color is {colorSpace, components, alpha?, hex?}";
+ if (!COLOR_SPACES.includes(value.colorSpace)) return `colorSpace "${value.colorSpace}" is not a DTCG colour space`;
+ const components = value.components;
+ if (!Array.isArray(components) || components.length !== COLOR_COMPONENTS || !components.every((part) => isNumber(part) || part === NO_COMPONENT)) {
+ return 'components must be three numbers or "none"';
+ }
+ if (value.alpha !== undefined && !(isNumber(value.alpha) && value.alpha >= 0 && value.alpha <= 1)) return "alpha must be a number in 0..1";
+ if (value.hex !== undefined && !HEX.test(value.hex)) return `hex "${value.hex}" must be # and six hex digits`;
+ return null;
+}
+
+function measureProblem(value, units) {
+ if (!isObject(value) || !isNumber(value.value)) return `a measure is {value: number, unit: ${units.join(" or ")}}`;
+ return units.includes(value.unit) ? null : `unit "${value.unit}" must be ${units.join(" or ")}`;
+}
+
+function fontWeightProblem(value) {
+ if (isNumber(value) && value >= FONT_WEIGHT_MIN && value <= FONT_WEIGHT_MAX) return null;
+ if (FONT_WEIGHT_KEYWORDS.includes(value)) return null;
+ return `fontWeight ${JSON.stringify(value)} must be 1 to 1000 or a keyword`;
+}
+
+function cubicBezierProblem(value) {
+ const valid = Array.isArray(value) && value.length === BEZIER_POINTS && value.every(isNumber) && BEZIER_X_INDEXES.every((index) => value[index] >= 0 && value[index] <= 1);
+ return valid ? null : "cubicBezier needs four numbers, x in 0..1";
+}
+
+function fontFamilyProblem(value) {
+ const valid = typeof value === "string" || (Array.isArray(value) && value.length > 0 && value.every((name) => typeof name === "string"));
+ return valid ? null : "fontFamily is a name or a list of names";
+}
+
+const SHAPES = {
+ color: colorProblem,
+ dimension: (value) => measureProblem(value, DIMENSION_UNITS),
+ duration: (value) => measureProblem(value, DURATION_UNITS),
+ fontWeight: fontWeightProblem,
+ cubicBezier: cubicBezierProblem,
+ fontFamily: fontFamilyProblem,
+ number: (value) => (isNumber(value) ? null : "a number token holds a number"),
+};
+
+/** What is wrong with a value of `type`, or null. Aliases and composites are not shapes. */
+const shapeProblem = (type, value) => (aliasOf(value) !== undefined || !SHAPES[type] ? null : SHAPES[type](value));
+
+/** A problem builder for tokens.json, naming the token path first. */
+const tokenProblem = (project) => (path, message) => ({ file: project.tokensFile, message: `${path}: ${message}` });
+const themesOf = (token) => (isObject(token.node.$extensions?.[THEMES_EXTENSION]) ? token.node.$extensions[THEMES_EXTENSION] : {});
+
+function jsonProblems(tree, project) {
+ return tree.invalid ? [{ file: project.tokensFile, message: "not JSON" }] : [];
+}
+
+function nameProblems(tree, project) {
+ const at = tokenProblem(project);
+ return tree.badNames.map((bad) => at(bad.path, bad.message));
+}
+
+function typeProblems(tree, project) {
+ const at = tokenProblem(project);
+ return [...tree.tokens].flatMap(([name, token]) => {
+ if (!("$value" in token.node)) return [at(name, "no $value")];
+ const type = typeOf(tree, token);
+ if (type === undefined) return [at(name, "no $type on it, its alias or a parent group")];
+ return TYPES.includes(type) ? [] : [at(name, `$type "${type}" is not a DTCG type`)];
+ });
+}
+
+function shapeProblems(tree, project) {
+ const at = tokenProblem(project);
+ return [...tree.tokens].flatMap(([name, token]) => {
+ const message = "$value" in token.node ? shapeProblem(typeOf(tree, token), token.node.$value) : null;
+ return message ? [at(name, message)] : [];
+ });
+}
+
+function aliasProblem(tree, value) {
+ const target = aliasOf(value);
+ if (target === undefined || tree.tokens.has(target)) return null;
+ return tree.groups.has(target) ? `alias {${target}} names a group, not a token` : `alias {${target}} names no token`;
+}
+
+function aliasProblems(tree, project) {
+ const at = tokenProblem(project);
+ return [...tree.tokens].flatMap(([name, token]) => {
+ const message = aliasProblem(tree, token.node.$value);
+ return message ? [at(name, message)] : [];
+ });
+}
+
+function themeProblems(tree, project) {
+ const at = tokenProblem(project);
+ const system = systemOf(project);
+ const declared = list(system?.frontMatter.themes);
+ return [...tree.tokens].flatMap(([name, token]) =>
+ Object.entries(themesOf(token)).flatMap(([theme, value]) => {
+ if (system && !declared.includes(theme)) return [at(name, `theme "${theme}" is not in system.md`)];
+ const message = shapeProblem(typeOf(tree, token), value) ?? aliasProblem(tree, value);
+ return message ? [at(name, `theme "${theme}": ${message}`)] : [];
+ })
+ );
+}
+
+function componentTokenProblems(tree, project) {
+ if (tree.invalid) return [];
+ return placed(project)
+ .filter((record) => COMPONENT_KINDS.includes(record.frontMatter.kind))
+ .flatMap((record) =>
+ list(record.frontMatter.tokens)
+ .filter((name) => !tree.tokens.has(name))
+ .map((name) => ({ file: record.file, message: `token "${name}" is not in tokens.json` }))
+ );
+}
+
+function remProblems(tree, project) {
+ const at = tokenProblem(project);
+ return [...tree.tokens]
+ .filter(([, token]) => typeOf(tree, token) === "dimension")
+ .filter(([, token]) => [token.node.$value, ...Object.values(themesOf(token))].some((value) => isObject(value) && value.unit === PIXEL_UNIT))
+ .map(([name]) => at(name, `sizes are in ${SIZE_UNIT}, not ${PIXEL_UNIT}`));
+}
+
+const RULES = [
+ jsonProblems, // T1
+ nameProblems, // T2
+ typeProblems, // T3
+ shapeProblems, // T4
+ aliasProblems, // T5
+ themeProblems, // T6
+ componentTokenProblems, // T7
+ remProblems, // T8
+];
+
+/** Every broken token rule, as `{file, message}`, in rule order. */
+function check(project) {
+ const tree = read(project);
+ return RULES.flatMap((rule) => rule(tree, project));
+}
+
+/** Each token path and its CSS custom property, `--` plus the path joined by `-`; null when
+ * tokens.json cannot be read, so renders do not repeat T1. */
+function cssNames(project) {
+ const tree = read(project);
+ if (tree.invalid) return null;
+ return new Map([...tree.tokens.values()].map((token) => [token.path.join(PATH_SEPARATOR), `${CSS_PREFIX}${token.path.join(CSS_SEPARATOR)}`]));
+}
+
+module.exports = { check, cssNames };
diff --git a/plugins/aidd-ui/hooks/ui-hook.cjs b/plugins/aidd-ui/hooks/ui-hook.cjs
new file mode 100644
index 000000000..e022ac42f
--- /dev/null
+++ b/plugins/aidd-ui/hooks/ui-hook.cjs
@@ -0,0 +1,68 @@
+// PostToolUse and SessionStart: runs the design system checks. After a write under
+// aidd_docs/ui/ or a code root, problems go back to the agent on stderr with exit 2; at session
+// start they are printed as context. Anything unexpected exits 0 in silence: a broken check
+// never blocks a session.
+const fs = require("node:fs");
+const path = require("node:path");
+const { load, UI_DIR } = require("./lib/project.cjs");
+const { codeRoots } = require("./lib/code.cjs");
+const { problemsOf, format } = require("./validate-ui.cjs");
+
+const POST_TOOL_USE = "PostToolUse";
+const SESSION_START = "SessionStart";
+const EXIT_SILENT = 0;
+const EXIT_BLOCKING = 2; // Claude Code hands a PostToolUse hook's stderr back to the agent
+const PATH_SEPARATOR = "/";
+
+/** The JSON object on stdin, or null when there is none or it is not one. */
+function readPayload() {
+ try {
+ const parsed = JSON.parse(fs.readFileSync(0, "utf8"));
+ return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+ } catch {
+ return null;
+ }
+}
+
+/** Whether `file` lies under `prefix`, both relative to the project root. */
+const isUnder = (file, prefix) => {
+ const folder = prefix.replace(/\/+$/, "");
+ return file === folder || file.startsWith(`${folder}${PATH_SEPARATOR}`);
+};
+
+/** Whether a written file belongs to the design system or to its code. */
+function isWatched(project, filePath) {
+ const file = path.relative(project.root, path.resolve(project.root, filePath)).split(path.sep).join(PATH_SEPARATOR);
+ return [UI_DIR, ...codeRoots(project)].some((prefix) => isUnder(file, prefix));
+}
+
+function afterWrite(project, payload) {
+ const filePath = payload.tool_input?.file_path;
+ if (typeof filePath !== "string" || !isWatched(project, filePath)) return EXIT_SILENT;
+ const problems = problemsOf(project);
+ if (!problems.length) return EXIT_SILENT;
+ process.stderr.write(`${format(problems).join("\n")}\n`);
+ return EXIT_BLOCKING;
+}
+
+function atSessionStart(project) {
+ const problems = problemsOf(project);
+ if (problems.length) process.stdout.write(`aidd-ui: ${problems.length} problems\n${format(problems).join("\n")}\n`);
+ return EXIT_SILENT;
+}
+
+function run() {
+ const payload = readPayload();
+ if (payload === null) return EXIT_SILENT;
+ const project = load(typeof payload.cwd === "string" ? payload.cwd : process.cwd());
+ if (project === null) return EXIT_SILENT;
+ if (payload.hook_event_name === POST_TOOL_USE) return afterWrite(project, payload);
+ if (payload.hook_event_name === SESSION_START) return atSessionStart(project);
+ return EXIT_SILENT;
+}
+
+try {
+ process.exitCode = run();
+} catch {
+ process.exitCode = EXIT_SILENT;
+}
diff --git a/plugins/aidd-ui/hooks/validate-ui.cjs b/plugins/aidd-ui/hooks/validate-ui.cjs
new file mode 100644
index 000000000..8de9c8798
--- /dev/null
+++ b/plugins/aidd-ui/hooks/validate-ui.cjs
@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// Usage: node validate-ui.cjs [project-root]
+// Checks a project's design system under aidd_docs/ui/: records, history, tokens, renders and
+// code links. Prints VALID, or one line per problem and exits 1. Prints nothing without one.
+const { load } = require("./lib/project.cjs");
+const records = require("./lib/records.cjs");
+const history = require("./lib/history.cjs");
+const tokens = require("./lib/tokens.cjs");
+const renders = require("./lib/renders.cjs");
+const code = require("./lib/code.cjs");
+
+const CHECKS = [records, history, tokens, renders, code];
+const VERDICT_VALID = "VALID";
+const EXIT_VALID = 0;
+const EXIT_INVALID = 1;
+const PROBLEM_MARK = "✗";
+
+/** Every problem of a loaded project, check by check. */
+const problemsOf = (project) => CHECKS.flatMap((check) => check.check(project));
+
+/** The problems of the design system under `root`, or null when it has none. */
+function validate(root) {
+ const project = load(root);
+ return project === null ? null : problemsOf(project);
+}
+
+/** One `✗ : ` line per problem, the file relative to the project root. */
+const format = (problems) => problems.map((problem) => `${PROBLEM_MARK} ${problem.file}: ${problem.message}`);
+
+function main(args) {
+ const problems = validate(args[0] ?? process.cwd());
+ if (problems === null) return EXIT_VALID;
+ console.log(problems.length ? format(problems).join("\n") : VERDICT_VALID);
+ return problems.length ? EXIT_INVALID : EXIT_VALID;
+}
+
+if (require.main === module) process.exitCode = main(process.argv.slice(2));
+
+module.exports = { validate, problemsOf, format };
diff --git a/scripts/__tests__/aidd-ui-code.test.js b/scripts/__tests__/aidd-ui-code.test.js
new file mode 100644
index 000000000..8b049948b
--- /dev/null
+++ b/scripts/__tests__/aidd-ui-code.test.js
@@ -0,0 +1,133 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { describe, it, beforeEach, afterEach } = require("node:test");
+const { UI, writeProject, edit, put } = require("./fixtures/aidd-ui/project.js");
+
+// Each rule has one mutation of the valid project, and the test asserts the whole problem
+// list: dropping the rule turns its own test red and leaves every other one green. Link
+// mutations land on search-field: it owns no file and is not coded, so none orphans a file.
+const LIB = path.resolve(__dirname, "../../plugins/aidd-ui/hooks/lib");
+const { load } = require(path.join(LIB, "project.cjs"));
+const code = require(path.join(LIB, "code.cjs"));
+
+const SYSTEM = `${UI}/system.md`;
+const BUTTON = `${UI}/components/button.md`;
+const SEARCH = `${UI}/components/search-field.md`;
+const DIALOG = `${UI}/components/dialog.md`;
+const SEARCH_CSS = "src/ui/SearchField.css";
+
+let tmp;
+
+beforeEach(() => {
+ tmp = fs.mkdtempSync(path.join(os.tmpdir(), "aidd-ui-code-"));
+ writeProject(tmp);
+});
+
+afterEach(() => {
+ fs.rmSync(tmp, { recursive: true, force: true });
+ assert.equal(fs.existsSync(tmp), false);
+});
+
+const problems = () => code.check(load(tmp)).map((problem) => `${problem.file}: ${problem.message}`);
+
+/** Gives search-field a code link. */
+const linkSearch = (link) => edit(tmp, SEARCH, "role: search", `role: search\ncode: ${link}`);
+
+/** Writes a stylesheet search-field links to, so only its content can raise a problem. */
+function linkedStylesheet(css) {
+ put(tmp, SEARCH_CSS, css);
+ linkSearch(`${SEARCH_CSS}#SearchField`);
+}
+
+/** Appends one line to a file of the project. */
+const append = (file, line) => fs.appendFileSync(path.join(tmp, file), `${line}\n`);
+
+describe("aidd-ui code link", () => {
+ it("passes the valid project", () => {
+ assert.deepEqual(problems(), []);
+ });
+
+ describe("C1 links", () => {
+ it("names a code file that does not exist", () => {
+ linkSearch("src/ui/Missing.tsx#SearchField");
+ assert.deepEqual(problems(), [`${SEARCH}: code file "src/ui/Missing.tsx" does not exist`]);
+ });
+
+ it("names an export absent from the file", () => {
+ edit(tmp, BUTTON, "#Button", "#Buttn");
+ assert.deepEqual(problems(), [`${BUTTON}: export "Buttn" is not in src/ui/Button.tsx`]);
+ });
+
+ it("names a link without #", () => {
+ linkSearch("src/ui/Button.tsx");
+ assert.deepEqual(problems(), [`${SEARCH}: code "src/ui/Button.tsx" must be path#Export or package:#Export`]);
+ });
+ });
+
+ describe("C2 libraries", () => {
+ it("names a package system.md does not list", () => {
+ edit(tmp, DIALOG, "package:@radix-ui/react-dialog#Root", "package:left-pad#Pad");
+ assert.deepEqual(problems(), [`${DIALOG}: package "left-pad" is not in system.md libraries`]);
+ });
+ });
+
+ describe("C3 coverage", () => {
+ it("names a file under a code root no record links and no ignore covers", () => {
+ put(tmp, "src/ui/Orphan.tsx", "export function Orphan() {}\n");
+ assert.deepEqual(problems(), ["src/ui/Orphan.tsx: no record links it and no ignore covers it"]);
+ });
+
+ it("accepts a valid link on a proposed record", () => {
+ edit(tmp, SEARCH, "status: validated", "status: proposed");
+ put(tmp, "src/ui/SearchField.tsx", "export function SearchField() {}\n");
+ linkSearch("src/ui/SearchField.tsx#SearchField");
+ assert.deepEqual(problems(), []);
+ });
+ });
+
+ describe("C4 colour literals", () => {
+ it("names a colour literal in UI code, with its line", () => {
+ append("src/ui/Button.tsx", 'const style = "color: #ff0000";');
+ assert.deepEqual(problems(), ['src/ui/Button.tsx: line 4: colour literal "#ff0000", use a token']);
+ });
+
+ it("skips an ignored file", () => {
+ append("src/ui/tokens.css", ".x { color: #ff0000; }");
+ assert.deepEqual(problems(), []);
+ });
+ });
+
+ describe("C4 unit literals", () => {
+ it("names a unit literal in a stylesheet", () => {
+ linkedStylesheet(".SearchField { padding: 16px; }\n");
+ assert.deepEqual(problems(), [`${SEARCH_CSS}: line 1: literal "16px", only tokens carry values`]);
+ });
+
+ it("leaves units in script files alone, a stated limit", () => {
+ append("src/ui/Button.tsx", 'const style = "padding: 16px";');
+ assert.deepEqual(problems(), []);
+ });
+ });
+
+ describe("C5 one record per file", () => {
+ it("names two records sharing one code link", () => {
+ linkSearch("src/ui/Button.tsx#Button");
+ assert.deepEqual(problems(), [`${SEARCH}: code "src/ui/Button.tsx#Button" is also ${BUTTON}'s`]);
+ });
+ });
+
+ describe("C6 logical properties in code", () => {
+ it("names a physical property in a stylesheet when rtl is declared", () => {
+ linkedStylesheet(".SearchField { margin-left: 0; }\n");
+ assert.deepEqual(problems(), [`${SEARCH_CSS}: line 1: physical property "margin-left", use its logical form`]);
+ });
+
+ it("allows it when only ltr is declared", () => {
+ edit(tmp, SYSTEM, "directions: [ltr, rtl]", "directions: [ltr]");
+ linkedStylesheet(".SearchField { margin-left: 0; }\n");
+ assert.deepEqual(problems(), []);
+ });
+ });
+});
diff --git a/scripts/__tests__/aidd-ui-records.test.js b/scripts/__tests__/aidd-ui-records.test.js
new file mode 100644
index 000000000..d46e57158
--- /dev/null
+++ b/scripts/__tests__/aidd-ui-records.test.js
@@ -0,0 +1,336 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { describe, it, beforeEach, afterEach } = require("node:test");
+const { UI, writeProject, edit, put, record, history } = require("./fixtures/aidd-ui/project.js");
+
+// Each rule has one mutation of the valid project, and the test asserts the whole problem
+// list: dropping the rule turns its own test red and leaves every other one green.
+const LIB = path.resolve(__dirname, "../../plugins/aidd-ui/hooks/lib");
+const { load } = require(path.join(LIB, "project.cjs"));
+const records = require(path.join(LIB, "records.cjs"));
+const historyRules = require(path.join(LIB, "history.cjs"));
+
+const SYSTEM = `${UI}/system.md`;
+const BRAND = `${UI}/brand.md`;
+const BUTTON = `${UI}/components/button.md`;
+const SEARCH = `${UI}/components/search-field.md`;
+const DIALOG = `${UI}/components/dialog.md`;
+const OLD = `${UI}/components/old-button.md`;
+const HOME = `${UI}/screens/home.md`;
+const JOURNEY = `${UI}/journeys/onboarding.md`;
+const ICON = `${UI}/assets/icon-search.md`;
+const REVIEW = `${UI}/reviews/first-pass.md`;
+
+let tmp;
+
+beforeEach(() => {
+ tmp = fs.mkdtempSync(path.join(os.tmpdir(), "aidd-ui-records-"));
+ writeProject(tmp);
+});
+
+afterEach(() => {
+ fs.rmSync(tmp, { recursive: true, force: true });
+ assert.equal(fs.existsSync(tmp), false);
+});
+
+/** Every problem both checks find, as `file: message`. */
+function problems() {
+ const project = load(tmp);
+ return [...records.check(project), ...historyRules.check(project)].map((problem) => `${problem.file}: ${problem.message}`);
+}
+
+const change = (file, from, to) => edit(tmp, file, from, to);
+
+describe("aidd-ui records and history", () => {
+ it("passes the valid project", () => {
+ assert.deepEqual(problems(), []);
+ });
+
+ it("loads nothing without aidd_docs/ui/", () => {
+ fs.rmSync(path.join(tmp, UI), { recursive: true });
+ assert.equal(load(tmp), null);
+ });
+
+ it("loads every record", () => {
+ assert.equal(load(tmp).records.length, 10);
+ });
+
+ describe("R1 front matter", () => {
+ it("names a record without front matter", () => {
+ put(tmp, JOURNEY, "# Onboarding\n");
+ assert.deepEqual(problems(), [`${JOURNEY}: line 1: no front matter, open and close it with a --- line`]);
+ });
+
+ it("names a line that is neither key: value nor key: [a, b]", () => {
+ change(JOURNEY, "persona: a first-time analyst", "persona: a first-time analyst\n - nested");
+ assert.deepEqual(problems(), [`${JOURNEY}: line 7: expected "key: value" or "key: [a, b]", got "- nested"`]);
+ });
+ });
+
+ describe("R2 kind and folder", () => {
+ it("names an unknown kind", () => {
+ change(JOURNEY, "kind: journey", "kind: widget");
+ assert.deepEqual(problems(), [`${JOURNEY}: unknown kind "widget"`]);
+ });
+
+ it("names a kind outside its folder", () => {
+ put(tmp, `${UI}/screens/extra.md`, record(["id: extra", "kind: atom", "status: proposed", "version: 1"], history(["1", "created", "no", "ds-init"])));
+ assert.deepEqual(problems(), [`${UI}/screens/extra.md: kind "atom" does not belong in screens/`]);
+ });
+ });
+
+ describe("R3 required keys and values", () => {
+ const missing = [
+ [SYSTEM, "locales: [fr, ar]\n", "locales"],
+ [BRAND, "version: 1\n", "version"],
+ [BUTTON, "role: button\n", "role"],
+ [HOME, "route: /\n", "route"],
+ [JOURNEY, "persona: a first-time analyst\n", "persona"],
+ [ICON, "alt: Search\n", "alt"],
+ [REVIEW, "scope: system\n", "scope"],
+ ];
+ for (const [file, line, key] of missing) {
+ it(`names ${key} missing from ${path.basename(file)}`, () => {
+ change(file, line, "");
+ assert.deepEqual(problems(), [`${file}: missing key "${key}"`]);
+ });
+ }
+
+ it("names an unknown status", () => {
+ change(JOURNEY, "status: validated", "status: done");
+ assert.deepEqual(problems(), [`${JOURNEY}: status "done" must be proposed, validated, coded or deprecated`]);
+ });
+
+ it("names an interactive value that is neither yes nor no", () => {
+ change(SEARCH, "interactive: yes", "interactive: maybe");
+ assert.deepEqual(problems(), [`${SEARCH}: interactive "maybe" must be yes or no`]);
+ });
+
+ it("names an unknown asset type", () => {
+ change(ICON, "type: icon", "type: photo");
+ assert.deepEqual(problems(), [`${ICON}: type "photo" must be icon, image or illustration`]);
+ });
+ });
+
+ describe("R4 identity", () => {
+ it("names an id that differs from the file name", () => {
+ change(JOURNEY, "id: onboarding", "id: onboard");
+ assert.deepEqual(problems(), [`${JOURNEY}: id "onboard" differs from the file name "onboarding"`]);
+ });
+
+ it("names an id two records hold", () => {
+ const screen = ["id: brand", "kind: screen", "status: proposed", "version: 1", "uses: []", "states: [default]", "breakpoints: [mobile]", "route: /brand"];
+ put(tmp, `${UI}/screens/brand.md`, record(screen, history(["1", "created", "no", "ds-init"])));
+ assert.deepEqual(problems(), [`${UI}/screens/brand.md: id "brand" already belongs to ${BRAND}`]);
+ });
+ });
+
+ describe("R5 version", () => {
+ for (const bad of ["0", "v2"]) {
+ it(`names element version ${bad}`, () => {
+ change(JOURNEY, "version: 1", `version: ${bad}`);
+ assert.deepEqual(problems(), [`${JOURNEY}: version "${bad}" must be an integer from 1`]);
+ });
+ }
+
+ it("names a system version that is not semver", () => {
+ change(SYSTEM, "version: 2.0.0", "version: 1.0");
+ assert.deepEqual(problems(), [`${SYSTEM}: version "1.0" must be semver, such as 2.0.0`]);
+ });
+ });
+
+ describe("R6 uses", () => {
+ it("names a used id no record has", () => {
+ change(SEARCH, "uses: [button, icon-search]", "uses: [button, icon-search, ghost]");
+ assert.deepEqual(problems(), [`${SEARCH}: uses "ghost", which no record has`]);
+ });
+
+ const levels = [
+ [OLD, "uses: []", "uses: [button]", 'atom cannot use atom "button"'],
+ [SEARCH, "uses: [button, icon-search]", "uses: [button, icon-search, dialog]", 'molecule cannot use composition "dialog"'],
+ [HOME, "uses: [search-field, dialog]", "uses: [search-field, dialog, home]", 'screen cannot use screen "home"'],
+ ];
+ for (const [file, from, to, message] of levels) {
+ it(`names a ${message.split(" ")[0]} using its own level or above`, () => {
+ change(file, from, to);
+ assert.deepEqual(problems(), [`${file}: ${message}`]);
+ });
+ }
+ });
+
+ describe("R7 states and keyboard", () => {
+ it("names an interactive component without hover", () => {
+ change(BUTTON, "states: [default, hover, focus, disabled]", "states: [default, focus, disabled]");
+ assert.deepEqual(problems(), [`${BUTTON}: interactive component lacks state "hover"`]);
+ });
+
+ it("names a component without default", () => {
+ change(OLD, "states: [default]", "states: [idle]");
+ assert.deepEqual(problems(), [`${OLD}: component lacks state "default"`]);
+ });
+
+ it("names a screen without default", () => {
+ change(HOME, "states: [default, empty, loading, error]", "states: [empty, loading, error]");
+ assert.deepEqual(problems(), [`${HOME}: screen lacks state "default"`]);
+ });
+
+ it("names an interactive component without a keyboard section", () => {
+ change(DIALOG, "## Keyboard\n\nEscape closes it; focus stays inside while it is open.\n\n", "");
+ assert.deepEqual(problems(), [`${DIALOG}: interactive component lacks a "## Keyboard" section`]);
+ });
+ });
+
+ describe("R8 coded", () => {
+ it("names a coded record without code", () => {
+ change(HOME, "code: src/ui/HomePage.tsx#HomePage\n", "");
+ assert.deepEqual(problems(), [`${HOME}: status coded needs "code"`]);
+ });
+ });
+
+ describe("R9 deprecated", () => {
+ it("names a deprecated record without replaced-by", () => {
+ change(OLD, "replaced-by: button\n", "");
+ assert.deepEqual(problems(), [`${OLD}: status deprecated needs "replaced-by"`]);
+ });
+
+ it("names a replacement no record has", () => {
+ change(OLD, "replaced-by: button", "replaced-by: ghost");
+ assert.deepEqual(problems(), [`${OLD}: replaced-by "ghost", which no record has`]);
+ });
+
+ it("names a replacement that is deprecated too", () => {
+ change(OLD, "replaced-by: button", "replaced-by: old-button");
+ assert.deepEqual(problems(), [`${OLD}: replaced-by "old-button" is deprecated too`]);
+ });
+
+ it("names replaced-by none without a deprecation section", () => {
+ change(OLD, "replaced-by: button", "replaced-by: none");
+ assert.deepEqual(problems(), [`${OLD}: replaced-by none needs a "## Deprecation" section saying why`]);
+ });
+ });
+
+ describe("R10 deprecated in use", () => {
+ it("names a live record using a deprecated one", () => {
+ change(SEARCH, "uses: [button, icon-search]", "uses: [button, icon-search, old-button]");
+ assert.deepEqual(problems(), [`${SEARCH}: uses "old-button", which is deprecated`]);
+ });
+ });
+
+ describe("R11 breakpoints", () => {
+ it("names a screen breakpoint system.md lacks", () => {
+ change(HOME, "breakpoints: [mobile, desktop]", "breakpoints: [mobile, tablet, desktop]");
+ assert.deepEqual(problems(), [`${HOME}: breakpoint "tablet" is not in system.md`]);
+ });
+ });
+
+ describe("R12 journeys", () => {
+ it("names a step whose screen is absent", () => {
+ change(JOURNEY, "| home | opens a result |", "| ghost | opens a result |");
+ assert.deepEqual(problems(), [`${JOURNEY}: step 2 names screen "ghost", which no screen has`]);
+ });
+ });
+
+ describe("R13 reviews", () => {
+ it("names a screen state with no verdict row", () => {
+ change(REVIEW, "| home | loading | ko | spinner too small |\n", "");
+ assert.deepEqual(problems(), [`${REVIEW}: no verdict row for home / loading`]);
+ });
+
+ it("names a verdict that is not ok, ko or pending", () => {
+ change(REVIEW, "| home | default | ok | |", "| home | default | maybe | |");
+ assert.deepEqual(problems(), [`${REVIEW}: verdict "maybe" for home / default must be ok, ko or pending`]);
+ });
+ });
+
+ describe("R14 brand", () => {
+ it("names a missing brand heading", () => {
+ change(BRAND, "## Users\n\nAnalysts.\n\n", "");
+ assert.deepEqual(problems(), [`${BRAND}: lacks "## Users"`]);
+ });
+ });
+
+ describe("R15 assets", () => {
+ it("names an asset whose file is absent", () => {
+ change(ICON, "file: icon-search.svg", "file: missing.svg");
+ assert.deepEqual(problems(), [`${ICON}: file "missing.svg" does not exist beside it`]);
+ });
+ });
+
+ describe("R16 system, brand and review statuses", () => {
+ const cases = [
+ [SYSTEM, "status: validated", "coded"],
+ [BRAND, "status: validated", "deprecated"],
+ [REVIEW, "status: proposed", "coded"],
+ ];
+ for (const [file, from, status] of cases) {
+ it(`names ${path.basename(file)} with status ${status}`, () => {
+ change(file, from, `status: ${status}`);
+ assert.deepEqual(problems(), [`${file}: status "${status}" is for elements: system, brand and reviews are proposed or validated`]);
+ });
+ }
+ });
+
+ describe("H1 history present", () => {
+ it("names a versioned record without a history table", () => {
+ change(JOURNEY, "## History", "## Changes");
+ assert.deepEqual(problems(), [`${JOURNEY}: no "## History" table`]);
+ });
+ });
+
+ describe("H2 one change per version", () => {
+ it("names two rows claiming one version, as a merge of two branches leaves", () => {
+ change(OLD, "| 2 | deprecated for button |", "| 2 | larger label | no | ds-init |\n| 2 | deprecated for button |");
+ assert.deepEqual(problems(), [`${OLD}: two changes claim version 2, renumber one`]);
+ });
+ });
+
+ describe("H3 version matches history", () => {
+ it("names a version that is not the highest row", () => {
+ change(JOURNEY, "version: 1", "version: 2");
+ assert.deepEqual(problems(), [`${JOURNEY}: version 2 is not the highest history row, 1`]);
+ });
+
+ it("names a gap in the history", () => {
+ change(BUTTON, "version: 1", "version: 3");
+ change(BUTTON, "| 1 | created | no | ds-init |", "| 1 | created | no | ds-init |\n| 3 | larger | no | ds-init |");
+ assert.deepEqual(problems(), [`${BUTTON}: history jumps from 1 to 3`]);
+ });
+ });
+
+ describe("H4 breaking", () => {
+ it("names a breaking value that is neither yes nor no", () => {
+ change(JOURNEY, "| 1 | created | no |", "| 1 | created | maybe |");
+ assert.deepEqual(problems(), [`${JOURNEY}: breaking "maybe" in version 1 must be yes or no`]);
+ });
+ });
+
+ describe("H5 system version follows its tasks", () => {
+ it("names a breaking task without a major bump", () => {
+ change(SYSTEM, "version: 2.0.0", "version: 1.1.0");
+ change(SYSTEM, "| 2.0.0 |", "| 1.1.0 |");
+ assert.deepEqual(problems(), [`${SYSTEM}: task "retire-old-button" breaks an element, yet system.md 1.1.0 raises no major version`]);
+ });
+
+ it("names a non-breaking task whose system row raises nothing", () => {
+ change(BUTTON, "version: 1", "version: 2");
+ change(BUTTON, "| 1 | created | no | ds-init |", "| 1 | created | no | ds-init |\n| 2 | larger padding | no | tweak |");
+ change(SYSTEM, "version: 2.0.0", "version: 2.0.1");
+ change(SYSTEM, "| 2.0.0 | old-button retired | yes | retire-old-button |", "| 2.0.0 | old-button retired | yes | retire-old-button |\n| 2.0.1 | button padding | no | tweak |");
+ assert.deepEqual(problems(), [`${SYSTEM}: task "tweak" changes an element, yet system.md 2.0.1 raises neither major nor minor`]);
+ });
+
+ it("names a task system.md has no row for", () => {
+ change(JOURNEY, "| no | ds-init |", "| no | new-flow |");
+ assert.deepEqual(problems(), [`${JOURNEY}: task "new-flow" has no row in system.md`]);
+ });
+ });
+
+ describe("H6 deprecation breaks", () => {
+ it("names a deprecated record whose last row is not breaking", () => {
+ change(OLD, "| yes | retire-old-button |", "| no | retire-old-button |");
+ assert.deepEqual(problems(), [`${OLD}: deprecated, yet its last history row is not breaking`]);
+ });
+ });
+});
diff --git a/scripts/__tests__/aidd-ui-tokens-renders.test.js b/scripts/__tests__/aidd-ui-tokens-renders.test.js
new file mode 100644
index 000000000..c36f0bd41
--- /dev/null
+++ b/scripts/__tests__/aidd-ui-tokens-renders.test.js
@@ -0,0 +1,208 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { describe, it, beforeEach, afterEach } = require("node:test");
+const { UI, writeProject, edit, editTokens } = require("./fixtures/aidd-ui/project.js");
+
+// Each rule has one mutation of the valid project, and the test asserts the whole problem
+// list: dropping the rule turns its own test red and leaves every other one green.
+const LIB = path.resolve(__dirname, "../../plugins/aidd-ui/hooks/lib");
+const { load } = require(path.join(LIB, "project.cjs"));
+const tokens = require(path.join(LIB, "tokens.cjs"));
+const renders = require(path.join(LIB, "renders.cjs"));
+
+const TOKENS = `${UI}/tokens.json`;
+const SYSTEM = `${UI}/system.md`;
+const BUTTON = `${UI}/components/button.md`;
+const BUTTON_RENDER = `${UI}/components/button.html`;
+const DIALOG = `${UI}/components/dialog.md`;
+const DIALOG_RENDER = `${UI}/components/dialog.html`;
+const INSERTED_LINE = 30; // the line before in button.html
+
+let tmp;
+
+beforeEach(() => {
+ tmp = fs.mkdtempSync(path.join(os.tmpdir(), "aidd-ui-tokens-renders-"));
+ writeProject(tmp);
+});
+
+afterEach(() => {
+ fs.rmSync(tmp, { recursive: true, force: true });
+ assert.equal(fs.existsSync(tmp), false);
+});
+
+/** Every problem both checks find, as `file: message`. */
+function problems() {
+ const project = load(tmp);
+ return [...tokens.check(project), ...renders.check(project)].map((problem) => `${problem.file}: ${problem.message}`);
+}
+
+/** Adds one token under a `misc` group. */
+const addToken = (name, token) => editTokens(tmp, (tree) => (tree.misc = { ...tree.misc, [name]: token }));
+
+/** Adds one element to button.html, on the line before . */
+const addToRender = (html) => edit(tmp, BUTTON_RENDER, "", `${html}\n`);
+
+describe("aidd-ui tokens and renders", () => {
+ it("passes the valid project", () => {
+ assert.deepEqual(problems(), []);
+ });
+
+ it("names every token's CSS custom property", () => {
+ const names = tokens.cssNames(load(tmp));
+ assert.equal(names.get("color.text.default"), "--color-text-default");
+ assert.equal(names.size, 7);
+ });
+
+ describe("T1 JSON", () => {
+ it("names a tokens file that is not JSON", () => {
+ fs.writeFileSync(path.join(tmp, TOKENS), "{ not json");
+ assert.deepEqual(problems(), [`${TOKENS}: not JSON`]);
+ });
+ });
+
+ describe("T2 names", () => {
+ it("names a $ key that is not reserved", () => {
+ editTokens(tmp, (tree) => (tree.color.$foo = 1));
+ assert.deepEqual(problems(), [`${TOKENS}: color.$foo: "$foo" is not a reserved key`]);
+ });
+
+ it("names a name holding a dot", () => {
+ addToken("a.b", { $type: "number", $value: 1 });
+ assert.deepEqual(problems(), [`${TOKENS}: misc.a.b: a name never holds ".", "{" or "}"`]);
+ });
+ });
+
+ describe("T3 value and type", () => {
+ const cases = [
+ [{ $type: "number" }, "no $value"],
+ [{ $value: 1 }, "no $type on it, its alias or a parent group"],
+ [{ $type: "colour", $value: 1 }, '$type "colour" is not a DTCG type'],
+ ];
+ for (const [token, message] of cases) {
+ it(`names a token with ${message}`, () => {
+ addToken("x", token);
+ assert.deepEqual(problems(), [`${TOKENS}: misc.x: ${message}`]);
+ });
+ }
+ });
+
+ describe("T4 primitive shapes", () => {
+ const cases = [
+ [{ $type: "color", $value: { colorSpace: "cmyk", components: [0, 0, 0] } }, 'colorSpace "cmyk" is not a DTCG colour space'],
+ [{ $type: "color", $value: { colorSpace: "srgb", components: [0, 0] } }, 'components must be three numbers or "none"'],
+ [{ $type: "color", $value: { colorSpace: "srgb", components: [0, 0, 0], hex: "#fff" } }, 'hex "#fff" must be # and six hex digits'],
+ [{ $type: "dimension", $value: { value: 1, unit: "em" } }, 'unit "em" must be px or rem'],
+ [{ $type: "duration", $value: { value: 1, unit: "min" } }, 'unit "min" must be ms or s'],
+ [{ $type: "fontWeight", $value: 1200 }, "fontWeight 1200 must be 1 to 1000 or a keyword"],
+ [{ $type: "cubicBezier", $value: [1.5, 0, 0.5, 1] }, "cubicBezier needs four numbers, x in 0..1"],
+ ];
+ for (const [token, message] of cases) {
+ it(`names ${message}`, () => {
+ addToken("x", token);
+ assert.deepEqual(problems(), [`${TOKENS}: misc.x: ${message}`]);
+ });
+ }
+ });
+
+ describe("T5 aliases", () => {
+ it("names an alias to no token", () => {
+ addToken("x", { $type: "color", $value: "{color.missing}" });
+ assert.deepEqual(problems(), [`${TOKENS}: misc.x: alias {color.missing} names no token`]);
+ });
+
+ it("names an alias to a group", () => {
+ addToken("x", { $type: "color", $value: "{color.brand}" });
+ assert.deepEqual(problems(), [`${TOKENS}: misc.x: alias {color.brand} names a group, not a token`]);
+ });
+ });
+
+ describe("T6 themes", () => {
+ const themes = (tree) => tree.color.brand.primary.$extensions["dev.ai-driven.themes"];
+
+ it("names a theme system.md lacks", () => {
+ editTokens(tmp, (tree) => {
+ themes(tree).sepia = themes(tree).dark;
+ delete themes(tree).dark;
+ });
+ assert.deepEqual(problems(), [`${TOKENS}: color.brand.primary: theme "sepia" is not in system.md`]);
+ });
+
+ it("names a theme value of the wrong shape", () => {
+ editTokens(tmp, (tree) => (themes(tree).dark.components = [0.4, 0.6]));
+ assert.deepEqual(problems(), [`${TOKENS}: color.brand.primary: theme "dark": components must be three numbers or "none"`]);
+ });
+ });
+
+ describe("T7 component tokens", () => {
+ it("names a component token absent from tokens.json", () => {
+ edit(tmp, BUTTON, "tokens: [color.brand.primary,", "tokens: [space.huge, color.brand.primary,");
+ assert.deepEqual(problems(), [`${BUTTON}: token "space.huge" is not in tokens.json`]);
+ });
+ });
+
+ describe("T8 sizes in rem", () => {
+ it("names a dimension in px", () => {
+ editTokens(tmp, (tree) => (tree.space.md.$value = { value: 16, unit: "px" }));
+ assert.deepEqual(problems(), [`${TOKENS}: space.md: sizes are in rem, not px`]);
+ });
+ });
+
+ describe("V1 render present", () => {
+ it("names a component without its render", () => {
+ fs.rmSync(path.join(tmp, DIALOG_RENDER));
+ assert.deepEqual(problems(), [`${DIALOG}: no render beside it, expected dialog.html`]);
+ });
+ });
+
+ describe("V2 every variant and state rendered", () => {
+ it("names a declared variant the render lacks", () => {
+ edit(tmp, BUTTON_RENDER, 'data-variant="secondary"', 'data-variant="primary"');
+ assert.deepEqual(problems(), [`${BUTTON_RENDER}: no data-variant="secondary"`]);
+ });
+
+ it("names a declared state the render lacks", () => {
+ edit(tmp, DIALOG_RENDER, 'data-state="hover"', 'data-state="default"');
+ assert.deepEqual(problems(), [`${DIALOG_RENDER}: no data-state="hover"`]);
+ });
+ });
+
+ describe("V3 token references", () => {
+ it("names a custom property no token defines", () => {
+ addToRender('