PMDevSolutions/Aurelius / .claude/skills/export-design-system
export-design-system
VerifiedExport Design System — Publishable Component Library Generator
Purpose
Take generated components and a design-tokens.lock.json and emit a versioned, publishable pnpm workspace:
@scope/design-tokens— framework-agnostic. Ships CSS custom properties, a typed token export, a Tailwind preset, and a JSON snapshot of the lockfile. Anyone (web app, RN app, Storybook, docs site) can consume it.@scope/<framework>-components— framework-specific. Ships compiled components, aThemeProvider+useTheme, and proper peer dependencies. React/Vue/Svelte build with Vite library mode; React Native usestsc(Vite is not part of the RN runtime).
The tokens package is the bridge — every component package depends on it via workspace:^, so updating tokens cascades through every framework target.
When to Use
- After a successful
/build-from-figma,/build-from-canva, or/build-from-screenshotrun, when you want to extract the result as a reusable library rather than ship the full app. - When a design system needs to be published to a private npm registry or installed across multiple consumer apps.
- When migrating from a single-app codebase to a shared component package.
This skill is not part of the autonomous build pipeline — it is invoked on demand via /export-design-system.
Running /export-design-system
$ARGUMENTS holds optional flags for the export script; with none, the framework comes from build-spec.json, the scope from package.json, and the output goes to dist/design-system/.
- Check the preconditions before anything else: a lockfile at
src/styles/design-tokens.lock.jsonordesign-tokens.lock.json, at least one component undersrc/components/(or--components-dir), and a discoverable framework (build-spec.json→outputTarget,package.jsondependencies, or--framework). If one is missing, stop and say which and how to fix it (run a/build-from-*pipeline, pass a flag); never repair the project automatically. - Confirm scope and output once, only when
$ARGUMENTSsets neither: ask for the npm scope (default frompackage.json, else@my-app) and the output directory (defaultdist/design-system) in one question. - Run
./scripts/export-design-system.shwith the resolved flags, forwarding--dry-runand--jsonas given. - Report the framework and scope, the package names (
<scope>/design-tokensand<scope>/<framework>-components), the component count and the output path, then the next steps (cd <output> && pnpm install && pnpm build) and any framework caveat (React Native builds withtsc, not Vite). On a non-zero exit, show the exit code and stderr verbatim and confirm with the user before trying a remedy.
The export only writes files. It does not install, build or publish; publishing is pnpm release inside the generated workspace (changeset publish), which the deploy guard stops for a human.
Inputs
- Required:
design-tokens.lock.json(auto-detected atsrc/styles/design-tokens.lock.jsonordesign-tokens.lock.json)- At least one component file under
src/components/(or override with--components-dir)
- Optional:
build-spec.json(auto-detected at.claude/plans/build-spec.jsonorbuild-spec.json) — read foroutputTarget. If absent, framework is inferred frompackage.jsondeps or supplied via--framework.--scope <name>— npm scope. Defaults to the existingpackage.jsonscope, or@my-app.--output <dir>— where to write the workspace. Default:dist/design-system/.
Outputs
A complete pnpm workspace at <output>/:
<output>/
├── package.json # workspace root with pnpm scripts and changesets
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── .changeset/ # versioning config
├── .npmrc, .gitignore
├── README.md
└── packages/
├── design-tokens/
│ ├── package.json # exports map for ".", "./tokens.css", "./tailwind-preset"
│ ├── tsconfig.json
│ ├── vite.config.ts # vite lib mode
│ ├── README.md
│ └── src/
│ ├── index.ts # barrel
│ ├── tokens.ts # typed token export
│ ├── tokens.css # CSS custom properties
│ ├── tokens.json # raw lockfile snapshot
│ └── tailwind-preset.ts
└── <framework>-components/
├── package.json # peerDeps: react|vue|svelte; depends on design-tokens via workspace:^
├── tsconfig.json
├── vite.config.ts # vite lib mode (or omitted for react-native)
├── README.md
└── src/
├── index.ts # barrel re-exports ThemeProvider + every component
├── components/ # copied from project, tests/stories/types stripped
└── theme/
└── ThemeProvider.{tsx,ts,svelte}
Process
Step 1: Detection
Auto-detect inputs in this order:
lockfile:src/styles/design-tokens.lock.json→design-tokens.lock.jsonbuildSpec:.claude/plans/build-spec.json→build-spec.jsoncomponentsDir:src/components→components→src/lib/componentsframework:buildSpec.outputTarget→package.jsondeps fallback
Refuse with a clear error if lockfile is missing or framework cannot be determined.
Step 2: Workspace scaffolding
Write the workspace root files: package.json, pnpm-workspace.yaml, tsconfig.base.json, .changeset/, .npmrc, .gitignore, README.md.
tsconfig.base.json enables strict, isolatedModules, bundler resolution. Both packages extend it.
Step 3: Tokens package
Generate packages/design-tokens/:
tokens.ts— typedtokensconstant from the lockfile (as constfor inference).tokens.css—:root { --color-...: ...; --space-...; --radius-...; }derived from lockfile.tokens.json— verbatim copy of the lockfile.tailwind-preset.ts— Tailwind preset that consumers extend; pulls colors, spacing, radii, fontFamily from the lockfile.vite.config.ts— Vite lib mode withvite-plugin-dtsfor declaration rollup. Two entries:indexandtailwind-preset.package.json— declaresexportsmap for.,./tokens.css,./tailwind-preset,./tokens.json.sideEffects: ["./dist/tokens.css"].
Step 4: Components package
Generate packages/<framework>-components/:
- Copy components from the source project into
src/components/, excluding*.test.*,*.spec.*,*.stories.*, and*.d.tsfiles (filter by extension matching the framework:.tsx/.tsfor React/RN,.vue/.tsfor Vue,.svelte/.tsfor Svelte). - Generate
theme/ThemeProvider.{tsx,ts,svelte}with framework-idiomatic context API and auseThemehook. - Generate
src/index.tsbarrel that re-exportsThemeProvider,useTheme, and every detected component. - Generate
vite.config.ts(Vite lib mode) for React/Vue/Svelte. Externalize the framework runtime (react,react-dom,react/jsx-runtime;vue;svelte,svelte/internal). - Generate
package.jsonwithpeerDependenciesfor the framework,dependencies: { @scope/design-tokens: workspace:^ }, properexportsmap,sideEffectsincluding CSS. - For
react-native: skipvite.config.ts, usetsc -p tsconfig.jsonfor build, setpeerDependenciesto react + react-native. Add a clear note in the README.
Step 5: Versioning
If --no-changesets is not set, scaffold .changeset/config.json with sensible defaults (commit: false, access: public, baseBranch: main). Workspace root scripts: pnpm changeset, pnpm version, pnpm release.
Step 6: Report
Emit a summary (text or JSON via --json):
- Framework + scope + output path
- Package names
- Component count and files copied
- Total files written
- Next steps:
pnpm install && pnpm build
Invocation
Direct script (the slash command wraps this):
node scripts/export-design-system.js [options]
# or via wrapper:
./scripts/export-design-system.sh [options]
Common flag combinations:
# Use detected outputTarget, default scope, default output dir
./scripts/export-design-system.sh
# Override scope and pick custom output
./scripts/export-design-system.sh --scope @acme --output packages/
# Dry-run to preview
./scripts/export-design-system.sh --dry-run
# Force overwrite of existing output
./scripts/export-design-system.sh --force
# Skip Storybook scaffolding and Changesets
./scripts/export-design-system.sh --no-storybook --no-changesets
# Machine-readable
./scripts/export-design-system.sh --json
Error Recovery
- No
design-tokens.lock.json→ exit 2. Run the relevant build pipeline (/build-from-figma, etc.) first to produce a lockfile. - Cannot detect framework → exit 2. Pass
--framework <react|vue|svelte|react-native>or setoutputTargetinbuild-spec.json. - Output directory exists → exit 1. Either pass
--forceto overwrite, or pick a different--output. - Unsupported framework → exit 3. Only
react,vue,svelte,react-nativeare supported.
Constraints & Gotchas
- Vite lib mode does not apply to React Native. RN apps run on Metro and have their own JSX/runtime concerns. The script falls back to
tsc -p tsconfig.jsonfor RN. Documented in the generated README. - Tokens are a snapshot. Re-running this skill regenerates the token package from the current lockfile. Bump versions via Changesets when the lockfile changes.
- Peer dependencies are conservative. React peer is
^18.0.0 || ^19.0.0. Vue is^3.4.0. Svelte is^5.0.0. Adjust per-package after generation if your consumers require narrower ranges. - The script does not run
pnpm installorpnpm build. It only writes files. The user runs install/build to verify the workspace. - Component file filtering is conservative.
*.test.*,*.spec.*,*.stories.*,*.d.tsare excluded. Co-located CSS modules and helper files with matching framework extensions ARE included.
Re-importing & Round-Trip
The exported tokens.json is a lossless snapshot of the lockfile, so the
export is fully reversible. scripts/import-design-tokens.js (the inverse of this
skill) reconstructs a design-tokens.lock.json from an exported package:
# Reconstruct a lockfile from an exported workspace
./scripts/import-design-tokens.sh --from dist/design-system --out design-tokens.lock.json
# Verify the round-trip (exit 0 if identical to the source, 1 if it drifted)
./scripts/import-design-tokens.sh --from dist/design-system --verify src/styles/design-tokens.lock.json
--from also accepts an installed package or a raw tokens.json path. Only
tokens.json/tokens.ts round-trip; tokens.css and tailwind-preset.ts are
derived, one-way views. See docs/design-system-export/consumers.md for the
interchange contract and how the named consumers ingest the export — Flavian
(WordPress/FSE theme.json) and Nerva (typed tokens in a Hono/Workers
backend). The guarantee is proved by scripts/__tests__/design-system-roundtrip.test.js.
Reference
- Script:
scripts/export-design-system.js - Wrapper:
scripts/export-design-system.sh - Slash command:
/export-design-system - Re-importer:
scripts/import-design-tokens.js/scripts/import-design-tokens.sh - Round-trip test:
scripts/__tests__/design-system-roundtrip.test.js - Consumer contract:
docs/design-system-export/consumers.md - Inputs:
design-tokens.lock.json(fromdesign-token-lockskill),build-spec.json(fromfigma-intake/canva-intake/screenshot-intakeskills)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 318k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |