@design-ai/cli 4.55.0

package/knowledge/patterns/design-system-qa.md

@@ -0,0 +1,356 @@
+<!-- hand-written -->
+---
+title: Design system QA — visual regression, token drift, a11y regression
+applies_to: [design-system, ci, testing]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Design system QA
+
+A design system without QA decays. Tokens drift from spec, components deviate from their docs, accessibility regresses silently. This is the test pyramid for a design system.
+
+## What can break
+
+| What | How it breaks | Detection |
+| --- | --- | --- |
+| **Token values** | Engineer hard-codes a hex instead of using a token | Token drift lint |
+| **Component visual** | Padding off by 4px after refactor | Visual regression test |
+| **Component API** | Prop signature changes silently | TypeScript + breaking-change detection |
+| **A11y** | New change introduces contrast under 4.5:1 | A11y regression (axe / lighthouse) |
+| **Token-to-Figma sync** | Code says brand-600 = #7C3AED; Figma still has #8B5CF6 | Sync diff CI job |
+| **Cross-component consistency** | Button radius is 8px, Input radius is 10px | Token-usage lint |
+
+## Test pyramid
+
+```
+                   ┌───────────────────────┐
+                   │  Visual regression    │  ← slow, expensive (Chromatic / Percy)
+                   │  (per release)         │
+                   └───────────────────────┘
+              ┌────────────────────────────────┐
+              │  A11y regression (axe-core)    │  ← per PR, fast
+              │  Token-usage lint              │
+              │  Component contract tests       │
+              └────────────────────────────────┘
+       ┌────────────────────────────────────────────┐
+       │  Unit: utility functions (color, format)   │  ← per commit, instant
+       │  Type: TypeScript on tokens + props        │
+       └────────────────────────────────────────────┘
+```
+
+## Layer 1 — token drift detection
+
+### Rule: no raw hex values in component code
+
+Engineers should **only reference tokens** — never inline `#7C3AED`. Lint catches violations:
+
+```js
+// .eslintrc — design-tokens-only rule
+{
+  rules: {
+    "no-restricted-syntax": [
+      "error",
+      {
+        selector: "Literal[value=/^#[0-9A-Fa-f]{3,8}$/]",
+        message: "Use a design token, not a raw hex value.",
+      },
+    ],
+  },
+}
+```
+
+Or via Stylelint for CSS:
+
+```js
+// .stylelintrc
+{
+  rules: {
+    "color-no-hex": [true, { severity: "error" }],
+  },
+}
+```
+
+Allow exceptions in:
+- The token source file itself (`tokens/source.json`).
+- Generated outputs (`tokens.css`).
+
+### Rule: tokens must reference, not duplicate
+
+Semantic tokens reference primitive tokens; they don't duplicate hex:
+
+```yaml
+# Correct
+color.semantic.primary:
+  $value: "{color.brand.primary.600}"
+
+# Wrong (duplicates the value)
+color.semantic.primary:
+  $value: "#7C3AED"
+```
+
+Style Dictionary and similar tools resolve `{path}` references; CI lints for direct values in semantic layers.
+
+### Token sync diff (Figma ↔ code)
+
+If both code and Figma host tokens, drift is inevitable. CI job:
+
+```bash
+#!/bin/bash
+# Pull Figma tokens via REST API
+curl -H "X-Figma-Token: $FIGMA_TOKEN" \
+  "https://api.figma.com/v1/files/$FIGMA_FILE/variables/local" \
+  | jq '...transform...' > /tmp/figma-tokens.json
+
+# Diff against committed tokens
+diff tokens/source.json /tmp/figma-tokens.json && echo "in sync" || {
+  echo "DRIFT DETECTED"
+  exit 1
+}
+```
+
+Run nightly OR on PR open. Fail PR if Figma tokens have drifted from `source.json`.
+
+Decide a direction-of-truth:
+- **Code is source**: drift means Figma needs update. Notify designer.
+- **Figma is source**: drift means code needs regeneration. Auto-PR if possible.
+
+See [`docs/TOKEN-SYNC.md`](../../docs/TOKEN-SYNC.md) for the broader sync strategy.
+
+## Layer 2 — visual regression
+
+Renders every component (or screen) and pixel-compares against a baseline image. Fails if pixels diverge beyond a threshold.
+
+### Tools
+
+| Tool | Cost | Use |
+| --- | --- | --- |
+| **Chromatic** | Paid (Storybook integration) | Best DX. Cloud-based. Diffs per PR. |
+| **Percy** (BrowserStack) | Paid | Similar to Chromatic. Less Storybook-tight. |
+| **Loki** | Free | OSS, pairs with Storybook. Limited features. |
+| **Playwright + image-snapshot** | Free | Roll-your-own with Playwright tests + screenshot diff. |
+| **happo** | Paid | Cross-browser visual regression. |
+
+### What to capture
+
+A test catalog (Storybook stories + critical screen flows):
+
+```js
+// Storybook story per component variant
+export const PrimarySolid = () => <Button intent="primary" variant="solid">Save</Button>;
+export const PrimaryDisabled = () => <Button intent="primary" disabled>Save</Button>;
+export const PrimaryLoading = () => <Button intent="primary" loading>Save</Button>;
+// ... for each variant × size × state combination
+```
+
+For a Button with 4 intents × 4 variants × 3 sizes × 6 states ≈ 288 visual tests. Catch any unintended pixel change.
+
+### Threshold tuning
+
+Set per-test threshold (typically 0.1–0.2% pixel diff):
+
+- **Too tight**: anti-aliasing changes flag every test.
+- **Too loose**: real regressions pass through.
+- Calibrate against your CI runner's font rendering (varies between OSes).
+
+### Approve workflow
+
+When a real change happens:
+1. PR introduces visual change.
+2. CI flags diffs.
+3. Reviewer inspects (Chromatic shows side-by-side).
+4. Reviewer approves diffs as new baseline.
+5. Merge.
+
+Don't mass-approve without inspection — defeats the purpose.
+
+### What to skip
+
+- **Chart rendering** with random data — flaky.
+- **Animations mid-frame** — capture at known states (start, settled, end).
+- **Localized text** — separate per-locale snapshot or use a locale-agnostic placeholder.
+
+## Layer 3 — a11y regression
+
+Axe-core or Lighthouse catches common a11y violations programmatically.
+
+### Tools
+
+- **axe-core**: industry standard. Integrates with Storybook (`storybook-addon-a11y`), Playwright, Cypress.
+- **Lighthouse**: broader audit (a11y, perf, SEO). Run in CI.
+- **pa11y-ci**: CLI a11y testing.
+
+### Per-component (Storybook + axe)
+
+```ts
+// Storybook addon-a11y runs axe on every story
+// Failures block CI
+```
+
+Catches:
+- Missing `<label>` for inputs
+- Missing `alt` on images
+- Insufficient contrast (computed from CSS)
+- Missing `aria-label` on icon-only buttons
+- Invalid ARIA combos
+- Heading hierarchy issues
+
+Doesn't catch:
+- Custom keyboard interactions (must hand-test)
+- Focus management on dynamic content (must hand-test)
+- Screen reader announcement quality (must hand-test)
+
+### Per-page (Playwright + axe)
+
+```ts
+import { test, expect } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+test("dashboard a11y", async ({ page }) => {
+  await page.goto("/dashboard");
+  const results = await new AxeBuilder({ page }).analyze();
+  expect(results.violations).toEqual([]);
+});
+```
+
+Run on every PR. Fail if new violations appear.
+
+## Layer 4 — component contract tests
+
+Tests that verify the component's API contract:
+
+```ts
+// Component spec contract test
+test("Button: aria-disabled when disabled", () => {
+  render(<Button disabled>Click</Button>);
+  expect(screen.getByRole("button")).toHaveAttribute("aria-disabled", "true");
+});
+
+test("Button: type defaults to button (not submit)", () => {
+  render(<Button>Click</Button>);
+  expect(screen.getByRole("button")).toHaveAttribute("type", "button");
+});
+
+test("Button: calls onClick on Enter key", async () => {
+  const onClick = vi.fn();
+  render(<Button onClick={onClick}>Click</Button>);
+  screen.getByRole("button").focus();
+  await userEvent.keyboard("{Enter}");
+  expect(onClick).toHaveBeenCalled();
+});
+```
+
+These run fast and catch:
+- API contract violations
+- Keyboard handler regressions
+- ARIA attribute regressions
+
+Pair these with the spec — every "Don't" or "States" entry in a component spec should have a contract test.
+
+## Layer 5 — TypeScript
+
+The strongest, cheapest layer:
+
+```ts
+// Tokens typed as a const tree
+export const tokens = {
+  color: {
+    primary: {
+      50: "#F5F3FF",
+      // ...
+      950: "#2E1065",
+    },
+  },
+  // ...
+} as const;
+
+// Component prop validation
+type ButtonProps = {
+  intent: "primary" | "secondary" | "danger";
+  size: "sm" | "md" | "lg";
+  // ...
+};
+```
+
+Catches API breakage at compile time. Pair with `--strict` and ESLint's `@typescript-eslint/strict-boolean-expressions` etc.
+
+## CI pipeline — putting it together
+
+```yaml
+# .github/workflows/design-qa.yml
+on: pull_request
+
+jobs:
+  qa:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Layer 5: TypeScript
+      - run: pnpm tsc --noEmit
+
+      # Layer 1: Token drift / lint
+      - run: pnpm lint
+      - run: pnpm test:tokens-validate
+
+      # Layer 4: Component contract tests
+      - run: pnpm test:unit
+
+      # Layer 3: A11y on Storybook
+      - run: pnpm storybook:build
+      - run: pnpm test:a11y
+
+      # Layer 2: Visual regression
+      - run: pnpm chromatic --auto-accept-changes=false
+
+      # Optional: Figma sync diff
+      - run: pnpm test:figma-sync
+```
+
+PR fails if any step fails. Visual regression is run-of-day (slow); the rest run on every push.
+
+## Per-component QA checklist
+
+When shipping a new component (or revising one), verify all five layers:
+
+- [ ] **Tokens used** — no raw hex/values inline
+- [ ] **TypeScript** — props typed, no `any`
+- [ ] **Storybook stories** — all variants × sizes × states present
+- [ ] **Contract tests** — required ARIA, keyboard handlers
+- [ ] **A11y** — axe passes; manual keyboard test; manual screen reader spot-check
+- [ ] **Visual regression** — baselines captured
+- [ ] **Spec doc updated** — `examples/component-X.md` reflects API
+
+## Korean considerations
+
+- Visual regression for IME composition states — Hangul mid-composition can render differently. Capture states.
+- Brand-color contrast (KakaoPay yellow, Toss blue, etc.) — verify focus rings clear 3:1 on these specific backgrounds.
+- Korean date formatting in components — test that `2026.05.07` renders correctly across locales.
+
+## Maintenance cadence
+
+| Cadence | Task |
+| --- | --- |
+| Per PR | TypeScript + tests + a11y + visual regression |
+| Nightly | Figma sync diff |
+| Weekly | Lighthouse score on key pages |
+| Monthly | Manual audit: spec docs vs implementation |
+| Quarterly | Token drift scan: which tokens are unused? Which were added without doc updates? |
+
+## Don't
+
+- Don't run visual regression in headless mode without controlling for OS font rendering — false positives.
+- Don't skip a11y tests because they're "annoying". They're catching real problems.
+- Don't write tests after merging — write the test, then the implementation (TDD reveals API issues).
+- Don't approve every diff. Approve diffs that match the intent.
+- Don't gate every PR on a 5-minute Chromatic run if your team can't afford the latency. Run nightly + on release branches.
+- Don't ship without contrast verification on real backgrounds. Tokens-only computation misses real-world overlays.
+
+## Cross-reference
+
+- [`docs/TOKEN-SYNC.md`](../../docs/TOKEN-SYNC.md) — token drift detection and Figma sync
+- [`docs/FIGMA-INTEGRATION.md`](../../docs/FIGMA-INTEGRATION.md) — Figma side of QA
+- [`knowledge/a11y/contrast.md`](../a11y/contrast.md) — what a11y regression catches
+- [`knowledge/a11y/keyboard-and-focus.md`](../a11y/keyboard-and-focus.md) — keyboard contract tests
+- [`skills/design-system-qa/PLAYBOOK.md`](../../skills/design-system-qa/PLAYBOOK.md) — the skill that applies this

package/knowledge/patterns/document-typography.md

@@ -0,0 +1,248 @@
+<!-- hand-written -->
+---
+title: Document typography (long-form reading)
+applies_to: [docs, articles, reports, books, marketing-prose]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Document typography
+
+Designing for **reading** is fundamentally different from designing for **scanning** (UI). Long-form documents — articles, technical docs, reports, books — need different rules than product UIs.
+
+The product UI rules in [`type-scale-fundamentals.md`](../typography/type-scale-fundamentals.md) bias toward scannable, dense, multi-purpose. Document typography biases toward sustained reading, lower fatigue, clear hierarchy.
+
+## Body — the most important decision
+
+Body text is what readers actually read. Get this right and everything else can be average; get it wrong and nothing else matters.
+
+| Property | Document | Product UI |
+| --- | --- | --- |
+| Font size | **18–20px** (web) / 11–12pt (print) | 14–16px |
+| Line height | **1.5–1.7** | 1.4–1.5 |
+| Line length (measure) | **60–75 characters** | not constrained |
+| Line color | `#1F2937` or similar (slightly off-black) | `#0F172A` |
+| Font | Serif OR humanist sans | Geometric sans |
+
+### Why bigger?
+
+At "product UI" 14px, sustained reading is fatiguing. 18px+ is the comfort zone for paragraphs of prose.
+
+### Why constrained measure?
+
+Lines too long: eyes lose place returning to next line.
+Lines too short: too many returns, choppy.
+
+**60–75 characters per line** is the sweet spot. Use `max-width: 65ch` (CSS).
+
+For Korean: 35–40 Hangul characters per line (Hangul syllables ~2× width of Latin chars).
+
+### Why off-black?
+
+Pure `#000` on `#FFF` has too much contrast (eye strain over long reads). `#1F2937` / `#272727` reduces glare while staying high-contrast.
+
+Print: ≥ 90% black on white paper, never 100%.
+
+## Heading hierarchy
+
+Documents need **clearer hierarchy** than UIs. Readers skim before reading; headings are the skim path.
+
+### Default scale (web)
+
+| Level | Tag | Size | Weight | Line height | Top margin |
+| --- | --- | --- | --- | --- | --- |
+| Display | h1 | 48–60px | 700 | 1.1 | — |
+| Section | h2 | 32–36px | 700 | 1.2 | 64px |
+| Subsection | h3 | 24px | 600 | 1.3 | 48px |
+| Sub-sub | h4 | 18–20px | 600 | 1.4 | 32px |
+| Body | p | 18–20px | 400 | 1.6 | 16px |
+
+The `top margin` matters: hierarchy is reinforced by space above the heading. h2 has more space than h3, signaling a bigger break.
+
+### Korean adjustment
+
+For Korean documents:
+- Headings: same size, **weight 600** (heavier than Latin's typical 400 for h3+).
+- Line height +10%: h2 1.3 → 1.35.
+- Line break behavior: `word-break: keep-all` to avoid mid-syllable breaks.
+
+## Vertical rhythm
+
+A document with consistent vertical rhythm reads as composed. Inconsistent rhythm reads as messy.
+
+### Single-axis baseline
+
+Pick a base line-height (e.g., 32px). Every spacing decision is a multiple:
+
+```
+Body line-height: 32px
+Body paragraph margin: 32px (= 1× line)
+h2 top margin: 64px (= 2× lines)
+h3 top margin: 48px (= 1.5× lines)
+Image bottom margin: 32px
+List item spacing: 16px (= 0.5× lines)
+```
+
+This is "vertical rhythm" — content sits on a consistent baseline, no awkward gaps.
+
+CSS for it:
+
+```css
+body {
+  --leading: 1.6em;
+}
+p, li, h1, h2, h3, h4 {
+  margin-bottom: var(--leading);
+}
+h2 {
+  margin-top: calc(var(--leading) * 2);
+}
+```
+
+## Paragraph styling
+
+| Property | Value | Why |
+| --- | --- | --- |
+| Indentation | None (modern web) OR 1em first-line (print/editorial) | Matches medium |
+| Margin between | 1× line-height (no indentation), 0 (with indentation) | Two cues for paragraph break is redundant |
+| First-letter drop cap | Editorial / hero sections only | Distractive in technical docs |
+| Justify | No, on web (rivers and uneven spacing) | Use left-align (LTR) / right-align (RTL) |
+
+### Korean paragraphs
+
+- No indentation; modern Korean web/print convention.
+- Paragraph spacing same as Latin (1 line-height).
+- For mixed Korean-English (loanwords, technical terms): use a single font that handles both well (Pretendard, IBM Plex Sans KR).
+
+## Inline text styles
+
+| Style | Use | Style |
+| --- | --- | --- |
+| **Bold** | Genuine emphasis (sparingly) | weight 700 |
+| _Italic_ | Title of work, emphasis (rare in tech) | font-style italic |
+| `Code` | Inline code, paths, identifiers | font-family monospace, slight bg tint |
+| ~~Strike~~ | Removed / superseded text | text-decoration line-through |
+| <u>Underline</u> | Avoid for non-link text — confusing | underline reserved for links |
+
+Korean-specific: italics don't render well for Hangul (no italic form). For emphasis, use:
+- `font-weight: 600`
+- Color shift (slightly darker)
+- Or wrap in `<mark>` for annotation
+
+## Links in long-form
+
+Links break reading flow. Choices:
+
+| Style | Use |
+| --- | --- |
+| Underline + brand color | Default. Most discoverable. |
+| Underline only | Editorial / minimal style |
+| Color only (no underline) | Avoid — fails for color-blind |
+| Subtle (low contrast underline) | Footnotes, references |
+
+For high-density link content (think Wikipedia): use subtle underline; underline-on-hover for less-noisy default.
+
+## Pull quotes
+
+Block quotes / pull quotes break monotony in long-form:
+
+```html
+<blockquote>
+  <p>The quote text, often slightly larger and italic or in a contrasting color.</p>
+  <cite>— Attribution</cite>
+</blockquote>
+```
+
+Style:
+- Larger font (1.25–1.5× body)
+- Different color (`--color-text-secondary` works)
+- Italic (Latin) / weight 500 (Hangul)
+- Vertical bar on left OR centered with quote marks
+
+Don't use for ordinary block content — reserve for actual quotes.
+
+## Image / figure handling
+
+In documents:
+- Images full-width to the body container.
+- Captions: smaller text below image (`figcaption`).
+- Image padding: 1 line-height above and below.
+- No drop shadows on documentation images (signals product UI, not editorial).
+- Photographs: rounded corners are jarring for editorial context. Use square corners for serious docs.
+
+## Code blocks in documents
+
+Different from inline code:
+- Full-bleed to container (or slightly inset).
+- Background tint (slightly darker than body bg).
+- Monospace font, 14–15px (smaller than body, intentional).
+- Optional language label at top.
+- Optional copy button (top-right, hover-only).
+- Line numbers for very long blocks (>20 lines).
+
+Cite [`examples/component-code.md`](../../examples/component-code.md).
+
+## Tables in documents
+
+Different from product UI tables:
+- Border-bottom on every row (light) — easier reading.
+- Header: bold + `border-bottom: 2px solid` to separate from body.
+- Row striping: optional. Use `--color-bg-subtle` very lightly OR not at all.
+- No filtering / sorting controls in document context (it's prose, not data).
+- For large data: extract to a separate component, not inline in prose.
+
+## Print-specific
+
+For docs meant to be printed (manuals, reports, contracts):
+- Body: 11pt (smaller than screen — print is denser).
+- Margins: 1 inch (2.5 cm) all sides.
+- Page breaks: avoid orphans/widows. CSS `orphans: 3; widows: 3;`.
+- Page numbers: small, bottom-center or bottom-right.
+- No light gray text — minimum 70% black.
+- No background colors that bleed to edges (uses paper, looks weird).
+
+## Document → web → print pipeline
+
+A doc may need to render in three contexts:
+
+```
+Markdown source (canonical)
+   ↓
+Web (your docs site)
+   ↓
+PDF (download)
+   ↓
+Print (paper)
+```
+
+Each context overrides the base styling:
+
+```css
+body { font-size: 18px; line-height: 1.6; }
+
+@media print {
+  body { font-size: 11pt; line-height: 1.5; }
+  a { color: #000; text-decoration: underline; }
+  a::after { content: " (" attr(href) ")"; }  /* show URL after link in print */
+}
+```
+
+## Common document typography mistakes
+
+- **Body too small** (14px) — looks like a UI, fatiguing to read.
+- **Lines too long** (no max-width) — eye fatigue.
+- **Heading too close to next paragraph** — no margin separation.
+- **All text justified** (web) — rivers, awkward gaps.
+- **Pure black text** — eye strain.
+- **Code blocks at body size** — should be slightly smaller.
+- **Pull quotes overused** — every paragraph has one, lose all impact.
+- **Multiple emphasis types in same paragraph** (bold + italic + code + link) — visual chaos.
+
+## Cross-reference
+
+- [`knowledge/typography/type-scale-fundamentals.md`](../typography/type-scale-fundamentals.md) — base scale concepts (UI-focused)
+- [`knowledge/i18n/korean-typography.md`](../i18n/korean-typography.md) — Korean adjustments
+- [`knowledge/i18n/korean-document-style.md`](../i18n/korean-document-style.md) — Korean doc-specific conventions
+- [`knowledge/patterns/information-architecture.md`](information-architecture.md) — IA for long docs
+- [`knowledge/patterns/technical-writing.md`](technical-writing.md) — voice and structure