---
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, figma-desktop
enabled: false
source: github:JuanJoseGonGi/skills
imported-from: github:JuanJoseGonGi/skills
---

# Create Design System Rules

## Overview

This skill generates custom design system rules tailored to your project. These rules guide AI coding agents to produce consistent, high-quality code when implementing Figma designs, ensuring your team's conventions are followed automatically.

Design system rules encode the "unwritten knowledge" of your codebase — which components to use, where files go, how tokens work, and what should never be hardcoded. Once defined, they eliminate repetitive prompting and ensure consistent output.

### Supported Rule Files

| Agent | Rule File |
|-------|-----------|
| Claude Code | `CLAUDE.md` or `.claude/rules/figma-design-system.md` |
| Codex CLI | `AGENTS.md` (append as new section; 32 KiB limit) |
| Cursor | `.cursor/rules/figma-design-system.mdc` (see `references/cursor-frontmatter.md`) |

## Prerequisites

- Figma MCP server must be connected and accessible
- Access to the project codebase for analysis

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

- `clientLanguages`: Comma-separated list (e.g., "typescript,javascript")
- `clientFrameworks`: Framework used (e.g., "react", "vue", "svelte", "angular", "unknown")

This returns guidance and a template for creating design system rules.

### Step 2: Analyze the Codebase

Analyze the project to understand existing patterns:

**Component Organization:**
- Where are UI components located? (e.g., `src/components/`, `app/ui/`)
- Is there a dedicated design system directory?
- How are components organized? (by feature, by type, flat)

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

**Component Patterns:**
- Naming conventions (PascalCase, kebab-case, prefixes)
- How are props structured?
- Common composition patterns

**Architecture:**
- State management approach
- Routing system
- Import patterns or path aliases

### Step 3: Generate Project-Specific Rules

Based on the codebase analysis, generate rules covering these categories. See `references/rule-templates.md` for full templates and code blocks for each category:

1. **General Component Rules** — paths, naming, exports
2. **Styling Rules** — framework, tokens, spacing, typography
3. **Figma MCP Integration Rules** — the required get_design_context → get_screenshot → implement → validate flow
4. **Asset Handling Rules** — use localhost sources directly, no placeholder icons
5. **Project-Specific Conventions** — architecture, imports, testing, accessibility

Key Figma integration rules to always include:
- Run `get_design_context` first, then `get_screenshot` for visual reference
- If response is truncated, use `get_metadata` to get the node map, then re-fetch specific nodes
- Treat Figma MCP output as a design representation, not final code
- Translate to the project's conventions, styles, and framework
- Validate against Figma for 1:1 visual parity before marking complete

Key asset rules to always include:
- Use localhost sources from Figma MCP server directly
- DO NOT import/add new icon packages
- DO NOT use placeholders if a localhost source is provided

### Step 4: Save Rules to the Appropriate Rule File

Detect which agent the user is working with and save:

| Agent | Rule File | Notes |
|-------|-----------|-------|
| Claude Code | `CLAUDE.md` in project root | Markdown format |
| Codex CLI | `AGENTS.md` in project root | Append as new section |
| Cursor | `.cursor/rules/figma-design-system.mdc` | Needs YAML frontmatter (see `references/cursor-frontmatter.md`) |

If unsure which agent, check for existing rule files or ask the user.

### Step 5: Validate and Iterate

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 for feedback
5. Update rules as the project evolves

## Rule Priority Guidelines

Rules fall into three priority tiers. See `references/rule-templates.md` for detailed examples of each:

| Priority | Category | What to Include |
|----------|----------|-----------------|
| **Essential** | Component discovery, token usage, styling approach | Always include — these prevent the most common issues |
| **Recommended** | Component patterns, import conventions, code quality | Highly valuable for consistency |
| **Optional** | Accessibility, performance, testing | Add based on project needs |

## Writing Effective Rules

- **Be specific**: "Use Button from `src/components/ui/Button.tsx` with variant prop" not "Use the design system"
- **Make rules actionable**: Tell the agent what to do, not just what to avoid
- **Use IMPORTANT prefix**: For rules that must never be violated
- **Document the why**: Explain reasoning when rules seem arbitrary
- **Start simple**: Begin with essential rules; add more as inconsistencies appear

See `references/best-practices-and-troubleshooting.md` for detailed guidance and common issue solutions.

## Quick Reference: Worked Examples

Full worked examples for different project types are in `references/examples.md`:

- **React + Tailwind** — Standard SPA with Tailwind utility classes
- **Vue + Custom CSS** — Vue 3 with CSS Modules and custom design tokens
- **Design System Team** — Monorepo with shared component library

## Additional Resources

- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)
- [Figma Variables and Design Tokens](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma)