Skip to content

feat: improve design-to-code prompt with component/token/SVG instructions #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
let-sunny merged 5 commits into from
Mar 27, 2026
+60 −9
Merged

feat: improve design-to-code prompt with component/token/SVG instructions #134

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7cb90cd
feat: improve design-to-code prompt with component/token/SVG instruct…
let-sunny Mar 27, 2026
919a81d
fix: address PR review feedback on PROMPT.md
let-sunny Mar 27, 2026
f42e80c
fix: unify image handling to <img> tags instead of background-image
let-sunny Mar 27, 2026
006dedd
fix: remove contradictory hover state from interpretations example
let-sunny Mar 27, 2026
14f1b8f
style: add language identifiers to fenced code blocks
let-sunny Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 60 additions & 9 deletions .claude/skills/design-to-code/PROMPT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,26 +11,73 @@ This prompt is used by all code generation pipelines:

## Conventions
- Semantic HTML elements
- CSS variables for colors
- Flexbox / Grid for layout

## CRITICAL: Do NOT Interpret. Reproduce Exactly.

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
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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 CSS background-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 -->

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
- Do NOT add any value that isn't in the Figma data (no extra padding, margin, gap, transition, hover effect)
- Do NOT change any value from the Figma data (if it says 160px padding, use 160px)
- Do NOT "improve" the design — if something looks wrong, reproduce it anyway
- Do NOT add responsive behavior unless the Figma data explicitly shows it
- Do NOT use min-height or min-width — use exact height and width from the data
- Do NOT use min-height or min-width unless the design tree explicitly includes them — use exact height and width from the data
- Do NOT add overflow: auto or scroll unless specified
- Fonts: load via Google Fonts CDN (`<link>` tag). Do NOT use system font fallbacks as primary — the exact font from the data must render.

### Component Reuse

Nodes annotated with `[component: ComponentName]` are instances of the same design component.

- Define a CSS class for each unique component name (e.g., `[component: Review Card]` → `.review-card { ... }`)
- If the same component appears multiple times, define the shared styles once in the class, then apply it to each instance
- `component-properties:` lines show variant overrides — use them to differentiate instances (e.g., different text content, sizes) while keeping shared styles in the class
- Component name → class name: lowercase, spaces to hyphens (e.g., `Review Card` → `.review-card`)
- Use CSS classes only — no Web Components, no JavaScript templates

### 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`.

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.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

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.

Copy link
Copy Markdown
Owner Author

@let-sunny let-sunny Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 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}`) → emits svg: <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.


**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:
```css
.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`).

### 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)

Comment on lines +68 to +74
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

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).

### Image Assets
- If the design tree shows `background-image: url(images/...)`, use that path directly
- If it shows `background-image: [IMAGE]`, the image asset is unavailable — use a placeholder color
- 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
Comment on lines +76 to +80
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

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.


### If data is missing
When the Figma data does not specify a value, you MUST list it as an interpretation.
Expand All @@ -47,14 +94,18 @@ Output as a code block with filename:
```

### 2. Interpretations
After the code block, output a section listing every value you had to guess or assume:
```
After the code block, list every value you had to guess or assume.
Keep this list to **only genuine ambiguities** — do not list standard defaults (e.g., `body { margin: 0 }` is always expected, not an interpretation).
**Maximum 10 items.** If you have more than 10, keep only the highest-impact ones.

```text
// interpretations:
- Used system font "Inter" fallback: -apple-system, BlinkMacSystemFont (font not embedded in data)
- Set body margin to 0 (not specified in Figma data)
- Used placeholder gray (#CCCCCC) for unavailable image asset
- Chose "Inter" font weight 500 for ambiguous "Medium" style reference
```

If you did not interpret anything, write:
```

```text
// interpretations: none
```
Loading