refactor(design): simplify conformance tooling and studio samples

Author: Bill Leoutsakos

.claude/rules/emcn-components.md

@@ -19,22 +19,13 @@ Canonical look: normal font-weight (never `font-medium`/`font-semibold`), value
 
 The menu surface intentionally diverges from the pill: `dropdown-menu.tsx` items use `text-small` and `gap-2` (a menu convention, not the chip pill). Keep them distinct.
 
-## Component catalogue
-
-- **`Chip` / `ChipLink`** — the pill button (`<button>` / Next `<Link>`). Variants: `primary`, `destructive`, `border-shadow`, `border`, `outline` (a true `--border` border, no shadow or hover fill); the bare chip is implicit (omit `variant`). `filled` is deliberately NOT a `Chip` variant — it is reserved for chip fields/triggers. For a selected/toggle chip use the `active` prop, never a variant. `leftIcon`/`rightIcon`, `active`, `fullWidth`. Chips carry **no outer margin** — space between them is the parent's `gap`. The old `mx-0.5` default and its `flush` opt-out are gone; do not reintroduce either, and never add a margin to a chip through `className`.
-- **`ChipInput`** — single-line text field. `icon`, `endAdornment`, `error`, `inputClassName` (inner `<input>`); `className` styles the chrome wrapper.
-- **`ChipCopyInput`** — the canonical view-only field: a read-only `ChipInput` at full opacity with a trailing copy-to-clipboard button. View-only is a display mode, not a disabled state — reach for it (or `ChipModalField type='copy'`) over a `disabled` (greyed) input for values the user cannot edit.
-- **`ChipTextarea`** — multi-line sibling. `error`, `resizable` (off by default), `viewOnly` (read-only at full opacity with the default cursor — the multi-line counterpart of `ChipCopyInput`).
-- **`ChipDropdown`** — pill that opens a menu. Single OR multi-select via the discriminated `multiple` prop (one component, not two). Owns its trailing chevron — no `rightIcon`.
-- **`ChipSelect` / `ChipCombobox`** — `Combobox`-backed pickers with search, groups, multi-select; for richer lists than `ChipDropdown`.
-- **`ChipModal` + `ChipModalField`** — declarative compact modal. The field's `type` (`input` | `email` | `textarea` | `dropdown` | `copy` | `file` | `emails` | `custom`) picks the control and **owns all chrome** — consumers describe intent, never pass `variant`/`className`/`id` to the inner control. `custom` (with a `title`) is the escape hatch for controls the field doesn't cover. Every body field is a `ChipModalField`; the gutter rhythm that makes this matter is in `sim-styling.md` → "Form / chip-modal layout rhythm".
-- **`ChipSwitch`** — segmented pill control (built from `chipVariants`).
-- **`ChipTag`** — 20px inline tag/badge (`mono`/`gray`/`invite`), not a pill trigger.
-- **`ChipDatePicker`** — chip-styled date field.
-- **`ChipTimePicker`** — minute-granular time sibling of `ChipDatePicker`, a `ChipInput` that leniently parses typed input (`9:47`, `947`, `2:05pm`, `14:30`), commits on Enter/blur, and re-renders the canonical `9:47 AM` label.
-- **`DropdownMenu`** — the canonical context/action menu (Radix-backed). Not a chip, but the standard menu for command/action lists; reach for it instead of a hand-rolled popover. Its surface intentionally diverges from the chip pill (`text-small`, `gap-2`) — keep them distinct. For a pill that opens a value picker, use `ChipDropdown`/`ChipSelect` instead.
-- **`useScrollEdges` + `scrollFadeClass` / `scrollFadeAttributes`** — the canonical scroll-region edge treatment. The hook reports which edges hide content (tracking scroll and resizes; pass the element itself, held in state, when the region mounts after its owner, e.g. inside a Radix portal); the class and attributes fade a fixed 12px band at an active edge only, so a list that fits or sits at its top is never fogged. A floating control over the top edge sets `--scroll-fade-inset` to its height. A region that scrolls sideways (a tab row, a chip strip) uses `useScrollEdges(ref, { axis: 'x' })` with `scrollFadeXClass`; the attributes helper is shared. Any divider beside the region belongs to the neighboring block (`border-b` above, `border-t` below), never to the masked element, and shows only while that edge is active. Never hand-roll a `mask-image` gradient for a scroll region.
-- **`OverflowText`** — the canonical single-line overflow treatment for read-only human labels and titles. It owns `min-w-0`, fade-only clipping (never an ellipsis), the conditional 18px edge mask, and the full-value floating tooltip; consumers pass only layout/typography through `className`. `overflowTextClipClass` and `overflowTextFadeClass` are the complete base/faded treatments for the rare component that must own measurement itself; never pair either with `truncate`, `text-ellipsis`, or hover-time mask removal. Use `DropdownMenuItemLabel` for a menu label beside icons, checks, or actions. A non-editable `Combobox` passes the full visual value through `overlayLabel`; the combobox owns the visual overlay's fade and keeps its one accessible tooltip on the interactive layer. Keep ordinary `truncate` only for editable values, code/log/path content, dense or virtualized grids, and rich composite content that cannot supply a plain tooltip label. Multiline copy uses an intentional `line-clamp-*` treatment instead.
+## Public components and design behavior
+
+The current public exports, variants, defaults, styling slots, and relationships are generated from source in `scripts/design-conformance/contracts.generated.json`. Run `bun run design:generate` when EMCN or `globals.css` changes. Browse and interact with the visual exports in the local Design Studio after `bun run studio:refresh`; do not maintain an export list here.
+
+Use chip fields and triggers for product forms, and `DropdownMenu` for context and action lists. Prefer a supported prop to a `className` chrome override. A selected chip uses `active`; outer spacing belongs to its parent. A view-only value stays at full opacity and uses the read-only copy field or `ChipModalField type='copy'`, not a disabled input. `ChipModalField` owns its inner control chrome; use `type='custom'` with a title for a control it does not cover. A chip dropdown owns its chevron and supports single or multi-select through `multiple`; use chip select or combobox for searchable or grouped lists. Inline tags are labels, not pill triggers.
+
+For scroll-region edge fading use `useScrollEdges` with `scrollFadeClass` or `scrollFadeXClass` and `scrollFadeAttributes`; do not hand-roll a mask. For a constrained, single-line, read-only human label use `OverflowText` or `DropdownMenuItemLabel` in a menu; keep its fade and full-value tooltip instead of adding an ellipsis. Keep editable values, code, logs, paths, dense grids, and composite content on their appropriate overflow treatments. Source and variants in EMCN remain the authority if these examples change.
 
 ## Modal keyboard defaults
 

