d2c_

Troubleshooting

Organized per skill. Each entry lists the symptom you'll see, the cause (why the skill is behaving that way), and the fix.

/d2c-init issues

"design-tokens.json uses an older schema version"

  • Symptom: d2c-init (or any other skill) stops and asks for confirmation with a message naming a version number or "none".
  • Cause: .claude/d2c/design-tokens.json was generated by an older d2c-init and is missing the current d2c_schema_version field, or has a number below 1.
  • Fix: Run /d2c-init --force. That regenerates the file with the current schema. If you had manual edits in the old file, diff the regenerated version against the old one and re-apply your edits before the other skills run.

"framework change detected"

  • Symptom: Warning prompt: Framework change detected: {old} → {new}.
  • Cause: d2c-init re-scanned and found a different framework than the one recorded. Usually means the project migrated (e.g. React → Vue) or a new meta-framework config appeared.
  • Fix: Confirm the new framework if the migration is real. The skill then rewrites framework-specific fields and re-runs library detection. If it was a false positive (e.g. stray Nuxt config), delete the trigger file and re-run.

Tokens got categorized as spacing but they're radii

  • Symptom: d2c-audit flags radius values as "spacing hardcoded"; borders section is empty.
  • Cause: d2c-init's Step 2 mis-categorization when the source uses a single scale for both (common with Tailwind before a borderRadius override).
  • Fix: Move the affected keys from spacing into borders in design-tokens.json. Future runs learn from the corrected file.

Nested token values ("value", "css_var")

  • Symptom: d2c-build refuses to emit code, warning about "nested token values (expected flat primitives)".
  • Cause: The extractor or a hand edit wrote { value: "#2563eb", css_var: "--primary" } instead of the flat "#2563eb".
  • Fix: Flatten — set the key equal to the string value only. See token schema.

/d2c-build issues

"threshold clamped to [50|100]"

  • Symptom: Warning on run start; the build uses a different threshold than you passed.
  • Cause: --threshold must be between 50 and 100; out-of-range values are clamped. See skill flags.
  • Fix: Pass a value in-range. Use --threshold 90 to accept 90% match, --threshold 97 for stricter acceptance.

"max rounds clamped to [1|10]"

  • Symptom: Warning on run start; build caps at 10 rounds.
  • Cause: Same shape as threshold clamping; valid range is 1–10.
  • Fix: Pass --max-rounds 6 (or similar) within range.

Build never clears the threshold; halts after max rounds

  • Symptom: Build finishes with "halted at round N" and a regions summary — component doesn't visually match.
  • Cause: Either the design uses primitives your codebase doesn't have (so d2c-build composes an approximation and can't close the gap), or the design tokens don't match the design (colors / spacing in the frame aren't in design-tokens.json).
  • Fix: Check the regions summary; it names which parts diverged. If the diff is a color value, run /d2c-audit to pick up the new value as a suggested token. If a primitive is missing from your components (e.g. no Accordion), either build it in your UI kit first or ask d2c-build to emit a local implementation.

"Schema validation failed" before the build starts

  • Symptom: Pre-flight warning listing schema errors.
  • Cause: design-tokens.json was edited by hand into a shape the schema rejects.
  • Fix: Re-read the error; usually one key moved. Either fix the shape or run /d2c-init --force to regenerate. If the schema file itself can't be found, the skill skips validation — that's silent but safe.

"auto-run /d2c-init" kicks in unexpectedly

  • Symptom: d2c-build starts a token scan before the frame fetch, even though tokens exist.
  • Cause: .claude/d2c/design-tokens.json is missing or unreadable.
  • Fix: Check file permissions; confirm the path. If the file is present but d2c-build can't see it, the pre-flight check is at the wrong CWD — run from the repo root.

/d2c-audit issues

"No hardcoded values found, but visually things still drift"

  • Symptom: Audit score is 100% but the component looks wrong.
  • Cause: d2c-audit checks token adherence, not visual match. Hardcoded values are one class of drift; layout drift, wrong primitive choice, or forgotten state variants are orthogonal and audited elsewhere.
  • Fix: Run /d2c-build on the affected component (or the Figma frame it came from). The build loop does visual verification; audit does token verification.

--fix doesn't touch a value you expected

  • Symptom: Audit reports a hardcoded value as a violation but --fix leaves it in place.
  • Cause: --fix only touches definite matches — values that exactly equal a token. undocumented values (close to a token but not exactly, or no match at all) are reported but not auto-fixed because the "right" replacement is ambiguous.
  • Fix: Either add the value as a new token to design-tokens.json (if it's a design primitive), or hand-edit the source to the nearest existing token.

--dry-run --fix shows changes you don't want

  • Symptom: Preview diff proposes a swap that's technically valid but loses semantic meaning (e.g. #000 → colors.fg when you wanted colors.neutral-900).
  • Cause: Multiple tokens map to the same value; d2c-audit picks the first match.
  • Fix: Pick "Selective" from the prompt and deselect the bad fixes. Then add more specific tokens to design-tokens.json so the ambiguity doesn't recur.

/d2c-guard issues

Guard doesn't fire when I edit a component

  • Symptom: You expected d2c-guard to intercept; it didn't.
  • Cause: Guard activates on component file extensions inside src/ or app/, derived from the framework field in design-tokens.json. Edits outside these dirs, or in files with the wrong extension, don't trigger.
  • Fix: Check the extension mapping in the d2c-guard SKILL.md — e.g. .tsx / .jsx for react/solid, .vue for vue, .svelte for svelte, .component.ts for angular, .astro for astro. If yours is right, confirm design-tokens.json exists (no tokens → no guard).

Guard blocks a legitimate edit

  • Symptom: Guard refuses a save with "hardcoded color" or similar.
  • Cause: Guard enforces the same non-negotiables as the other skills — no raw color/spacing/typography/shadow/radius values in component files.
  • Fix: Add the value to design-tokens.json as a new token (if it's a design primitive), or use an existing token. If the value is temporary (prototype), add a comment explaining why — guard respects opt-out comments the project-level conventions specify.

Guard won't substitute my preferred library

  • Symptom: Guard refuses to suggest a library that's installed and, in your view, appropriate.
  • Cause: Only libraries in preferred_libraries.<category>.selected are allowed. Installed but unselected libraries are treated as noise.
  • Fix: Either explicitly select the library in design-tokens.json (run /d2c-init and re-answer the library prompt), or stop using it and uninstall.

General

"I think the skills are reading a stale design-tokens.json"

  • Fix: Skills read the file on every invocation; there's no cache on the skill side. If a change doesn't seem to stick, check you're editing the same file the skill reads — it's always .claude/d2c/design-tokens.json at the project root, not under ~/.claude/.

"The docs site shows a cached pill next to View source"

  • Symptom: A reference or skill page shows cached inside the "View source" link.
  • Cause: The docs site couldn't reach GitHub at request time, so it served the last committed snapshot from public/snapshots/.
  • Fix: Nothing on your side. The pill is advisory — the content is correct as of the last nightly snapshot refresh. When GitHub is reachable again, the pill disappears on the next page load.

Still stuck?

File an issue. Attach your design-tokens.json (redacting API keys) and the full skill output — the non-negotiables and the clamping warnings are written into the output for exactly this reason.