# Design System To Storybook

> Build or update framework-native, token-backed Storybook foundations, shared UI components, and stories from an extracted design-system package. Use after design-system-extractor, or when Codex must adapt design-system Markdown, tokens, and traced Figma/image/code/route evidence to an existing or new React, Vue, Angular, Svelte, Web Components, meta-framework, monorepo, or other frontend target; select the correct app root, renderer, builder, file conventions, and optional tooling; infer component dependency order; sync component documentation; plan batches; or bootstrap Storybook without silently imposing React/Vite or migrating the product framework. Also use when updating, version-checking, or explaining this skill's bundled tools: the Figma export addon and the Storybook Code To Design Figma importer.

- Skill: `harrychuang/design-system-to-storybook` (Agent Skill, multi-file: 468 files)
- Install (CLI): `npx skillmds@latest add harrychuang/design-system-to-storybook`
- Raw SKILL.md: https://api.skillmd.com/api/skills/harrychuang/design-system-to-storybook/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: harrychuang (https://skillmd.com/u/harrychuang)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/harrychuang/design-system-to-storybook

---


# Design System to Storybook

Use this skill to turn an already extracted design-system package into a product repo's Storybook implementation. The design-system documentation and tokens are the normative source of truth. Original Figma nodes, UI or graphic images, rendered routes, and frontend folders recorded by `design-system-extractor` are supporting evidence for implementation details, Storybook parity, and visual verification.

This is a downstream implementation skill. Do not re-extract a design system here. If the required design-system docs, token architecture, source evidence, or component specs are missing, ask to run or continue `design-system-extractor` first.

## Expected Inputs

- **Design-system package:** usually contains `design-system/`, `tokens/`, and generated docs under `docs/design-system/`.
- **Product repo:** the codebase where Storybook, shared UI components, and token imports should be created or updated.
- **Implementation scope:** specific components, typographic/text-lockup components, all extracted components, foundations only, or a product-owned component library.
- **Runtime constraints:** target app/workspace root, framework and meta-framework, rendering mode, language, package manager, Storybook renderer/builder/version, styling system, and test commands.
- **Framework decision:** explicit current-user or approved target-specific handoff choice when present; otherwise the selected target root's evidence and any ambiguity that must be resolved before setup.
- **Storybook bootstrap preference:** when Storybook must be created, whether to use the bundled `storybook-template`, use a product-native Storybook setup, or create a separate template workspace.
- **Batch budget:** optional number of components to implement in the current pass.
- **Extractor source evidence:** `DESIGN_EVIDENCE_MAP.md`, `SESSION_STATE.md`, component spec `Evidence` tables, component-review image links, and any Figma URLs/nodes, UI screenshots, graphic/brand/editorial image references, rendered routes, or frontend folders listed there.
- **Documentation sync inputs:** existing component folders, co-located Storybook stories, component CSS token usage, explicit user component briefs, `COMPONENT_INVENTORY.md`, and component-review status JSON when design-system docs need auditing or backfilling.
- **Bundled Figma export addon:** detect renderer, builder, and Storybook major before installation. React + Vite + Storybook 10 and Vue 3 + Vite + Storybook 10 have verified full Export, Review, Visual Comments, persistence, report, and source-action parity. Other detected Storybook 10 renderers receive core export only when the capability report marks it `supported`; never infer full review support from core export support.
- **Bundled Figma import plugin:** machine-level Figma tooling paired with a compatible exporter payload; it is not a renderer or exporter by itself. It ships inside this skill; solo developers load the skill-folder manifest, while teams with designers commit a repo copy as the distribution channel.
- **Bundled Storybook template:** optional React + Vite + Storybook 10 workspace; ask before using it and never treat it as the universal bootstrap.
- **Figma export readiness:** stable component node naming, token-bindable CSS, auto-layout-friendly DOM, source URL parameters, and export payload validation.
- **Prototype handoff:** when the user wants PRD-led product prototypes or UI Flow, continue with `storybook-product-prototype`; record whether the template-only Prototype Inspector and Static Flow helpers are actually available.

## First Actions