.cursor/rules/emcn-components.mdc

@@ -20,22 +20,13 @@ Canonical look: normal font-weight (never `font-medium`/`font-semibold`), value
 
 The menu surface intentionally diverges from the pill: `dropdown-menu.tsx` items use `text-small` and `gap-2` (a menu convention, not the chip pill). Keep them distinct.
 
-## Component catalogue
-
-- **`Chip` / `ChipLink`** — the pill button (`<button>` / Next `<Link>`). Variants: `primary`, `destructive`, `border-shadow`, `border`, `outline` (a true `--border` border, no shadow or hover fill); the bare chip is implicit (omit `variant`). `filled` is deliberately NOT a `Chip` variant — it is reserved for chip fields/triggers. For a selected/toggle chip use the `active` prop, never a variant. `leftIcon`/`rightIcon`, `active`, `fullWidth`. Chips carry **no outer margin** — space between them is the parent's `gap`. The old `mx-0.5` default and its `flush` opt-out are gone; do not reintroduce either, and never add a margin to a chip through `className`.
-- **`ChipInput`** — single-line text field. `icon`, `endAdornment`, `error`, `inputClassName` (inner `<input>`); `className` styles the chrome wrapper.
-- **`ChipCopyInput`** — the canonical view-only field: a read-only `ChipInput` at full opacity with a trailing copy-to-clipboard button. View-only is a display mode, not a disabled state — reach for it (or `ChipModalField type='copy'`) over a `disabled` (greyed) input for values the user cannot edit.
-- **`ChipTextarea`** — multi-line sibling. `error`, `resizable` (off by default), `viewOnly` (read-only at full opacity with the default cursor — the multi-line counterpart of `ChipCopyInput`).
-- **`ChipDropdown`** — pill that opens a menu. Single OR multi-select via the discriminated `multiple` prop (one component, not two). Owns its trailing chevron — no `rightIcon`.
-- **`ChipSelect` / `ChipCombobox`** — `Combobox`-backed pickers with search, groups, multi-select; for richer lists than `ChipDropdown`.
-- **`ChipModal` + `ChipModalField`** — declarative compact modal. The field's `type` (`input` | `email` | `textarea` | `dropdown` | `copy` | `file` | `emails` | `custom`) picks the control and **owns all chrome** — consumers describe intent, never pass `variant`/`className`/`id` to the inner control. `custom` (with a `title`) is the escape hatch for controls the field doesn't cover. Every body field is a `ChipModalField`; the gutter rhythm that makes this matter is in `sim-styling.md` → "Form / chip-modal layout rhythm".
-- **`ChipSwitch`** — segmented pill control (built from `chipVariants`).
-- **`ChipTag`** — 20px inline tag/badge (`mono`/`gray`/`invite`), not a pill trigger.
-- **`ChipDatePicker`** — chip-styled date field.
-- **`ChipTimePicker`** — minute-granular time sibling of `ChipDatePicker`, a `ChipInput` that leniently parses typed input (`9:47`, `947`, `2:05pm`, `14:30`), commits on Enter/blur, and re-renders the canonical `9:47 AM` label.
-- **`DropdownMenu`** — the canonical context/action menu (Radix-backed). Not a chip, but the standard menu for command/action lists; reach for it instead of a hand-rolled popover. Its surface intentionally diverges from the chip pill (`text-small`, `gap-2`) — keep them distinct. For a pill that opens a value picker, use `ChipDropdown`/`ChipSelect` instead.
-- **`useScrollEdges` + `scrollFadeClass` / `scrollFadeAttributes`** — the canonical scroll-region edge treatment. The hook reports which edges hide content (tracking scroll and resizes; pass the element itself, held in state, when the region mounts after its owner, e.g. inside a Radix portal); the class and attributes fade a fixed 12px band at an active edge only, so a list that fits or sits at its top is never fogged. A floating control over the top edge sets `--scroll-fade-inset` to its height. A region that scrolls sideways (a tab row, a chip strip) uses `useScrollEdges(ref, { axis: 'x' })` with `scrollFadeXClass`; the attributes helper is shared. Any divider beside the region belongs to the neighboring block (`border-b` above, `border-t` below), never to the masked element, and shows only while that edge is active. Never hand-roll a `mask-image` gradient for a scroll region.
-- **`OverflowText`** — the canonical single-line overflow treatment for read-only human labels and titles. It owns `min-w-0`, fade-only clipping (never an ellipsis), the conditional 18px edge mask, and the full-value floating tooltip; consumers pass only layout/typography through `className`. `overflowTextClipClass` and `overflowTextFadeClass` are the complete base/faded treatments for the rare component that must own measurement itself; never pair either with `truncate`, `text-ellipsis`, or hover-time mask removal. Use `DropdownMenuItemLabel` for a menu label beside icons, checks, or actions. A non-editable `Combobox` passes the full visual value through `overlayLabel`; the combobox owns the visual overlay's fade and keeps its one accessible tooltip on the interactive layer. Keep ordinary `truncate` only for editable values, code/log/path content, dense or virtualized grids, and rich composite content that cannot supply a plain tooltip label. Multiline copy uses an intentional `line-clamp-*` treatment instead.
+## Public components and design behavior
+
+The current public exports, variants, defaults, styling slots, and relationships are generated from source in `scripts/design-conformance/contracts.generated.json`. Run `bun run design:generate` when EMCN or `globals.css` changes. Browse and interact with the visual exports in the local Design Studio after `bun run studio:refresh`; do not maintain an export list here.
+
+Use chip fields and triggers for product forms, and `DropdownMenu` for context and action lists. Prefer a supported prop to a `className` chrome override. A selected chip uses `active`; outer spacing belongs to its parent. A view-only value stays at full opacity and uses the read-only copy field or `ChipModalField type='copy'`, not a disabled input. `ChipModalField` owns its inner control chrome; use `type='custom'` with a title for a control it does not cover. A chip dropdown owns its chevron and supports single or multi-select through `multiple`; use chip select or combobox for searchable or grouped lists. Inline tags are labels, not pill triggers.
+
+For scroll-region edge fading use `useScrollEdges` with `scrollFadeClass` or `scrollFadeXClass` and `scrollFadeAttributes`; do not hand-roll a mask. For a constrained, single-line, read-only human label use `OverflowText` or `DropdownMenuItemLabel` in a menu; keep its fade and full-value tooltip instead of adding an ellipsis. Keep editable values, code, logs, paths, dense grids, and composite content on their appropriate overflow treatments. Source and variants in EMCN remain the authority if these examples change.
 
 ## Modal keyboard defaults
 

