Imported from justinlietz93/Perfect_Prompts (Prompts/System_Prompts_Leaks/Anthropic/claude-code/skills/design-sync/storybook/SKILL.md). Install upstream with npx skills add justinlietz93/Perfect_Prompts --skill storybook. Copyright stays with the author.

Storybook source shape

Storybook is the fidelity oracle, not the runtime. The converter bundles the package's compiled dist/ into _ds_bundle.js — the same bundle the claude.ai/design agent builds with — and generates each preview by compiling the story source module itself (hooks, fixtures, local helpers — the whole closure comes along), with every component import resolved to that shipped bundle (lib/story-imports.mjs redirects package and relative component imports to window.<Global>). The repo's own storybook render is the ground truth those previews must match: a compare harness screenshots each story in the reference storybook and the matching preview render side by side, and you iterate until they match. Nothing from storybook-static is uploaded, and no story code is ever evaluated at build time — stories run only in the browser, against the real artifact.

Requires React 18+. Playwright + chromium are required for this shape (the compare loop is the verification), not optional.

First sync or re-sync? A re-sync is marked by a config whose projectId and pkg were both in place before this run started — most of this document then doesn't apply; go to §7, where one driver run routes the work and untouched components cost nothing. Everything else takes the full flow (§2 build → §3 self-heal → §4 match → conventions header (base SKILL.md, before upload) → §6 upload), where every component gets verified and graded once — that includes a partial config left by an aborted run, and a pin this run itself just recorded in the base skill's §1. (Only the old design-sync.config.json present? Move it first and commit: mkdir -p .design-sync && mv -n design-sync.config.json .design-sync/config.json, then apply the same test.)

2. Build, then run the converter

1. Build the DS package and its workspace dependencies. The converter bundles dist/ into window.<Global>. Run <pm> run build; in a monorepo use turbo run build --filter=<pkg> or pnpm -F "<pkg>..." build (the trailing ... is required — bare -F <pkg> skips dependencies and you'll see Cannot find module '@scope/tokens'). If package.json module/exports['.'] points at TS source, find the actual built entry and pass it via --entry. Do this before step 2 — storybook often imports sibling packages from their built dist/.

2. Build the reference storybook ONCE into .design-sync/sb-reference/ — NOT under ds-bundle/ (the converter wipes --out on every rebuild, and storybook builds take minutes; the reference must survive the fix loop):

   npx storybook build -c <storybookConfigDir> -o .design-sync/sb-reference

   Run it from the directory whose package.json has the storybook devDependencies — usually the one containing .storybook/; monorepos often have several storybooks, so pick the one covering the package you're syncing. Make -o the repo-root path (e.g. -o "$(git rev-parse --show-toplevel)/.design-sync/sb-reference"): the converter and compare resolve .design-sync/ from the repo root, so a cwd-relative -o in a subpackage puts the reference where nothing will find it. Use npx storybook build directly, not the repo's npm run build-storybook script (wrong output dir). Then check .design-sync/sb-reference/iframe.html exists and is >10KB — index.json alone can exist with a failed build.

   Long builds: background them through your shell tool's background mode only and wait for the completion notification. Never a bare & (untracked — the notification never comes), and never a pgrep -f '<script>' poll loop (it matches its own command line and spins to timeout). Headless / -p sessions: run long commands synchronously instead — there is no task-notification re-invocation there, so a backgrounded run is never resumed.

   .gitignore additions: .design-sync/sb-reference/, .design-sync/learnings/, .design-sync/.cache/, .design-sync/node_modules (fork symlink — recreated per clone), .ds-sync/, ds-bundle/ — build artifact, transient scratch, verification working state, the symlink, staged scripts, regenerated output. Committed: the durable set (the rule in non-storybook §2, same here: everything under .design-sync/ not gitignored — previews/ holds your authored files ONLY; generated story-module wrappers live in .design-sync/.cache/previews/ and regenerate every build; the converter never writes or deletes anything in previews/). Verification state is never committed — cross-machine carry-forward comes from the uploaded project's _ds_sync.json. Rebuild the reference only when stories or the DS source change.

3. Write .design-sync/config.json — only pkg and globalName required. If it already exists, read it first and keep what's there — titleMap, overrides, and provider accumulate fixes from prior syncs. Also Read .design-sync/NOTES.md first — its Re-sync risks section is the prior run's watch-list; re-verify those items instead of assuming carry-forward covers them. The package-shape field table in ../non-storybook/SKILL.md §2.6 applies verbatim; the fields that matter most here:

   Field	Value
   pkg / globalName	pkg required; globalName auto-derived from it when omitted
   shape	"storybook" — pins detection
   storybookStatic	".design-sync/sb-reference" — so re-syncs and compare find the reference without flags
   storybookConfigDir	the .storybook/ dir (monorepos)
   buildCmd	what to re-run before the converter on re-sync
   titleMap	{title: ExportName} when story titles don't match export names; {title: null} excludes a non-visual/internal component from the sync entirely
   overrides	{<Name>: {skip: [storyIds], cardMode: "single"|"column", primaryStory: "<Export>", viewport: "WxH"}} — skip for stories that can't render statically; cardMode: "single" for overlay components (§4a.5, §5), "column" for stories wider than a grid cell (the [GRID_OVERFLOW] row in §3)
   provider	usually unnecessary for previews — .storybook/preview decorators are auto-bundled; set only when that fails. Before §6 upload, distill decorator-provided context into cfg.provider — README/prompt.md wrap guidance is generated from config only (decorator-only wrapping ships a generic note). Setting it also replaces the decorators as the preview wrapper on the next build: scoped-compare a themed component after the switch — an incomplete distillation regresses previews the decorators rendered fine, and carried-forward grades won't catch it. Format: {"component": "ThemeProvider", "props": {…}, "inner": {…}} — a nested chain, outermost first; each component must be a bundle export. Literal props are for small scalars ("theme": "light") and stable snippets. For data that already exists in the repo — a locale JSON, a theme object — prefer {"$ref": "<export>"} backed by a 2-line module added via cfg.extraEntries (e.g. export { default as previewI18n } from '../locales/en.json'): a $ref emits window.<Global>.<export>, so the data lives once in the bundle and re-reads from its source file on every build. Inlining a copy is acceptable for something tiny and stable, but know the cost — a literal duplicates into every card's html and silently rots when the source file changes, so anything sizable or evolving belongs behind a $ref. Path forms for extraEntries: a bare name resolves from node_modules; a repo-owned module needs an explicit .//../ package-relative path (workspace-bounded — the build logs ! extraEntries: … skipped if it escapes).

4. Stage scripts + install converter deps (isolated in .ds-sync/, repo lockfile untouched):

   mkdir -p .ds-sync && cp -r "<skill-base-dir>"/package-build.mjs "<skill-base-dir>"/package-validate.mjs "<skill-base-dir>"/resync.mjs "<skill-base-dir>"/lib "<skill-base-dir>"/storybook "<skill-base-dir>"/non-storybook .ds-sync/
   echo '{"name":"ds-sync-deps","private":true}' > .ds-sync/package.json
   (cd .ds-sync && npm i esbuild ts-morph @types/react playwright && npx playwright install chromium)

   If chromium install fails, npx playwright install-deps chromium first; if the environment can't install chromium, set DS_CHROMIUM_PATH=<system-chromium>.

5. Run the converter, validator, and compare — synchronously, stopping at the first non-zero exit (compare only runs once build + validate are clean — §3). Large DSes (≈100+ components) may need NODE_OPTIONS=--max-old-space-size=<MB> for the build; never pipe the build through head/tail (the pipeline masks the exit code — an OOM looks like success); redirect to a file and read it:

   node .ds-sync/package-build.mjs --config .design-sync/config.json --node-modules <pkg-node-modules> \
     --entry <built-dist-entry> --out ./ds-bundle
   node .ds-sync/package-validate.mjs ./ds-bundle
   node .ds-sync/storybook/compare.mjs --out ./ds-bundle --storybook-static .design-sync/sb-reference \
     --components <solo-phase picks>   # scope the FIRST compare to the §4b solo components

   In a monorepo, --node-modules is the DS package's own node_modules — unless hoisting leaves it sparse (yarn's node-modules linker keeps react only at the repo root): if react/ or react-dom/ is missing inside, pass the repo-root node_modules instead. In the DS's own source repo node_modules/<pkg> doesn't exist, hence --entry. The build logs [ICON_PKG] / [TOKENS_PKG] auto-detections and bundles .storybook/preview decorators as the preview wrapper (preview-decorators.js) so previews get the same provider chain stories do.

   Scope the first compare run: a full capture of a large DS is thousands of chromium navigations — pointless before the solo phase has flushed global issues (each global fix invalidates every capture). The first roster-wide run happens per §4b step 3 — and on a DS over 20 storied components even that is size-gated into §4c's scoped batches, so the only mandatory full-roster run is the §4d receipt, which carries graded work forward instead of recapturing it. For a DS with >100 storied components, also tell the user the expected scale (components × stories) before fan-out and let them narrow scope if they want.

3. Self-heal loop (build + validate)

Fix [TAG] errors → rebuild → re-validate until both exit 0, before starting the compare loop in §4 — there's no point pixel-matching previews while the bundle itself is broken. Shared converter tags ([NO_DIST], [WORKSPACE_SIBLING], [CSS_*], [FONT_*], [TOKENS_MISSING], [DTS_*], [RENDER*], …) behave identically to the package shape — use the table in ../non-storybook/SKILL.md §3. Lines printed as hypothesis: under an error are leads, not instructions: run their verify step first, and if it doesn't confirm, drop the hypothesis and diagnose from the error text itself. Storybook-specific:

Incremental path (base SKILL.md §3) — this is the open-the-channel gate. The first time build + validate both exit 0, open the upload channel before starting §4: the user approves once here, then watches components land as grading proceeds. Nothing uploads until the first graded batch — the shared base files ride with it — and the batch pushes come from §4b/§4c. (Atomic path: nothing uploads until §6.)

4. Match previews to storybook

compare.mjs is a capture harness — it photographs, you grade. It computes no similarity heuristics (pixel/text/font scores mislead whenever framing legitimately differs); the judgment is made from the two true screenshots. Compiled previews capture per story — each story renders alone via ?story=<Export> at the full capture viewport, exactly as storybook frames the reference side — so sibling stories can't interfere (portal stacking, shared radio-group names, focus, container measurement). Two output tiers:

• Transient (under ds-bundle/, wiped by rebuilds): _screenshots/compare/<group>__<Name>.png — sheet with one row per story: the true storybook render | the true preview render, side by side. Sheet images are shrunk to fit; the full-resolution originals are in …/compare/raw/ (…__sb.png / …__ds.png) — Read those when the sheet is too small to judge confidently.
• Campaign state (in .design-sync/.cache/compare/, gitignored): <Name>.grade.json — your verdicts — and <Name>.json — capture facts: story↔cell pairing, shot paths, previewKind, the component's srcSha (story-file fingerprint), spot-check anchors. Reconstructible — absence just means "capture again". The only verdicts the script emits are factual: sb-error (story doesn't render in storybook), unpaired (no preview cell for the story), error (cell threw); every rendered pair is needs-grade.

Compare captures at most 6 stories per component by default — [STORY_CAP] in the log names components with more, and --max-stories <n> raises the cap. The cap is NOT part of the grade contract: raising it just captures the tail stories for incremental grading, and existing verdicts survive. One consequence to know: a capped component that grades fully match/close is verified-by-upload in full on future syncs even though its tail stories were never individually graded — raise the cap when those tail stories carry distinct variants worth verifying. Fan-out subagents must not change it mid-wave (sheets would cover different story sets than the orchestrator's worklist assumed).

State across runs — the first run verifies everything once; after that, one rule: grades follow your sources — the story files, your owned previews, the story set, the preview-affecting config (provider/storyImports/extraEntries/overrides/titleMap), and committed .design-sync/overrides/ forks. Pipeline churn (a skill or toolchain update re-rendering everything) is auto-verified by a sampled [SPOT_CHECK] with grades kept; your edits re-grade only what they touch. Pixel jitter can never churn grades.

• Sources unchanged + fully graded match/close → skipped outright (carried forward): no capture, no re-grade — even when the bundle, styling, storybook, or the converter itself were rebuilt. --force recaptures everything and clears all grades — systemic re-verification, not casual sheet regeneration.
• Sources changed (story edited, .tsx edited, config/fork edited) → recapture, grade cleared, re-grade from the fresh sheet. [STORY_CHANGED] marks stories whose code moved — those are the ones where an OWNED .tsx must be updated (generated previews re-derive automatically); a recapture without [STORY_CHANGED] usually just needs the re-grade.
• [SPOT_CHECK] → re-captures named components without clearing their grades; Read the fresh sheets and confirm they still match the recorded grades. It can arrive driver-triggered after pipeline churn — the normal verification of a skill/toolchain update, not a bug. Divergence remediation scales with the churned set: a couple of components → re-grade just those; widespread → stop, diagnose, then --force a full pass. --spot-check N tunes the full-run random sample (0 disables); --spot-check-components A,B names picks explicitly, honored on scoped runs too (the §7 step-4 audit).
• [REFERENCE_STALE?] → the bundle changed but the reference storybook didn't. If the DS source changed, rebuild .design-sync/sb-reference before grading — a stale reference makes every grade a comparison against the old design.
• A story renders differently every capture (new Date()/Math.random() content) → the fingerprint is the story FILE, so the contract is stable — but the pixels aren't, and grading judges pixels. The frozen capture clock stabilizes date renders; for truly random content, pin values in an owned .tsx or cfg.overrides.<Name>.skip the story with a NOTES.md line.

Captures are stabilized for grading comparability (animations fast-forwarded, reduced motion, frozen clock — both panels show the same settled frame, the same rendered date). This is verification-only: shipped previews are untouched and fully animated.

Grading is done by whoever is working the component — you in the solo phase, each subagent for its own components in fan-out. After each compare run: Read the sheet (and raw PNGs when in doubt), judge each story from the images alone, Write the verdicts to .design-sync/.cache/compare/<Name>.grade.json (campaign-local working state — what makes a verdict durable is the upload: the uploaded _ds_sync.json anchors verified-by-upload skips on every future sync, any machine):

{"stories": {"Default": {"verdict": "match"}, "Compact": {"verdict": "match", "basis": "sibling-trusted"}}}
{"stories": {"Loading": {"verdict": "mismatch", "note": "spinner missing — story uses MSW mock"}}}

(Two components' files: a clean one graded under the sampling rule below — Default is the image-judged primary story, match on a warning-free component, which is what licenses the sibling-trusted entries — and a mismatching one, whose note drives the next fix.)

Rubric — grade what a designer would care about, looking at the two renders:

• match — same content, composition, and styling. Ignore antialiasing fuzz, scrollbar slivers, sub-5px offsets, and framing differences (the storybook canvas and the preview page frame differently — judge the component, not its surroundings).
• close — recognizably the same rendering with a minor delta (slightly different padding, focus ring, placeholder text). close is still a fix target, not an exit: if you can name the delta, you can usually name the knob — keep iterating. Accept close only after an iteration fails to improve it or no actionable cause remains, and the note must then say both what's off and what you tried / why it's not fixable (e.g. "focus ring color differs — storybook applies a global focus addon, not part of the DS").
• mismatch — wrong/missing content, unstyled output, wrong variant, missing icons/images, default fonts. The note must say what differs — it drives the next fix.

When the REFERENCE side is the artifact — storybook gates the story behind UI chrome (a theme/control toggle message) while the preview renders the real component — judge the component render on its own and note the gating; a preview that renders more than the gated reference is not close.

Grade the primary story, trust the rest. Sibling stories of one component run through the same pipeline — same imports, same provider chain, same CSS — so when one of them renders faithfully the rest almost always do too. On a first sync, judge from images the component's primary story only (cfg.overrides.<Name>.primaryStory when set — the same story the single-mode card renders — else the sheet's first story). If it grades match and the component is clean — no sb-error/unpaired/error cells, no [PORTAL?], no [RENDER_BLANK], no blank or size-anomalous shots — write match for the remaining stories with a basis marker, {"verdict": "match", "basis": "sibling-trusted"}, so the record says how each verdict was reached (compare reads only the verdict string). All of a component's verdicts — the image-judged primary plus every sibling-trusted entry — go in its one grade.json Write: trusted siblings cost no image opens and no per-story passes. Grade exhaustively, story by story, when the component has portals/overlays, theme or provider sensitivity, an owned preview, or any warning — and always for the §4b solo set, whose exhaustive grading is what earns the trust in the first place.

Capture photographs every story either way — sampling saves grading attention, not capture time, and the sheets stay available for any deliberate later look (the §7 step-4 carried-grade audit uses the same grades-kept spot-check path). This is the same trust class as [STORY_CAP]'s ungraded tail stories, applied deliberately. Sampling never relaxes [FONT_MISSING] (§4a) — that check is invisible to the compare images either way.

4a. Fix decision tree — global first

Work top-down; a global fix repairs every component at once, a per-component fix repairs one:

1. Most/all components wrong the same way → global, fix in config + full rebuild:
   • Context/provider errors in cells (use<X> must be inside <Provider>) → decorators didn't bundle (§3 ! preview decorator bundle failed rows) → cfg.provider.
   • Everything unstyled / default fonts → cfg.cssEntry (check [CSS_FROM_STORYBOOK] in the build log), cfg.tokensPkg, cfg.extraFonts.
   • [FONT_MISSING] — the compare loop cannot see this one. When neither side ships the font, both panels render the same chromium fallback, so the sheets look "matching" while every claude.ai/design user gets the wrong font — never accept "both sides fall back the same way" as a pass. Resolve per the [FONT_MISSING] row in ../non-storybook/SKILL.md §3; storybook-specific extras: cfg.extraFonts paths are bounded by the git repo enclosing dirname(--node-modules) — sibling typography packages in the monorepo work as-is; only with no .git ancestor does the bound narrow to dirname(--node-modules), and if you add a font the reference lacks, inject the same @font-face into .design-sync/sb-reference/iframe.html so the oracle verifies with the real font on both sides.
   • Icons missing everywhere → cfg.extraEntries (check [ICON_PKG]).
2. One component, unpaired or fallback preview → its .tsx lacks a cell for that story. Previews compile the story MODULE whole (hooks, fixtures, local helpers all included — closures are not a failure mode), so the causes are: pairing failed (storyName override), the wrapper build failed (! preview build failed in the build log), or the module threw at load — check the sheet's (page) error row for the real exception (module-scope calls into a package the stubs don't cover). Open the wrapper (generated: .design-sync/.cache/previews/<Name>.tsx; owned: .design-sync/previews/<Name>.tsx), add/rename the export or drop the offending import — and if it's the generated one, save your fix as .design-sync/previews/<Name>.tsx WITHOUT the first-line marker (an in-place cache edit is preserved on this machine but gitignored — it vanishes on a fresh clone, and it recompiles without ever re-grading; only the owned copy moves the grade contract, and the rebuild warns about edited cache twins). Story imports use the location-independent @ds-stories/<repo-relative path> form, so the file works unchanged from either home.
3. One component, you graded mismatch → wrong props/composition. Read the story source; mirror it in an owned .design-sync/previews/<Name>.tsx (copy the cache wrapper there minus its marker line). That's the only lever for compiled story previews.
4. sb-error → the story doesn't render in storybook either (data-fetching, interaction-driven). Add its id to cfg.overrides.<Name>.skip and note why in NOTES.md.
5. [PORTAL?] / overlay components (Dialog/Tooltip/Toast) → grading is already isolated (per-story capture), but the PRODUCT card renders the whole grid html, so open-overlay stories paint over sibling cells there too. Set cfg.overrides.<Name>.cardMode: "single" — the card renders one story (primaryStory picks it; first export otherwise) full-bleed in a wrapper that contains position:fixed descendants, and declares the grading viewport on the card so the product renders at the size you verified. For stories that are merely too WIDE for a grid cell (data tables, full-width bars — validate flags these as [GRID_OVERFLOW] … wide), use cardMode: "column" instead: every story keeps full card width, nothing is dropped. Targeted-rebuild that component (preview-rebuild.mjs --components <Name>, seconds) — grades carry (cardMode/primaryStory aren't in the grade key or the stamped config slices); only a viewport change re-grades (it's the capture viewport) and needs the full build (it moves the slices).

Rebuild rules — rebuild only what the change can reach. Styling changes (css/fonts/tokens) re-render every preview without moving any grade contract — grades carry forward. Provider, storyImports, extraEntries, and fork edits are part of the grade contract (they change what the preview mounts) — affected grades clear and re-grade on the rebuild.

Mid-campaign — §4c waves still pending — read this table's "full compare.mjs" as eventually, via the batches: the rebuild clears the affected grades either way, the next wave's scoped runs recapture those components, and the §4d receipt is the roster-wide settlement (§4c between-waves step 2). Pay an immediate roster-wide compare only when no waves remain.

--skip-dts skips the per-component type extraction — the slow part of a large-DS build — and emits stub .d.ts bodies, so its validate fails [DTS_STUBBED] by design (the render checks still answer "did the fix work?"); the §4d/§6 gate's validate-exits-0 requirement forces the final build to run without it. Expect stub-build floor cards and README blurbs to look bare — the final build restores them. --skip-dts is for fix-loop iteration only: any build that an upload reads — an incremental batch push (base SKILL.md §3) as much as the §6 close-out — must be a real one, so if .ds-build-meta.json still carries dtsStubbed, rebuild without the flag before pushing (batch pushes upload the on-disk .d.ts).

Batch config edits into one cycle. Before paying a rebuild, sweep every pending sheet verdict and known issue for ALL the config edits they imply (skips, titleMap entries, cardModes) and apply them together — two edits discovered minutes apart must not cost two rebuild+validate+compare cycles.

Compare run died partway (browser crash, OOM): the sheets it captured are valid — grade them first, then re-run; carry-forward scopes the recapture to the gap. Never restart a crashed run with --force (it clears the grades you just earned).

On a large DS, verify the fix is right BEFORE paying the full rebuild: run the targeted loop below on one affected component (or probe its rendered page) first — a wrong guess validated by a full rebuild costs the whole cycle. Intermediate validates can sample: global breakage is systemic by nature, so --render-sample 10 answers "did the fix work?" at a fraction of the cost; the FULL render-check is required at the §4d/§6 upload gate whenever anything render-affecting moved — on an anchored re-sync the §7 driver applies that rule automatically (the tier rule lives there).

The .tsx-only targeted loop:

node .ds-sync/lib/preview-rebuild.mjs --config .design-sync/config.json --node-modules <nm> --out ./ds-bundle --components <Name>
node .ds-sync/storybook/compare.mjs --out ./ds-bundle --storybook-static .design-sync/sb-reference --components <Name>

The targeted loop recompiles previews but does not re-key grade contracts from source: a story-file edit followed by only this loop carries the old grade until the next full build or driver run re-keys it — route story edits through a full build (the driver does that automatically).

4b. Solo phase — one, then a few

Do NOT fan out immediately. Global issues must be flushed into config first, or every subagent rediscovers them.

1. One component. Pick a simple, well-storied one (Button-like: several stories, no portals). Run the §4a loop until you've graded every story match from its images — settle for close only when an iteration stops improving it (rubric above). Every fix becomes a bullet in .design-sync/NOTES.md: symptom → root cause → fix, marked [GENERAL] when it isn't component-specific.
2. Three more, chosen for diversity: one compound/overlay (Dialog/Tabs), one icon- or asset-heavy whose stories load remote images (this is the [ASSETS_BLOCKED] canary — §3's row: a network-sandboxed shell blanks assets on BOTH panels, so grades falsely pass; surfacing it here costs one component's recapture, surfacing it after a roster-wide pass costs the whole pass), one theme/provider-sensitive — and make sure the set spans one text-heavy component (font/typography bugs hide from button-only solos and then invalidate a whole grading wave). Same loop, solo. Incremental path: the solo set, once every story grades match (or close per the rubric's acceptance bar), is the first verified batch — push it (base SKILL.md §3).
3. First roster-wide capture — size-gated on the storied-component count.
   • 20 or fewer: run one full compare.mjs over the roster. Background it through the shell tool's background mode and wait for the completion notification — §2.2's rule, restated here because this is where it gets violated: a foreground sleep-poll blocks the very notification that would wake you, and a pgrep -f loop matches its own command line and spins to timeout. (Headless / -p session: run it synchronously instead — there is no task-notification re-invocation in headless mode, so a backgrounded run is never resumed.) If ≥30% of components fail with the same reason, that's a global issue you missed — fix it in config and re-run before fanning out. Batch every skip and pairing fix the listing shows before rebuilding — each rebuild+compare cycle costs minutes; fixing them one at a time pays that cost per item.
   • More than 20: do NOT run a monolithic full capture. Capture happens inside §4c's batches — each subagent runs one scoped compare.mjs --components <its batch> and grades the sheets it just captured. This buys three things: scoped captures run concurrently (the roster renders in a fraction of a serial sweep's wall-clock); grading starts when the first batch's sheets exist instead of after the last component renders; and when a wave surfaces a [GENERAL] issue, the work at risk is the few batches graded so far, not the whole roster's captures and grades. The ≥30% same-reason check moves with the capture — it becomes the wave-1 learnings review (§4c between-waves). The roster-wide run you do NOT skip is the §4d receipt: by then everything is graded, so it carries components forward instead of recapturing them and costs seconds, not minutes.

4c. Fan-out — parallel subagents