1. Locate the design-system package root and the product repo root. They may be the same folder.
2. Read `design-system/SESSION_STATE.md`, `DESIGN_EVIDENCE_MAP.md`, `TOKEN_ARCHITECTURE.md`, `COMPONENT_INVENTORY.md`, `DESIGN_ELEMENTS.md`, and relevant `design-system/components/*.md`.
3. Run the source trace script to resolve extractor sources before implementation: `node <skill-root>/scripts/trace_sources.mjs <design-system-package-root> --write`.
4. Run the component planner before choosing implementation order and queue rows: `node <skill-root>/scripts/plan_component_batches.mjs <design-system-package-root> --write --queue`.
5. Inspect referenced design sources for the selected scope: use Figma MCP for Figma nodes, inspect local UI or graphic images/crops, and inspect referenced frontend folders/routes when present.
6. Read `references/framework-adaptation.md`, inspect every plausible app/workspace root, and record the selected root, framework/meta-framework, renderer, builder, file conventions, and evidence before scaffolding or dependency installation.
7. Apply the framework decision gate: inherit an unambiguous existing stack without a redundant framework question; for greenfield, ambiguous, conflicting, multi-root, or migration cases, ask for the missing decision before writing setup files. Never migrate frameworks without explicit approval.
8. If Storybook is absent or a new workspace is requested, ask whether to initialize product-native Storybook unless that choice is already explicit. Offer the bundled React/Vite template only for a React/Vite target or an explicitly requested separate token/docs or React workspace.
9. Run the component documentation checker for product repos that already contain components: `node <skill-root>/scripts/check_component_docs.mjs <product-repo-root> --design-system-root <design-system-package-root>`. Use `--write` only when the user asked to backfill missing docs or when this pass creates new components.
10. Record an implementation map before code changes. Prefer `design-system/STORYBOOK_IMPLEMENTATION_MAP.md` when the design-system package lives in the product repo; otherwise use `docs/design-system/storybook-implementation.md`.
11. Run the bundled Figma export installer when Storybook 10 is present. Let it auto-detect renderer/builder/major and inspect the capability report before accepting generated wiring. Full review wiring is verified for React + Vite and Vue 3 + Vite; supported non-Vite/other-renderer targets fall back to core export wiring. Use `--renderer` only to resolve conflicting static signals.
12. Confirm the bundled Figma import plugin only when a compatible exporter payload is available: run the importer script to report its version, manifest path, and once-per-machine Figma Desktop setup; pick the distribution channel by audience — skill-folder manifest for a solo developer machine, committed repo copy (`--copy-to figma/storybook-code-to-design`) when designers or teammates need the plugin without an agent skill install.
13. Read `references/figma-export-readiness.md` before implementing components when the Figma export addon is installed or planned.
14. If implementing more than one component, create or update a component queue before reading every spec or editing code.
15. If the product has explicit design-system governance instructions, follow them. Otherwise apply the gates in this skill.

## Scope Modes

Choose the smallest mode that satisfies the user request:

- **Product-native Storybook:** create or update Storybook inside the selected app/package using that target's framework, meta-framework, builder, package manager, and source/story conventions.
- **Template bootstrap:** after approval, create a separate React/Vite/Storybook 10 workspace for shared token/docs verification or a separately requested React implementation; it cannot render or validate Vue or other non-React product components and must not convert or substitute for their product-native Storybook.
- **Foundations:** import or mirror tokens and add Storybook docs for color, typography, typographic composition, spacing, radius, elevation, and motion.
- **Typographic component pass:** implement selected text-lockup specs such as hero title lockups, editorial heading stacks, metric lockups, quote lockups, and label/value text groups as token-backed display components with stories.
- **Component pass:** implement selected `extracted` or `planned` component specs as shared components with stories.
- **Documentation sync pass:** audit and backfill `design-system/components/*.md`, `COMPONENT_INVENTORY.md`, implementation map entries, queue status, and review-status coverage for components that already exist in code or were just created.
- **Library pass:** build or update a reusable component package from the full component inventory.
- **Batch pass:** implement one dependency-aligned group from a large component queue.
- **Adoption pass:** replace ad hoc product UI with documented shared components after the Storybook catalog exists.
- **Prototype handoff:** stop design-system component work at the Storybook foundation boundary and use `storybook-product-prototype`; use project-native equivalents when template-only Prototype Inspector or Static Flow helpers are unavailable.

Do not compose product screens before the required shared components and stories exist unless the user explicitly asks for a product route first.

## Agent Installation

If the user asks to install or share this skill with Claude Code, Codex, or Cursor, read `references/agent-installation.md` and use `scripts/install_agent_skill.mjs`. Install the full skill directory so `SKILL.md`, scripts, references, and the bundled Storybook addon asset remain together.

## Tool Updates

If the user asks to update this skill or its bundled tools, check tool versions, or understand how tool updates reach projects and Figma, read `references/tooling-updates.md` and follow its three-layer update journey: machine (skills repo pull + skill reinstall), project (export addon tarball re-run + repo-copy importer refresh + commit), and Figma (one-time manifest import per machine, then refresh the files behind that path only). After any tool update, tell the user in their language which versions changed, what must be committed in the product repo, and whether a once-per-machine Figma step applies.

## Workflow

### 1. Package Readiness

Confirm the extracted package is usable:

| Required file | Purpose |
|---|---|
| `design-system/SESSION_STATE.md` | extraction status, known gaps, and recommended next step |
| `design-system/DESIGN_EVIDENCE_MAP.md` | source inventory, source fingerprints, and evidence IDs |
| `design-system/TOKEN_ARCHITECTURE.md` | token layers and naming rules |
| `tokens/tokens-ref.css` | raw reference values |
| `tokens/tokens-sys.css` | reusable semantic roles |
| `tokens/tokens-comp.css` | component-facing slots |
| `design-system/COMPONENT_INVENTORY.md` | component priority and status |
| `design-system/components/*.md` | anatomy, variants, states or display modes, accessibility, and token contracts |

If a required file is absent, continue only for the modes that still have enough evidence. For example, foundations can proceed without component specs, but component implementation cannot unless the user provides an explicit component brief for the current pass. When a component doc is created from code, stories, or a user brief instead of extracted evidence, mark it as `implementation-derived` or `brief-derived` and `needs-review`; do not treat it as an extracted source of truth until reviewed.

### 2. Source Trace And Design Source Discovery

Build a source trace before editing code:

```sh
node <skill-root>/scripts/trace_sources.mjs <design-system-package-root> --write
```

Default output is `design-system/STORYBOOK_SOURCE_TRACE.md`. Use it to connect component specs to original sources:

- **Figma URL or normalized node:** use Figma MCP to inspect the referenced node. Prefer `get_design_context` for component-level nodes, `get_metadata` for pages/structure, `get_variable_defs` for token variables, and `get_screenshot` for visual parity references. If only a page is known, use metadata to find the most relevant frame/component before implementing.
- **UI or graphic image / screenshot crop:** resolve the local path, inspect the actual bitmap, and use it as the visual reference for Storybook screenshot checks. Do not rely on alt text or filename alone.
- **Frontend folder or prototype source:** inspect the referenced code, Storybook entries, token files, rendered routes, and component API. Treat prototype code as migration evidence only when the user asks to migrate it; otherwise use it to understand behavior and states.
- **Rendered route:** run or inspect the route only if the product setup makes that cheap and safe. Record viewport, state, and command in the implementation map when used for verification.

Use the `Story Source URL Parameters` section from `STORYBOOK_SOURCE_TRACE.md` when creating or updating stories. Prefer Figma URLs and write them to `parameters.figmaSourceUrl`; use non-Figma web URLs only when they are the best available source and write them to `parameters.design.url`. Do not invent a URL from a local image path or normalized Figma fingerprint unless the design-system docs also provide the matching Figma file URL.

If the trace finds source IDs in component specs that cannot be resolved, mark the affected component `blocked` or `needs-extraction` in the queue before writing component code. If the trace finds Figma or image evidence for a component, do not skip that source unless the source is unavailable; record the reason.

Use original sources to clarify implementation details, not to silently override extracted design decisions. When Figma/image/frontend evidence contradicts the extracted tokens or component spec, stop and update the implementation map with the conflict; ask whether to revise the extraction or implement the documented spec.

### 3. Component Dependency Planning

Build a dependency plan before selecting components or batches:

```sh
node <skill-root>/scripts/plan_component_batches.mjs <design-system-package-root> --write --queue
```

Default outputs are `design-system/STORYBOOK_COMPONENT_PLAN.md` and `design-system/STORYBOOK_COMPONENT_QUEUE.md`. Use them to decide which component should be built next. The planner reads `COMPONENT_INVENTORY.md`, component specs, and `STORYBOOK_SOURCE_TRACE.md`, then infers:

