@awarebydefault/display-case 1.0.0

package/docs/tweaks.md

@@ -0,0 +1,75 @@
+# Tweaks
+
+> Nav: [Quick start](quick-start.md) · [Writing cases](writing-cases.md) · [Hierarchy](hierarchy.md) · **Tweaks** · [Theming](theming.md) · [Documentation panel](documentation-panel.md) · [Writing placard docs](writing-placard-docs.md) · [Testing](testing.md) · [CLI](cli.md) · [AI agents](ai-agents.md) · [Configuration](configuration.md)
+
+Tweaks are typed, interactive controls attached to a case. Instead of writing one variant per prop combination, declare the props as tweaks and let the viewer adjust them live.
+
+```tsx
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { TweakControl } from './tweak-control'
+
+export default defineCases('TweakControl', {
+  Playground: {
+    tweaks: {
+      label: tweak.text('Save changes'),
+      kind: tweak.choice(['text', 'boolean', 'choice'], 'text'),
+      disabled: tweak.boolean(false),
+    },
+    render: (t) => (
+      <TweakControl
+        kind={t.kind as 'text' | 'boolean' | 'choice'}
+        label={t.label}
+        disabled={t.disabled}
+      />
+    ),
+  },
+}, { level: 'atom' })
+```
+
+A tweaked case is an object with two keys: a `tweaks` schema and a `render` function that receives the resolved values.
+
+## Control kinds
+
+There are four serializable tweak builders, all imported from the `tweak` namespace:
+
+| Builder | Resolved value type | Default argument |
+| --- | --- | --- |
+| `tweak.text(default?)` | `string` | optional, defaults to `''` |
+| `tweak.boolean(default?)` | `boolean` | optional, defaults to `false` |
+| `tweak.number(default?)` | `number` | optional, defaults to `0` |
+| `tweak.choice(options, default)` | `string` | both required |
+
+```ts
+tweak.text('Hello')                         // text field
+tweak.boolean(true)                          // toggle
+tweak.number(8)                              // number field
+tweak.choice(['sm', 'md', 'lg'], 'md')       // select from fixed options
+```
+
+The keys of the `tweaks` object become the control labels and the property names on the `render` argument.
+
+## Values are URL-encoded
+
+A tweak's current value is serialized into the render URL as `t.<name>`, so any tweaked state is a shareable, snapshottable link:
+
+```
+/render/tweak-control/playground?theme=dark&t.label=Delete&t.kind=choice&t.disabled=1
+```
+
+Encoding rules:
+
+- `boolean` — `1` / `true` is true; anything else is false.
+- `number` — parsed with `Number(...)`.
+- `text` and `choice` — used verbatim.
+- A missing `t.<name>` falls back to the declared `default`.
+
+This is what lets an AI agent or screenshot tool reproduce an exact tweaked state deterministically — see [AI agents](ai-agents.md).
+
+## Typing
+
+`choice` returns a plain `string` at runtime, so when feeding it back into a union-typed prop you may need a cast (as in the example above). The other kinds resolve to their natural types (`string`, `boolean`, `number`).
+
+## When to reach for tweaks
+
+- **Use a tweaked case** for an exploratory "playground" where many prop combinations matter.
+- **Use plain cases** for the canonical, named variants you want to keep visible and snapshot in tests — these render with fixed inputs and are the stable surface for visual regression. See [Testing](testing.md).

package/docs/writing-cases.md

@@ -0,0 +1,144 @@
+# Writing cases
+
+> Nav: [Quick start](quick-start.md) · **Writing cases** · [Hierarchy](hierarchy.md) · [Tweaks](tweaks.md) · [Theming](theming.md) · [Documentation panel](documentation-panel.md) · [Writing placard docs](writing-placard-docs.md) · [Testing](testing.md) · [CLI](cli.md) · [AI agents](ai-agents.md) · [Configuration](configuration.md)
+
+A case file is the unit of the showcase: a `*.case.tsx` file colocated with the component it demonstrates, default-exporting one call to `defineCases` or `defineFlow`.
+
+```tsx
+// src/components/tweak-control.case.tsx
+import { defineCases } from '@awarebydefault/display-case'
+import { TweakControl } from './tweak-control'
+
+export default defineCases('TweakControl', {
+  Kinds: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
+      <TweakControl kind="text" label="Label" value="Save" />
+      <TweakControl kind="boolean" label="Disabled" value={false} />
+      <TweakControl kind="choice" label="Variant" options={['sm', 'md', 'lg']} value="md" />
+    </div>
+  ),
+  Boolean: () => <TweakControl kind="boolean" label="Disabled" value={true} />,
+  Disabled: () => <TweakControl kind="text" label="Label" value="Save" disabled />,
+}, { level: 'atom' })
+```
+
+## `defineCases(component, cases, meta?)`
+
+| Argument | Type | Notes |
+| --- | --- | --- |
+| `component` | `string` | The display name shown in the sidebar. Its slug (kebab-case) forms the URL, e.g. `TweakControl` → `/c/tweak-control`. |
+| `cases` | `Record<string, Case>` | Keyed by display name; **insertion order is preserved**. Each value is either a simple render thunk or a tweaked case (see below). |
+| `meta.level` | `HierarchyLevel?` | One of `atom`, `molecule`, `organism`, `template`, `page` (`flow` is set automatically by `defineFlow`). Drives sidebar grouping. Omit to leave it "unclassified" (sorted last). See [Hierarchy](hierarchy.md). |
+| `meta.area` | `string?` | Free-form layout tag passed to the [`decorator`](configuration.md#decorator) so it can wrap this case in app chrome (nav/header/footer). Display Case mandates no vocabulary — the decorator interprets the value. Takes precedence over folder-based detection via `sourcePath`; omit to fall back to that (or to render bare). |
+
+### Two shapes of case
+
+A **simple case** is a thunk returning a React node:
+
+```tsx
+Disabled: () => <TweakControl kind="text" label="Label" value="Save" disabled />,
+```
+
+A **tweaked case** declares typed controls and receives their resolved values:
+
+```tsx
+Playground: {
+  tweaks: { label: tweak.text('Save') },
+  render: (t) => <TweakControl kind="text" label="Label" value={t.label} />,
+},
+```
+
+See [Tweaks](tweaks.md) for the full control set.
+
+### Order the default-landing variant first
+
+Clicking a component in the sidebar navigates to its **first** case, so lead with the most exploratory variant — a tweaked `Playground` case, or a "do-anything" interactive demo (e.g. a stateful, clickable example). Keep isolated single-state variants (one `Disabled`, one `With error`) *after* it: those exist mainly for snapshots and visual-regression, not as the thing a reader should land on. Flow steps are the exception — order them in flow sequence (`defineFlow` below).
+
+## `defineFlow(name, { steps })`
+
+For behavioural multi-step flows — a wizard, a sign-in sequence — use `defineFlow`. Each step is an ordered, individually addressable, snapshottable state. A step may declare preset `tweaks`, `transitions` to other steps, and wire its injected `goto` into a presentational view's callbacks so an in-step button advances the flow in place.
+
+```tsx
+// src/components/sign-in-flow.case.tsx
+import { defineFlow } from '@awarebydefault/display-case'
+import { RequestLink, CheckEmail, SignedIn } from './sign-in-screens'
+
+export default defineFlow('Sign-in flow', {
+  steps: {
+    'Request link': {
+      transitions: ['Check email'],
+      render: ({ goto }) => <RequestLink onSubmit={() => goto('Check email')} />,
+    },
+    'Check email': {
+      transitions: ['Signed in'],
+      render: ({ goto }) => <CheckEmail onOpen={() => goto('Signed in')} />,
+    },
+    'Signed in': { render: () => <SignedIn /> },
+  },
+})
+```
+
+Keep the views pure: a step wires `goto` to the view's callbacks; the view never imports navigation, so the same view is reused in the real route. `goto(step, overrides?)` re-enters the target step with optional preset tweak values. A flow whose steps declare no transitions is a static, walkable sequence. A flow is always at the `flow` level. See [Hierarchy](hierarchy.md#flows) for how flows differ from regular cases.
+
+`defineFlow` also accepts an optional `area` alongside `steps` — the same free-form layout tag as [`meta.area`](#definecasescomponent-cases-meta) — so a flow can be wrapped in app chrome by the decorator:
+
+```tsx
+export default defineFlow('Checkout', { area: 'app', steps: { /* … */ } })
+```
+
+**Typed step values.** A bare step object has loosely-typed `values`. To read typed preset values (`values.error` as `boolean`), wrap the step in the `flowStep` helper, which infers the step's own tweak schema:
+
+```tsx
+import { defineFlow, flowStep, tweak } from '@awarebydefault/display-case'
+
+export default defineFlow('Sign-in', {
+  steps: {
+    'Check email': flowStep({
+      tweaks: { error: tweak.boolean(false) },
+      render: ({ values, goto }) => (
+        <CheckEmail error={values.error} onVerify={() => goto('Signed in')} />
+      ),
+    }),
+    'Signed in': { render: () => <SignedIn /> },
+  },
+})
+```
+
+`goto`/`transitions` targets are not key-checked at compile time — an unknown target renders the not-found step at runtime.
+
+## Authoring rules
+
+- **Default-export the definition.** A file with no valid default export (or one whose `component` is not a string) is skipped and reported as a load error; the rest still load.
+- **No top-level side effects.** Render functions are lazy. The server imports the module to build the manifest without rendering — so don't call hooks, fetch, or touch the DOM at module top level.
+- **Give an interactive specimen a distinct per-case `key`.** This is a foot-gun worth understanding. A controlled component needs a little wrapper that owns its state (`function Demo({ initial }) { const [v, setV] = useState(initial); … }`), and you'll reuse that one wrapper across several cases. But the browse chrome **swaps cases in place** — it re-renders one persistent root with `root.render()` and never unmounts (so theme/tweak changes don't flicker). React then sees the *same* `<Demo>` at the *same* position across cases and **keeps its `useState` value** instead of re-seeding from the new case's `initial`. Between cases whose props differ — a different selected id, or a disjoint set of options — the leaked value shows the wrong selection, or (if it isn't in the new options) *no* selection at all. Fix it by giving each case's wrapper a distinct `key` so React remounts it:
+
+  ```tsx
+  function Demo({ options, initial }: { options: Opt[]; initial: string }) {
+    const [value, setValue] = useState(initial)
+    return <Toggle options={options} value={value} onChange={setValue} />
+  }
+
+  export default defineCases('Toggle', {
+    // A bare <Demo …/> here would carry the previous case's value across the swap.
+    Two:  () => <Demo key="two"  options={two}  initial="b" />,
+    Five: () => <Demo key="five" options={five} initial="lg" />,
+  })
+  ```
+
+  A tweaked `Playground` that re-seeds from a tweak follows the same rule — key it by the seeding tweak (`key={`pg-${t.count}`}`) so changing the tweak remounts with the new `initial`. A specimen rendered in only *one* case is safe (switching to any sibling case mounts a different element, which remounts it anyway). The `interactive-cases-keyed` structure check flags a stateful wrapper reused across cases with a missing `key`; waive a deliberate exception with a `// display-case: allow-interactive-cases-keyed <reason>` comment.
+- **Compose freely inside a render.** Layout wrappers, multiple instances, sample data — anything that returns a React node is fine.
+- **One component (or flow) per file.** Coverage tooling expects a `<name>.case.tsx` sibling for each component module.
+- **Edits are picked up on save; reload to see them.** The dev server watches case files and rebuilds on every change — including manifest-shape edits (case *order*, case/component *names*, hierarchy `level`, tweak schema). There is no in-page HMR, so reload the browser to pick up a rebuild. (The rebuild reads the manifest in a fresh subprocess because Bun caches ES modules by path for a process's lifetime; without that, an in-process re-import would return the stale module.)
+
+## Coverage
+
+The coverage check fails if a showcased component module has no colocated `*.case.tsx`. Wire it into your lint or CI step to keep every component browsable. To exempt a non-showcasable module, add a comment anywhere in the component file:
+
+```tsx
+// display-case: no-case this is an internal helper, not a visual component
+```
+
+## See also
+
+- Runnable examples: [examples/](examples/) — a plain case, a tweaks case, and a multi-variant case.
+- [Configuration](configuration.md) for `roots` globs that decide which files are discovered.

package/docs/writing-placard-docs.md

@@ -0,0 +1,194 @@
+# Writing placard docs
+
+> Nav: [Quick start](quick-start.md) · [Writing cases](writing-cases.md) · [Hierarchy](hierarchy.md) · [Tweaks](tweaks.md) · [Theming](theming.md) · [Documentation panel](documentation-panel.md) · **Writing placard docs** · [Testing](testing.md) · [CLI](cli.md) · [AI agents](ai-agents.md) · [Configuration](configuration.md)
+
+A `<component>.placard.md` is the component's **prose contract**: the one place that
+tells a reader what the types can't. [Documentation panel](documentation-panel.md)
+covers how the file is discovered and rendered; this guide covers what to *put in
+it*. For a complete, annotated specimen see
+[`examples/tweak-control.placard.md`](examples/tweak-control.placard.md).
+
+## Who reads it, and why that decides everything
+
+The primary reader is an **AI agent** assembling a UI; the secondary reader is a
+human skimming the doc panel. Both arrive already holding two things you should
+never restate:
+
+- the **source** — every prop name, type, and default is in the `.tsx`;
+- the **manifest** — every case, `renderUrl`, and `tweaks` schema is already
+  enumerated for machine readers (see [AI agents](ai-agents.md)).
+
+So the placard doc earns its tokens only by carrying what *neither* of those can
+express: **intent, judgement, and contract.** A good doc lets a reader choose the
+component and use it correctly on the **first try, without opening the source.**
+That is the whole bar.
+
+> **The one principle:** document what the types can't. A signature says a prop is
+> `(next: string[]) => void`; only prose says whether `next` is *the toggled item*
+> or *the full next array*. Spend your words there.
+
+## What to include
+
+Ordered by value. Lead with the highest; stop when a reader could use the
+component correctly without the source. Most atoms need only the first three.
+
+1. **Identity line.** A bold name, an em-dash, and one sentence: *what it is* and
+   *the single most common reason to reach for it*. This is what shows when the
+   library is scanned, so it must stand alone. Lead with the conclusion.
+
+2. **Canonical example.** One minimal, **correct, copy-pasteable** `tsx` snippet
+   of the idiomatic call — the common case, not every prop. Agents paste it
+   verbatim, so a wrong example is worse than none. Add a second snippet only when
+   a distinct mode (a different `kind`, a controlled vs. composed form) genuinely
+   needs one.
+
+3. **Variants and when to pick each.** Map each variant/mode to its *meaning and
+   use*, not its type union. Name the default. Use a GFM table once there are more
+   than three; a sentence suffices below that. Restate semantics, never the
+   signature — semantics drift more slowly than types.
+
+4. **Decision boundary — when *not* to use it.** The highest-value, most-skipped
+   content. Point to the sibling that fits the case you're excluding, by name, so
+   the reader navigates the library instead of misusing this part: *"for long or
+   searchable lists, reach for `Combobox`"*; *"inline notice, not a transient
+   toast — use `Toast` for those."* This is the single biggest defence against an
+   agent picking the wrong primitive.
+
+5. **State & callback contract.** Controlled or uncontrolled? What does each
+   callback *emit* — the changed item or the whole next value? What fires on
+   mount? None of this is visible in a type and all of it is guessed wrong.
+
+6. **Composition & required wrappers.** Relationships the type system permits but
+   the design requires: *"wrap in `FormField` for the label and error"*; *"at most
+   one Other choice per question."* Constraints that aren't compile errors.
+
+7. **Accessibility behaviour.** What the component handles for you (so the reader
+   doesn't double up a `role`) and what the caller **must** supply (a label, alt
+   text). State it in one line; omit if there's nothing non-obvious.
+
+8. **Gotchas & anti-patterns.** The non-obvious rule and the tempting wrong use.
+   One bullet each; skip the section if there are none.
+
+## What to leave out
+
+Every line here is either drift waiting to happen or a duplicate of a better
+source:
+
+- **Prop tables that retype the TypeScript.** Restate a prop only to add meaning
+  the type lacks. The source is the signature of record.
+- **The case list, render URLs, or tweak schema.** The manifest owns these and
+  stays in sync automatically; a copy here only rots.
+- **Styling internals** — CSS variables, class names, DOM structure, token math.
+- **Implementation detail** — how it works inside. Document the contract, not the
+  mechanism.
+- **Changelog or version history.** That is what git is for.
+- **Anything the name already says.** `<Spinner>` spins.
+
+## Form: write for the medium
+
+The doc renders as **CommonMark + GFM** (tables, task lists, strikethrough,
+autolinks) — but with [two limits](documentation-panel.md#two-intentional-limits):
+
+- **No raw HTML.** Embedded `<div>`/`<span>`/`<style>` is stripped, not rendered.
+  Stay in Markdown.
+- **No syntax highlighting.** Fenced blocks are plain `<pre>`. Use fences for
+  *structure*, never to imply colour.
+
+And because the file is ingested into a context window as often as it is read on a
+screen:
+
+- **Be dense.** Every sentence earns its tokens. The model of a great doc is
+  short — see [`Button.placard.md`](../src/ui/design-system/components/controls/Button.placard.md):
+  identity line, example, one variant sentence. Scale up only for real complexity.
+- **Be scannable.** Bold lead line always; `##` headings only once the doc has
+  enough distinct sections to need them. A five-line atom needs no headings.
+- **Be present-tense and declarative**, in the calm house voice — no marketing,
+  no hedging.
+- **Keep examples runnable and current.** They are the most-copied lines in the
+  file; treat a stale example as a bug.
+
+## Length is a function of complexity, not a target
+
+| Component shape | Doc shape |
+| --- | --- |
+| Atom, 1–2 props, one behaviour | Identity line + one example + a variant sentence. ~5 lines. |
+| Several variants or modes | Add a variant table and a decision-boundary line. |
+| Non-obvious callback or composition | Add the state/callback contract and required-wrapper notes. |
+| Subtle a11y or footguns | Add an accessibility line and a gotchas bullet. |
+
+Stop at the point where an agent could use the component correctly without the
+source. Past that, more words are liability, not value.
+
+## Pages, templates, and flows
+
+Everything above assumes a **reusable component** (atom / molecule / organism) —
+something you instantiate, so the doc revolves around the *call*: identity,
+canonical example, variants, decision boundary, prop/callback contract.
+Template-, page-, and flow-level exhibits aren't parts you instantiate, so that
+shape mostly doesn't apply. There is **no idiomatic call to paste, no prop API,
+no variant union** — drop the canonical-example snippet, the variant table, and
+the state/callback contract. The one principle holds, but what you document turns
+**behavioural / structural**, and the [manifest](ai-agents.md) already enumerates
+the cases / steps / `renderUrl`s / `transitions` — restate their *meaning*, never
+re-list them.
+
+- **Template** (page-level layout, no real data) — document **expected usage**:
+  the regions/slots the layout defines and what each is meant to hold, and when to
+  reach for this layout over a sibling. Structure, not data, not behaviour.
+- **Page** (a template filled with representative content) — document **expected
+  behaviour**: what screen it represents, what a viewer can do on it, the states
+  it exercises, and which template + content it composes. What it *does*.
+- **Flow** (a multi-step journey) — document **expected behaviour end to end**:
+  the ordered steps and what each represents, and — critically — *what advances
+  the flow between them* (the trigger on each transition), plus entry/exit and any
+  preset step state ([Hierarchy](hierarchy.md#flows) explains the flow model).
+
+Skeletons for the three:
+
+````md
+<!-- template -->
+**Name** — the layout it is; the one reason to reach for it.
+
+Regions: `header` (…) · `main` (…) · `aside` (…) — what each holds.
+
+Use this layout for X; for Y reach for `OtherTemplate`.
+````
+
+````md
+<!-- page -->
+**Name** — the screen it represents; what it demonstrates.
+
+Behaviour: what the viewer can do; the states shown.
+
+Composes `SomeTemplate` with `…` content.
+````
+
+````md
+<!-- flow -->
+**Name** — the journey and its outcome.
+
+Steps, in order: `step-one` (…) → `step-two` (…) → `done` (…).
+
+Advances when: `step-one`'s submit → `step-two`; … . Entry: … . Preset: … .
+````
+
+## A skeleton to copy
+
+````md
+**ComponentName** — what it is; the one reason to reach for it.
+
+```tsx
+<ComponentName prop="idiomatic" onChange={handle} />
+```
+
+Variants: `default` (…, the default) · `alt` (…). Restate what each *means*.
+
+Use this for X. For Y, reach for `SiblingComponent` instead.
+
+Controlled — pass `value`/`onChange`; `onChange` emits the exact contract.
+Wrap in `FormField` for a label and error. Handles `role=…` itself.
+````
+
+Drop any line that would only restate the type or the name. The
+[canonical example](examples/tweak-control.placard.md) fills this skeleton in for a
+real component, with margin notes on each choice.

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@awarebydefault/display-case",
+  "version": "1.0.0",
+  "description": "A Bun-native, AI-friendly component showcase — a lightweight alternative to Storybook.",
+  "license": "MIT",
+  "author": "Jake Uskoski <jake@awarebydefault.com>",
+  "type": "module",
+  "sideEffects": false,
+  "homepage": "https://github.com/AwareByDefault/display-case#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AwareByDefault/display-case.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AwareByDefault/display-case/issues"
+  },
+  "keywords": [
+    "bun",
+    "component",
+    "showcase",
+    "storybook",
+    "storybook-alternative",
+    "react",
+    "ssr",
+    "design-system",
+    "ai-agents",
+    "preview",
+    "playground",
+    "visual-regression",
+    "accessibility"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "packageManager": "bun@1.3.14",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "display-case": "src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./tokens-check": "./src/checks/tokens-check.ts",
+    "./prod-server": "./src/server/prod-server.ts"
+  },
+  "files": [
+    "src",
+    "skills",
+    "docs",
+    "display-case.prompt.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "setup": "bun scripts/setup.ts",
+    "clean": "rm -rf .display-case dist dist-showcase",
+    "dev": "bun src/cli.ts . --dev",
+    "display-case": "bun src/cli.ts .",
+    "display-case:check": "bun src/cli.ts check .",
+    "lint": "biome check . && bun tools/lint/index.ts",
+    "lint:fix": "biome check --write . && bun tools/lint/index.ts --fix",
+    "lint:checks": "bun tools/lint/index.ts",
+    "typecheck": "tsc --noEmit",
+    "openspec": "openspec",
+    "check": "bun src/cli.ts check . --structure --tokens --ssr",
+    "baselines:record": "bun scripts/record-baselines.ts",
+    "test": "bun test",
+    "test:container": "bun test ./test/publish-container.test.ts",
+    "e2e": "playwright test",
+    "e2e:headed": "playwright test --headed",
+    "e2e:install": "playwright install chromium",
+    "release": "semantic-release",
+    "release:dry": "semantic-release --dry-run --no-ci",
+    "prepare": "husky"
+  },
+  "peerDependencies": {
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "dependencies": {
+    "@parcel/watcher": "^2.5.6",
+    "markdown-to-jsx": "^9.8.2"
+  },
+  "optionalDependencies": {
+    "@axe-core/playwright": "^4.10.1",
+    "pixelmatch": "^6.0.0",
+    "playwright": "^1.50.1",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@commitlint/cli": "^19.6.0",
+    "@commitlint/config-conventional": "^19.6.0",
+    "@emotion/cache": "^11.14.0",
+    "@emotion/react": "^11.14.0",
+    "@emotion/server": "^11.11.0",
+    "@fission-ai/openspec": "1.4.1",
+    "@playwright/test": "^1.60.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/bun": "^1.2.0",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "husky": "^9.1.7",
+    "semantic-release": "^25.0.5",
+    "typescript": "^5.7.0"
+  }
+}

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

@@ -0,0 +1,20 @@
+# display-case-author-case
+
+Scaffold a `*.case.tsx` for a component that doesn't have one yet.
+
+## What it does
+
+Reads a component's source for its real props, then writes a colocated case file that default-exports `defineCases(...)` — a `Default`, the meaningful variants, and a `Playground` with typed tweaks — tagged with the right Atomic Design `level`. The result shows up in the showcase and satisfies the `display-case-coverage` lint.
+
+## When it triggers
+
+The coverage check fails for a component, a new shared component is added, or someone asks to "add a case" / "showcase this component".
+
+## How it works
+
+1. Read `<name>.tsx` (and `<name>.placard.md`) for exports and prop types.
+2. Write `<name>.case.tsx` with variants + a tweaks playground, choosing the hierarchy `level` by composition.
+3. Keep cases side-effect-free (lazy thunks; stateful demos as inner components).
+4. Verify with `bun run display-case`; the `display-case-coverage` lint passes.
+
+Authoring spec: [`../../display-case.prompt.md`](../../display-case.prompt.md).

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

@@ -0,0 +1,40 @@
+---
+name: display-case-author-case
+description: >
+  Write a Display Case *.case.tsx file for a component that lacks one, so it
+  appears in the showcase and passes the display-case-coverage lint. Use when
+  the coverage check fails, when adding a new shared component, or when asked to
+  "add a case", "showcase this component", or "cover <component> in Display Case".
+---
+
+Author a colocated `*.case.tsx` for a component so it shows up in Display Case.
+
+## Steps
+
+1. **Read the component source** (`<name>.tsx`) to get the exact exported name and prop types. Read the sibling `<name>.placard.md` if present for realistic usage.
+2. **Create `<name>.case.tsx`** next to it, default-exporting `defineCases`:
+   ```tsx
+   import { defineCases, tweak } from '@awarebydefault/display-case'
+   import { TweakControl } from './tweak-control'
+
+   export default defineCases(
+     'TweakControl',
+     {
+       Default: () => <TweakControl kind="text" label="Label" />,
+       Variants: () => (/* one instance per meaningful variant */),
+       Playground: {
+         tweaks: { label: tweak.text('Variant'), disabled: tweak.boolean(false) },
+         render: (t) => <TweakControl kind="text" label={t.label} disabled={t.disabled} />,
+       },
+     },
+     { level: 'atom' }, // atom|molecule|organism|template|page
+   )
+   ```
+3. **Pick the hierarchy `level`** by composition: primitives→`atom`, small composites→`molecule`, sections→`organism`, layouts→`template`, full screens→`page`. A behavioural multi-step flow uses `defineFlow(name, { steps, area? })` instead (level `flow`). For a `page`/`flow` case that should render inside app chrome (nav/header), add a free-form `area` tag — `defineCases(name, cases, { level: 'page', area: 'app' })` or `defineFlow(name, { area: 'app', steps })` — which the package's decorator maps to a layout (it overrides folder-based detection via the case's path).
+4. **Add tweaks** for the interesting props (`tweak.text/boolean/number/choice`); cast a `choice` value into a union-typed prop.
+5. **Keep it side-effect-free**: cases are lazy thunks. For controlled components, define a tiny stateful demo component above the export and reference it.
+6. **Verify**: `bun run display-case` shows it; the `display-case-coverage` lint passes.
+
+## Reference
+
+`../../display-case.prompt.md` is the authoring spec; `../../docs/writing-cases.md`, `../../docs/hierarchy.md`, and `../../docs/tweaks.md` go deeper.

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

@@ -0,0 +1,24 @@
+# display-case-author-placard-doc
+
+Write a `<component>.placard.md` — the prose doc panel — that lets a reader use the component correctly without opening its source.
+
+## What it does
+
+Reads a component's source for its real props, defaults, and callback contracts (and its case file for variants), then writes a colocated `.placard.md` following the [Writing placard docs](../../docs/writing-placard-docs.md) best practices: an identity line, a copy-pasteable canonical example, variant semantics, the decision boundary to sibling components, the state/callback contract, and composition/a11y notes — and deliberately *omits* anything the source, the manifest, or the component name already says.
+
+## When it triggers
+
+A new shared component is added, a component has a `.case.tsx` but no `.placard.md`, or someone asks to "write a placard doc", "document this component", "add a doc panel", or "write usage docs for `<component>`".
+
+## How it works
+
+1. Read `<name>.tsx` (props, defaults, what callbacks emit) and `<name>.case.tsx` (variants); improve an existing `.placard.md` rather than replace it.
+2. Find the decision boundary — the sibling components this one is easily confused with — by scanning the package's component inventory.
+3. Draft top-down, highest value first (identity → example → variants → decision boundary → state/callback contract → composition/a11y → gotchas), stopping once the source is unnecessary.
+4. Restate meaning, never type signatures; cut prop tables, case/render-URL lists, styling internals, and changelogs.
+5. Write for the medium: GFM, no raw HTML, no syntax highlighting, dense.
+6. Verify it renders in the doc panel and that every example is correct and copy-pasteable.
+
+Unlike a `.case.tsx`, a `.placard.md` is not enforced by any lint — its only value is quality, so the bar is applied by judgement.
+
+Authoring 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).