Design once. Agents build without drift.

1. 01

   Step 1. Receive the task

   Product intent arrives in prose. Nothing about the design system is decided yet.

   Build the account settings screen with profile information, notification preferences, and destructive account actions.

2. 02

   Step 2. Query the system

   The agent reads canonical context instead of inferring APIs. Every source below ships inside the package and the published release.

   • design-system.manifest.json
   • llms.txt
   • llms-full.txt
   • AGENTS.md
   • templates/agent/manifest.json

   bashCopy Code

   npm run agent:query -- context
   npm run agent:query -- templates
   npm run agent:query -- component toggle
   npm run agent:query -- guideline accessibility

3. 03

   Step 3. Select approved building blocks

   The settings brief matches one reviewed archetype. The template names its slots, its required states, and the primitives it composes.

   • archetype: workspace, subtype settings
   • components: Button, Notice, Surface, Toggle
   • states: ready, saving, saved, error, forbidden
   • semantic tokens through the shared Tailwind preset

   bashCopy Code

   npm run agent:query -- template settings

4. 04

   Step 4. Implement

   Composition happens against public exports and documented props. Local reinvention of a shared primitive is not an implementation detail; it is drift.

   Uses

   • public components from @ai-created/ui
   • documented props and variants
   • semantic tokens and utilities
   • approved composition patterns

   Rejected by validation

   • locally recreated design-system components
   • raw color values
   • undocumented variants
   • arbitrary radius, shadow, and palette utilities
   • guessed component APIs
5. 05

   Step 5. Validate

   The same commands run for an agent, a contributor, and continuous integration. None of them are advisory.

   bashCopy Code

   npm run agent:check
   npm run typecheck
   npm run validate

6. 06

   Step 6. Pass or fail loudly

   There is no third outcome where a departure quietly ships. A justified departure is written down, scoped, owned, and given an expiry date.

   Contract satisfied

   Every blocking check exits zero and the work is publishable.

   Design policy violation

   The validator prints the rule, file, line, and required correction.

The system should never silently accept design-system drift. An agent either follows the contract, fails a blocking check, or records a narrowly scoped exception for human review.

npm run validate runs typecheck, lint, tests, the full agent contract, the portal build, and the package check in one command. Browser and visual coverage runs through npm run test:browser. Both are required on every pull request.

Product work stays flexible. System decisions stay governed.

1. 01

   Product requirement

   A real, specific need appears in product work.

2. 02

   No approved system solution

   Composition and every approved template were tried first.

3. 03

   Document exception

   One rule, narrow file globs, a concrete reason, an owner, and a review date.

4. 04

   Human review

   A person decides. The validator only enforces the shape and the expiry.

{
  "exceptions": [
    {
      "rule": "no-raw-color",
      "files": ["src/product/legacy-chart-theme.ts"],
      "reason": "The charting vendor needs literal hex until the token adapter lands.",
      "owner": "Design Systems",
      "reviewBy": "2026-12-01"
    }
  ]
}

The schema at contracts/design-policy.schema.json requires all five fields, rejects catch-all globs, and limits the rule to one of the 6 policy rules. Read the full policy in the governance guideline.