CLAUDE.md

@@ -106,7 +106,7 @@ The `'use client'` server boundary, the app/worker runtime env split, and featur
 
 ## Styling and EMCN
 
-- Tailwind only. Inline `style` only for a genuinely dynamic value or a CSS variable. Never update global styles; keep styling local to the component. `cn()` from `@sim/emcn` for conditional classes. `size-*` for equal height and width (icons default `size-[14px]`), never `h-N w-N`.
+- Tailwind only. Inline `style` only for a genuinely dynamic value or a CSS variable. Keep component-specific styling local. Change tokens in `globals.css` deliberately when the shared design decision changes, then run `bun run design:generate`. `cn()` from `@sim/emcn` for conditional classes. `size-*` for equal height and width (icons default `size-[14px]`), never `h-N w-N`.
 - Import components, `cn`, and tokens from the `@sim/emcn` barrel; icons from `@sim/emcn/icons`; CSS modules by file path. Never deep-import other component subpaths.
 - The chip family is the canonical chrome: `ChipInput`, `ChipTextarea`, `ChipModal`/`ChipModalField`, `ChipSelect`/`ChipCombobox`/`ChipDropdown`, `ChipSwitch`, `ChipDatePicker`, `Chip`/`ChipLink`, `ChipTag`; `DropdownMenu` for context/action menus. Components own their chrome: consumers pass props (`error`, `icon`, `endAdornment`, `inputClassName`) and `className` carries only layout/sizing. Every labeled field inside a `ChipModalBody` is a `ChipModalField`.
 - Consumer rules, tokens, text scale, and modal rhythm: `.claude/rules/sim-styling.md`. Authoring components in `packages/emcn`: `.claude/rules/emcn-components.md`. Product UI copy: `.claude/rules/sim-ui-copy.md`. Marketing copy and positioning: `.claude/rules/constitution.md`.

scripts/check-design-conformance-colour-assignments.test.ts

@@ -408,7 +408,6 @@ test('landing remains excluded, source is never executed and discovery order is
   const forward = inspectControlAnalysis(files).colourAssignments
   const reverse = inspectControlAnalysis(
     { ...files, entries: [...files.entries].reverse() },
-    [],
     'reverse'
   ).colourAssignments
   expect(reverse).toEqual(forward)

scripts/check-design-conformance-control-comparison.test.ts

@@ -280,38 +280,6 @@ test('registered EMCN chrome is reported once when both analysis passes see it',
   ).toHaveLength(1)
 })
 
-test('changing a reviewed effect recipe or deleting its colour revokes approval despite unchanged shadow text', async () => {
-  const repo = mkdtempSync(path.join(temp, 'shadow-extra-'))
-  git(repo, ['init', '-q'])
-  const global = 'apps/sim/app/_styles/globals.css'
-  const css =
-    'apps/sim/app/workspace/[workspaceId]/files/components/file-viewer/rich-markdown-editor/rich-markdown-editor.css'
-  const tokens = ':root { --selection-bg: #add6ff; --shadow-subtle: 0 2px 4px #000; }'
-  const rule =
-    '.rich-markdown-nodes hr.rich-leaf-in-selection { box-shadow: 0 0 0 0.4em var(--selection-bg); border-radius: 1px; }'
-  put(repo, global, tokens)
-  const empty = commit(repo)
-  put(repo, css, rule)
-  const base = commit(repo)
-  const introduced = await checkComparison({ repo, base: empty, head: base })
-  expect(introduced.shadowExtras).toHaveLength(1)
-  expect(introduced.findings.some((f) => f.rule === 'local-shadow')).toBe(true)
-  expect(introduced.findings.filter((f) => f.rule === 'central-shadow')).toEqual([])
-  put(repo, css, rule.replace('border-radius: 1px', 'border-radius: 2px'))
-  const changed = commit(repo)
-  const report = await checkComparison({ repo, base, head: changed })
-  expect(report.findings.filter((f) => f.rule === 'central-shadow')).toHaveLength(1)
-  expect(report.shadowExtras).toHaveLength(0)
-  put(repo, css, rule)
-  put(repo, global, tokens.replace('--selection-bg: #add6ff;', ''))
-  const removed = commit(repo)
-  expect(
-    (await checkComparison({ repo, base, head: removed })).findings.filter(
-      (f) => f.rule === 'central-shadow'
-    )
-  ).toHaveLength(1)
-})
-
 test('public diff checks approve a verified colour usage but still flag fallbacks and removed writers', async () => {
   const repo = mkdtempSync(path.join(temp, 'colour-usage-'))
   git(repo, ['init', '-q'])

scripts/check-design-conformance-coverage.test.ts

@@ -2,8 +2,7 @@
 import { readFileSync } from 'node:fs'
 import { expect, test } from 'vitest'
 import { inspectControlAnalysis } from '#control-analysis/analysis'
-import { associateFindings } from '#control-analysis/associations'
-import type { ControlSource, InventoryFinding } from '#control-analysis/model'
+import type { ControlSource } from '#control-analysis/model'
 import { ReviewCollector } from '#control-analysis/review'
 import { productScope } from '#control-analysis/scope'
 import { extract } from '#design-conformance/extract'
@@ -12,6 +11,9 @@ import { inspectionFailure } from '#design-conformance/model'
 
 const globals = 'apps/sim/app/_styles/globals.css'
 const ui = 'apps/sim/components/example.tsx'
+const metadata = JSON.parse(
+  readFileSync('scripts/design-conformance/contracts.generated.json', 'utf8')
+) as GeneratedContracts
 function source(files: Record<string, string>): ControlSource {
   return {
     entries: Object.entries(files).map(([path, text]) => ({
@@ -24,20 +26,15 @@ function source(files: Record<string, string>): ControlSource {
     read: (entry) => files[entry.path],
   }
 }
-const metadata = JSON.parse(
-  readFileSync('scripts/design-conformance/contracts.generated.json', 'utf8')
-) as GeneratedContracts
 const inspect = (files: Record<string, string>) =>
   inspectControlAnalysis(
     source({
       [globals]: ':root { --caution: #f59e0b; --color-yellow-500: #eab308; --text-body: #444; }',
       ...files,
     }),
-    [],
     'forward',
     undefined,
     undefined,
-    undefined,
     metadata
   )
 
@@ -403,38 +400,6 @@ test.each([
   )
 })
 
-test('conditional input branches remain directly associated with their control', () => {
-  const finding: InventoryFinding = {
-    id: 'branch',
-    rule: 'component-chrome',
-    category: 'colours',
-    property: 'color',
-    file: ui,
-    line: 1,
-    column: 10,
-    context: 'View / @sim/emcn#Button / className/then',
-    value: 'text-white',
-    reason: 'owned chrome',
-    observedFrom: [ui],
-  }
-  const uses = [
-    {
-      id: 'control',
-      file: ui,
-      line: 1,
-      column: 1,
-      endLine: 1,
-      endColumn: 40,
-      owner: 'View',
-      tag: 'Button',
-      slots: [{ name: 'className', line: 1, column: 5, endLine: 1, endColumn: 30 }],
-    },
-  ]
-  expect(associateFindings(uses, [finding], () => ['@sim/emcn#Button']).get('control')).toEqual({
-    direct: ['branch'],
-    potential: [],
-  })
-})
 test.each([
   'CSS assignment source is nonregular or exceeds the parsing limit',
   'Artwork parser failure; only blob change is known',