Skip to content

paperclipai/paperclip / .agents/skills/directions-lab

directions-lab

Verified

Scaffold a directions lab that shows shipped UI (Today) beside 2-3 design directions, with surface tabs, theme and animation toggles and the V1 MVP hover motion, registered in design-proposals Storybook. Use for a directions page or lab, or to explore design directions next to production.

FileKindSize
SKILL.mdskill md15.4 KB
agents/openai.yamlconfig291 B
assets/PRECEDENTother187 B
assets/motion/v1-mvp-motion.cssother787 B
assets/templates/api-routes.ts.mjsscript531 B
assets/templates/api-stub.ts.mjsscript1.9 KB
assets/templates/build-info.ts.mjsscript220 B
assets/templates/define-lab.ts.mjsscript3.9 KB
assets/templates/direction/MotionSpecimen.tsx.mjsscript2.3 KB
assets/templates/direction/SlotBody.tsx.mjsscript521 B
assets/templates/direction/index.tsx.mjsscript445 B
assets/templates/direction/tokens.css.mjsscript1.1 KB
assets/templates/entry.html.mjsscript752 B
assets/templates/fixtures.ts.mjsscript1.2 KB
assets/templates/frames/AppShell.tsx.mjsscript5.2 KB
assets/templates/frames/Board.tsx.mjsscript4.8 KB
assets/templates/frames/LabToolbar.tsx.mjsscript4.4 KB
assets/templates/frames/Slot.tsx.mjsscript329 B
assets/templates/frames/SurfaceFrame.tsx.mjsscript1.3 KB
assets/templates/frames/SurfaceView.tsx.mjsscript540 B
assets/templates/kit.ts.mjsscript1.9 KB
assets/templates/lab-state.ts.mjsscript1.8 KB
assets/templates/lab.css.mjsscript74 B
assets/templates/launch-entries.json.mjsscript680 B
assets/templates/main.tsx.mjsscript6.2 KB
assets/templates/providers.tsx.mjsscript920 B
assets/templates/registry.ts.mjsscript1.6 KB
assets/templates/shot.cjs.mjsscript10.0 KB
assets/templates/stories/compare.stories.tsx.mjsscript3.4 KB
assets/templates/tests/api-stub.test.ts.mjsscript1.6 KB
assets/templates/tests/lab-state.test.ts.mjsscript3.1 KB
assets/templates/tests/motion-contract.test.ts.mjsscript5.7 KB
assets/templates/tests/registry.test.ts.mjsscript2.5 KB
assets/templates/tests/today.test.tsx.mjsscript2.0 KB
assets/templates/today/SlotBody.tsx.mjsscript972 B
assets/templates/today/adapters.ts.mjsscript748 B
assets/templates/today/index.tsx.mjsscript387 B
assets/templates/vite.config.mjs.mjsscript2.9 KB
evals/asks-how-many-directions/case.yamlconfig343 B
evals/asks-how-many-directions/graders/01-expected-output.mdmarkdown347 B
evals/asks-how-many-directions/prompt.mdmarkdown197 B
evals/multi-surface-three-directions/case.yamlconfig674 B
evals/multi-surface-three-directions/graders/01-expected-output.mdmarkdown672 B
evals/multi-surface-three-directions/prompt.mdmarkdown510 B
evals/single-surface-two-directions/case.yamlconfig398 B
evals/single-surface-two-directions/graders/01-expected-output.mdmarkdown397 B
evals/single-surface-two-directions/prompt.mdmarkdown284 B
references/canonical-directory.mdmarkdown15.5 KB
references/design-proposals-storybook.mdmarkdown29.2 KB
references/drawing-phases.mdmarkdown21.7 KB
references/generator.mdmarkdown25.7 KB
references/lab-anatomy.mdmarkdown28.7 KB
references/lifecycle.mdmarkdown18.9 KB
references/motion-spec.mdmarkdown21.1 KB
references/questions-and-defaults.mdmarkdown15.6 KB
references/repo-gates.mdmarkdown20.8 KB
references/today-fixtures-and-build.mdmarkdown34.9 KB
scripts/lib/args.mjsscript2.4 KB
scripts/lib/capabilities.mjsscript2.1 KB
scripts/lib/check.mjsscript10.6 KB
scripts/lib/context.mjsscript8.6 KB
scripts/lib/modes.mjsscript1001 B
scripts/lib/ports.mjsscript1.9 KB
scripts/lib/registry-edit.mjsscript5.2 KB
scripts/lib/render.mjsscript3.6 KB
scripts/lib/shared-files.mjsscript2.9 KB
scripts/lib/verify.mjsscript1.8 KB
scripts/lib/write.mjsscript2.3 KB
scripts/scaffold.mjsscript14.3 KB
scripts/scaffold.test.mjsscript33.7 KB

references/canonical-directory.md

View on GitHub
# Canonical directory: the governance PR (separate, opened only on Tonio's yes)

Paste-ready diffs that make the Storybook **Design proposals** section the design directory:
the source of truth for visual references, with `DESIGN.md` recording decisions and pointing at
entries. The skill does not need it: every lab ships in mode A (story `status: "proposed"`, stage
carried by the registry's `stage` field and, once a per-direction story is written by hand, by its
first sentence; see `lifecycle.md`). Part 1 is the governance change, prose only. Part 2 is the
optional mode-B script change that lets an entry carry `current` or `historical`. Today's framing,
and why it exists, is `design-proposals-storybook.md` section 6; it is not repeated here.

Rules:

- Never apply any of this inside a lab PR. Offer it once, in one line of the lab PR body:
  "The design-directory governance change (`canonical-directory.md`) is ready as a separate PR
  on request." Open it only when Tonio says yes: branch `claude/design-directory`, title
  `docs(design): make the Design proposals section the design directory`, body from
  `.github/PULL_REQUEST_TEMPLATE.md` with every section filled, including Model Used.
- Part 1 alone is a complete PR. Part 2 alone is not: do not change the script while
  `DESIGN.md:9` still says Storybook does not define the system.
- Line numbers were read on 2026-10-24 at `5e26b733b`. Re-check each with `sed -n` before
  editing: every `-` line below must still match byte for byte, or the diff is stale.

## Part 1: governance diffs (prose only, no script change)

### 1.1 `DESIGN.md:9`, the source-of-truth sentence (under `## What this document is for`, line 7)

```diff
-Agents and humans modifying `ui/` treat this file as the source of truth for design decisions. Storybook is the verification surface — it documents the system; it does not define it. If a change conflicts with this document, change this document first (with review) or change the code.
+Agents and humans modifying `ui/` treat this file and the Storybook **Design proposals** directory as the source of truth: a directory entry (meta id `design-*`) is the canonical visual reference for its subject at its recorded stage; this document records the decisions and points at the entries. The rest of Storybook is the verification surface — it documents the system; it does not define it. If a change conflicts with this document or with a directory entry, change the document or the entry first (with review) or change the code.
```

Why "at its recorded stage": a `proposed` entry is canonical for what the proposal looks like,
not a claim that the product renders it. The stage is what separates the two.

### 1.2 New `## Design directory` section (additive)

Insert after line 9, before `## Product stance` (`DESIGN.md:11`), beside the sentence that
grants the authority:

```markdown
## Design directory

The Storybook **Design proposals** section is the design directory. Each row names the
entry (its stable meta id, `design-*`) that is the canonical visual reference for a subject
and the stage recorded for it. Advance a row's stage in the PR that advances the entry.
A subject without a row has no canonical reference yet. Entries never count as
production coverage; the product's own feature-home stories do.

| Subject | Entry | Stage |
| --- | --- | --- |
| Artifacts | `design-artifact-directions-compare` | adopted (`enableArtifactsV1`) |
```

No URL column: the meta id is the durable pointer (`/iframe.html?id=<meta id>--<export>`); the
published host is not. First-row facts: the id is at
`ui/storybook/stories/design-proposals/artifact-directions-compare.stories.tsx:39` (the story is
`status: "proposed"`, `home: "design-proposals"`, lines 52-53); the flag is `enableArtifactsV1`
(`packages/shared/src/feature-catalog.ts:202`, read by `ui/src/hooks/useArtifactsV1Enabled.ts:7-8`).
The artifact lab predates the `design-<slug>-directions` id convention, hence the `-compare`
suffix; new labs use `registry.storyId`. `lifecycle.md` section 10 offers a lab's row as text in
this table's shape; the table stays literal Markdown.

### 1.3 `DESIGN.md:304` and `:311-313`, "review references" and the move on adoption

Both sit in one paragraph (`DESIGN.md:297-313`) of `## Task-row refresh: proposed specimen`
(`:289`). Leave line 303 (`home: "design-proposals"`, `status: "proposed"`, "an explicit staging
reason") alone in Part 1: the catalog still enforces exactly that (`scripts/storybook-catalog.mjs:99-100`).
Line 311 starts mid-sentence; keep its first clause.

```diff
-These stories are review references and do not count as current production coverage.
+Directory entries are the canonical references for their subjects and never count as production coverage.
 ...
-for tasks explicitly implementing the refresh. After design review and adoption
-in the app, move each suite to its feature or Foundations home and update its
-classification while retaining its explicit story ID and exports.
+for tasks explicitly implementing the refresh. After adoption in the app the entry stays in
+the directory with its ID and exports; the shipped component gets its own story in its
+feature home, and the Design directory table above records the new stage.
```

### 1.4 `maps/storybook-map/README.md:34-35`, the exception is the entry's purpose

```diff
-Staged design work may use `home: "design-proposals"`, with `status: "proposed"`
-and an exception explaining why it is staged separately from production references.
+Design directory entries use `home: "design-proposals"`, `status: "proposed"` and an
+exception stating the entry's purpose: the subject it is the canonical reference for and
+what it compares.
```

### 1.5 `maps/storybook-map/README.md:60-75`, the section's role and the stages

Lines 61-69 (folder, title prefix, group order, "Preserve explicit story IDs and exports") stay.

```diff
-**Design proposals** is a separate top-level review section. Its stories live in
+**Design proposals** is the design directory: a separate top-level section whose entries
+are the canonical visual references named in `DESIGN.md` (Design directory). Its stories live in
 ...
-Retain capability references so proposals remain discoverable from the feature
-guide, but never count them as current production examples. Keep using shared
-components and tokens rather than creating a parallel design implementation.
-When a proposal is reviewed and adopted in the app, move its story into the usual
-feature or Foundations home, update its classification and staging metadata, and
-preserve the explicit CSF ID and exports so review links remain valid.
+Retain capability references so entries remain discoverable from the feature guide,
+but never count them as production coverage. Keep using shared components and tokens
+rather than creating a parallel design implementation. An entry has one of four stages:
+proposed, adopted (behind a flag), current (shipped as the default) and
+historical (superseded, with `replacement` naming the successor). The stage is recorded
+in the entry's description and in the `DESIGN.md` Design directory table; the catalog
+status stays `proposed` while the catalog accepts only that status in this home. Entries
+stay in the directory at every stage and keep their explicit CSF ID and exports; the
+shipped component gets its own story in its feature home.
```

Why entries stay put: fifteen of the twenty directory ids are pinned by Playwright specs, and a
directory whose entries leave when they succeed is not a directory. The count, from the repo root
(two of the fifteen, `tasks-list-page-design` and `tasks-row-design`, have no `design-` prefix):

```sh
for id in $(git ls-files 'ui/storybook/stories/design-proposals/*.stories.tsx' | xargs grep -hoE '^\s*id: "[^"]+"' | cut -d'"' -f2); do grep -rqF -- "$id" tests/storybook-visual && echo "$id"; done | wc -l   # 15 of the 20 ids
```

### Part 1 verification

Nothing executable reads this prose. Run what AGENTS.md requires after a `maps/` edit, plus the
catalog, which must be unaffected:

```sh
node scripts/check-maps.mjs                 # today: "Maps aligned: 35 areas, 191 capability IDs"
node scripts/storybook-catalog.mjs --check  # today: "Storybook map: 316 files, 2973 stories."
```

## Part 2 (optional): mode-B script change

Mode B lets a directory entry carry `status: "current"` or `"historical"` under
`home: "design-proposals"` while still never counting as coverage. The skill detects mode A by
the exact message `design proposal home requires proposed status` in `scripts/storybook-catalog.mjs`
(`scripts/lib/modes.mjs`; `lifecycle.md` section 2). The new message below does not contain that substring (the comma
breaks it), which is what flips detection to mode B. Do not shorten the message back.

### 2.1 `scripts/storybook-catalog.mjs:99`, the status gate

```diff
-      if (entry.status !== "proposed") errors.push(`${label}: design proposal home requires proposed status`);
+      if (!["proposed", "current", "historical"].includes(entry.status)) errors.push(`${label}: design proposal home requires proposed, current or historical status`);
```

`mixed` and `unreviewed` stay rejected: a directory entry is a decision, and both mean the
decision has not been made. Line 100 (the exception requirement) is unchanged.

### 2.2 `scripts/storybook-catalog.mjs:133`, the home description in the generated index

```diff
-    { id: "design-proposals", title: "Proposed design system", section: "Design proposals", description: "Staged design work for review. These examples retain capability references but do not count as current product coverage." },
+    { id: "design-proposals", title: "Proposed design system", section: "Design proposals", description: "Design directory. Canonical references for design subjects; they never count as product coverage." },
```

### 2.3 `scripts/storybook-catalog.mjs:165` and `:169`, coverage excludes the home regardless of status

```diff
-  const examples = catalog.entries.filter(entry => entry.implementation !== "guide" && !["historical", "proposed"].includes(entry.status));
+  const examples = catalog.entries.filter(entry => entry.implementation !== "guide" && !["historical", "proposed"].includes(entry.status) && storyHome(entry) !== "design-proposals");
 ...
-    `${capabilities.length} capabilities; ${missing.length} without a current, mixed or unreviewed example. Historical examples, proposals and guides do not remove gaps.`, "",
+    `${capabilities.length} capabilities; ${missing.length} without a current, mixed or unreviewed example. Historical examples, proposals, design directory entries and guides do not remove gaps.`, "",
```

`storyHome` is defined in the same module (`:70-72`). Without the new clause a `current`
directory entry silently closes a capability gap; the test in 2.4 fails on exactly that
(verified: with only this clause reverted, "1 without" becomes "0 without"). The line-169
wording keeps the generated `maps/generated/verification.md` true; no test matches that tail
(`storybook-catalog.test.mjs:98,159` match only `/2 without a current, mixed or unreviewed example/`).

### 2.4 `scripts/storybook-catalog.test.mjs:101-115`

Lines 109-114 (exception, title and folder assertions) are unchanged. `renderVerification` is
already imported at line 6.

```diff
-test("design proposal homes require proposed status, a staging reason and their own navigation", t => {
+test("design proposal homes require a directory status, a staging reason and their own navigation", t => {
   const f = mapFixture(t);
   const metadata = { home: "design-proposals", status: "proposed", capabilities: ["tasks/create"], exception: "Staged refresh for review." };
   const options = { area: "design-proposals", title: "Design proposals/Tasks/Task row" };
-  for (const status of ["current", "mixed", "unreviewed", "historical"]) {
+  for (const status of ["mixed", "unreviewed"]) {
     f.story("proposal", { ...metadata, status }, options);
-    assert.match(inspect(f).errors.join("\n"), /design proposal home requires proposed status/);
+    assert.match(inspect(f).errors.join("\n"), /design proposal home requires proposed, current or historical status/);
   }
+  f.story("proposal", { ...metadata, status: "current", capabilities: ["tasks/discussion"] }, options);
+  const current = inspect(f);
+  assert.deepEqual(current.errors, []);
+  assert.match(renderVerification(current.catalog, current.index), /1 without a current, mixed or unreviewed example/);
+  f.story("proposal", { ...metadata, status: "historical" }, options);
+  assert.deepEqual(inspect(f).errors, []);
   f.story("proposal", { ...metadata, exception: undefined }, options);
```

Why `tasks/discussion`: `mapFixture` (`scripts/map-test-fixture.mjs:31-32`) seeds `tasks` with
`create` and `discussion` and one `unreviewed` story on `tasks/create`, so `discussion` is the
one open gap. A `current` directory entry on it must leave "1 without"; "0 without" means the
entry counted as coverage.

### Part 2 verification

Run from the repo root and paste the three results into the PR's Verification section:

```sh
node --test scripts/storybook-catalog.test.mjs        # 13 tests, 13 pass, before and after (one test rewritten, none added)
node scripts/storybook-catalog.mjs --check             # "Storybook map: 316 files, 2973 stories."; all 20 directory entries are proposed, so nothing flips
cd ui && npx vitest run storybook/map-tooling.test.ts  # 1 passed; wraps the three node --test files (ui/storybook/map-tooling.test.ts:6)
```

The vitest wrapper is the CI signal (`maps/storybook-map/README.md:104-105`); a green
`node --test` alone is not. `cd ui && pnpm typecheck` also re-runs the catalog (`ui/package.json:23`);
report it as not run if `@paperclipai/plugin-sdk` is not built.

With Part 2 merged, a lab records stages as `lifecycle.md` mode B says: proposed and adopted map
to `status: "proposed"`, current to `"current"`, historical to `"historical"` plus `replacement`.
`scaffold.mjs check` then derives the expected Compare `status` from the registry stages
(`scripts/lib/modes.mjs`, `labStage`): `"proposed"` while any exploration is proposed or adopted,
`"historical"` plus `replacement` when every exploration is historical, `"current"` otherwise.
In the same PR amend README line 34 from `status: "proposed"` to "`status` of `proposed`,
`current` or `historical` (adopted entries keep `proposed`)" and drop the 1.5 clause "the catalog status stays
`proposed` while the catalog accepts only that status in this home".

## What does not change

- The literal-only rule: `parameters.paperclip` is parsed, never executed, and must follow
  spreads (`scripts/storybook-catalog.mjs:26-59`). Stage never becomes a computed value.
- The `statuses` list (`:13`) and the `home` allow-list (`:95`): no new status, no new home.
- Meta ids and exports: `stableId` is required (`:109`) and every id stays; Part 1 removes the
  move-on-adoption that used to put them at risk.
- The folder and title rules (`:107-108`): entries live in `ui/storybook/stories/design-proposals/`
  with titles under `Design proposals/`; the sidebar slot (`scripts/storybook-feature-index.mjs:11`)
  and the proposal theme scope (`ui/storybook/.storybook/preview-base.tsx:853`) key on the same home.
- The home's `title` ("Proposed design system") and `section` ("Design proposals") at `:133`:
  only the description changes, so the Overview guide and sidebar labels are untouched.
- The capability lookup (`:159`) keeps printing `(<status>)` after each entry; under mode B a
  directory entry shows `(current)` there while `verification.md` still lists the gap. Intended:
  lookup is navigation, coverage is `verification.md`.
- `doc/DEVELOPING.md` and the three commands above: no command changes.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall