From a80c052551bcc40c7260b1e30fca685d0e1fe04d Mon Sep 17 00:00:00 2001 From: Ashwin Mathews Date: Thu, 12 Mar 2026 09:19:04 -0700 Subject: [PATCH 1/5] add figma skills --- .../skills/code-connect-components/SKILL.md | 332 +++++++++++ .../create-design-system-rules/SKILL.md | 541 ++++++++++++++++++ .../figma/skills/implement-design/SKILL.md | 245 ++++++++ 3 files changed, 1118 insertions(+) create mode 100644 plugins/figma/skills/code-connect-components/SKILL.md create mode 100644 plugins/figma/skills/create-design-system-rules/SKILL.md create mode 100644 plugins/figma/skills/implement-design/SKILL.md diff --git a/plugins/figma/skills/code-connect-components/SKILL.md b/plugins/figma/skills/code-connect-components/SKILL.md new file mode 100644 index 00000000..949169a0 --- /dev/null +++ b/plugins/figma/skills/code-connect-components/SKILL.md @@ -0,0 +1,332 @@ +--- +name: code-connect-components +description: Connects Figma design components to code components using Code Connect. Use when user says "code connect", "connect this component to code", "connect Figma to code", "map this component", "link component to code", "create code connect mapping", "add code connect", "connect design to code", or wants to establish mappings between Figma designs and code implementations. Requires Figma MCP server connection. +metadata: + mcp-server: figma +--- + +# Code Connect Components + +## Overview + +This skill helps you connect Figma design components to their corresponding code implementations using Figma's Code Connect feature. It analyzes the Figma design structure, searches your codebase for matching components, and establishes mappings that maintain design-code consistency. + +## Prerequisites + +- Figma MCP server must be connected and accessible + - Before proceeding, verify the Figma MCP server is connected by checking if Figma MCP tools (e.g., `get_code_connect_suggestions`) are available. + - 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. +- User must provide a Figma URL with node ID: `https://figma.com/design/:fileKey/:fileName?node-id=1-2` + - **IMPORTANT:** The Figma URL must include the `node-id` parameter. Code Connect mapping will fail without it. +- **IMPORTANT:** The Figma component must be published to a team library. Code Connect only works with published components or component sets. +- **IMPORTANT:** Code Connect is only available on Organization and Enterprise plans. +- Access to the project codebase for component scanning + +## Required Workflow + +**Follow these steps in order. Do not skip steps.** + +### Step 1: Get Code Connect Suggestions + +Call `get_code_connect_suggestions` to identify all unmapped components in a single operation. This tool automatically: + +- Fetches component info from the Figma scenegraph +- Identifies published components in the selection +- Checks existing Code Connect mappings and filters out already-connected components +- Returns component names, properties, and thumbnail images for each unmapped component + +Parse the URL to extract `fileKey` and `nodeId`, then call `get_code_connect_suggestions`. + +**IMPORTANT:** When extracting the node ID from a Figma URL, convert the format: + +- URL format uses hyphens: `node-id=1-2` +- Tool expects colons: `nodeId=1:2` + +**Parse the Figma URL:** + +- URL format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2` +- Extract file key: `:fileKey` (segment after `/design/`) +- Extract node ID: `1-2` from URL, then convert to `1:2` for the tool + +``` +get_code_connect_suggestions(fileKey=":fileKey", nodeId="1:2") +``` + +**Handle the response:** + +- If the tool returns **"No published components found in this selection"** → inform the user and stop. The components may need to be published to a team library first. +- If the tool returns **"All component instances in this selection are already connected to code via Code Connect"** → inform the user that everything is already mapped. +- Otherwise, the response contains a list of unmapped components, each with: + - Component name + - Node ID + - Component properties (JSON with prop names and values) + - A thumbnail image of the component (for visual inspection) + +### Step 2: Scan Codebase for Matching Components + +For each unmapped component returned by `get_code_connect_suggestions`, search the codebase for a matching code component. + +**What to look for:** + +- Component names that match or are similar to the Figma component name +- Component structure that aligns with the Figma hierarchy +- Props that correspond to Figma properties (variants, text, styles) +- Files in typical component directories (`src/components/`, `components/`, `ui/`, etc.) + +**Search strategy:** + +1. Search for component files with matching names +2. Read candidate files to check structure and props +3. Compare the code component's props with the Figma component properties returned in Step 1 +4. Detect the programming language (TypeScript, JavaScript) and framework (React, Vue, etc.) +5. Identify the best match based on structural similarity, weighing: + - Prop names and their correspondence to Figma properties + - Default values that match Figma defaults + - CSS classes or style objects + - Descriptive comments that clarify intent +6. If multiple candidates are equally good, pick the one with the closest prop-interface match and document your reasoning in a 1-2 sentence comment before your tool call + +**Example search patterns:** + +- If Figma component is "PrimaryButton", search for `Button.tsx`, `PrimaryButton.tsx`, `Button.jsx` +- Check common component paths: `src/components/`, `app/components/`, `lib/ui/` +- Look for variant props like `variant`, `size`, `color` that match Figma variants + +### Step 3: Present Matches to User + +Present your findings and let the user choose which mappings to create. The user can accept all, some, or none of the suggested mappings. + +**Present matches in this format:** + +``` +The following components match the design: +- [ComponentName](path/to/component): DesignComponentName at nodeId [nodeId](figmaUrl?node-id=X-Y) +- [AnotherComponent](path/to/another): AnotherDesign at nodeId [nodeId2](figmaUrl?node-id=X-Y) + +Would you like to connect these components? You can accept all, select specific ones, or skip. +``` + +**If no exact match is found for a component:** + +- Show the 2 closest candidates +- Explain the differences +- Ask the user to confirm which component to use or provide the correct path + +**If the user declines all mappings**, inform them and stop. No further tool calls are needed. + +### Step 4: Create Code Connect Mappings + +Once the user confirms their selections, call `send_code_connect_mappings` with only the accepted mappings. This tool handles batch creation of all mappings in a single call. + +**Example:** + +``` +send_code_connect_mappings( + fileKey=":fileKey", + nodeId="1:2", + mappings=[ + { nodeId: "1:2", componentName: "Button", source: "src/components/Button.tsx", label: "React" }, + { nodeId: "1:5", componentName: "Card", source: "src/components/Card.tsx", label: "React" } + ] +) +``` + +**Key parameters for each mapping:** + +- `nodeId`: The Figma node ID (with colon format: `1:2`) +- `componentName`: Name of the component to connect (e.g., "Button", "Card") +- `source`: Path to the code component file (relative to project root) +- `label`: The framework or language label for this Code Connect mapping. Valid values include: + - Web: 'React', 'Web Components', 'Vue', 'Svelte', 'Storybook', 'Javascript' + - iOS: 'Swift UIKit', 'Objective-C UIKit', 'SwiftUI' + - Android: 'Compose', 'Java', 'Kotlin', 'Android XML Layout' + - Cross-platform: 'Flutter' + - Docs: 'Markdown' + +**After the call:** + +- On success: the tool confirms the mappings were created +- On error: the tool reports which specific mappings failed and why (e.g., "Component is already mapped to code", "Published component not found", "Insufficient permissions") + +**Provide a summary** after processing: + +``` +Code Connect Summary: +- Successfully connected: 3 + - Button (1:2) → src/components/Button.tsx + - Card (1:5) → src/components/Card.tsx + - Input (1:8) → src/components/Input.tsx +- Could not connect: 1 + - CustomWidget (1:10) - No matching component found in codebase +``` + +## Examples + +### Example 1: Connecting a Button Component + +User says: "Connect this Figma button to my code: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15" + +**Actions:** + +1. Parse URL: fileKey=`kL9xQn2VwM8pYrTb4ZcHjF`, nodeId=`42-15` → convert to `42:15` +2. Run `get_code_connect_suggestions(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15")` +3. Response shows: Button component (unmapped) with `variant` (primary/secondary) and `size` (sm/md/lg) properties, plus a thumbnail image +4. Search codebase for Button components: Find `src/components/Button.tsx` +5. Read `Button.tsx` and confirm it has `variant` and `size` props +6. Present to user: "I found a match: + - [Button](src/components/Button.tsx): Button at nodeId [42:15](https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15) + + Would you like to connect this component?" + +7. User confirms: "Yes" +8. Detect that it's a TypeScript React component +9. Run `send_code_connect_mappings(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15", mappings=[{ nodeId: "42:15", componentName: "Button", source: "src/components/Button.tsx", label: "React" }])` + +**Result:** Figma button component is now connected to the code Button component. + +### Example 2: Multiple Components with Partial Selection + +User says: "Connect components in this frame: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-50" + +**Actions:** + +1. Parse URL: fileKey=`pR8mNv5KqXzGwY2JtCfL4D`, nodeId=`10-50` → convert to `10:50` +2. Run `get_code_connect_suggestions(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50")` +3. Response shows 3 unmapped components: ProductCard, Badge, and CustomWidget +4. Search codebase: + - ProductCard: Found `src/components/ProductCard.tsx` (props match) + - Badge: Found `src/components/Badge.tsx` (props match) + - CustomWidget: No matching component found +5. Present to user: + "The following components match the design: + - [ProductCard](src/components/ProductCard.tsx): ProductCard at nodeId [10:51](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-51) + - [Badge](src/components/Badge.tsx): Badge at nodeId [10:52](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-52) + + I couldn't find a match for CustomWidget (10:53). + + Would you like to connect these components? You can accept all, select specific ones, or skip." + +6. User: "Just connect ProductCard, skip Badge for now" +7. Run `send_code_connect_mappings(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50", mappings=[{ nodeId: "10:51", componentName: "ProductCard", source: "src/components/ProductCard.tsx", label: "React" }])` + +**Result:** Only ProductCard is connected, per the user's selection. + +### Example 3: Component Needs Creation + +User says: "Connect this icon: https://figma.com/design/8yJDMeWDyBz71EnMOSuUiw/Icons?node-id=5-20" + +**Actions:** + +1. Parse URL: fileKey=`8yJDMeWDyBz71EnMOSuUiw`, nodeId=`5-20` → convert to `5:20` +2. Run `get_code_connect_suggestions(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20")` +3. Response shows: CheckIcon component (unmapped) with color and size properties +4. Search codebase for CheckIcon: No matches found +5. Search for generic Icon components: Find `src/icons/` directory with other icons +6. Report to user: "I couldn't find a CheckIcon component, but I found an icons directory at src/icons/. Would you like to: + - Create a new CheckIcon.tsx component first, then connect it + - Connect to a different existing icon + - Provide the path to the CheckIcon if it exists elsewhere" +7. User provides path: "src/icons/CheckIcon.tsx" +8. Detect language and framework from the file +9. Run `send_code_connect_mappings(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20", mappings=[{ nodeId: "5:20", componentName: "CheckIcon", source: "src/icons/CheckIcon.tsx", label: "React" }])` + +**Result:** CheckIcon component is successfully connected to the Figma design. + +## Best Practices + +### Proactive Component Discovery + +Don't just ask the user for the file path — actively search their codebase to find matching components. This provides a better experience and catches potential mapping opportunities. + +### Accurate Structure Matching + +When comparing Figma components to code components, look beyond just names. Check that: + +- Props align (variant types, size options, etc.) +- Component hierarchy matches (nested elements) +- The component serves the same purpose + +### Clear Communication + +When offering to create a mapping, clearly explain: + +- What you found +- Why it's a good match +- What the mapping will do +- How props will be connected + +### Handle Ambiguity + +If multiple components could match, present options rather than guessing. Let the user make the final decision about which component to connect. + +### Graceful Degradation + +If you can't find an exact match, provide helpful next steps: + +- Show close candidates +- Suggest component creation +- Ask for user guidance + +## Common Issues and Solutions + +### Issue: "No published components found in this selection" + +**Cause:** The Figma component is not published to a team library. Code Connect only works with published components. +**Solution:** The user needs to publish the component to a team library in Figma: + +1. In Figma, select the component or component set +2. Right-click and choose "Publish to library" or use the Team Library publish modal +3. Publish the component +4. Once published, retry the Code Connect mapping with the same node ID + +### Issue: "Code Connect is only available on Organization and Enterprise plans" + +**Cause:** The user's Figma plan does not include Code Connect access. +**Solution:** The user needs to upgrade to an Organization or Enterprise plan, or contact their administrator. + +### Issue: No matching component found in codebase + +**Cause:** The codebase search did not find a component with a matching name or structure. +**Solution:** Ask the user if the component exists under a different name or in a different location. They may need to create the component first, or it might be located in an unexpected directory. + +### Issue: "Published component not found" (CODE_CONNECT_ASSET_NOT_FOUND) + +**Cause:** The source file path is incorrect, the component doesn't exist at that location, or the componentName doesn't match the actual export. +**Solution:** Verify the source path is correct and relative to the project root. Check that the component is properly exported from the file with the exact componentName specified. + +### Issue: "Component is already mapped to code" (CODE_CONNECT_MAPPING_ALREADY_EXISTS) + +**Cause:** A Code Connect mapping already exists for this component. +**Solution:** The component is already connected. If the user wants to update the mapping, they may need to remove the existing one first in Figma. + +### Issue: "Insufficient permissions to create mapping" (CODE_CONNECT_INSUFFICIENT_PERMISSIONS) + +**Cause:** The user does not have edit permissions on the Figma file or library. +**Solution:** The user needs edit access to the file containing the component. Contact the file owner or team admin. + +### Issue: Code Connect mapping fails with URL errors + +**Cause:** The Figma URL format is incorrect or missing the `node-id` parameter. +**Solution:** Verify the URL follows the required format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`. The `node-id` parameter is required. Also ensure you convert `1-2` to `1:2` when calling tools. + +### Issue: Multiple similar components found + +**Cause:** The codebase contains multiple components that could match the Figma component. +**Solution:** Present all candidates to the user with their file paths and let them choose which one to connect. Different components might be used in different contexts (e.g., `Button.tsx` vs `LinkButton.tsx`). + +## Understanding Code Connect + +Code Connect establishes a bidirectional link between design and code: + +**For designers:** See which code component implements a Figma component +**For developers:** Navigate from Figma designs directly to the code that implements them +**For teams:** Maintain a single source of truth for component mappings + +The mapping you create helps keep design and code in sync by making these connections explicit and discoverable. + +## Additional Resources + +For more information about Code Connect: + +- [Code Connect Documentation](https://help.figma.com/hc/en-us/articles/23920389749655-Code-Connect) +- [Figma MCP Server Tools and Prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/) diff --git a/plugins/figma/skills/create-design-system-rules/SKILL.md b/plugins/figma/skills/create-design-system-rules/SKILL.md new file mode 100644 index 00000000..07f2f75a --- /dev/null +++ b/plugins/figma/skills/create-design-system-rules/SKILL.md @@ -0,0 +1,541 @@ +--- +name: create-design-system-rules +description: Generates custom design system rules for the user's codebase. Use when user says "create design system rules", "generate rules for my project", "set up design rules", "customize design system guidelines", or wants to establish project-specific conventions for Figma-to-code workflows. Requires Figma MCP server connection. +metadata: + mcp-server: figma +--- + +# Create Design System Rules + +## Overview + +This skill helps you generate custom design system rules tailored to your project's specific needs. These rules guide AI coding agents to produce consistent, high-quality code when implementing Figma designs, ensuring that your team's conventions, component patterns, and architectural decisions are followed automatically. + +### Supported Rule Files + +| Agent | Rule File | +|-------|-----------| +| Claude Code | `CLAUDE.md` | +| Codex CLI | `AGENTS.md` | +| Cursor | `.cursor/rules/figma-design-system.mdc` | + +## What Are Design System Rules? + +Design system rules are project-level instructions that encode the "unwritten knowledge" of your codebase - the kind of expertise that experienced developers know and would pass on to new team members: + +- Which layout primitives and components to use +- Where component files should be located +- How components should be named and structured +- What should never be hardcoded +- How to handle design tokens and styling +- Project-specific architectural patterns + +Once defined, these rules dramatically reduce repetitive prompting and ensure consistent output across all Figma implementation tasks. + +## Prerequisites + +- Figma MCP server must be connected and accessible + - Before proceeding, verify the Figma MCP server is connected by checking if Figma MCP tools (e.g., `create_design_system_rules`) are available. + - 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. +- Access to the project codebase for analysis +- Understanding of your team's component conventions (or willingness to establish them) + +## When to Use This Skill + +Use this skill when: + +- Starting a new project that will use Figma designs +- Onboarding an AI coding agent to an existing project with established patterns +- Standardizing Figma-to-code workflows across your team +- Updating or refining existing design system conventions +- Users explicitly request: "create design system rules", "set up Figma guidelines", "customize rules for my project" + +## Required Workflow + +**Follow these steps in order. Do not skip steps.** + +### Step 1: Run the Create Design System Rules Tool + +Call the Figma MCP server's `create_design_system_rules` tool to get the foundational prompt and template. + +**Parameters:** + +- `clientLanguages`: Comma-separated list of languages used in the project (e.g., "typescript,javascript", "python", "javascript") +- `clientFrameworks`: Framework being used (e.g., "react", "vue", "svelte", "angular", "unknown") + +This tool returns guidance and a template for creating design system rules. + +Structure your design system rules following the template format provided in the tool's response. + +### Step 2: Analyze the Codebase + +Before finalizing rules, analyze the project to understand existing patterns: + +**Component Organization:** + +- Where are UI components located? (e.g., `src/components/`, `app/ui/`, `lib/components/`) +- Is there a dedicated design system directory? +- How are components organized? (by feature, by type, flat structure) + +**Styling Approach:** + +- What CSS framework or approach is used? (Tailwind, CSS Modules, styled-components, etc.) +- Where are design tokens defined? (CSS variables, theme files, config files) +- Are there existing color, typography, or spacing tokens? + +**Component Patterns:** + +- What naming conventions are used? (PascalCase, kebab-case, prefixes) +- How are component props typically structured? +- Are there common composition patterns? + +**Architecture Decisions:** + +- How is state management handled? +- What routing system is used? +- Are there specific import patterns or path aliases? + +### Step 3: Generate Project-Specific Rules + +Based on your codebase analysis, create a comprehensive set of rules. Include: + +#### General Component Rules + +```markdown +- IMPORTANT: Always use components from `[YOUR_PATH]` when possible +- Place new UI components in `[COMPONENT_DIRECTORY]` +- Follow `[NAMING_CONVENTION]` for component names +- Components must export as `[EXPORT_PATTERN]` +``` + +#### Styling Rules + +```markdown +- Use `[CSS_FRAMEWORK/APPROACH]` for styling +- Design tokens are defined in `[TOKEN_LOCATION]` +- IMPORTANT: Never hardcode colors - always use tokens from `[TOKEN_FILE]` +- Spacing values must use the `[SPACING_SYSTEM]` scale +- Typography follows the scale defined in `[TYPOGRAPHY_LOCATION]` +``` + +#### Figma MCP Integration Rules + +```markdown +## Figma MCP Integration Rules + +These rules define how to translate Figma inputs into code for this project and must be followed for every Figma-driven change. + +### Required Flow (do not skip) + +1. Run get_design_context first to fetch the structured representation for the exact node(s) +2. If the response is too large or truncated, run get_metadata to get the high-level node map, then re-fetch only the required node(s) with get_design_context +3. Run get_screenshot for a visual reference of the node variant being implemented +4. Only after you have both get_design_context and get_screenshot, download any assets needed and start implementation +5. Translate the output (usually React + Tailwind) into this project's conventions, styles, and framework +6. Validate against Figma for 1:1 look and behavior before marking complete + +### Implementation Rules + +- Treat the Figma MCP output (React + Tailwind) as a representation of design and behavior, not as final code style +- Replace Tailwind utility classes with `[YOUR_STYLING_APPROACH]` when applicable +- Reuse existing components from `[COMPONENT_PATH]` instead of duplicating functionality +- Use the project's color system, typography scale, and spacing tokens consistently +- Respect existing routing, state management, and data-fetch patterns +- Strive for 1:1 visual parity with the Figma design +- Validate the final UI against the Figma screenshot for both look and behavior +``` + +#### Asset Handling Rules + +```markdown +## Asset Handling + +- The Figma MCP server provides an assets endpoint which can serve image and SVG assets +- IMPORTANT: If the Figma MCP server returns a localhost source for an image or SVG, use that source directly +- IMPORTANT: DO NOT import/add new icon packages - all assets should be in the Figma payload +- IMPORTANT: DO NOT use or create placeholders if a localhost source is provided +- Store downloaded assets in `[ASSET_DIRECTORY]` +``` + +#### Project-Specific Conventions + +```markdown +## Project-Specific Conventions + +- [Add any unique architectural patterns] +- [Add any special import requirements] +- [Add any testing requirements] +- [Add any accessibility standards] +- [Add any performance considerations] +``` + +### Step 4: Save Rules to the Appropriate Rule File + +Detect which AI coding agent the user is working with and save the generated rules to the corresponding file: + +| Agent | Rule File | Notes | +|-------|-----------|-------| +| Claude Code | `CLAUDE.md` in project root | Markdown format. Can also use `.claude/rules/figma-design-system.md` for modular organization. | +| Codex CLI | `AGENTS.md` in project root | Markdown format. Append as a new section if file already exists. 32 KiB combined size limit. | +| Cursor | `.cursor/rules/figma-design-system.mdc` | Markdown with YAML frontmatter (`description`, `globs`, `alwaysApply`). | + +If unsure which agent the user is working with, check for existing rule files in the project or ask the user. + +For Cursor, wrap the rules with YAML frontmatter: + +```markdown +--- +description: Rules for implementing Figma designs using the Figma MCP server. Covers component organization, styling conventions, design tokens, asset handling, and the required Figma-to-code workflow. +globs: "src/components/**" +alwaysApply: false +--- + +[Generated rules here] +``` + +Customize the `globs` pattern to match the directories where Figma-derived code will live in the project (e.g., `"src/**/*.tsx"` or `["src/components/**", "src/pages/**"]`). + +After saving, the rules will be automatically loaded by the agent and applied to all Figma implementation tasks. + +### Step 5: Validate and Iterate + +After creating rules: + +1. Test with a simple Figma component implementation +2. Verify the agent follows the rules correctly +3. Refine any rules that aren't working as expected +4. Share with team members for feedback +5. Update rules as the project evolves + +## Rule Categories and Examples + +### Essential Rules (Always Include) + +**Component Discovery:** + +```markdown +- UI components are located in `src/components/ui/` +- Feature components are in `src/components/features/` +- Layout primitives are in `src/components/layout/` +``` + +**Design Token Usage:** + +```markdown +- Colors are defined as CSS variables in `src/styles/tokens.css` +- Never hardcode hex colors - use `var(--color-*)` tokens +- Spacing uses the 4px base scale: `--space-1` (4px), `--space-2` (8px), etc. +``` + +**Styling Approach:** + +```markdown +- Use Tailwind utility classes for styling +- Custom styles go in component-level CSS modules +- Theme customization is in `tailwind.config.js` +``` + +### Recommended Rules (Highly Valuable) + +**Component Patterns:** + +```markdown +- All components must accept a `className` prop for composition +- Variant props should use union types: `variant: 'primary' | 'secondary'` +- Icon components should accept `size` and `color` props +``` + +**Import Conventions:** + +```markdown +- Use path aliases: `@/components`, `@/styles`, `@/utils` +- Group imports: React, third-party, internal, types +- No relative imports beyond parent directory +``` + +**Code Quality:** + +```markdown +- Add JSDoc comments for exported components +- Include PropTypes or TypeScript types for all props +- Extract magic numbers to named constants +``` + +### Optional Rules (Project-Specific) + +**Accessibility:** + +```markdown +- All interactive elements must have aria-labels +- Color contrast must meet WCAG AA standards +- Keyboard navigation required for all interactions +``` + +**Performance:** + +```markdown +- Lazy load images with the `Image` component from `@/components/Image` +- Use React.memo for components that receive complex props +- Icons should be SVG components, not icon fonts +``` + +**Testing:** + +```markdown +- Include unit tests for new components in `__tests__/` directory +- Use Testing Library queries (getByRole, getByLabelText) +- Test all interactive states and variants +``` + +## Examples + +### Example 1: React + Tailwind Project + +User says: "Create design system rules for my React project" + +**Actions:** + +1. Run `create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="react")` +2. Analyze codebase structure +3. Generate rules: + +```markdown +# Figma MCP Integration Rules + +## Component Organization + +- UI components are in `src/components/ui/` +- Page components are in `src/app/` +- Use Tailwind for styling + +## Figma Implementation Flow + +1. Run get_design_context for the node +2. Run get_screenshot for visual reference +3. Map Figma colors to Tailwind colors defined in `tailwind.config.js` +4. Reuse components from `src/components/ui/` when possible +5. Validate against screenshot before completing + +## Styling Rules + +- IMPORTANT: Use Tailwind utility classes, not inline styles +- Colors are defined in `tailwind.config.js` theme.colors +- Spacing uses Tailwind's default scale +- Custom components go in `src/components/ui/` + +## Asset Rules + +- IMPORTANT: Use localhost sources from Figma MCP server directly +- Store static assets in `public/assets/` +- DO NOT install new icon libraries +``` + +4. Save to the appropriate rule file for the user's agent +5. Test with a simple button implementation + +**Result:** The agent now consistently follows the project's conventions when implementing Figma designs. + +### Example 2: Vue + Custom CSS Project + +User says: "Set up Figma rules for my Vue app" + +**Actions:** + +1. Run `create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="vue")` +2. Discover that project uses CSS modules and a custom design token system +3. Generate rules: + +```markdown +# Figma MCP Integration Rules + +## Component Organization + +- Components are in `src/components/` +- Composables are in `src/composables/` +- Vue SFC structure: