PaperClipAI/maps/storybook-map

Storybook map

Browse the published feature guide, or run pnpm storybook for the current checkout. The feature and capability IDs come from the feature recipes. Product behavior and permissions remain governed by the implementation spec and access companions.

Authored sources

Each story owns its small parameters.paperclip annotation. There is no authored central catalog, review ledger, date stamp, source list or fingerprint to update. Storybook's CSF parser supplies filenames, titles, explicit meta IDs, exports, play-function counts and story IDs without executing story modules.

const meta = {
  id: "tasks-create",
  title: "Tasks and conversations/Task creation and lifecycle/Create",
  parameters: {
    paperclip: {
      capabilities: ["tasks/create"],
      implementation: "production",
      boundary: "fixtures",
      notes: "Uses the shipped composer; submission is simulated.",
    },
  },
};

capabilities is an array of stable area/capability IDs. Its first entry is the primary home; others cross-list the same suite. An empty array requires an exception explaining the intentional scope. Shared foundations may use home: "foundations" with an exception to keep their existing location and links. The metadata must be literal; place it after any other parameter spreads.

Field	Values and purpose
status	current, proposed, historical, mixed, unreviewed (default). Authored product alignment intent, not a live review certificate.
implementation	production, prototype, mixed, guide, unreviewed (default). What actually renders.
boundary	fixtures, fixture-server, static, unreviewed (default). What is simulated or requires an owned fixture.
notes	Optional durable scenario limits and rationale. Do not append a history of unrelated changes.
replacement	Optional repository-relative path of an existing replacement story.

A production component can use fixtures. A prototype that imports production primitives remains a prototype of its outer subject. Use unreviewed when intent or parity is unclear. Preserve useful historical examples and their explanations. Historical examples, proposals and guides do not remove missing-example gaps. No annotation or story count proves permissions, persistence, provider behavior, full recipe coverage or passing tests.

Navigation and outputs

Stories live in ui/storybook/stories/<primary-feature-area>/. Sidebar titles use the recipe's section and H1 title, followed by the suite name. / in feature labels becomes , in the sidebar. Preserve explicit CSF IDs across title/folder changes. Compare the built index.json when changing navigation.

The generator discovers feature recipes and story annotations. It assembles:

• ui/storybook/generated/catalog.json and feature-index.json.
• A generated Overview story per feature, retaining feature-map-<area>--overview.
• ui/storybook/.storybook/preview.tsx, with the literal sidebar order required by Storybook and the authored decorators/fixtures from preview-base.tsx.
• Markdown feature, access, Storybook and verification indexes, plus the current page inventory, under maps/generated/.

All these outputs are ignored. Storybook start/build and UI typechecking generate from a fresh checkout. The published Storybook includes the guide and each feature's verification scope. After edits during a dev session, rerun the generator (restart Storybook after navigation changes). Obsolete generated Overview files are removed. Never edit generated outputs or commit them to resolve a merge conflict.

Checks and review

node scripts/check-maps.mjs
node scripts/storybook-catalog.mjs
node scripts/storybook-catalog.mjs --check
node --test scripts/check-maps.test.mjs scripts/storybook-catalog.test.mjs scripts/storybook-feature-index.test.mjs

--write is a compatibility alias for the default generation command. --check validates authored inputs without requiring existing outputs or writing files. Checks reject malformed annotations, unknown capabilities, duplicate IDs, broken map references, missing companions and invalid navigation. CI runs the map tests through the UI Vitest suite and validates/generates inputs during UI typechecking.

Use Git diffs to select changed stories, rendered subjects, fixtures, and recipes for review. A changed source is a review candidate, not an instruction to refresh metadata on every dependent example. Inspect actual imports and contracts; shared fixture changes can require broad review without broad acknowledgement edits. Keep revision-specific findings and executed evidence in the PR, issue or CI artifact. Move only durable limitations into the affected source annotation or recipe. Past review history remains available through Git.

maintain-storybook owns stories and their annotations; review-storybook exercises them. Product/access maintenance owns the recipes, including optional capability verification scope. Use the existing Storybook browser workflow. Report source inspection, rendering, play assertions, visual comparison and production acceptance separately. Do not publish new baselines to pass a map cleanup.