- component category/tier: foundation, primitive, typographic, form-control, layout, navigation, data-display, feedback, overlay, composite, product-pattern, or unknown
- dependencies from explicit dependency/composition/anatomy/slot sections
- dependencies from component-name composition such as `IconButton` depending on `Button`
- dependency phrases from component spec mentions, such as `uses`, `contains`, `renders`, `wraps`, or `depends on`
- dependents, so heavily reused primitives are prioritized before the components that consume them
- story source URLs from the source trace, so queue rows inherit the right source URL

Use the recommended order unless product discovery proves that a dependency already exists and can be reused. Do not build a composite component before its listed dependencies are implemented, reused, or explicitly marked blocked with a reason. If the planner reports a cycle, pick the lowest-level reusable primitive in that cycle first, record the cycle in the implementation map, and update the queue after the first component breaks the cycle.

For any multi-component pass, create or update the queue from `STORYBOOK_COMPONENT_PLAN.md`. The next component should come from the earliest unfinished row in the recommended build order whose dependencies are done, reused, or blocked with an accepted decision.

Re-run the planner with `--queue` after dependency decisions change. It preserves existing queue statuses, product targets, story targets, and decisions while refreshing order, batch, dependency, and source URL data.

### 4. Product Discovery

Read `references/framework-adaptation.md` and find the local implementation pattern before adding files:

- Workspace/app roots: workspace manifests, package boundaries, route/runtime configs, lockfiles, and architecture docs that identify the actual implementation target.
- Runtime: framework, meta-framework, rendering mode, language, package manager, bundler/builder, and framework-specific plugins.
- Storybook config: `.storybook/`, `*.stories.*`, `*.mdx`, docs pages, decorators, preview styles.
- Components: `src/components/`, `components/`, `src/ui/`, `src/design-system/`, `packages/ui/`, or existing exports.
- Pages and composed screens: `src/pages/`, `pages/`, `src/screens/`, route modules, or existing composed view folders.
- Tokens and themes: CSS variables, token CSS imports, Tailwind config, theme objects, Sass variables, style dictionaries, or package-level token builds.
- Accessibility and tests: existing interaction tests, visual tests, a11y addons, Playwright, Vitest, Jest, Testing Library.
- i18n: locale files or message catalogs when stories or components need visible text.

Use this priority: explicit current-user or approved target-specific handoff choice, then evidence from the selected target root. Inherit a single coherent existing stack without asking the user to repeat it. Ask before scaffolding or installing when the target is greenfield, multiple roots are plausible, evidence conflicts, the framework/builder cannot be established, or the work would migrate frameworks. Do not use a sibling app's clearer stack as evidence for the selected target, and do not migrate merely to gain bundled tooling.

Do not install Storybook or unrelated dependencies unless the user asked for Storybook setup or approves it after discovery. When Storybook is missing, follow the bootstrap section. Core Storybook implementation is renderer-neutral; bundled export/import tooling is conditional capability, not a prerequisite.

### Storybook Template Bootstrap

Use the bundled template only when the user explicitly selects a React/Vite target or a separate React/Vite workspace. It is one bootstrap option, not the default for every greenfield project. Vue and other non-React products use product-native Storybook. A separate React workspace may verify shared tokens/docs or host a separately requested React implementation, but it cannot render or validate the product's Vue, Angular, Svelte, or Web Component implementation. Do not migrate an existing app or Storybook onto the template without explicit migration approval.

When Storybook is absent and the target/stack or workspace choice is not already explicit, ask one short question before installing or scaffolding:

```text
Which app/workspace and frontend stack should Storybook target? I can initialize Storybook with that product-native framework and builder. If you separately need shared token/docs checks or React components, I can also create the bundled React + Vite workspace.
```

For an existing unambiguous app, state the inferred product-native framework/builder and ask only for unresolved setup approval; do not re-ask which framework it uses or offer a separate React workspace by default for a non-React product. For greenfield, multi-root, conflicting, or migration cases, wait for the consequential decision. Product-native setup is the normal choice when components must be consumed by that product. The bundled template adds React + Vite + Storybook 10, token checks, foundation/catalog checks, Figma review wiring, a local importer manifest, and Prototype UI Flow helpers, but those capabilities apply only inside that separate template workspace.

For product-native setup, prefer the official Storybook CLI's dependency auto-detection inside the selected app root. If it cannot detect the framework or the repo is intentionally custom, inspect the current CLI help and use its supported `--type` fallback. Preserve the selected renderer, builder, meta-framework integration, package manager, and repo-native story/source conventions; record the exact command and evidence. See `references/framework-adaptation.md` for the complete decision flow.

If the user chooses the template, collect or infer:

- target root or subfolder
- project display name
- token prefix, using lowercase ASCII letters, digits, and single hyphens, starting with a lowercase letter
- optional package name
- optional Figma design file URL

Install with the bundled installer:

```sh
node <skill-root>/scripts/install_storybook_template.mjs <target-root> --name "<project-name>" --prefix <token-prefix> [--package-name <package-name>] [--figma-url "<figma-url>"]
```

The installer copies `storybook-template/`, skips local development artifacts such as `.git`, `node_modules`, Storybook build output, and local agent/editor folders, refuses file collisions by default, and runs the template initializer. Use `--dry-run` before installing into a non-empty target. Use `--force` only after explicit approval because it overwrites existing files.

After the template is installed:

1. Record the template decision, target root, project name, token prefix, package name, Figma URL, and installer command in the implementation map.
2. Run `npm install` only when dependencies are missing and the user approves registry access if network is required.
3. Run `npm run check`, `npm run storybook:build`, or the nearest available template checks after dependencies are available.
4. Replace starter `example-card` and example prototype content only as the implementation scope requires; keep them until real components or prototypes exist so catalog checks remain meaningful.
5. Continue with source trace, component planning, token integration, and co-located component/page implementation inside the template workspace.

### 5. Target File Layout

Use folder co-location for new implementation files. Do not create a separate root `stories/` folder for component stories.

- Shared components live in the product's component root, normally `src/components/<ComponentName>/`.
- Each component folder contains framework-native source, styling when separate, and a story using the repo's extensions—for example `.tsx` for React, `.vue` for Vue, `.component.ts` for Angular, or `.svelte` for Svelte. Never treat `.tsx` or a separate `.css` file as a universal default.
- Component stories must be co-located with their component. Avoid `stories/<ComponentName>.stories.*`, `src/stories/<ComponentName>.stories.*`, or other detached component-story targets for new files.
- Component story meta must opt into Storybook Autodocs with `tags: ["autodocs"]` or the repo's exact equivalent. Prefer an explicit meta-level tag for every shared component even when the project also has global docs settings.
- Foundation guides/docs may live in the Storybook docs area, normally `stories/` or `src/stories/`, because they document tokens rather than a single component implementation.
- Page or screen implementations requested by the user live outside the shared component root, normally `src/pages/<PageName>/`.
- Each page folder co-locates its framework-native page/view source, local style file only when the repo uses one, and story using the selected renderer's conventions.
- Pages should compose existing shared components. Do not create page-only primitives inside `pages/` if they belong in the reusable component library.

If the product has an established component or page root, use that root while preserving the co-located folder shape. When editing existing files, avoid moving unrelated stories unless the current component/page needs cleanup for this rollout.

### 6. Figma Export Addon

Auto-install and configure the bundled `@harrychuang/storybook-addon-figma-export` only when its verified baseline requirements are met:

- Storybook exists and is `^10`
- renderer and builder signals are unambiguous, or the user supplies an explicit `--renderer` override
- package manager is detectable
- `.storybook/main.*` has a safe ESM default-export shape; `.storybook/preview.*` is either absent or can be wrapped safely

If the bundled `storybook-template` was installed in this pass, treat its vendored addon package, `.storybook/figma-export.config.ts`, and review server wiring as the addon baseline. Update the template config and source URL mappings as needed; do not run `install_figma_export_addon.mjs` unless the vendored addon package is missing or the template wiring has been removed.

The addon package is vendored in this skill at `assets/figma-export-addon/`, sourced from `harrychuang/storybook-addons#main:packages/figma-export`. Do not install it from GitHub during normal use. On verified React or Vue 3 Vite Story view, its additive visual-comments workflow may persist trusted-LAN/no-auth meeting data and portable reports under `design-system/figma-export-review/`; keep `visualComments` and `commentsDir` project-local, treat screenshots as durable state evidence rather than state replay, and never delete that directory during addon rollback. DOM-to-image does not promise framebuffer-perfect capture for video, WebGL, nested iframes, or cross-origin images without CORS.

Install it with the bundled installer:

```sh
node <skill-root>/scripts/install_figma_export_addon.mjs <product-repo-root>
```

The installer first reads package dependencies and static `.storybook/main.*` references, then reports `renderer`, `builder`, `storybookMajor`, `confidence`, `signals`, and independent `coreExport`, `reviewWorkspace`, `visualComments`, and `persistence` states. Conflicting or unknown renderer evidence fails before package, lockfile, tarball, or Storybook config mutation. `--renderer <react|vue3|angular|svelte|web-components>` resolves a known conflict; it does not override an unsupported builder/version matrix. `--json` emits one machine-readable report on stdout.

After preflight, the installer packs the vendored addon into a versioned tarball at `.storybook/vendor/harrychuang-storybook-addon-figma-export-<version>.tgz`, detects the package manager, and installs it as a local `file:` dependency plus `@storybook/icons` when needed. It generates renderer-neutral `.storybook/figma-export.main.mjs` and `.storybook/figma-export.preview.mjs` wrappers and wraps safe ESM default exports without replacing existing config objects. React + Vite + Storybook 10 and Vue 3 + Vite + Storybook 10 receive full review/server wiring; other supported Storybook 10 combinations receive core export wiring only. Use `--skip-configure` when equivalent project-owned wiring already exists, or `--configure-only` to regenerate wrappers without changing dependencies.

Commit the tarball together with `package.json`, the lockfile, generated wiring, and the modified Storybook config files so teammates and CI install the same version. Re-running upgrades in place; `--check` reports bundled vs installed versions; `--copy-only` only produces the tarball. Older copied-directory installs are migrated to `figma-export-addon-legacy-backup` until verified and deleted. If the bundled asset is missing/incomplete or config cannot be wrapped safely, mark `figma-export-addon` as `blocked`; do not fall back to GitHub or overwrite project-owned wiring.

To ship an addon update through this skill, refresh `assets/figma-export-addon/` with new `dist/` output and a version bump in its `package.json`, then re-run the installer in each product repo. The installer keys upgrades off that version, so never change `dist/` without bumping the version. Read `references/tooling-updates.md` for the full machine/project/Figma update journey and the user-facing reporting checklist.

If Storybook is missing or not version 10, do not auto-install or force the addon; mark `figma-export-addon` as `unavailable` or `blocked` with the reason and continue core Storybook implementation. For Storybook 10, trust the per-capability report: `supported` may be wired, `unsupported` must be omitted, and `unverified` requires a separate validation pass. Do not install, upgrade, or migrate the app solely for this addon. Do not create a full Vue template; validate Vue through the product-native Storybook and the addon's real Vue fixture.

Generate a project-local addon config before editing `.storybook/main.*` or `.storybook/preview.*`:

```sh
node <skill-root>/scripts/generate_figma_export_config.mjs <design-system-package-root> --product-root <product-repo-root> --write
```

Default output is `<product-repo-root>/.storybook/figma-export.config.ts`; keep project-specific URLs, node IDs, class prefixes, theme globals, local graphics, token imports, review API settings, and source fallbacks there or in product code, never inside the bundled addon package.

Read `references/figma-export-review-setup.md` before wiring `.storybook/main.*` or `.storybook/preview.*`, and again if the toolbar, review overlay, Open source action, visual meeting API, or capture flow is missing. Record the vendored tarball path, installed addon version, installed package spec, generated config path, config values, config files, options, and review helper usage in the implementation map.

Read `references/figma-export-readiness.md` before implementing or changing a component/story with the addon installed. The component DOM, CSS, tokens, story metadata, and layout choices should be optimized for editable Figma JSON/importer output while preserving the extracted design. Prefer fixing DOM/CSS/token usage over patching generated export payloads.

### 7. Figma Import Plugin

Confirm the paired Figma importer only when the Figma export addon, bundled template, or another validated exporter produces a compatible payload. The importer consumes export JSON; it does not make an otherwise incompatible renderer export-ready.

The importer is machine-level Figma tooling, not a runtime project dependency. It ships inside this skill at `assets/figma-plugin-code-to-design/`, so on any machine with the skill installed the manifest physically lives in that machine's skill folder (for example `~/.claude/skills/design-system-to-storybook/assets/figma-plugin-code-to-design/manifest.json`); the skills repo checkout is the canonical source when present. A Figma dev plugin re-reads its built runtime on every run, so updating a loaded plugin never needs a re-import — only the files behind the imported manifest path must be refreshed.

Pick the distribution channel by audience:

- **Solo developer machine (skill installed):** load the skill-folder manifest once in Figma Desktop. Agent skill folders are hidden directories, so the Figma file dialog will not show them — press `Cmd+Shift+G` and paste the full path (or `Cmd+Shift+.` to toggle hidden files). Updates arrive by refreshing the skill copy in place (`git pull` in the skills repo checkout, or `install_agent_skill.mjs --force` for installed skill folders) — same path, no re-import.
- **Team with designers (default for shared repos):** commit a repo copy. Designer machines usually have no agent skill folder at all, and hidden paths are hard to select, so the product repo is the distribution channel: designers `git pull` and import a visible, stable manifest path. Also use this for air-gapped or deliberately self-contained workspaces.

Confirm and report the bundled plugin with:

```sh
node <skill-root>/scripts/install_figma_import_plugin.mjs [product-repo-root]
```

The default mode validates the bundled plugin (manifest, built runtime, and that the stamped `PLUGIN_VERSION` matches the plugin `package.json`), prints the plugin version, the skill-folder manifest path with the hidden-folder dialog hint, and the update flow. With a product root it also reports whether a repo copy at `figma/storybook-code-to-design/` matches the bundled plugin, is outdated (refresh with `--copy-to ... --force` and commit), or is absent.

If the bundled `storybook-template` was installed in this pass and `figma/storybook-code-to-design/manifest.json` exists, treat that importer as the template workspace's baseline: the template stays self-contained. Record the manifest path and loading instructions instead of duplicating another importer.

Create or refresh a repo copy with:

```sh
node <skill-root>/scripts/install_figma_import_plugin.mjs <product-repo-root> --copy-to figma/storybook-code-to-design [--dry-run] [--force]
```

Repo copies must include the plugin source and built runtime — `manifest.json`, `ui.html`, `code.ts`, `code.js`, `package.json`, and lock/config files — while skipping `.git`, `node_modules`, and local OS artifacts. Commit the copy together with the rest of the pass. If `code.js` is missing, mark `figma-import-plugin` as `blocked`; the Figma manifest points to that built runtime. Use `--dry-run` before copying into a non-empty target and `--force` only after explicit approval because it overwrites changed plugin files.

Report the setup steps for the chosen channel, which run once per designer machine rather than once per project:

```text
Figma importer plugin (once per machine):
1. Open Figma Desktop.
2. Go to Plugins > Development > Import plugin from manifest...
3. Select the manifest for the chosen channel:
   - repo copy: <product-repo>/figma/storybook-code-to-design/manifest.json
   - skill folder: <skill-root>/assets/figma-plugin-code-to-design/manifest.json
     (hidden folder — press Cmd+Shift+G in the file dialog and paste the path)
4. In Storybook, export JSON, then import it with Storybook Code To Design.
5. To update later: git pull (repo copy) or refresh the skill copy — no re-import needed.
```

Record the plugin version, the chosen distribution channel with its manifest path, machine setup status, and any blocked reason in the implementation map. The plugin version constant and UI badge are stamped from the plugin `package.json` by its `prebuild` script; never hand-edit `PLUGIN_VERSION` or the badge, and never patch the bundled plugin asset for a single product. Read `references/tooling-updates.md` for the full update journey across machine, project, and Figma layers.

### 8. Implementation Map

Before editing code, create or update the implementation map with:

| Design-system item | Source file | Product target | Decision | Status |
|---|---|---|---|---|
| token layer or component | extracted doc/token path | target token/component/story path | reuse, extend, create, defer | planned, done, blocked |

Also record:

