Lord1Egypt Storybook source shape
.storybook/ found — the repo's own Storybook is the preview source. The converter ships storybook-static/ as _sb/ and each preview card is an iframe grid of _sb/iframe.html?id=<storyId>, so whatever renders in their Storybook renders here verbatim (their builder's CSS, addons, and providers apply as-is).
Requires React 18+.
2. Build, then run the converter
Build the DS package. The converter bundles
dist/intowindow.<Global>. Run<pm> run build(orturbo run build --filter=<pkg>,pnpm -F <pkg> build,nx build <pkg>in a monorepo). Ifpackage.jsonmodule/exports['.']points at TS source, find the actual built entry and pass it via--entry.Build Storybook directly into
ds-bundle/_sb/.npx storybook build -o ds-bundle/_sb(ornpm run build-storybook -- -o ds-bundle/_sb). Checkds-bundle/_sb/iframe.htmlexists and is >10KB —index.jsonalone can exist with a failed build. Building straight into_sb/means no copy step; the converter strips.map/manager files in-place.Write
design-sync.config.json— onlypkgandglobalNamerequired. Commit it.Field Value pkg/globalNamepackage name and the window.*global — requiredbuildCmdthe DS build command — Claude re-runs this before the converter on re-sync entryexplicit dist entry if package.jsondoesn't point at itextraEntriespackage names/subpaths to merge into window.<Global>(icon package,<pkg>/experimental, etc.)titleMap{title: ExportName}when story titles don't match export namesdocsDir/docsMap/guidelinesGlobper-component docs + design guidelines extraFonts@font-facecss or.woff2files when[FONT_MISSING]firesreplacesextends the adherence-config raw-element map notespath to a notes file — default ./.design-sync/NOTES.mdRun the converter. Stage
lib/+storybook/, install deps (use the repo's own package manager ifnpm i --no-savefails onworkspace:protocol), then:
cp -r "<skill-base-dir>"/lib "<skill-base-dir>"/storybook .
npm i --no-save esbuild ts-morph @types/react playwright && npx playwright install chromium
node storybook/build.mjs --config design-sync.config.json --node-modules ./node_modules \
--pkg-dir . --out ./ds-bundle
node storybook/validate.mjs ./ds-bundle
Run build and validate synchronously (foreground) and check each exit code. If chromium install fails, run npx playwright install-deps chromium first.
3. Self-heal loop
| Tag | Symptom | Fix |
|---|---|---|
[SB_MISSING] |
no iframe.html / index.json |
Run build-storybook. Check PIPESTATUS — the build can exit 0 with a broken output. |
[NO_DIST] / [CONFIG] can't find <pkg>/package.json |
package not built or not found | Run the DS build; pass --pkg-dir / --entry. |
[ZERO_MATCH] |
no story titles matched an export | Check titleMap — titles should resolve to export names. |
[TITLE_UNMAPPED] |
N titles didn't match | Add cfg.titleMap entries. |
[BUNDLE_EXPORT] |
N components aren't functions on window.<Global> |
Check extraEntries for subpath exports; check the dist entry is the full build. |
[BUNDLE_MOUNT] |
first component threw on mount | Usually the provider needs a required prop (theme, locale, etc.). Set cfg.provider with props: {"component": "<Provider>", "props": {"theme": {...}}}. For a chain, nest via "inner": {...}. |
[BUNDLE_STYLE] |
rendered but no styling reached the element | For CSS-in-JS DSes this usually means the provider wrapper isn't passing a theme — set cfg.provider with the theme prop the DS expects. Otherwise check styles.css has @import './_ds_bundle.css' + the storybook-static CSS concat. |
[NO_CHROMIUM] |
playwright not installed | Degraded — .prompt.md has no argTypes table and provider isn't auto-detected. Set cfg.provider manually if the DS needs one. |
[TOKENS_MISSING] |
styles.css has no custom properties |
Informational — CSS-in-JS DSes may have none. |
[IFRAME_LOAD] |
first preview iframe didn't render | _sb/iframe.html failed to load a story. Open it in a browser; check for missing _sb/ assets the strip dropped. |
[SB_SIZE] |
_sb/ >50MB |
Consider excluding dev/playground/kitchen-sink stories from the storybook config's stories glob. |
[PROVIDER_DETECTED] |
<Chain> |
Informational — written to config + README so the design agent wraps output the same way. |
4. Upload
DesignSync(finalize_plan) with localDir: "./ds-bundle", writes: ["components/**", "_sb/**", "_vendor/**", "guidelines/**", "fonts/**", "_ds_bundle.js", "_ds_bundle.css", "styles.css", "README.md", "_ds_needs_recompile"], deletes: []. Dot-prefixed entries stay local.
When done, tell the user: the project URL, component count, _sb/ size, and that validate exited clean. Commit design-sync.config.json and .design-sync/NOTES.md.
What this is not
Not an LLM rewriting components. The previews are the repo's own Storybook verbatim; the bundle is their compiled dist/.