Skip to content

Commit af22181

Browse files
noisysockscursoragentclaudejonathanKingston
authored
Add agent skills and auto-prettier hooks for Claude Code and Cursor (#2386)
* Add playwright-cli and implement-design skills * Add Claude Code prettier hook, reuse Cursor format.sh for both tools - Add .claude/settings.json with a PostToolUse hook that runs prettier via the existing .cursor/hooks/format.sh script - Update format.sh to extract file_path from both Cursor (.file_path) and Claude Code (.tool_input.file_path) JSON payloads - Whitelist .claude/settings.json in .gitignore Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Jonathan Kingston <jkingston@duckduckgo.com> Co-authored-by: Jonathan Kingston <jonathan@jooped.co.uk>
1 parent 5d8e5c7 commit af22181

17 files changed

Lines changed: 1643 additions & 2 deletions

File tree

‎.agents/skills/implement-design/SKILL.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
---
2+
name: implement-design
3+
description: Translates Figma designs into production-ready code with 1:1 visual fidelity. Use when implementing UI from Figma files, when user mentions "implement design", "generate code", "implement component", "build Figma design", provides Figma URLs, or asks to build components matching Figma specs. Requires Figma MCP server connection.
4+
metadata:
5+
mcp-server: figma
6+
---
7+
8+
# Implement Design
9+
10+
## Overview
11+
12+
This skill provides a structured workflow for translating Figma designs into production-ready code with pixel-perfect accuracy. It ensures consistent integration with the Figma MCP server, proper use of design tokens, and 1:1 visual parity with designs.
13+
14+
## Prerequisites
15+
16+
- Figma MCP server must be connected and accessible
17+
- Before proceeding, verify the Figma MCP server is connected by checking if Figma MCP tools (e.g., `get_design_context`) are available.
18+
- If the tools are not available, the Figma MCP server may not be enabled. Guide the user to enable the Figma MCP server that is included with the plugin. They may need to restart their MCP client afterward.
19+
- User must provide a Figma URL in the format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
20+
- `:fileKey` is the file key
21+
- `1-2` is the node ID (the specific component or frame to implement)
22+
- Project should have an established design system or component library (preferred)
23+
24+
## Required Workflow
25+
26+
**Follow these steps in order. Do not skip steps.**
27+
28+
### Step 1: Get Node ID
29+
30+
#### Option A: Parse from Figma URL
31+
32+
When the user provides a Figma URL, extract the file key and node ID to pass as arguments to MCP tools.
33+
34+
**URL format:** `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
35+
36+
**Extract:**
37+
38+
- **File key:** `:fileKey` (the segment after `/design/`)
39+
- **Node ID:** `1-2` (the value of the `node-id` query parameter)
40+
41+
**Example:**
42+
43+
- URL: `https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15`
44+
- File key: `kL9xQn2VwM8pYrTb4ZcHjF`
45+
- Node ID: `42-15`
46+
47+
### Step 2: Fetch Design Context
48+
49+
Run `get_design_context` with the extracted file key and node ID.
50+
51+
```
52+
get_design_context(fileKey=":fileKey", nodeId="1-2")
53+
```
54+
55+
This provides the structured data including:
56+
57+
- Layout properties (Auto Layout, constraints, sizing)
58+
- Typography specifications
59+
- Color values and design tokens
60+
- Component structure and variants
61+
- Spacing and padding values
62+
63+
**If the response is too large or truncated:**
64+
65+
1. Run `get_metadata(fileKey=":fileKey", nodeId="1-2")` to get the high-level node map
66+
2. Identify the specific child nodes needed from the metadata
67+
3. Fetch individual child nodes with `get_design_context(fileKey=":fileKey", nodeId=":childNodeId")`
68+
69+
### Step 3: Capture Visual Reference
70+
71+
Run `get_screenshot` with the same file key and node ID for a visual reference.
72+
73+
```
74+
get_screenshot(fileKey=":fileKey", nodeId="1-2")
75+
```
76+
77+
This screenshot serves as the source of truth for visual validation. Keep it accessible throughout implementation.
78+
79+
### Step 4: Download Required Assets
80+
81+
Download any assets (images, icons, SVGs) returned by the Figma MCP server.
82+
83+
**IMPORTANT:** Follow these asset rules:
84+
85+
- If the Figma MCP server returns a `localhost` source for an image or SVG, use that source directly
86+
- DO NOT import or add new icon packages - all assets should come from the Figma payload
87+
- DO NOT use or create placeholders if a `localhost` source is provided
88+
- Assets are served through the Figma MCP server's built-in assets endpoint
89+
90+
### Step 5: Translate to Project Conventions
91+
92+
Translate the Figma output into this project's framework, styles, and conventions.
93+
94+
**Key principles:**
95+
96+
- Treat the Figma MCP output (typically React + Tailwind) as a representation of design and behavior, not as final code style
97+
- Replace Tailwind utility classes with the project's preferred utilities or design system tokens
98+
- Reuse existing components (buttons, inputs, typography, icon wrappers) instead of duplicating functionality
99+
- Use the project's color system, typography scale, and spacing tokens consistently
100+
- Respect existing routing, state management, and data-fetch patterns
101+
102+
### Step 6: Achieve 1:1 Visual Parity
103+
104+
Strive for pixel-perfect visual parity with the Figma design.
105+
106+
**Guidelines:**
107+
108+
- Prioritize Figma fidelity to match designs exactly
109+
- Avoid hardcoded values - use design tokens from Figma where available
110+
- When conflicts arise between design system tokens and Figma specs, prefer design system tokens but adjust spacing or sizes minimally to match visuals
111+
- Follow WCAG requirements for accessibility
112+
- Add component documentation as needed
113+
114+
### Step 7: Validate Against Figma
115+
116+
Before marking complete, validate the final UI against the Figma screenshot.
117+
118+
**Validation checklist:**
119+
120+
- [ ] Layout matches (spacing, alignment, sizing)
121+
- [ ] Typography matches (font, size, weight, line height)
122+
- [ ] Colors match exactly
123+
- [ ] Interactive states work as designed (hover, active, disabled)
124+
- [ ] Responsive behavior follows Figma constraints
125+
- [ ] Assets render correctly
126+
- [ ] Accessibility standards met
127+
128+
## Implementation Rules
129+
130+
### Component Organization
131+
132+
- Place UI components in the project's designated design system directory
133+
- Follow the project's component naming conventions
134+
- Avoid inline styles unless truly necessary for dynamic values
135+
136+
### Design System Integration
137+
138+
- ALWAYS use components from the project's design system when possible
139+
- Map Figma design tokens to project design tokens
140+
- When a matching component exists, extend it rather than creating a new one
141+
- Document any new components added to the design system
142+
143+
### Code Quality
144+
145+
- Avoid hardcoded values - extract to constants or design tokens
146+
- Keep components composable and reusable
147+
- Add TypeScript types for component props
148+
- Include JSDoc comments for exported components
149+
150+
## Examples
151+
152+
### Example 1: Implementing a Button Component
153+
154+
User says: "Implement this Figma button component: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"
155+
156+
**Actions:**
157+
158+
1. Parse URL to extract fileKey=`kL9xQn2VwM8pYrTb4ZcHjF` and nodeId=`42-15`
159+
2. Run `get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")`
160+
3. Run `get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")` for visual reference
161+
4. Download any button icons from the assets endpoint
162+
5. Check if project has existing button component
163+
6. If yes, extend it with new variant; if no, create new component using project conventions
164+
7. Map Figma colors to project design tokens (e.g., `primary-500`, `primary-hover`)
165+
8. Validate against screenshot for padding, border radius, typography
166+
167+
**Result:** Button component matching Figma design, integrated with project design system.
168+
169+
### Example 2: Building a Dashboard Layout
170+
171+
User says: "Build this dashboard: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5"
172+
173+
**Actions:**
174+
175+
1. Parse URL to extract fileKey=`pR8mNv5KqXzGwY2JtCfL4D` and nodeId=`10-5`
176+
2. Run `get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` to understand the page structure
177+
3. Identify main sections from metadata (header, sidebar, content area, cards) and their child node IDs
178+
4. Run `get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId")` for each major section
179+
5. Run `get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` for the full page
180+
6. Download all assets (logos, icons, charts)
181+
7. Build layout using project's layout primitives
182+
8. Implement each section using existing components where possible
183+
9. Validate responsive behavior against Figma constraints
184+
185+
**Result:** Complete dashboard matching Figma design with responsive layout.
186+
187+
## Best Practices
188+
189+
### Always Start with Context
190+
191+
Never implement based on assumptions. Always fetch `get_design_context` and `get_screenshot` first.
192+
193+
### Incremental Validation
194+
195+
Validate frequently during implementation, not just at the end. This catches issues early.
196+
197+
### Document Deviations
198+
199+
If you must deviate from the Figma design (e.g., for accessibility or technical constraints), document why in code comments.
200+
201+
### Reuse Over Recreation
202+
203+
Always check for existing components before creating new ones. Consistency across the codebase is more important than exact Figma replication.
204+
205+
### Design System First
206+
207+
When in doubt, prefer the project's design system patterns over literal Figma translation.
208+
209+
## Common Issues and Solutions
210+
211+
### Issue: Figma output is truncated
212+
213+
**Cause:** The design is too complex or has too many nested layers to return in a single response.
214+
**Solution:** Use `get_metadata` to get the node structure, then fetch specific nodes individually with `get_design_context`.
215+
216+
### Issue: Design doesn't match after implementation
217+
218+
**Cause:** Visual discrepancies between the implemented code and the original Figma design.
219+
**Solution:** Compare side-by-side with the screenshot from Step 3. Check spacing, colors, and typography values in the design context data.
220+
221+
### Issue: Assets not loading
222+
223+
**Cause:** The Figma MCP server's assets endpoint is not accessible or the URLs are being modified.
224+
**Solution:** Verify the Figma MCP server's assets endpoint is accessible. The server serves assets at `localhost` URLs. Use these directly without modification.
225+
226+
### Issue: Design token values differ from Figma
227+
228+
**Cause:** The project's design system tokens have different values than those specified in the Figma design.
229+
**Solution:** When project tokens differ from Figma values, prefer project tokens for consistency but adjust spacing/sizing to maintain visual fidelity.
230+
231+
## Understanding Design Implementation
232+
233+
The Figma implementation workflow establishes a reliable process for translating designs to code:
234+
235+
**For designers:** Confidence that implementations will match their designs with pixel-perfect accuracy.
236+
**For developers:** A structured approach that eliminates guesswork and reduces back-and-forth revisions.
237+
**For teams:** Consistent, high-quality implementations that maintain design system integrity.
238+
239+
By following this workflow, you ensure that every Figma design is implemented with the same level of care and attention to detail.
240+
241+
## Additional Resources
242+
243+
- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)
244+
- [Figma MCP Server Tools and Prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)
245+
- [Figma Variables and Design Tokens](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma)

0 commit comments

Comments
 (0)