- selected app/workspace root; framework, meta-framework, rendering mode, language, package manager, and styling conventions
- Storybook renderer, builder, version or catalog alternative; source/story extensions and framework-native authoring convention
- decision source and evidence, unresolved ambiguity, user approval when asked, and whether migration is `none` or explicitly approved
- Storybook template decision, target root, project name, token prefix, package name, Figma URL, and installer command when template bootstrap is used or declined
- target layout roots for co-located components, foundation docs, and pages
- Figma export addon status and options
- bundled addon tarball path and installed addon version in the product repo
- generated `.storybook/figma-export.config.ts` path and inferred project-specific values
- Figma import plugin version, chosen distribution channel (skill-folder manifest or committed repo copy) with its manifest path, machine setup status, and Figma Desktop loading instructions
- Figma export readiness decisions: root `data-component` / `data-variant` naming, `componentClassPrefixes`, `absoluteFidelityComponents`, embedded SVG mappings, export payload validation results, and any accepted validator warnings
- source trace path and per-component source IDs
- component dependency plan path, recommended order, and current dependency decisions
- per-component state coverage list (`evidenced` / `inferred` / `out-of-scope`) and the user confirmation that approved it
- per-component design parity report path (`reports/design-pixel-align/<component>/`), its open/adjudicated `strict` drift count, the capture's font environment status, and the fidelity mode captured when the toolbar exists
- fidelity toolbar decision when the package records accessibility remaps: installed, declined, or not applicable
- component documentation provenance: extracted, brief-derived, implementation-derived, or needs-review
- original Figma nodes, local images, frontend folders, and rendered routes used for implementation
- token import strategy
- components reused from the product repo
- current batch, when using a queue
- open questions and blocked specs
- capability status for core Storybook, bundled exporter, importer payload path, and template-only Prototype Inspector/Static Flow helpers

### 9. Component Queue And Batch Planning

Use this section when implementing more than one component, when `COMPONENT_INVENTORY.md` contains more than 8 components, or when the user asks to build a full library.

Create or update `design-system/STORYBOOK_COMPONENT_QUEUE.md` when the design-system package lives in the product repo. Otherwise create `docs/design-system/storybook-component-queue.md`. Use `assets/storybook-component-queue-template.md` as the output shape when starting a new queue.

Plan before implementation:

1. Start from `STORYBOOK_COMPONENT_PLAN.md`; do not manually invent the first batch while the planner output is available.
2. Categorize components as foundations, primitives, typographic lockups, form controls, navigation, data display, feedback, overlays, layout, composites, or product-specific patterns.
3. Build a dependency order: tokens first, primitives and typographic lockups before composites, lower-level slots before containers, common variants before rare variants.
4. Rank by dependency depth, reuse/dependent count, source confidence, implementation risk, token readiness, and whether an existing product component can be extended.
5. Mark blocked items explicitly: `needs-extraction`, `needs-source`, `needs-token`, `needs-api-decision`, `needs-existing-component-review`, or `out-of-scope`.
6. Build a **state coverage list** for every component and page in the candidate batch before implementation: enumerate the plausible states (`default`, `loading`, `empty`, `error`, `disabled`, `selected`, plus spec-specific ones — or display modes for display-only components) and mark each one `evidenced` (a source proves it), `inferred` (proposed extrapolation), or `out-of-scope` (will not be built). Record it in the queue's `State Coverage` table.
7. Confirm the state coverage list with the user **before the batch starts**. The scope decision — especially which states will *not* exist — belongs to the user up front, not to the implementation pass after the fact. "No evidence, so not built" is correct behavior, but it must be an agreed decision, not a surprise discovered in the shipped UI.
8. Pick the next batch from adjacent dependencies. Default to 3-5 simple components, 1-2 complex composites, or one cross-cutting foundation pass.
9. Read only the selected batch specs and their direct dependencies. Do not load every component spec into context unless generating or repairing the queue.
10. Finish token integration, co-located component/page code, co-located stories, source URL parameters, queue updates, and verification for each component before starting the next component.

Each batch should produce a clean resumable state:

| Batch | Components | Dependencies | Design sources | Target files | Validation | Status |
|---|---|---|---|---|---|---|
| `B01` | component names | tokens/components needed first | source IDs, Figma nodes, images, or routes | planned product files | checks to run | queued/done/blocked |

### 10. Long-Running Implementation Protocol

Use this protocol for every multi-component implementation pass and every resume after a long run:

1. Re-read `STORYBOOK_COMPONENT_PLAN.md`, `STORYBOOK_COMPONENT_QUEUE.md`, `STORYBOOK_IMPLEMENTATION_MAP.md`, and `git status --short` before editing.
2. Select exactly one next component: the earliest unfinished queue row whose dependencies are `done`, `reused`, or accepted blocked decisions.
3. Mark that component `in-progres

…(truncated)