feat(design): derive contracts from snapshot source and unify findings

Author: Bill Leoutsakos

.agents/skills/emcn-design-review/SKILL.md

@@ -8,9 +8,10 @@ argument-hint: "[scope] [fix=true|false]"
 
 Review the requested product UI scope (default: current changes). When `fix=false`, explain proposed changes without applying them.
 
-1. During UI work, run `bun run check:design --base origin/staging --working-tree` from the repo root, substituting the actual PR target for `origin/staging`. After committing, use `--head HEAD` for the immutable PR comparison. Exit 1 means findings to review; exit 2 means the check failed and must be repaired or reported. CI is warning-only for findings and fails on incomplete analysis.
-2. For each new finding or relevant review signal, inspect the cited source, the applicable public EMCN export in `packages/emcn/src/index.ts`, and tokens and recipes in `apps/sim/app/_styles/globals.css`. Reuse a suitable component, prop, variant, or global token when it expresses the design intent. Avoid near-duplicate local colours or overriding EMCN chrome merely for convenience.
-3. A genuinely new product treatment may remain an Extra. Explain its visual intent and why existing EMCN or global styling does not fit in the PR. The check does not decide design approval and must not be silenced by adding an arbitrary token, broad exclusion, or fake component wrapper. Ask the designer or engineer when changing a shared recipe would have broad or ambiguous effects.
-4. Keep unresolved `unchecked` inputs and inspection failures distinct from proven violations. A quiet diff means no *new detected* debt, not proof of complete visual conformance. Existing debt stays quiet; a new copy can warn. Landing and docs are out of product scope; Monaco presentation, provider branding, and block identity palettes have deliberate exclusions. See `scripts/design-conformance/README.md` for exact rule boundaries.
+1. When EMCN, global styles, recipes or design ownership metadata change, run `bun run design:generate` and commit `scripts/design-conformance/contracts.generated.json` with the source. `bun run check:design-generated` checks freshness without writing. Regeneration does not hide the originating design-system finding.
+2. During UI work, run `bun run check:design --base origin/staging --working-tree` from the repo root, substituting the actual PR target for `origin/staging`. After committing, use `--head HEAD` for the immutable PR comparison. Exit 1 means findings to review; exit 2 means the check failed and must be repaired or reported. CI is warning-only for findings and fails on incomplete analysis.
+3. For each new finding, inspect the cited source, the applicable public EMCN export in `packages/emcn/src/index.ts`, and tokens and recipes in `apps/sim/app/_styles/globals.css`. Reuse a suitable component, prop, variant, or global token when it expresses the design intent. Avoid near-duplicate local colours or overriding EMCN chrome merely for convenience.
+4. A genuinely new product treatment may remain an Extra. Explain its visual intent and why existing EMCN or global styling does not fit in the PR. The check does not decide design approval and must not be silenced by adding an arbitrary token, broad exclusion, or fake component wrapper. Ask the designer or engineer when changing a shared recipe would have broad or ambiguous effects.
+5. Keep unresolved `unchecked` inputs and inspection failures separate from findings. A quiet diff means no *new detected* debt, not proof of complete visual conformance. Existing debt stays quiet; a new copy can warn. Landing and docs are out of product scope; Monaco presentation, provider branding, and block identity palettes have deliberate exclusions. See `scripts/design-conformance/README.md` for exact rule boundaries.
 
 Do not turn this review into an unrelated whole-codebase cleanup. Preserve intended appearance when migrating product UI and use before/after screenshots when a treatment changes.

.agents/skills/ship/SKILL.md

@@ -102,6 +102,8 @@ When the user runs `/ship`:
 
 ## Committed design check
 
+When central EMCN sources, global styles, recipes or `@designAllow`/`@designProtect` metadata change, run `bun run design:generate`, review the result and commit `contracts.generated.json` alongside the source. `check:design-generated` is part of `check:audits`; stale output is an infrastructure error. Regeneration does not suppress the source finding.
+
 During product UI work, run `bun run check:design --base origin/staging --working-tree` so staged, unstaged and nonignored new files are included. Review findings against EMCN and `globals.css`; explain intentional new Extras rather than weakening the checker. After committing and before **every push**, run this from the repository root with Bun 1.4.1:
 
 ```bash

.claude/rules/emcn-components.md

@@ -57,3 +57,7 @@ Declare keyboard intent on the action-owning primitive; never add document-level
 - Use Radix UI primitives for accessibility. Export the component and its `variants` (when using CVA). Document with TSDoc + a usage example.
 
 Color tokens and icon-size conventions are canonical in `.claude/rules/sim-styling.md` — follow it rather than restating.
+
+## Generated design contracts
+
+Run `bun run design:generate` after public API, styling, recipe or ownership changes and commit `scripts/design-conformance/contracts.generated.json` with the source. CI checks freshness through `check:design-generated`. Ownership is derived from implementation; intentional customization belongs in component TSDoc (`@designAllow <slot> <CSS properties or policy groups>`, `@designProtect` for ownership that cannot be inferred). Review the diff findings after generation; they retain originating central changes. Browser reports and captures remain local, outside the repository.

.cursor/rules/emcn-components.mdc

@@ -58,3 +58,7 @@ Declare keyboard intent on the action-owning primitive; never add document-level
 - Use Radix UI primitives for accessibility. Export the component and its `variants` (when using CVA). Document with TSDoc + a usage example.
 
 Color tokens and icon-size conventions are canonical in `.claude/rules/sim-styling.md` — follow it rather than restating.
+
+## Generated design contracts
+
+Run `bun run design:generate` after public API, styling, recipe or ownership changes and commit `scripts/design-conformance/contracts.generated.json` with the source. CI checks freshness through `check:design-generated`. Ownership is derived from implementation; intentional customization belongs in component TSDoc (`@designAllow <slot> <CSS properties or policy groups>`, `@designProtect` for ownership that cannot be inferred). Review the diff findings after generation; they retain originating central changes. Browser reports and captures remain local, outside the repository.

biome.json

@@ -169,7 +169,8 @@
     {
       "includes": [
         "scripts/design-conformance/catalogue.json",
-        "scripts/design-conformance/contracts.json"
+        "scripts/design-conformance/contracts.json",
+        "scripts/design-conformance/contracts.generated.json"
       ],
       "formatter": {
         "enabled": false

package.json

@@ -20,8 +20,8 @@
     "test:search-performance": "KNOWLEDGE_SEARCH_PERFORMANCE_TEST=true bun --no-env-file scripts/test-integration.ts search-latency",
     "format": "biome format --write scripts/design-conformance scripts/check-design-conformance*.ts && turbo run format",
     "format:check": "biome format scripts/design-conformance scripts/check-design-conformance*.ts && turbo run format:check",
-    "lint": "biome check --write scripts/design-conformance scripts/design-scan scripts/design-studio tools/design-studio scripts/check-design-conformance*.ts && turbo run lint",
-    "lint:check": "biome check scripts/design-conformance scripts/design-scan scripts/design-studio tools/design-studio scripts/check-design-conformance*.ts && turbo run lint:check",
+    "lint": "biome check --write scripts/design-conformance scripts/design-scan scripts/design-studio tools/design-studio scripts/check-design-conformance*.ts scripts/generate-design-contracts*.ts && turbo run lint",
+    "lint:check": "biome check scripts/design-conformance scripts/design-scan scripts/design-studio tools/design-studio scripts/check-design-conformance*.ts scripts/generate-design-contracts*.ts && turbo run lint:check",
     "lint:helm": "helm lint helm/sim --strict --values helm/sim/ci/default-values.yaml",
     "lint:all": "bun run lint && bun run lint:helm",
     "check": "bun run format:check",
@@ -129,7 +129,9 @@
     "studio:dev": "next dev tools/design-studio --hostname 127.0.0.1 --port 3001",
     "type-check:studio": "tsc --noEmit -p tools/design-studio/tsconfig.json",
     "type-check:design": "tsc --noEmit -p scripts/design-conformance/tsconfig.json",
-    "check:agent-cli-boundary": "bun run scripts/check-agent-cli-boundary.ts"
+    "check:agent-cli-boundary": "bun run scripts/check-agent-cli-boundary.ts",
+    "design:generate": "bun --no-env-file scripts/generate-design-contracts.ts",
+    "check:design-generated": "bun run --no-env-file scripts/generate-design-contracts.ts --check"
   },
   "overrides": {
     "react": "19.2.4",

packages/emcn/src/components/banner/banner.tsx

@@ -32,6 +32,7 @@ export interface BannerProps
   textClassName?: string
 }
 
+/** @designAllow textClassName typography */
 export function Banner({
   actionClassName,
   actionDisabled,

packages/emcn/src/components/chip-input/chip-input.tsx

@@ -50,6 +50,9 @@ export interface ChipInputProps extends Omit<React.InputHTMLAttributes<HTMLInput
 /**
  * Forwards its ref to the inner `<input>` so callers can focus or measure the
  * field directly, exactly like a native input.
+ * @designProtect className colours font-family font-size padding height gap border-radius borders box-shadow
+ * @designProtect style colours font-family font-size padding height gap border-radius borders box-shadow
+ * @designAllow inputClassName typography
  */
 export const ChipInput = React.forwardRef<HTMLInputElement, ChipInputProps>(
   (

packages/emcn/src/components/chip-textarea/chip-textarea.tsx

@@ -39,7 +39,9 @@ export interface ChipTextareaProps
   viewOnly?: boolean
 }
 
-/** Forwards its ref to the underlying `<textarea>`, exactly like a native textarea. */
+/** Forwards its ref to the underlying `<textarea>`, exactly like a native textarea. * @designProtect className colours font-family font-size padding gap border-radius borders box-shadow
+ * @designProtect style colours font-family font-size padding gap border-radius borders box-shadow
+ */
 export const ChipTextarea = React.forwardRef<HTMLTextAreaElement, ChipTextareaProps>(
   ({ className, error, resizable = false, viewOnly = false, readOnly, ...props }, ref) => (
     <textarea

packages/emcn/src/components/input/input.tsx

@@ -33,7 +33,11 @@ const INPUT_CLASS =
 
 export type InputProps = React.InputHTMLAttributes<HTMLInputElement>
 
-/** Minimal input component matching the textarea styling. */
+/**
+ * Minimal input component matching the textarea styling.
+ * @designProtect className height
+ * @designProtect style height
+ */
 const Input = React.forwardRef<HTMLInputElement, InputProps>(
   ({ className, type = 'text', ...props }, ref) => {
     return <input type={type} className={cn(INPUT_CLASS, className)} ref={ref} {...props} />