Partition the components that still need work into batches of 5–8 — on a large DS (§4b step 3's >20 gate) that is every component outside the solo set, most with no sheet captured yet; after a small-DS full capture it is the non-matching set. Group related components together (shared providers, shared fixtures — one diagnosis then serves the whole batch). Launch up to 4 subagents per wave (Agent tool, in one message so they run concurrently). Four is also the browser-concurrency cap: each subagent's scoped compare runs its own chromium, and more than ~4 concurrent captures risks launch failures from machine-level contention. For each subagent, fill every {…} in this prompt and paste the current NOTES.md content in (subagents inherit the solo phase's learnings through it):

Fix design-sync previews so they match the repo's own storybook render.
Repo: {REPO_ROOT}. Your components (yours alone): {COMPONENT_LIST}.

Why this matters: this design system is being synced to claude.ai/design, where
a design agent will build real UIs from this exact compiled bundle. The
storybook render is the proof of how each component is supposed to look; a
preview that matches it proves the component arrived intact, and one that
doesn't means every design the agent builds with it will be wrong the same way.

Artifacts per component (read these first):
- {OUT}/_screenshots/compare/<group>__<Name>.png — the true storybook render (left) vs the true preview render (right), per story. Full-res originals in {OUT}/_screenshots/compare/raw/.
- .design-sync/.cache/compare/<Name>.json — pairing facts + shot paths (no similarity scores — your eyes are the judge).
- The preview source (real JSX importing from '{PKG}'): .design-sync/previews/<Name>.tsx when owned, else the generated .design-sync/.cache/previews/<Name>.tsx. Your fixes are written to .design-sync/previews/<Name>.tsx (step 2).
- {OUT}/.stories-map.json — maps components to story ids; find each story's source file via its id in .design-sync/sb-reference/index.json (`importPath`). The story source is the authority on intended props/composition.
- .ds-sync/storybook/SKILL.md §4 — the grading rubric and fix decision tree.

First action, once for the whole batch: if any of your components has no compare sheet yet, run
  node .ds-sync/storybook/compare.mjs --out {OUT} --storybook-static {SB_REF} --components {COMPONENT_LIST}
One scoped run captures every missing sheet in your batch (one browser launch, not one per component); components already graded with unchanged sources skip automatically.

Per component (max 3 iterations):
1. Read the sheet; judge the primary story FROM THE TWO IMAGES (raw PNGs when the sheet is too small) per the §4 sampling rule — exhaustively when the component has portals, theme/provider sensitivity, an owned preview, or any warning; diagnose failures via the decision tree.
2. Copy .design-sync/.cache/previews/<Name>.tsx to .design-sync/previews/<Name>.tsx and DELETE its first-line `// @ds-preview generated …` marker (owned files live in previews/, win over the generated twin, and are durable + committed; an in-place cache edit survives rebuilds on this machine but is gitignored and vanishes on a fresh clone). The `@ds-stories/...` imports work unchanged from the new location. Mirror the story's JSX; inline story-local fixture data.
3. node .ds-sync/lib/preview-rebuild.mjs --config .design-sync/config.json --node-modules {NM} --out {OUT} --components <Name>
4. node .ds-sync/storybook/compare.mjs --out {OUT} --storybook-static {SB_REF} --components <Name>   (your edit changed the component's contract, so this clears its old grade — that's intended)
5. Re-Read the fresh sheet and Write your verdicts to .design-sync/.cache/compare/<Name>.grade.json ({"stories": {"<story>": {"verdict": "match|close|mismatch", "note": "…"}}}); siblings you trust under the §4 sampling rule get {"verdict": "match", "basis": "sibling-trusted"} — written in the same single grade.json Write, no image opens for them. Done when you grade every story match. A close story is still a fix target — if you can name the delta, try the knob for it; accept close only when an iteration didn't improve it or there's no actionable cause, and the note must say what's off AND what you tried. Blocked after 3 iterations → grade honestly (mismatch/close + note), record the exact blocker, move on.

HARD RULES — violating these corrupts other agents' work:
- Edit ONLY .design-sync/previews/{<your components>}.tsx, your components' .design-sync/.cache/compare/*.grade.json files, and .design-sync/learnings/{BATCH_ID}.md.
- NEVER edit .design-sync/config.json, .design-sync/NOTES.md, .ds-sync/, or any other component's files.
- NEVER run package-build.mjs or package-validate.mjs — they rewrite the shared bundle. preview-rebuild.mjs + compare.mjs scoped via --components are your only build commands.
- NEVER write an image-judged grade for images you haven't Read in this iteration. A sibling-trusted verdict must carry "basis": "sibling-trusted" and is allowed only when the image-judged primary story graded match and the component is warning-free (§4 sampling rule).
- A story that doesn't render in storybook either (sb-error) needs cfg.overrides.<Name>.skip; likewise [PORTAL?] needs cfg.overrides.<Name>.cardMode "single". Both are config edits you may NOT make — record them in your learnings file and final report; the orchestrator applies them. NEVER "fix" overlay bleed by neutralizing a story's open state in the .tsx — that destroys the fidelity being verified.
- If the SAME root cause appears in 2+ of your components — or even once when the cause is config-level (provider/css/font/token/import resolution) — STOP on those components: it's global. Write it to your learnings file `[GENERAL]`, report it, do not work around it per-component. Per-component fixes for a global cause are worse than waste: nothing ever machine-deletes `.design-sync/previews/`, so an owned preview you land for it persists and SHADOWS the corrected generated preview on every future build.

Learnings: append to .design-sync/learnings/{BATCH_ID}.md as you go — one bullet per discovery:
`<Component>: <symptom> → <root cause> → <fix>`, prefixed [GENERAL] if it applies beyond that component.

Known repo gotchas (read before starting):
{CURRENT_NOTES_MD_CONTENT}

Final report: per component — match/close/blocked + one-line reason; then any [GENERAL] learnings verbatim.

Between waves (orchestrator) — the learnings fold is mandatory, not optional:

1. Read every .design-sync/learnings/*.md. Promote [GENERAL] bullets into .design-sync/NOTES.md (dedup; keep them terse), then delete each learnings file you've folded. Full compare.mjs runs print [LEARNINGS_UNMERGED] while any learnings file exists, and the §4d driver receipt fails its verdict on the same condition — an overlooked fold can't silently ship.
2. Act on every [GENERAL] learning NOW, before the next wave launches — however few components showed it. A 2-of-24 incidence is still global; a wave dispatched past an un-actioned [GENERAL] re-pays it per component, and those grades wash out when the config fix finally lands. Apply the config fix, delete any owned previews subagents authored to work around that same cause (owned files are never machine-deleted — left in place they shadow the fix), then full rebuild (a real one — step 3's batch push uploads the on-disk files, so never a --skip-dts stub) + validate. Then prove the fix worked with a scoped compare.mjs --components on 1–2 components the issue actually hit — do not run a roster-wide compare mid-campaign. The rebuild already cleared whatever grades the fix's contract change touched; those components simply rejoin the queue, the next wave's scoped runs recapture them, and the §4d receipt settles the whole roster at the end. A roster-wide run mid-campaign that captures a large share of components is a symptom, not a routine step: either captured components were never graded (each batch must grade everything it captures) or a global-slice config edit cleared grades that were already earned — diagnose before paying for the render time.
3. Incremental path: push the wave's components that now meet the §4d grade bar (every story match, or close per the rubric) as a verified batch (base SKILL.md §3) — after steps 1–2, so a global fix from this wave rebuilds them first.
4. Next wave gets the updated NOTES.md content and the still-failing components. After the last wave, repeat step 1 for whatever remains and delete .design-sync/learnings/.

4d. Done criteria + report

• One §7 driver run is the closing receipt — every path. Make the session's FINAL build the driver (resync.mjs); omit --remote when no anchor exists (first syncs, recovered projects) — a full re-verify of an anchored project still passes it. The gate is the driver's verdict: ok: true with verification.pendingGrade empty. Its capture scope is the capturable subset of its worklist — every storied component on a first sync, the changed+added set on a re-sync — with carried-forward grades skipped, so the receipt costs a scoped pass, not a full re-capture (uncapturable members re-ship via the upload partition with nothing to grade; verified-by-upload components are outside the gate). The driver checks .design-sync/learnings/ itself and fails the verdict with [LEARNINGS_UNMERGED] while any unfolded learnings file remains (.compare-report.json aggregation stays full-run-only). On this final run every in-scope component should print carried forward with zero grade cleared — that line IS the proof the next sync will be fast. A cleared grade on a no-change run means a nondeterministic source input (volatile story content) — chase it now; a driver-triggered [SPOT_CHECK] is not that (pipeline churn being auto-verified — confirm the sheets and move on).
• Every IN-SCOPE storied component has a current .grade.json with every story match — or close meeting the rubric's acceptance bar (§4) — or skipped via cfg.overrides.<Name>.skip with a NOTES.md justification. The mechanical check is the driver's verification.pendingGrade: a component listed there has stories without current verdicts and is not done (verified-by-upload components are exempt).
• package-validate.mjs still exits 0 after the final rebuild, with no unresolved [FONT_MISSING] (§4a — the one warning the compare oracle can't see).
• Call DesignSync({method: 'report_validate', counts: {total, bad, thin, variantsIdentical, iterations}}) from the final ds-bundle/.render-check.json (written by package-validate.mjs; iterations = full rebuild passes). On a driver-scoped receipt (§7) that file is absent (skip tier) or covers only the sample — re-run the driver with --render-sample 0 first when this call needs full counts; on a no-change re-sync that uploads nothing, skip the call.
• NOTES.md has a current Re-sync risks section, written now while you still know them: what can silently go stale (data inlined into config, neutralized story exports, owned previews tied to upstream APIs), what was verified only partially (story caps, accepted close rationales), and what the build assumed (toolchain version, CDN-fetched assets). Fixes record what you did; this section tells the next run what to watch.
• Tell the user: N/M components graded match, which are close (and why that's acceptable), which were skipped and why.

5. When the repo is strange — escape hatches

First runs against unusual repos WILL hit things the defaults don't cover. Every heuristic has a committed override — the rule is: never hand-patch generated output; put the fix in the file the next run reads. Map from failure class to knob:

For story handling specifically, the fork points by concern: story-imports.mjs (ALL import-resolution policy for preview compiles — the seam built for per-repo customization; honored by both the full build and preview-rebuild.mjs), source-storybook.mjs (index.json discovery, title→component mapping, story-source resolution + export pairing), preview-gen-storybook.mjs (the wrapper template / composeStories semantics), css-fallback.mjs (CSS/font scraping from the storybook build). Fork the narrowest module that owns the breakage, keep its export signature, and record what the repo does differently in NOTES.md — the next sync inherits all of it. A fork loads from .design-sync/overrides/ while its siblings stay in the staged scripts — repoint the fork's relative imports (./common.mjs etc.) at ../../.ds-sync/lib/. A fork that imports a bare converter dep (esbuild) also needs ln -sfn ../.ds-sync/node_modules .design-sync/node_modules so node can resolve it from the fork's location — once per clone, not once ever: the link is gitignored (node_modules rules) while the committed fork that needs it survives the clone, so recreating it is part of the fresh-clone setup.

The ladder's last rung, for repos genuinely outside the converter's envelope: the upload format is the contract, not the converter (see the base skill). Generate the layout however the repo allows — but package-validate.mjs and the compare/grading gate apply unchanged to whatever you produce. The oracle is never forked.

Everything in that table is a committed file, and §2.3 requires reading the existing config + NOTES.md before doing anything — so run N+1 replays every decision run N made. When you fix something on a strange repo, ask: "which committed file makes this automatic next time?" If the answer is none, that's a NOTES.md entry at minimum — and likely a missing row here worth reporting.

Author the conventions header (before upload)

With previews verified — whether newly authored or carried forward by a re-sync — run the conventions-authoring step in the base SKILL.md ("Author the conventions header") — it distills what you just learned making the previews render into .design-sync/conventions.md, wired via the readmeHeader config key. Ordering matters: author the file and set the key FIRST, then rebuild per the base step's rebuild rule (a fresh DRIVER run on every path — first syncs omit --remote) so the generated README actually carries the header and the §4d receipt describes the build §6 uploads. Then proceed to Upload below.

6. Upload

Which of the two paths applies was decided by the base skill §1 router (pinned-at-run-start → atomic; otherwise empty → incremental, non-empty → atomic):

Incremental path (first sync into an empty project): the plan has been open since this file's §3 gate and verified batches have already landed. After §4d passes and the conventions-header step has run (base SKILL.md — it must precede the upload its rebuild feeds), run the close-out in base SKILL.md §3 — sentinel fence → full content writes → reconciliation deletes → sentinel re-arm → _ds_sync.json last. This section's chunking, hygiene, and stays-local rules apply to those writes; projectId was already recorded in §1; the handoff audit at the end of this section still applies. Skip the rest of this section's sequence — it is the atomic path.

Atomic path (re-sync, or any non-empty target — it may be in active use, so it updates in one pass after everything is verified): everything below. Only after §4d and the conventions-header step (base SKILL.md). DesignSync(finalize_plan) with localDir: "./ds-bundle".

• Writes — everything, always (full re-verifies and re-syncs alike): writes: ["components/**", "tokens/**", "fonts/**", "_vendor/**", "_preview/**", "guidelines/**", "_ds_bundle.js", "_ds_bundle.css", "styles.css", "README.md", "_ds_sync.json", "_ds_needs_recompile"]. Re-uploading unchanged files is idempotent and cheap. An under-scoped writes list silently and permanently desyncs the project — full writes are the safe default.
• Deletes. Anchored re-syncs: verbatim from the diff — copy .sync-diff.json's upload.deletePaths exactly; never hand-derive the list, never pass [] when the diff lists paths. No anchor (a re-adopted or recovered non-empty project being fully re-verified): the diff can't see the project's history, so review its list_files NOW — before finalize_plan — for files this build doesn't produce, and put those reviewed paths in the plan's deletes (a delete not named in the plan is rejected).
• The §4d closing receipt doubles as the upload's source of truth. The session's FINAL build is already a §7 driver run (§4d); bare package-build.mjs runs wipe .sync-diff.json, and the driver's diff stage regenerates it, so deletePaths and upload.any describe the exact bytes you upload — one run is both the verification receipt and the upload manifest, with no separate full compare after it.
• upload.any === false → skip the upload entirely — the project already matches this build. (The handoff audit below still applies.)
• _ds_sync.json is the absolute final write — after all content writes, all deletes, and the sentinel re-arm, in its own write_files call. Uploaded early, a mid-plan failure leaves the anchor vouching for files the project doesn't have, and deterministic rebuilds mean no later sync would repair them.
• What stays local: _sb/** (storybook-static is a reference, never uploaded), dot-prefixed entries (.stories-map.json, .compare-report.json, .ds-build-meta.json, .sb-static/, .sync-diff.json), and _screenshots/. _vendor/ and _preview/ DO upload — the preview cards load React and the compiled previews from them.

If finalize_plan is denied, stop — denial means the session can't approve, not that the arguments were wrong. Tell the user what was denied and ask how they'd like to proceed: try the approval again, or take the validated ds-bundle/ and run the upload interactively themselves.

After plan approval, the upload is a fixed sequence:

1. Sentinel first: DesignSync(write_files, [{path: "_ds_needs_recompile", localPath: "_ds_needs_recompile"}]) — it fences the app's manifest/copy machinery against a half-upload

Truncated - read the full file at https://github.com/justinlietz93/Perfect_Prompts/blob/ee649c7a56c5a002f8d9be0d2ee78eb9168f90a5/Prompts/System_Prompts_Leaks/Anthropic/claude-code/skills/design-sync/storybook/SKILL.md.