Initial skill v0.1 — SKILL.md, README.md, CLAUDE.md - #2
Merged
Conversation
Brings figma-to-code-implement skill into existence as a runtime
artifact for the first time, consuming the design captured in PLAN.md.
SKILL.md (310 lines)
- Frontmatter with explicit triggers ("build this Figma frame",
"implement this design", "generate code for [URL]", "make this
component") and explicit mapping-prerequisite in description
- Twelve hard rules — emit-verbs throughout. Rule #2 includes the
trigger box distinguishing implement-intent sentences from
auto-clipboard noise. Rules #11 (no minimal-adjust escape) and #12
(no improvising on gaps) carry the design decisions from PLAN.md
- B1-B8 workflow with cache-first MCP fetch and three-path B4.1
component-lookup (direct → fingerprint via mapping-data → halt)
- Mapping → implement contract: read-only with two narrow propose-
to-user write exceptions (Path C halt routing, Path B fingerprint
match accepted → verify-queue.md row)
- Skill boundary table, slash commands, what-to-read-when,
references
README.md (168 lines)
- Vision + four mechanisms
- For-whom + mapping-prerequisite framing — explicitly not a bare-MCP
alternative
- Two-layer setup table (skill / input / output)
- Installation via symlink, parallel to mapping skill
- Usage: implement command, check command, init-claude-md
- Sister-skill section with bidirectional routing explanation
- What this is not — explicit boundaries
CLAUDE.md (89 lines)
- Edit rules: branch+PR, version bump, mapping/implementation line
policing
- Skills.sh design rationale — what we took (screenshot, metadata
fallback, post-emit visual check, asset discipline) and what we
rejected (minimal-adjust escape, bare MCP, implicit drift, no
verify-queue, no pattern search, no traceability)
- Three rule-text-determining open decisions flagged for resolution
before Fase 2 rule-tuning
- Lessons-learned format ready for first entries
Files comparable in scope and structure to mapping skill (504 / 152
/ 49 lines), with implementation-specific differences (rules
formulated in emit-verbs, B1-B8 instead of A1-A6, mapping-driven
component-lookup instead of mapping-itself).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds SKILL.md (emit-time spec with B1–B8 resolution and hard rules), README.md (usage, setup, and integration), CLAUDE.md (repo-specific contributor rules and open decisions), and DEFERRED-FIXES.md (deferred decisions backlog and resolution process). ChangesFigma-to-Code Implement Skill Documentation
Sequence Diagram(s)sequenceDiagram
participant User as Contributor
participant Implement as figma-to-code-implement
participant Mapping as figma-to-code-mapping
participant MCP as figma-context/<node-id>.json
participant Verify as verify-queue.md
User->>Implement: /figma-to-code-implement (emit) or /check
Implement->>Mapping: read mapping outputs (tokens, components, specs, drifts)
Implement->>MCP: check figma-context/<node-id>.json hash (cache-first)
MCP-->>Implement: cached payload or indicate stale/missing
Implement->>Mapping: fingerprint match / component lookup (A/B/C)
Implement->>Verify: consult verify-queue.md for blockers
Implement->>User: halt+ask if mapping/cache/verify blockers found
Implement->>User: emit PR with traceability (mapping sources + context hash)
User->>Verify: add drift entry when emit surfaces drift
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (3)
SKILL.md (1)
270-275: Consider adding language identifier to code block.The commit message template would benefit from a language identifier for proper syntax highlighting.
💡 Proposed refinement
-``` +```text Implements <Figma-nodeId> per: - docs/components/<spec>.md - docs/tokens.md - figma-context/<node-id>.json (hash: <hash>)</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@SKILL.mdaround lines 270 - 275, Update the triple-backtick code block that
contains "Implements per:" so it includes a language identifier
for proper highlighting (e.g., changetotext); locate the literal block
containing the lines "- docs/components/.md", "- docs/tokens.md", and "-
figma-context/.json (hash: )" and add the language tag
immediately after the opening backticks.</details> </blockquote></details> <details> <summary>CLAUDE.md (1)</summary><blockquote> `9-76`: **Consider adding language identifiers to code blocks.** Two code blocks would benefit from language identifiers for proper rendering. <details> <summary>💡 Proposed refinements</summary> Line 9 (symlink path): ```diff -``` +```text ~/.claude/skills/figma-to-code-implement → ~/Github/figma2code-implement ``` ``` Line 76 (lessons-learned template): ```diff -``` +```text [LESSON — YYYY-MM-DD] [type: correction | confirmation] Situation: <what happened, 1 line> What worked (or did not): <observation, 1-2 lines> Proposal: <change rule or keep, 1 line> ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@CLAUDE.mdaround lines 9 - 76, Two code blocks lack language identifiers;
add a language tag to ensure proper rendering. Update the symlink code block
that contains "~/.claude/skills/figma-to-code-implement →
~/Github/figma2code-implement" to usetext and also addtext to the
lessons-learned template code block that starts with "[LESSON — YYYY-MM-DD]
[type: correction | confirmation]". Ensure both opening fences include the
language identifier (text) and keep the existing block contents unchanged.</details> </blockquote></details> <details> <summary>README.md (1)</summary><blockquote> `85-141`: **Add language identifiers to code blocks.** Multiple code blocks are missing language identifiers, which affects syntax highlighting and accessibility. The blocks at lines 85, 96, 102, 112, 120, 128, and 141 should specify their language. <details> <summary>🎨 Proposed fixes</summary> Line 85 (mapping setup commands): ```diff -``` +```console $ cd /path/to/project $ claude > /figma-to-code-mapping setup ``` Line 96 (implement command): ```diff -``` +```console > /figma-to-code-implement <Figma-link-or-nodeId> ``` ``` Line 102 (natural language examples): ```diff -``` +```text > Build this Figma frame: <URL> > Implement this design: <URL> ``` Line 112 (check command): ```diff -``` +```console > /figma-to-code-implement check <Figma-link-or-nodeId> ``` ``` Line 120 (init command): ```diff -``` +```console > /figma-to-code-implement init-claude-md ``` ``` Line 128 (file tree): ```diff -``` +```text figma2code-implement/ ├── SKILL.md ``` Line 141 (routing flow): ```diff -``` +```text User: build this Figma frame → implement skill triggers ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@README.md` around lines 85 - 141, Several fenced code blocks in README.md lack language identifiers; update the blocks containing the mapping setup commands (the block with "/figma-to-code-mapping setup" and the cd/claude lines) to use "console", the "/figma-to-code-implement <Figma-link-or-nodeId>" and the ">/figma-to-code-implement check <Figma-link-or-nodeId>" and ">/figma-to-code-implement init-claude-md" examples to use "console", the natural-language examples beginning with "Build this Figma frame:" and "Implement this design:" to use "text", the file tree block under "figma2code-implement/" to use "text", and the routing flow block that starts with "User: build this Figma frame" to use "text" so each fenced block (refer to the literal strings /figma-to-code-mapping, /figma-to-code-implement, init-claude-md, the figma2code-implement tree, and the "User: build this Figma frame" routing example) has an appropriate language tag for syntax highlighting and accessibility. ``` </details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Inline comments:
In@CLAUDE.md:
- Line 88: Update the capitalization of the repository path in the README:
replace the substring ~/Github/figma2code-implement/ with
~/GitHub/figma2code-implement/ so the product name is correctly spelled (refer
to the phrase "git pullin your own~/Github/figma2code-implement/" in
CLAUDE.md); optionally scan and change any other occurrences such as the similar
mention on line 10 for consistency.In
@README.md:
- Line 165: The README contains mixed Dutch in the sentence "- Not a
minimal-adjust pixel-fixer. ... (Bewuste afwijking van skills.sh stap 6.)";
replace the Dutch fragment "Bewuste afwijking van skills.sh stap 6" with an
English equivalent such as "Deliberate deviation from skills.sh step 6" so the
entire sentence is consistently in English (edit the README line containing that
parenthetical to use the English phrase).In
@SKILL.md:
- Line 69: In the sentence "(Deviates from skills.sh stap 6 which permits
minimal-adjust to match visuals. We hold the drift-detection line.)" replace the
typo "stap" with "step" so it reads "skills.sh step 6"; update that exact phrase
in the SKILL.md text near "No minimal-adjust escape" to correct the spelling.- Line 69: Remove the parenthetical comparison text "(Deviates from skills.sh
stap 6 which permits minimal-adjust to match visuals. We hold the
drift-detection line.)" from the SKILL.md rule "No minimal-adjust escape." and
instead add that exact parenthetical as a rationale note in CLAUDE.md's Rejected
table entry for the same rule (the "No minimal-adjust escape" / rejected
rationale row) so the skills.sh comparison is documented only in CLAUDE.md for
maintainers.- Around line 306-310: Add a "Lessons learned" section to SKILL.md (before the
References list) following the required format defined in CLAUDE.md (lines
72–83): create a "Lessons learned" header and add one or more entries for
significant lessons using the prescribed bullet/metadata format (date, short
lesson title, context, and actionable takeaway), ensuring each entry references
the related decision or file (e.g., PLAN.md or decision IDs) so the section
satisfies "For every significant lesson-learned, add an entry to SKILL.md §
Lessons learned."
Nitpick comments:
In@CLAUDE.md:
- Around line 9-76: Two code blocks lack language identifiers; add a language
tag to ensure proper rendering. Update the symlink code block that contains
"~/.claude/skills/figma-to-code-implement → ~/Github/figma2code-implement" to
usetext and also addtext to the lessons-learned template code block that
starts with "[LESSON — YYYY-MM-DD] [type: correction | confirmation]". Ensure
both opening fences include the language identifier (text) and keep the existing
block contents unchanged.In
@README.md:
- Around line 85-141: Several fenced code blocks in README.md lack language
identifiers; update the blocks containing the mapping setup commands (the block
with "/figma-to-code-mapping setup" and the cd/claude lines) to use "console",
the "/figma-to-code-implement " and the
">/figma-to-code-implement check " and
">/figma-to-code-implement init-claude-md" examples to use "console", the
natural-language examples beginning with "Build this Figma frame:" and
"Implement this design:" to use "text", the file tree block under
"figma2code-implement/" to use "text", and the routing flow block that starts
with "User: build this Figma frame" to use "text" so each fenced block (refer to
the literal strings /figma-to-code-mapping, /figma-to-code-implement,
init-claude-md, the figma2code-implement tree, and the "User: build this Figma
frame" routing example) has an appropriate language tag for syntax highlighting
and accessibility.In
@SKILL.md:
- Around line 270-275: Update the triple-backtick code block that contains
"Implements per:" so it includes a language identifier for proper
highlighting (e.g., changetotext); locate the literal block containing
the lines "- docs/components/.md", "- docs/tokens.md", and "-
figma-context/.json (hash: )" and add the language tag
immediately after the opening backticks.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro Plus **Run ID**: `b1c1aa8e-a33d-4a5e-8266-34b5fc249000` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 0f2c4c69c32add1f32ccb5ddfc4ee197b7f64e97 and 9b7c5ff33a0e68ae03c9686b6b402f016f4a926e. </details> <details> <summary>📒 Files selected for processing (3)</summary> * `CLAUDE.md` * `README.md` * `SKILL.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| ## Reference | ||
|
|
||
| - The symlink is created by the end user (see `README.md`); for debug sessions you can run `ls -la ~/.claude/skills/figma-to-code-implement` to verify the symlink exists. | ||
| - Test changes: `git pull` in your own `~/Github/figma2code-implement/`, then trigger Claude in a test project with `/figma-to-code-implement check <Figma-link>` on a node that has mapping. |
There was a problem hiding this comment.
Fix capitalization: "Github" → "GitHub".
The official name of the platform uses a capital "H".
✏️ Proposed fix
-- Test changes: `git pull` in your own `~/Github/figma2code-implement/`, then trigger Claude in a test project with `/figma-to-code-implement check <Figma-link>` on a node that has mapping.
+- Test changes: `git pull` in your own `~/GitHub/figma2code-implement/`, then trigger Claude in a test project with `/figma-to-code-implement check <Figma-link>` on a node that has mapping.Note: You may also want to update line 10 for consistency:
-~/.claude/skills/figma-to-code-implement → ~/Github/figma2code-implement
+~/.claude/skills/figma-to-code-implement → ~/GitHub/figma2code-implement🧰 Tools
🪛 LanguageTool
[uncategorized] ~88-~88: The official name of this software platform is spelled with a capital “H”.
Context: ... - Test changes: git pull in your own ~/Github/figma2code-implement/, then trigger Cl...
(GITHUB)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` at line 88, Update the capitalization of the repository path in
the README: replace the substring ~/Github/figma2code-implement/ with
~/GitHub/figma2code-implement/ so the product name is correctly spelled (refer
to the phrase "`git pull` in your own `~/Github/figma2code-implement/`" in
CLAUDE.md); optionally scan and change any other occurrences such as the similar
mention on line 10 for consistency.
|
|
||
| - **Not a mapping tool.** It consumes mapping; it does not produce or update it. Mapping changes happen in `figma-to-code-mapping`. | ||
| - **Not a bare-MCP alternative.** Projects without mapping should use bare Figma MCP or skills.sh — this skill is the strict-mode pipeline on top of mapping. | ||
| - **Not a minimal-adjust pixel-fixer.** This skill refuses inline pixel-fixes to match Figma exactly. Mismatches surface as drift, mapping's drift loop decides resolution. (Bewuste afwijking van skills.sh stap 6.) |
There was a problem hiding this comment.
Remove mixed Dutch from English documentation.
The phrase "Bewuste afwijking" (deliberate deviation) is in Dutch. Should be fully in English for consistency.
🌐 Proposed fix
-- **Not a minimal-adjust pixel-fixer.** This skill refuses inline pixel-fixes to match Figma exactly. Mismatches surface as drift, mapping's drift loop decides resolution. (Bewuste afwijking van skills.sh stap 6.)
+- **Not a minimal-adjust pixel-fixer.** This skill refuses inline pixel-fixes to match Figma exactly. Mismatches surface as drift, mapping's drift loop decides resolution. (Deliberate deviation from skills.sh step 6.)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Not a minimal-adjust pixel-fixer.** This skill refuses inline pixel-fixes to match Figma exactly. Mismatches surface as drift, mapping's drift loop decides resolution. (Bewuste afwijking van skills.sh stap 6.) | |
| - **Not a minimal-adjust pixel-fixer.** This skill refuses inline pixel-fixes to match Figma exactly. Mismatches surface as drift, mapping's drift loop decides resolution. (Deliberate deviation from skills.sh step 6.) |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` at line 165, The README contains mixed Dutch in the sentence "-
**Not a minimal-adjust pixel-fixer.** ... (Bewuste afwijking van skills.sh stap
6.)"; replace the Dutch fragment "Bewuste afwijking van skills.sh stap 6" with
an English equivalent such as "Deliberate deviation from skills.sh step 6" so
the entire sentence is consistently in English (edit the README line containing
that parenthetical to use the English phrase).
Comment on lines
+306
to
+310
|
|
||
| - [`figma-to-code-mapping`](https://github.com/blisdigital/figma2code-mapping) — sister skill that produces the input this skill consumes | ||
| - [PLAN.md](PLAN.md) — full design history with open decisions | ||
| - [README.md](README.md) — installation, usage, prerequisites | ||
| - [CLAUDE.md](CLAUDE.md) — edit rules for this repo + skills.sh design rationale |
There was a problem hiding this comment.
Add the missing "Lessons learned" section.
Line 310 references "Lessons learned" and CLAUDE.md lines 72-83 define the required format, but the section doesn't exist in this file. As per coding guidelines, "For every significant lesson-learned, add an entry to SKILL.md § Lessons learned" with the specified format.
📚 Proposed fix
Add before the References section:
## Drift handling
Implement consumes drift, does not detect. Three drift types from mapping:
- **`value-mismatch`** (mapped in spec drift notes) → surface in B6 check `#7`, ask user how to proceed before emit.
- **`token-mismatch`** (mapped in `drifts.md`) → emit code token (code is source of truth, mapping rule `#2`); surface that Figma diverges.
- **`component-missing`** (mapped in `drifts.md`) → halt, route to user; do not auto-generate (rule `#5`).
No silent resolution at any point. No minimal-adjust pixel-fix (rule `#11`).
+## Lessons learned
+
+Significant operational lessons from applying this skill in practice. Format: `[LESSON — YYYY-MM-DD] [type: correction | confirmation]`, followed by Situation (1 line), What worked/didn't (1-2 lines), Proposal (1 line).
+
+_(No entries yet — v0.1 is initial release.)_
+
## References
- [`figma-to-code-mapping`](https://github.com/blisdigital/figma2code-mapping) — sister skill that produces the input this skill consumes📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - [`figma-to-code-mapping`](https://github.com/blisdigital/figma2code-mapping) — sister skill that produces the input this skill consumes | |
| - [PLAN.md](PLAN.md) — full design history with open decisions | |
| - [README.md](README.md) — installation, usage, prerequisites | |
| - [CLAUDE.md](CLAUDE.md) — edit rules for this repo + skills.sh design rationale | |
| ## Drift handling | |
| Implement consumes drift, does not detect. Three drift types from mapping: | |
| - **`value-mismatch`** (mapped in spec drift notes) → surface in B6 check `#7`, ask user how to proceed before emit. | |
| - **`token-mismatch`** (mapped in `drifts.md`) → emit code token (code is source of truth, mapping rule `#2`); surface that Figma diverges. | |
| - **`component-missing`** (mapped in `drifts.md`) → halt, route to user; do not auto-generate (rule `#5`). | |
| No silent resolution at any point. No minimal-adjust pixel-fix (rule `#11`). | |
| ## Lessons learned | |
| Significant operational lessons from applying this skill in practice. Format: `[LESSON — YYYY-MM-DD] [type: correction | confirmation]`, followed by Situation (1 line), What worked/didn't (1-2 lines), Proposal (1 line). | |
| _(No entries yet — v0.1 is initial release.)_ | |
| ## References | |
| - [`figma-to-code-mapping`](https://github.com/blisdigital/figma2code-mapping) — sister skill that produces the input this skill consumes | |
| - [PLAN.md](PLAN.md) — full design history with open decisions | |
| - [README.md](README.md) — installation, usage, prerequisites | |
| - [CLAUDE.md](CLAUDE.md) — edit rules for this repo + skills.sh design rationale |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@SKILL.md` around lines 306 - 310, Add a "Lessons learned" section to SKILL.md
(before the References list) following the required format defined in CLAUDE.md
(lines 72–83): create a "Lessons learned" header and add one or more entries for
significant lessons using the prescribed bullet/metadata format (date, short
lesson title, context, and actionable takeaway), ensuring each entry references
the related decision or file (e.g., PLAN.md or decision IDs) so the section
satisfies "For every significant lesson-learned, add an entry to SKILL.md §
Lessons learned."
Closes the broken reference from CLAUDE.md ("Tracked in PLAN.md §
Open beslissingen — verplaatsen naar DEFERRED-FIXES.md in Fase 1").
Three-tier system parallel to mapping skill:
- Rule-text-determining (must land before v1.0 rule-tuning): #1
verify-queue scope, #2 rule #2 trigger box list, #3 confirmation
gate before B7 emit
- Implementation-detail (can land during iterations): #4 cache hash
format, #5 --force flag, #6 B5 confidence floor calibration
- Nice-to-have / mapping-repo suggestions: #7 mapping-side
classification methodology, #8 per-spec fingerprint section
Resolved-decisions section documents five design decisions that
landed during this design pass (partial mapping, deviation comment,
fingerprint route, drift-write permissions, skill name) for
traceability.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Empty directory now tracked by git, ready for Fase 3 deliverables: emit-trace.md, pre-emit-checklist.md, post-emit-visual-check.md, claude-md-snippet.md, component-missing-drift.md, pattern-adoption-note.md. Parallel to mapping skill's templates/ structure. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes a dangling reference in § Mapping → implement contract that listed master_verified_via as input for B4.1 but never explained how implement uses it. Now spelled out: when cache has master_verified_via: "instance-id-format", implement recognizes Figma instance-id format I<frame-id>;<master-id> to resolve master via the verified frame without separate master-cache lookup. Matches mapping skill line 153 instance-id verification convention. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mirrors mapping skill's fundamental principle into this skill's Vision section. Previously implicit through rule #11 (no minimal-adjust) — now stated up front so a runtime reader understands the directionality before reading the rules. Phrasing parallels mapping SKILL.md line 26: "Code is source of truth, Figma is intent." Adds the consequence specific to implement: mismatches surface as drift, never as inline pixel-fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two sections borrowed from mapping skill's structure that improve runtime-reader scannability and self-containment: 1. "What this is not" — appended to § Skill boundary. Five explicit non-claims (not mapping, not bare-MCP alternative, not pixel- fixer, not mapping-writer, not code-quality enforcer). Matches mapping SKILL.md "What this is not" passage. README has similar text but a runtime reader who opens only SKILL.md should not need to cross-reference. 2. "Component selection — atomic level" — new section between What-to-read-when and Method B1-B8. Introduces Brad Frost atomic- design taxonomy that rules #5 and B4.1 reference repeatedly but never explain. Without this, a reader unfamiliar with the convention has to leave the file. Matches mapping skill § 196-209. Not done (deliberate): - B3 sub-steps stay as numbered list with bold leaders, not h4 sub-headers. Sub-steps are 1-2 lines each; promoting to headers would fragment without improving scan. - "The documents" overview table from mapping is not duplicated — § Mapping → implement contract already documents which mapping files implement reads. - Drift handling section stays short. For implement, drift is consumption (not detection), so brevity is correct. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
♻️ Duplicate comments (2)
SKILL.md (2)
318-334:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd required
Lessons learnedsection in strict formatThe file ends at
## Referencesand is missing the required bottom## Lessons learnedsection/entries.Proposed section skeleton (before References)
+## Lessons learned + +[LESSON — 2026-05-11] [type: confirmation] +Situation: Initial strict-mode implement skill release aligned to mapping-first contract. +What worked: Hard halt-and-route rules prevented improvisation and preserved mapping/implement boundaries. +Proposal: Keep enforce-only behavior in implement; push all detection/documentation updates to mapping skill. + ## ReferencesAs per coding guidelines: "Add lessons-learned entries at the bottom of
SKILL.mdin strict format: [LESSON — YYYY-MM-DD] [type: correction | confirmation], Situation, What worked, Proposal."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@SKILL.md` around lines 318 - 334, Append a new "## Lessons learned" section at the bottom of SKILL.md following the exact required format: start with "## Lessons learned" and add one or more entries like "[LESSON — YYYY-MM-DD] [type: correction | confirmation], Situation, What worked, Proposal"; include at least one entry referring to the "Drift handling" decisions (mentioning value-mismatch, token-mismatch, component-missing and rules `#2`, `#5`, `#7`, `#11`) describing the situation, what worked (e.g., consumes vs detects, code-as-source-of-truth policy), and a concise proposal for future handling; ensure formatting matches the bracketed header and fields exactly and place the section after the existing "## References".
71-71:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove skills.sh design-rationale references from runtime skill text
Line 71 and Line 94 still leak skills.sh comparisons into
SKILL.md. Keep those comparisons only inCLAUDE.md; runtime users should not see maintainers’ design-rationale references.Proposed minimal edit
-11. **No minimal-adjust escape.** Mismatches between Figma and code surface as drift (rule `#8`), never as inline pixel-fixes. *(Deviates from skills.sh stap 6 which permits minimal-adjust to match visuals. We hold the drift-detection line.)* +11. **No minimal-adjust escape.** Mismatches between Figma and code surface as drift (rule `#8`), never as inline pixel-fixes. ... -- **Not a minimal-adjust pixel-fixer.** Refuses inline pixel-fixes to match Figma exactly. Mismatches surface as drift (rule `#11`, deviates from skills.sh stap 6). +- **Not a minimal-adjust pixel-fixer.** Refuses inline pixel-fixes to match Figma exactly. Mismatches surface as drift (rule `#11`).As per coding guidelines: "Skills.sh references are design-rationale and stay in
CLAUDE.mdonly, not inSKILL.md— runtime users do not need that context."Also applies to: 94-95
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@SKILL.md` at line 71, Remove any references to skills.sh design-rationale from SKILL.md by deleting the comparative sentences that mention "skills.sh" and the rule text like "No minimal-adjust escape. Mismatches between Figma and code surface as drift (rule `#8`), never as inline pixel-fixes." (the same wording appearing near the later block referenced around lines mentioning 94-95). Instead, ensure the runtime-facing SKILL.md only contains the user-facing rule text without maintainers' rationale; if needed, move the removed rationale sentences into CLAUDE.md so the design-rationale remains available to maintainers.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@SKILL.md`:
- Around line 318-334: Append a new "## Lessons learned" section at the bottom
of SKILL.md following the exact required format: start with "## Lessons learned"
and add one or more entries like "[LESSON — YYYY-MM-DD] [type: correction |
confirmation], Situation, What worked, Proposal"; include at least one entry
referring to the "Drift handling" decisions (mentioning value-mismatch,
token-mismatch, component-missing and rules `#2`, `#5`, `#7`, `#11`) describing the
situation, what worked (e.g., consumes vs detects, code-as-source-of-truth
policy), and a concise proposal for future handling; ensure formatting matches
the bracketed header and fields exactly and place the section after the existing
"## References".
- Line 71: Remove any references to skills.sh design-rationale from SKILL.md by
deleting the comparative sentences that mention "skills.sh" and the rule text
like "No minimal-adjust escape. Mismatches between Figma and code surface as
drift (rule `#8`), never as inline pixel-fixes." (the same wording appearing near
the later block referenced around lines mentioning 94-95). Instead, ensure the
runtime-facing SKILL.md only contains the user-facing rule text without
maintainers' rationale; if needed, move the removed rationale sentences into
CLAUDE.md so the design-rationale remains available to maintainers.
The "What this is not" section I added in commit def94db duplicated content already in four other places: - "Not a mapping tool" → intro + Skill boundary table - "Not a bare-MCP alternative" → sentence directly above it - "Not a minimal-adjust pixel-fixer" → rule #11 - "Not a writer of mapping files" → § Mapping → implement contract - "Not a code-quality enforcer" → CLAUDE.md skills.sh-rationale Four of five bullets were dead text. Removing. Kept: "Component selection — atomic level" section. Brad Frost taxonomy (Atom/Molecule/Organism/Template/Page) is referenced in rules #5 and B4.1 but not explained anywhere else in this file. Skills are dependent on each other but separate skills — a reader must be able to understand basic concepts without opening the sister skill for every reference. This is shared-concept context, not duplication of mapping-specific methodology. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@SKILL.md`:
- Line 3: Update the SKILL.md frontmatter version from "0.1" to "0.2" to reflect
the significant refinement in this PR; locate the version field in SKILL.md (the
line currently reading version: "0.1") and change it to version: "0.2" so the
document's patch version advances as required by the guidelines.
- Line 286: The fenced code block starting at the uncovered snippet lacks a
language tag (violates MD040); edit the opening fence (the ``` line) in SKILL.md
so it includes an explicit language identifier such as "text" or "diff" (e.g.,
change ``` to ```text) to satisfy markdownlint and clarify the block's
formatting.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| @@ -0,0 +1,326 @@ | |||
| --- | |||
| name: figma-to-code-implement | |||
| version: "0.1" | |||
There was a problem hiding this comment.
Bump SKILL.md version for this significant refinement.
Line 3 still shows version: "0.1" even though this PR includes meaningful spec refinements; bump to the next patch version to keep skill evolution traceable.
As per coding guidelines: “Bump version in frontmatter on every significant change to SKILL.md: patch version (0.1 → 0.2) for refinements…”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@SKILL.md` at line 3, Update the SKILL.md frontmatter version from "0.1" to
"0.2" to reflect the significant refinement in this PR; locate the version field
in SKILL.md (the line currently reading version: "0.1") and change it to
version: "0.2" so the document's patch version advances as required by the
guidelines.
|
|
||
| Produce code. In the commit message and PR body, document which mapping sources were consumed: | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add a language to the fenced code block.
Line 286 opens a fenced block without a language (```), which violates markdownlint MD040. Use something like ```text for this snippet.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 286-286: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@SKILL.md` at line 286, The fenced code block starting at the uncovered
snippet lacks a language tag (violates MD040); edit the opening fence (the ```
line) in SKILL.md so it includes an explicit language identifier such as "text"
or "diff" (e.g., change ``` to ```text) to satisfy markdownlint and clarify the
block's formatting.
Mapping skill is stack-agnostic; implement must be too. The user's codebase may use Tailwind, Emotion, styled-components, CSS modules, custom CSS, or any combination — and React, Vue, Svelte, etc. The skill should follow what mapping documents, never impose. Three concrete fixes: 1. Vision: add explicit "Stack-agnostic" paragraph as third directional claim alongside "code is source of truth". States that styling stack and framework choice come from mapping's documentation of the codebase, not from this skill. 2. Rule #2 + B4.2 "hoist target": was opinionated "hoist to a page-level CSS variable", which assumes vanilla CSS. Now stack-agnostic: "hoist via the project's styling stack to a higher-scope token-like construct (CSS variable, theme value, Tailwind config token, etc. — whatever the stack uses, per mapping's documentation)". 3. B5 pattern-search heuristic example: was Next.js-only (app/(routes)/.../error.tsx). Now multi-framework example (Next.js error.tsx, Nuxt error.vue, etc.). Untouched (already agnostic): - Rule #3 example "no className alongside Emotion, no Tailwind in an Emotion project" — these are illustrations of the generic "single styling API" principle, not impositions. - Rule #9 lucide-react / @mui/icons-material example — legitimate illustration of the no-new-packages rule; React-named packages but the principle is framework-neutral. - B5 pattern-search heuristic "adopt structural and styling conventions" — already agnostic after prior fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two coordinated parity fixes for matching mapping skill structure: 1. LESSONS.md placeholder file added at root, parallel to mapping skill. Format reference matches mapping. First entries land after Fase 5 dogfood. Keeps lessons out of SKILL.md so the skill itself stays scannable. 2. component-missing-drift.md removed from Fase 3 template plan. Reason: implement never writes to mapping drifts.md itself — at B4.1 Path C halt we route to mapping skill, which writes the drift-row in its own drifts.md template format. Our version would have duplicated mapping's template. Updated Fase 3 plan now has 5 implement-specific workflow templates instead of 6: - emit-trace.md (B7 commit/PR footer) - pre-emit-checklist.md (B6 8-point invulbaar) - post-emit-visual-check.md (B8 7-point invulbaar) - claude-md-snippet.md (additive on mapping snippet) - pattern-adoption-note.md (B5 outcome) All five are implement-unique workflow artifacts, none duplicate mapping's output-schema templates (component-spec, tokens, drifts, verify-queue). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Clarifies what was implicit but never stated: implement skill templates are not the same kind of artifact as mapping skill templates, and the difference has consequences. Mapping templates are output-schemas copied to project repo via /figma-to-code-mapping setup; project then persists them (tokens.md, components.md, per-component specs). Implement templates are workflow-formats Claude reads per run and fills dynamically. Output goes to commit message / PR body / chat, never persisted as project files. One exception: claude-md-snippet is shown by Claude and pasted once by user into project CLAUDE.md. Concrete consequence: implement skill has no setup command, only <link>, check, init-claude-md. PLAN.md content-placement table now spells this out; CLAUDE.md and README.md template references align with this framing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two small additions inspired by Oleksandra Huba's "Dear LLM, here's
how my design system works" (uxdesign.cc, Mar 2026). The article
emphasizes two practices our SKILL.md was implicit about.
1. B7 file-path determination — was silent on where emitted code
lands. Now explicit:
- Existing component file → edit (path from components.md)
- Existing page/route file → emit alongside, framework conventions
from B5 pattern-search
- New file required → halt + ask user (implement does not invent
directory structures)
Traceability block extended with "Emitted to:" line.
2. B4 consumable-bites principle — atomic-ordering already
implicitly batches by stopping at highest mapped level. Now
explicit: when no parent Page/Template exists in code, emit one
organism/molecule per cycle rather than attempting the full
scope. Smaller batches → more reliable B6 validation, easier
review.
Not adopted from the article:
- Three-file structure (design-system-rules.md +
figma-mcp-rules.md + README.md). Their handwritten design-system
rules are dynamic mapping output for us, which is conceptually
stronger than static markdown.
- Components-as-JSON (Anova plugin) — mapping skill's markdown
spec choice is deliberate; JSON would be a mapping-side upgrade.
- Explicit WCAG 2.1 AA framing — already implicit in B6 #5 and
B8 #7 a11y checks.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Previous text suggested "templates have no project-side persistent storage." That holds for 4 of 5 templates, but is wrong for claude-md-snippet: it ends up pasted into project CLAUDE.md via the user and persists there team-wide (committed to git). Now explicit two subgroups across PLAN.md (Fase 3 + content- placement table), CLAUDE.md, and README.md: 1. Ephemeral workflow-formats (4 files: emit-trace, pre-emit-checklist, post-emit-visual-check, pattern-adoption-note) — Claude reads per run, fills dynamically, output lands in commit/PR/chat. Not persisted in project. 2. One-time paste-block (1 file: claude-md-snippet) — Claude shows via init-claude-md, user pastes once into project CLAUDE.md (persistent there as user-action, not as skill-write). In both cases: no /figma-to-code-implement setup command, unlike mapping skill which copies its output-schema templates to project on setup. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 11, 2026
k-rutten
added a commit
that referenced
this pull request
May 11, 2026
Four references to blisdigital/figma2code-mapping#6 were dangling clickable links to a closed (not merged) coordination PR. Mapping v3.3 has since shipped and may already cover what mapping#6 tracked; the linked PR no longer represents current state. Removed clickable links, kept informational context for traceability: 1. README.md sister-skill section — was "see mapping#6". Now points to current mapping SKILL.md on main for routing state. 2. CLAUDE.md reference list — was "Coordination doc: mapping#6". Now points to opening a fresh PR/issue in mapping repo for future coordination, with historical note that mapping#6 closed. 3-4. DEFERRED-FIXES.md items #2 and #4 — were "coupled with mapping coordination edit #N in mapping#6". Now point to current mapping SKILL.md sections (rule #2 trigger box; Cache + hash check) for alignment verification, with historical note. Result: no clickable links to mapping#6 remain. Three mentions of the name remain as historical context, marked "now closed, mapping v3.3+ may already cover". A reviewer landing on these later understands where the reference came from without being misled to a stale PR. Sister-skill maintenance work, no functional change to the skill. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
k-rutten
added a commit
that referenced
this pull request
May 11, 2026
User-resolved three of the rule-text-determining open decisions from DEFERRED-FIXES.md, plus confirmed the stand-alone-skill scope boundary. One open beslissing remains (#3 confirmation gate) — awaiting clearer framing. Changes: 1. SKILL.md frontmatter version 0.2 → 0.3 per CLAUDE.md edit rule #3 (rule-text changes affect emit-time behavior). 2. SKILL.md rule #2 trigger box — added developer-style Figma-MCP invocations: "Use Figma MCP", "Implement this Figma design". Lets devs reach this skill from their normal Figma-MCP workflow, not just from natural-language emit requests. 3. SKILL.md rule #7 — verify-queue scope narrowed to "same per-component spec only". Was abstract "in-scope only"; now concrete and least-deadlocking. Documented why: broader definitions block on every implement run. 4. README.md "What this is not" — stand-alone note expanded. Explicit no-plans for a non-mapping variant; link to skills.sh `figma-implement-design` and bare Figma MCP as the alternatives. Replicating bare-MCP would dilute the strict-mode value proposition (drift discipline, verify-queue, traceability). 5. DEFERRED-FIXES.md — two items moved to Resolved decisions: "Verify-queue scope" and "Rule #2 trigger box exact list". Plus "Stand-alone (no-mapping) variant" added to resolved. Renumbered remaining items 2-6 (cache hash, --force flag, B5 confidence floor, mapping-side classification, per-spec fingerprint section). Still open (1 item): Confirmation gate before B7 emit. User asked for clearer framing — will be re-asked with concrete scenario. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
10 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Brings the
figma-to-code-implementskill into existence as a runtime artifact for the first time, consuming the design captured in PLAN.md (merged via PR #1).Three files, 567 lines total:
SKILL.md(310 lines) — runtime rules + workflow loaded when the skill triggers in a projectREADME.md(168 lines) — developer-facing setup + usage on GitHubCLAUDE.md(89 lines) — edit rules for this repo + skills.sh design rationale + open decisionsAfter this PR merges, a symlink from
~/.claude/skills/figma-to-code-implement/ → ~/Github/figma2code-implementmakes the skill installable.What landed in SKILL.md
verify-queue.md)What landed in README.md
What landed in CLAUDE.md
File parallel with mapping skill
SKILL.mdREADME.mdCLAUDE.mdMapping has more SKILL.md content because it has the full A1-A6 method with detailed A4 sub-steps and the cache/MCP fallback section in full. Implement's SKILL.md is leaner — many sections defer to mapping skill (e.g. asset handling). Both will evolve in tandem.
Open coordination
The coordination PR in mapping repo captures four mapping-side edits needed for naadloze koppeling. Application sequence: this PR merges → mapping coordination edits apply → cross-test the routing loop. See PLAN.md § Koppeling met mapping skill.
Out of scope (planned for later phases)
templates/directory — emit-trace, pre-emit-checklist, post-emit-visual-check, claude-md-snippet, component-missing-drift, pattern-adoption-noteTest plan
ln -s ~/Github/figma2code-implement ~/.claude/skills/figma-to-code-implementand/skillslists the skillSummary by CodeRabbit