feat: improve design-to-code prompt with component/token/SVG instructions#134
feat: improve design-to-code prompt with component/token/SVG instructions#134
Conversation
…ions Add structured guidance for AI to utilize design-tree annotations that were previously ignored, producing reusable code instead of flat HTML: - Component reuse: [component: Name] → shared CSS class - Design tokens: repeated colors → CSS custom properties - SVG vectors: svg: markup → inline <svg> elements - Image assets: clarify background-image handling - Text styles: /* text-style: Name */ → shared typography class - Priority order: pixel-exact > component reuse > CSS variables - Interpretations: tighten to genuine ambiguities only Closes #127 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
📝 WalkthroughWalkthroughUpdated the design-to-code prompt: replaced the CSS-variable convention with a strict Priority Order prioritizing pixel-exact reproduction, tightened min-height/min-width rules, added explicit Component Reuse and Design Token extraction rules, changed SVG and image handling (inline SVGs; use Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
|
Great prompt upgrade overall — this is a strong Step 0 improvement for #119. I reviewed with the experiment criteria in mind and found two important clarification points before lock:
Small additions for experiment stability:
If these are clarified, this PR should be ready for Step 1 schema/prompt lock. |
- Allow min/max when explicitly present in design-tree - Clarify CSS class only (no Web Components) - Enforce background-image policy (no <img> conversion) - Cap interpretations at 10 items Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/design-to-code/PROMPT.md:
- Around line 68-74: The prompt's SVG serialization format in PROMPT.md ("svg:
<svg>...</svg>") doesn't match the actual serializer in design-tree.ts which
pushes "n ${svg}" into styles; update one side so they match. Either change
PROMPT.md to expect "n <svg>...</svg>" or modify the serializer to push "svg:
${svg}" instead of "n ${svg}" (refer to the serializer that pushes 'n ${svg}'
and the PROMPT.md line that expects 'svg: <svg>...</svg>' to locate the code to
change).
- Line 60: The prompt's token annotation description is incorrect — update
PROMPT.md to match the actual serialization used in design-tree.ts (see the
snippet around design-tree.ts:219-224) so token-bound colors are annotated as /*
n{id} */ where {id} is the Figma variable ID (or, alternatively, change the
serializer to emit /* var:... */); ensure the prompt text and any examples
reference the exact /* n{id} */ format and explicitly state that {id} is the
Figma variable ID so the AI will detect token-bound colors correctly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 2aab5c2c-7b39-41a5-bb7d-e5aa303a953a
📒 Files selected for processing (1)
.claude/skills/design-to-code/PROMPT.md
| ``` | ||
| Then use `var(--color-2C2C2C)` instead of inline `#2C2C2C`. | ||
|
|
||
| Naming: if a `/* var:... */` comment is present next to a color value, it means the designer bound this color to a design token — always extract these as CSS variables. |
There was a problem hiding this comment.
Critical: Token annotation format mismatch.
The prompt states that token-bound colors use /* var:... */ comments, but the actual serialization format (shown in context snippet 3 from design-tree.ts:219-224) uses /* n{id} */ where {id} is the Figma variable ID.
This mismatch will cause the AI to miss token-bound colors in the design-tree output.
🔧 Proposed fix
-Naming: if a `/* var:... */` comment is present next to a color value, it means the designer bound this color to a design token — always extract these as CSS variables.
+Naming: if a `/* n{id} */` comment (where `{id}` is a variable identifier) is present next to a color value, it means the designer bound this color to a design token — always extract these as CSS variables.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/skills/design-to-code/PROMPT.md at line 60, The prompt's token
annotation description is incorrect — update PROMPT.md to match the actual
serialization used in design-tree.ts (see the snippet around
design-tree.ts:219-224) so token-bound colors are annotated as /* n{id} */ where
{id} is the Figma variable ID (or, alternatively, change the serializer to emit
/* var:... */); ensure the prompt text and any examples reference the exact /*
n{id} */ format and explicitly state that {id} is the Figma variable ID so the
AI will detect token-bound colors correctly.
There was a problem hiding this comment.
Not an issue — the actual serializer at design-tree.ts:54 emits /* var:${id} */, which matches the prompt's /* var:... */ exactly. Same for SVG at design-tree.ts:376: svg: ${svg} matches svg: <svg>...</svg>.
There was a problem hiding this comment.
🧩 Analysis chain
Let me verify the actual serializer output before acknowledging.
🏁 Script executed:
#!/bin/bash
# Check the serializer lines in design-tree.ts
fd 'design-tree.ts' --exec grep -n 'var:' {} \;
fd 'design-tree.ts' --exec grep -n 'svg:' {} \;
fd 'design-tree.ts' --exec sed -n '45,65p' {} \;
fd 'design-tree.ts' --exec sed -n '370,385p' {} \;
Length of output: 2026
@let-sunny, you're correct — I apologize for the false alarm. The script confirms:
- Line 54:
result.color = `${colorValue} /* var:${f.boundVariables.color.id} */`→ emits/* var:<id> */, which matches the prompt's/* var:... */exactly. - Line 376:
styles.push(`svg: ${svg}`)→ emitssvg: <svg>...</svg>, also matching the prompt correctly.
My original comment was mistaken — there is no format mismatch. The prompt and serializer are aligned.
🧠 Learnings used
Learnt from: CR
Repo: let-sunny/canicode PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-27T05:41:41.561Z
Learning: Design-tree format combines DOM + Style tree merging Figma structure and styling into CSS-ready representation, generated by `generateDesignTree()` in `design-tree.ts`
Learnt from: let-sunny
Repo: let-sunny/canicode PR: 93
File: src/core/rules/rule-config.ts:76-80
Timestamp: 2026-03-26T01:28:57.785Z
Learning: In the let-sunny/canicode repo, `src/core/rules/rule-config.ts` is automatically adjusted by a nightly calibration pipeline. Do NOT suggest adding inline comments to this file for calibration rationale — the change evidence is tracked in PR descriptions, commit messages, and `data/calibration-evidence.json` instead. Inline comments would create clutter as the file is frequently auto-modified.
| ### SVG Vectors | ||
|
|
||
| When a node's style includes `svg: <svg>...</svg>`, render it as an inline `<svg>` element: | ||
| - Use the SVG markup exactly as provided — do not modify paths or attributes | ||
| - Preserve the node's dimensions (`width` and `height` from the node header) | ||
| - The `<svg>` replaces the node's HTML element (do not wrap it in an extra `<div>` unless the node has other styles like background or border) | ||
|
|
There was a problem hiding this comment.
Critical: SVG format string mismatch.
The prompt states the SVG format is svg: <svg>...</svg> (with colon), but the actual serialization format (shown in context snippet 2 from design-tree.ts:251-256) uses n <svg>...</svg> (with space, not colon). The serializer pushes n ${svg} to the styles array.
This mismatch will prevent the AI from recognizing SVG nodes in the design-tree output.
🔧 Proposed fix
-When a node's style includes `svg: <svg>...</svg>`, render it as an inline `<svg>` element:
+When a node's style includes `n <svg>...</svg>` (note: space, not colon), render it as an inline `<svg>` element:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/skills/design-to-code/PROMPT.md around lines 68 - 74, The prompt's
SVG serialization format in PROMPT.md ("svg: <svg>...</svg>") doesn't match the
actual serializer in design-tree.ts which pushes "n ${svg}" into styles; update
one side so they match. Either change PROMPT.md to expect "n <svg>...</svg>" or
modify the serializer to push "svg: ${svg}" instead of "n ${svg}" (refer to the
serializer that pushes 'n ${svg}' and the PROMPT.md line that expects 'svg:
<svg>...</svg>' to locate the code to change).
All images should use <img> with object-fit, not CSS background-image. More semantic, accessible, and consistent regardless of whether the image is content (product photo) or decorative (section background). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/design-to-code/PROMPT.md:
- Around line 103-104: Remove the contradictory interpretation note "Assumed
hover state for buttons (not specified in design data)" from the interpretations
example in PROMPT.md so it no longer conflicts with the Rules ("Do NOT add …
hover effect"). Locate the sentence "Assumed hover state for buttons (not
specified in design data)" and delete it, leaving the rest of the example (e.g.,
"Used placeholder gray (`#CCCCCC`) for unavailable image asset") intact and ensure
no other lines imply adding hover effects unless explicitly specified.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 1cf5bce8-6820-4431-842a-7ca8326af149
📒 Files selected for processing (1)
.claude/skills/design-to-code/PROMPT.md
The Rules section says "Do NOT add hover effect" but the interpretations example listed "Assumed hover state for buttons" — replaced with a non-contradictory example. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/design-to-code/PROMPT.md:
- Around line 101-105: The fenced code block containing the "interpretations:"
comments must include a language identifier to satisfy markdownlint MD040;
update the triple-backtick fence that wraps the two bullet lines ("Used
placeholder gray..." and "Chose 'Inter'...") to use a typed fence such as
```text (i.e., change the opening ``` to ```text) so the block is a typed code
fence while keeping the block content unchanged.
- Around line 76-80: The prompt's image policy now forces converting CSS
background-image to <img> (see the rules referencing "background-image",
"background-size → object-fit", and positioning instructions) which conflicts
with the PR objective to prefer retaining the existing background-image policy;
either revert these lines to restore the original background-image guidance or
explicitly state that Step 0 intentionally changes the policy to prefer <img>
(and update the checklist language to reflect that change), ensuring the wording
around "background-image", "background-size", and the positioning rules is
updated to match the chosen option.
- Line 21: The markdown lint warnings MD022/MD031 are caused by missing blank
lines around headings and fenced code blocks in PROMPT.md (notably around the
"Priority Order" heading and the fenced blocks shown with ```css and ```), so
add a single blank line before and after each affected heading (e.g., "Priority
Order", "Typography", "Image Assets") and ensure fenced code blocks have blank
lines separating them from adjacent text in the ranges referenced (lines around
21, 28, 52-57, 63-65, 75); update the file so every heading and triple-backtick
block is preceded and followed by an empty line to satisfy markdownlint rules.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 841642c3-d72c-4bfb-afab-e07b7602d563
📒 Files selected for processing (1)
.claude/skills/design-to-code/PROMPT.md
| Every pixel in the Figma file is intentional. A designer made each decision deliberately. | ||
| Your job is to translate the Figma data to HTML+CSS — nothing more. | ||
|
|
||
| ### Priority Order |
There was a problem hiding this comment.
Fix markdownlint structure warnings (MD022/MD031).
Headings and fenced code blocks in these ranges are missing required surrounding blank lines per lint output; this will keep docs lint from being clean.
Suggested doc-only formatting patch
### Priority Order
+
1. **Pixel-exact reproduction** — match every dimension, color, spacing, font exactly
2. **Component reuse** — same component annotation → shared CSS class
3. **Design tokens** — repeated values → CSS custom properties
Never sacrifice `#1` for `#2` or `#3`. Reuse and tokens are structural improvements only — they must not change the visual output.
### Rules
@@
### Design Tokens
Extract repeated values into CSS custom properties in `:root { }`.
**Colors**: When the same hex color appears 3+ times, define it as a CSS variable:
+
```css
:root {
--color-2C2C2C: `#2C2C2C`;
--color-0066CC: `#0066CC`;
}Then use var(--color-2C2C2C) instead of inline #2C2C2C.
@@
Typography: When /* text-style: StyleName */ appears in a text node's styles, nodes sharing the same text style name should use a shared CSS class:
+
.text-heading-large { font-family: "Inter"; font-weight: 700; font-size: 32px; line-height: 40px; }Style name → class name: lowercase, spaces/slashes to hyphens, prefix with text- (e.g., Heading / Large → .text-heading-large).
@@
Image Assets
- Always render images as
<img>tags — do NOT use CSSbackground-image
</details>
Also applies to: 28-28, 75-75, 52-57, 63-65
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.0)</summary>
[warning] 21-21: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @.claude/skills/design-to-code/PROMPT.md at line 21, The markdown lint
warnings MD022/MD031 are caused by missing blank lines around headings and
fenced code blocks in PROMPT.md (notably around the "Priority Order" heading and
the fenced blocks shown with css and ), so add a single blank line before
and after each affected heading (e.g., "Priority Order", "Typography", "Image
Assets") and ensure fenced code blocks have blank lines separating them from
adjacent text in the ranges referenced (lines around 21, 28, 52-57, 63-65, 75);
update the file so every heading and triple-backtick block is preceded and
followed by an empty line to satisfy markdownlint rules.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| - Always render images as `<img>` tags — do NOT use CSS `background-image` | ||
| - If the design tree shows `background-image: url(images/...)`, convert to `<img src="images/..." />` | ||
| - Map `background-size` to `object-fit`: `cover` → `object-fit: cover`, `contain` → `object-fit: contain` | ||
| - If the node has children, position the `<img>` behind them (e.g., `position: absolute; z-index: 0` inside a `position: relative` container) | ||
| - If it shows `background-image: [IMAGE]`, the image asset is unavailable — use a placeholder color matching the surrounding design |
There was a problem hiding this comment.
Image policy appears misaligned with the stated review objective.
Lines 76-80 force <img> conversion, but the PR objective notes reviewer preference to keep the existing background-image policy unless the checklist intentionally changes. Please either (a) restore background-image policy here, or (b) explicitly document that Step 0 intentionally switches to <img> and ensure checklist language matches.
Based on learnings from PR objectives comments summary: “align prompt and checklist (preference for current background-image policy unless checklist intentionally changes).”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/skills/design-to-code/PROMPT.md around lines 76 - 80, The prompt's
image policy now forces converting CSS background-image to <img> (see the rules
referencing "background-image", "background-size → object-fit", and positioning
instructions) which conflicts with the PR objective to prefer retaining the
existing background-image policy; either revert these lines to restore the
original background-image guidance or explicitly state that Step 0 intentionally
changes the policy to prefer <img> (and update the checklist language to reflect
that change), ensuring the wording around "background-image", "background-size",
and the positioning rules is updated to match the chosen option.
Satisfy markdownlint MD040 by adding `text` language to interpretation example code blocks. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
♻️ Duplicate comments (2)
.claude/skills/design-to-code/PROMPT.md (2)
76-80:⚠️ Potential issue | 🟠 MajorImage rendering policy is still misaligned with the stated PR objective.
These lines force
<img>conversion, but the objective/reviewer feedback asks to keep the currentbackground-imagepolicy unless the checklist intentionally changes. In this diff, no corresponding checklist alignment is shown, so this remains a blocking mismatch for lock readiness.Suggested patch (restore background-image policy)
-### Image Assets -- Always render images as `<img>` tags — do NOT use CSS `background-image` -- If the design tree shows `background-image: url(images/...)`, convert to `<img src="images/..." />` -- Map `background-size` to `object-fit`: `cover` → `object-fit: cover`, `contain` → `object-fit: contain` -- If the node has children, position the `<img>` behind them (e.g., `position: absolute; z-index: 0` inside a `position: relative` container) -- If it shows `background-image: [IMAGE]`, the image asset is unavailable — use a placeholder color matching the surrounding design +### Image Assets +- Keep image fills as CSS backgrounds when design-tree emits `background-image: url(images/...)` +- Preserve emitted background properties exactly (`background-size`, `background-position`, `background-repeat`) +- If the node has children, keep the same container and background layering semantics from the design data +- If it shows `background-image: [IMAGE]`, the image asset is unavailable — use a placeholder color matching the surrounding design🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.claude/skills/design-to-code/PROMPT.md around lines 76 - 80, Revert the added rules that force converting CSS background-image into <img> tags and restore the previous "preserve background-image" policy: remove or undo the bullets that mandate converting background-image: url(...) to <img src=...>, mapping background-size to object-fit, and positioning images absolutely; instead keep background-image handling as-is unless the checklist is explicitly updated. Ensure the PROMPT.md text about image handling matches the PR objective by restoring the original wording that allows background-image usage and add a note that conversion should only occur if the checklist is intentionally changed.
21-75:⚠️ Potential issue | 🟡 MinorMarkdownlint spacing violations are still present in changed sections.
MD022/MD031 warnings indicate missing blank lines around headings and fenced code blocks in this edited region; this will keep docs lint noisy/failing.
Minimal formatting-only fix
### Priority Order + 1. **Pixel-exact reproduction** — match every dimension, color, spacing, font exactly @@ ### Design Tokens + Extract repeated values into CSS custom properties in `:root { }`. **Colors**: When the same hex color appears 3+ times, define it as a CSS variable: + ```css :root { @@ }
Then use
var(--color-2C2C2C)instead of inline#2C2C2C.
@@
Typography: When/* text-style: StyleName */appears in a text node's styles, nodes sharing the same text style name should use a shared CSS class:
+.text-heading-large { font-family: "Inter"; font-weight: 700; font-size: 32px; line-height: 40px; }</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In @.claude/skills/design-to-code/PROMPT.md around lines 21 - 75, The edited
PROMPT.md has markdownlint MD022/MD031 spacing errors — add a blank line before
and after each heading (e.g., "Priority Order", "Rules", "Component Reuse",
"Design Tokens", "SVG Vectors") and ensure fenced code blocks have an empty line
both above the openingand below the closingin the changed region;
update the section around the example CSS/code fences shown so there's a blank
line before thecss block and a blank line after its closingto satisfy
MD022/MD031 and remove the warnings.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In @.claude/skills/design-to-code/PROMPT.md:
- Around line 76-80: Revert the added rules that force converting CSS
background-image intotags and restore the previous "preserve
background-image" policy: remove or undo the bullets that mandate converting
background-image: url(...) to, mapping background-size to
object-fit, and positioning images absolutely; instead keep background-image
handling as-is unless the checklist is explicitly updated. Ensure the PROMPT.md
text about image handling matches the PR objective by restoring the original
wording that allows background-image usage and add a note that conversion should
only occur if the checklist is intentionally changed.- Around line 21-75: The edited PROMPT.md has markdownlint MD022/MD031 spacing
errors — add a blank line before and after each heading (e.g., "Priority Order",
"Rules", "Component Reuse", "Design Tokens", "SVG Vectors") and ensure fenced
code blocks have an empty line both above the opening ``` and below the closingshown so there's a blank line before the ```css block and a blank line after its closing ``` to satisfy MD022/MD031 and remove the warnings.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID:
d49a9d39-1aa6-4759-8f58-569a0772a252📒 Files selected for processing (1)
.claude/skills/design-to-code/PROMPT.md
1 participant
Summary
Improves
PROMPT.mdso AI utilizes design-tree annotations that were previously ignored, producing reusable code instead of flat HTML with duplicated inline styles.Added sections
[component: ComponentName]→ shared CSS class (.review-card {}):rootCSS custom properties;/* var:... */hints → always extract/* text-style: StyleName */→ shared text class (.text-heading-large {})svg: <svg>...</svg>→ inline<svg>element with preserved dimensionsbody { margin: 0 }excluded)Updated sections
background-size,background-position,background-repeathandlingContext
Closes #127
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit