@awarebydefault/display-case 1.0.0

package/skills/display-case-author-placard-doc/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: display-case-author-placard-doc
+description: >
+  Write or improve a component's `<name>.placard.md` — the prose doc panel that
+  tells an AI agent (and a human) how to use the component correctly on the first
+  try. Use when adding a new shared component, when a component has a `.case.tsx`
+  but no `.placard.md`, or when asked to "write a placard doc", "document this
+  component", "add a doc panel", or "write usage docs for <component>".
+---
+
+Author a colocated `<name>.placard.md` for a component, following
+`../../docs/writing-placard-docs.md`. The doc is **not** required by any lint
+(only `.case.tsx` is) — its whole value is quality, so apply the bar deliberately.
+
+## The one principle
+
+The reader already holds the **source** (every prop, type, default) and the
+**manifest** (every case, `renderUrl`, tweak schema). The doc earns its place only
+by carrying what neither can express: **intent, judgement, and contract.** Aim for
+a doc that lets a reader pick the component and use it correctly **without opening
+the source.** Restate *meaning*, never the type signature.
+
+## Steps
+
+1. **Gather intent, not just signatures.** Read `<name>.tsx` for the exact export
+   name, props, defaults, and — critically — *what each callback emits* (the
+   changed item vs. the whole next value: invisible in the type, guessed wrong).
+   Read `<name>.case.tsx` for the real variants, and any existing `.placard.md` to
+   improve rather than replace.
+2. **Find the decision boundary.** Scan the package's component inventory (its
+   `README.md` / sibling components) for the parts this one is easily confused
+   with — the long-list vs. short-list control, the inline notice vs. the toast.
+   You will name the right sibling so a reader doesn't misuse this one.
+3. **Draft top-down, highest value first** (stop once the source is unnecessary):
+   - **Identity line** — bold name, em-dash, one sentence: what it is + the single
+     most common reason to reach for it. Must stand alone in a library scan.
+   - **Canonical example** — one minimal, **correct, copy-pasteable** `tsx` snippet
+     of the idiomatic call. A second snippet only for a genuinely different mode.
+   - **Variants and when to pick each** — meaning and use, not the type union; name
+     the default; a GFM table once there are more than three.
+   - **Decision boundary** — "use this for X; for Y reach for `Sibling`." The
+     single biggest defense against picking the wrong primitive.
+   - **State & callback contract** — controlled vs. uncontrolled; exactly what each
+     callback emits; what fires on mount.
+   - **Composition & a11y** — required wrappers (`FormField`…), what the component
+     handles itself (so the reader doesn't double up a `role`), what the caller
+     must supply (a label, alt text).
+   - **Gotchas / anti-patterns** — one bullet each; skip if none.
+4. **Cut what rots or duplicates:** no prop tables retyping TypeScript, no list of
+   the component's cases / `renderUrl`s / tweak schema (the manifest owns those),
+   no styling internals, no changelog, nothing the name already says.
+5. **Write for the medium.** CommonMark + GFM, but **no raw HTML** (stripped) and
+   **no syntax highlighting** (use fences for structure only). Be dense — the file
+   is ingested into a context window; every line earns its tokens. Bold lead line
+   always; `##` headings only once the doc has enough sections to need them. A
+   simple atom is ~5 lines (see `../../../ui/src/components/button.placard.md`).
+6. **Verify.** Open the doc panel (`bun run display-case`) to confirm it renders,
+   and re-check that every example is correct and copy-pasteable — a stale example
+   is a bug, since those lines get pasted verbatim.
+
+## Reference
+
+Full guide: [`../../docs/writing-placard-docs.md`](../../docs/writing-placard-docs.md).
+Annotated specimen: [`../../docs/examples/tweak-control.placard.md`](../../docs/examples/tweak-control.placard.md).
+How the panel renders (GFM, the two limits): [`../../docs/documentation-panel.md`](../../docs/documentation-panel.md).

package/skills/display-case-review/README.md

@@ -0,0 +1,19 @@
+# display-case-review
+
+Run Display Case's checks and triage the findings into fixes.
+
+## What it does
+
+Runs `display-case check` — accessibility (axe, WCAG A/AA), visual regression (pixel diff vs baselines), and design-token conformance — then classifies each finding (case-authoring vs component/token issue vs intended visual change) and proposes the fix at the right layer.
+
+## When it triggers
+
+"Review the components", "check accessibility/contrast", "run the display-case checks", or verifying the showcase after a UI change.
+
+## How it works
+
+1. `bun run display-case:check` (or a single phase via `--a11y` / `--visual` / `--tokens`).
+2. Triage: fix the case when an example is malformed; fix the component/tokens when the component itself fails; re-record baselines with `--update` only for intended changes.
+3. Re-run until clean. Never silence a real finding.
+
+Details: [`../../docs/testing.md`](../../docs/testing.md).

package/skills/display-case-review/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: display-case-review
+description: >
+  Run Display Case's accessibility, visual-regression, and design-token checks
+  over the component showcase, then triage the findings and propose fixes. Use
+  when asked to "review the components", "check accessibility / contrast", "run
+  the display-case checks", or to verify the showcase after a UI change.
+---
+
+Run the Display Case `check` runner and turn its output into actionable fixes.
+
+## Steps
+
+1. **Run the checks**: `bun run display-case:check` (or `bunx @awarebydefault/display-case check <pkgDir>`). Phases:
+   - **a11y** — axe, WCAG 2 A/AA, per case × theme.
+   - **visual** — pixel-diff each case (light + dark) against recorded baselines.
+   - **tokens** — design-token conformance.
+   - Run one phase with a flag, e.g. `bunx @awarebydefault/display-case check <pkgDir> --a11y`.
+2. **Triage each finding** by category:
+   - **a11y** (`label`, `color-contrast`, `aria-*`, …): if the case renders a bare control, fix the *case* (add a label/`aria-label`); if the component itself fails (contrast tokens, missing accessible name), fix the *component*/tokens.
+   - **visual** diffs: inspect the written `*.diff.png`; if the change is intended, re-record with `--update`; otherwise it's a regression to fix.
+   - **tokens**: resolve the flagged custom property, or add it to the config `tokens.allow` if it's supplied by a host stylesheet.
+3. **Fix at the right layer** — prefer fixing the component/tokens over weakening the check. Never silence a real finding.
+4. **Re-run** until the relevant phase is clean (exit 0).
+
+## Notes
+
+- Visual baselines live in the gitignored `.display-case/baselines/` by default (or the configured `baselineDir`); `--update` re-records them.
+- The runner drives the same `/render` endpoint a viewer sees, so findings reflect real appearance.
+- Deeper detail: `../../docs/testing.md`.

package/skills/display-case-snapshot/README.md

@@ -0,0 +1,20 @@
+# display-case-snapshot
+
+Render and screenshot a single component variant in isolation — in light and dark — without booting the app.
+
+## What it does
+
+Resolves a component's case from the Display Case manifest, builds the deterministic `/render/<component>/<case>?theme=…&t.<tweak>=…` URL, and captures the chrome-free HTML with a headless browser. Because the full state lives in the URL, the same inputs always produce the same image.
+
+## When it triggers
+
+"Show me the Button", "screenshot the Alert error state", "what does the survey form look like in dark mode", or any request to see/capture a component's appearance for review.
+
+## How it works
+
+1. Ensure `bun run display-case` is running (port 3100).
+2. Read `/manifest.json` (or `--print-manifest`) to find the case's `renderUrl` and `tweaks`.
+3. Append `theme`, optional `width`, and `t.<name>` params.
+4. Screenshot the page with a headless browser, light and dark.
+
+See [`../../docs/ai-agents.md`](../../docs/ai-agents.md) for the endpoint reference.

package/skills/display-case-snapshot/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: display-case-snapshot
+description: >
+  Render and screenshot a single component variant in isolation, in light and
+  dark themes, without booting the app. Use when asked to "show me <component>",
+  "screenshot a component", "what does <case> look like", or to capture a
+  component's appearance for review. Drives the Display Case dev server's
+  chrome-free /render endpoint.
+---
+
+Capture one component case as an image, deterministically, via Display Case.
+
+## Steps
+
+1. **Ensure the server is running.** Start it if needed: `bun run display-case` (serves at `http://localhost:3100`). It needs no database or app — just the showcase.
+2. **Enumerate.** `GET http://localhost:3100/manifest.json` (or `bunx @awarebydefault/display-case <pkgDir> --print-manifest`, no server needed) to find the component and its cases. Each case has a `renderUrl` like `/render/tweak-control/playground` and an optional `tweaks` schema.
+3. **Build the render URL.** Append query params to pin the exact state:
+   - `theme=light|dark`
+   - `width=<px>` (optional, constrains to a centered max-width)
+   - `t.<name>=<value>` per tweak (`boolean`→`1`/`0`; `number`→numeric; text/choice verbatim)
+   - e.g. `http://localhost:3100/render/tweak-control/playground?theme=dark&t.kind=choice`
+4. **Rasterize.** The endpoint returns chrome-free **HTML**, so capture it with a headless browser (Playwright `page.goto(url); page.screenshot()`). Capture both `theme=light` and `theme=dark` unless told otherwise.
+5. **Report** the screenshots and the exact URLs used, so the state is reproducible.
+
+## Notes
+
+- The render is isolated (its own document, `data-theme` on the root), so it never includes the browse sidebar/controls — ideal for clean snapshots.
+- Same URL → same render. Pin tweaks in the URL rather than interacting with the page.
+- For the full contract see `../../docs/ai-agents.md`.

package/src/checks/a11y-scanner.test.ts

@@ -0,0 +1,240 @@
+import { afterEach, expect, test } from 'bun:test'
+import { readFileSync, statSync } from 'node:fs'
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { cacheDir } from '../core/discovery'
+import type {
+  A11yViolation,
+  DisplayCaseConfig,
+  RenderDriver,
+  RenderedPage,
+} from '../index'
+import { makeTempDir, writeFiles } from '../testing/test-helpers'
+import {
+  type A11yScanStatus,
+  type A11yVariant,
+  createA11yScanner,
+} from './a11y-scanner'
+
+const dirs: string[] = []
+afterEach(async () => {
+  while (dirs.length)
+    await rm(dirs.pop() as string, { recursive: true, force: true })
+})
+
+// Display Case's own version, mirrored exactly so the cache entries we hand-write
+// are accepted (a `toolVersion` mismatch discards an entry).
+const TOOL_VERSION = (() => {
+  try {
+    return (
+      (
+        JSON.parse(
+          readFileSync(
+            join(import.meta.dir, '..', '..', 'package.json'),
+            'utf8',
+          ),
+        ) as { version?: string }
+      ).version ?? '0'
+    )
+  } catch {
+    return '0'
+  }
+})()
+
+const VIOLATION: A11yViolation = {
+  id: 'color-contrast',
+  help: 'Elements must have sufficient contrast',
+  nodes: 1,
+  impact: 'serious',
+}
+
+/** A render driver whose audit always returns one violation; records opens. */
+function fakeDriver(opens: string[]): RenderDriver {
+  const page: RenderedPage = {
+    screenshot: async () => new Uint8Array(),
+    audit: async () => [VIOLATION],
+    dispose: async () => {},
+  }
+  return {
+    open: async (url) => {
+      opens.push(url)
+      return page
+    },
+    close: async () => {},
+  }
+}
+
+/** A driver that cannot launch — stands in for a missing browser/axe. */
+function failingDriver(): RenderDriver {
+  throw new Error('no browser')
+}
+
+interface Harness {
+  pkgDir: string
+  caseAbs: Record<string, string>
+}
+
+/** Temp package with `n` case files, each importing nothing. */
+async function harness(ids: string[]): Promise<Harness> {
+  const pkgDir = await makeTempDir()
+  dirs.push(pkgDir)
+  const files: Record<string, string> = {}
+  const caseAbs: Record<string, string> = {}
+  for (const id of ids) {
+    files[`src/${id}.case.tsx`] = `export const cases = {} // ${id}\n`
+    caseAbs[id] = join(pkgDir, `src/${id}.case.tsx`)
+  }
+  await writeFiles(pkgDir, files)
+  return { pkgDir, caseAbs }
+}
+
+/** Hand-write a cache entry whose recorded stats match the case file on disk, so
+ *  the scanner's stat fast-path accepts it as reusable without a content hash. */
+async function seedCache(
+  h: Harness,
+  componentId: string,
+  caseId: string,
+  theme: string,
+  violations: A11yViolation[],
+): Promise<void> {
+  const dir = join(cacheDir(h.pkgDir), 'a11y')
+  await mkdir(dir, { recursive: true })
+  const abs = h.caseAbs[componentId]
+  const st = statSync(abs)
+  const entry = {
+    toolVersion: TOOL_VERSION,
+    hash: 'unused-when-stats-match',
+    files: [
+      { path: relative(h.pkgDir, abs), mtimeMs: st.mtimeMs, size: st.size },
+    ],
+    violations,
+    scannedAt: 1,
+  }
+  await writeFile(
+    join(dir, `${componentId}__${caseId}__${theme}.json`),
+    JSON.stringify(entry),
+  )
+}
+
+function makeScanner(
+  h: Harness,
+  driverFactory: () => RenderDriver,
+  onResult: (
+    c: string,
+    cs: string,
+    th: 'light' | 'dark',
+    s: A11yScanStatus,
+  ) => void,
+) {
+  const config: DisplayCaseConfig = {
+    title: 'T',
+    roots: ['src/**/*.case.tsx'],
+    providers: { driver: driverFactory },
+  }
+  return createA11yScanner({
+    pkgDir: h.pkgDir,
+    config,
+    baseUrl: () => 'http://localhost:0',
+    caseFileAbs: (id) => h.caseAbs[id] ?? null,
+    onResult,
+  })
+}
+
+const variant = (
+  componentId: string,
+  caseId: string,
+  theme: 'light' | 'dark',
+): A11yVariant => ({ componentId, caseId, theme })
+
+test('off mode is a no-op: no results, no scans', async () => {
+  const h = await harness(['foo'])
+  await seedCache(h, 'foo', 'default', 'light', [VIOLATION])
+  const opens: string[] = []
+  const calls: string[] = []
+  const scanner = makeScanner(
+    h,
+    () => fakeDriver(opens),
+    (c, cs, th) => calls.push(`${c}/${cs}/${th}`),
+  )
+  await scanner.populateAtStartup([variant('foo', 'default', 'light')], 'off')
+  expect(calls).toEqual([])
+  expect(opens).toEqual([])
+  await scanner.close()
+})
+
+test('cached mode emits reusable cached results and runs no scans', async () => {
+  const h = await harness(['foo', 'bar'])
+  await seedCache(h, 'foo', 'default', 'light', [VIOLATION])
+  // `bar` has no cache entry → it must stay unmarked (no emit) in cached mode.
+  const opens: string[] = []
+  const results: Array<{ id: string; status: A11yScanStatus }> = []
+  const scanner = makeScanner(
+    h,
+    () => fakeDriver(opens),
+    (c, cs, th, status) => results.push({ id: `${c}/${cs}/${th}`, status }),
+  )
+  await scanner.populateAtStartup(
+    [variant('foo', 'default', 'light'), variant('bar', 'default', 'light')],
+    'cached',
+  )
+  expect(results).toHaveLength(1)
+  expect(results[0].id).toBe('foo/default/light')
+  expect(results[0].status).toEqual({ status: 'ok', violations: [VIOLATION] })
+  expect(opens).toEqual([]) // never launched the driver
+  await scanner.close()
+})
+
+test('refresh mode reuses fresh cache and scans uncached/stale variants', async () => {
+  const h = await harness(['foo', 'bar'])
+  await seedCache(h, 'foo', 'default', 'light', [VIOLATION])
+  // `bar` is uncached → refresh must scan it via the driver.
+  const opens: string[] = []
+  const results: Array<{ id: string; status: A11yScanStatus }> = []
+  let resolveScan: () => void = () => {}
+  const scanned = new Promise<void>((r) => {
+    resolveScan = r
+  })
+  const scanner = makeScanner(
+    h,
+    () => fakeDriver(opens),
+    (c, cs, th, status) => {
+      results.push({ id: `${c}/${cs}/${th}`, status })
+      if (c === 'bar') resolveScan()
+    },
+  )
+  await scanner.populateAtStartup(
+    [variant('foo', 'default', 'light'), variant('bar', 'default', 'light')],
+    'refresh',
+  )
+  await scanned
+  const byId = Object.fromEntries(results.map((r) => [r.id, r.status]))
+  // foo came straight from cache (no scan); bar was scanned.
+  expect(byId['foo/default/light']).toEqual({
+    status: 'ok',
+    violations: [VIOLATION],
+  })
+  expect(byId['bar/default/light']).toEqual({
+    status: 'ok',
+    violations: [VIOLATION],
+  })
+  expect(opens).toHaveLength(1)
+  expect(opens[0]).toContain('/render/bar/default')
+  await scanner.close()
+})
+
+test('refresh mode emits nothing extra when the scan prerequisite is unavailable', async () => {
+  const h = await harness(['foo', 'bar'])
+  await seedCache(h, 'foo', 'default', 'light', [VIOLATION])
+  const results: string[] = []
+  const scanner = makeScanner(h, failingDriver, (c, cs, th) =>
+    results.push(`${c}/${cs}/${th}`),
+  )
+  await scanner.populateAtStartup(
+    [variant('foo', 'default', 'light'), variant('bar', 'default', 'light')],
+    'refresh',
+  )
+  // The reusable cache hit still surfaces; the uncached variant is not scanned
+  // because the driver could not launch — no flood of `unavailable` events.
+  expect(results).toEqual(['foo/default/light'])
+  await scanner.close()
+})