Back to Details

figma-create-design-system-rules

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
此技能可帮助您生成符合项目特定需求的自定义设计系统规则。这些规则指导AI编码代理在实现Figma设计时生成一致、高质量的代码，确保团队的约定、组件模式和架构决策被自动遵循。

Supported Rule Files

支持的规则文件

AgentRule File
Claude Code
CLAUDE.md
Codex CLI
AGENTS.md
Cursor
.cursor/rules/figma-design-system.mdc
代理规则文件
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.
设计系统规则是项目级别的指令，编码了代码库中的“隐性知识”——也就是资深开发者了解并会传递给新团队成员的专业经验：
  • 应使用哪些布局基础组件和组件
  • 组件文件应存放在何处
  • 组件应如何命名和结构化
  • 哪些内容绝对不能硬编码
  • 如何处理设计令牌和样式
  • 项目特定的架构模式
规则定义完成后，会大幅减少重复提示，并确保所有Figma实现任务的输出保持一致。

Prerequisites

前提条件

  • Figma MCP server must be connected and accessible
  • Access to the project codebase for analysis
  • Understanding of your team's component conventions (or willingness to establish them)
  • 必须已连接并可访问Figma MCP服务器
  • 有权访问项目代码库以进行分析
  • 了解团队的组件约定（或愿意建立这些约定）

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"
在以下场景使用此技能：
  • 启动一个将使用Figma设计的新项目
  • 让AI编码代理接入已有既定模式的现有项目
  • 在团队中标准化Figma转代码工作流
  • 更新或优化现有的设计系统约定
  • 用户明确请求：“创建设计系统规则”、“设置Figma指南”、“为我的项目自定义规则”

Required Workflow

必需的工作流程

Follow these steps in order. Do not skip steps.
请按顺序执行以下步骤，不要跳过。

Step 1: Run the Create Design System Rules Tool

步骤1：运行创建设计系统规则工具

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.
调用Figma MCP服务器的
create_design_system_rules
工具，获取基础提示和模板。
参数：
  • clientLanguages
    ：项目使用的语言列表，用逗号分隔（例如："typescript,javascript"、"python"、"javascript"）
  • clientFrameworks
    ：使用的框架（例如："react"、"vue"、"svelte"、"angular"、"unknown"）
此工具会返回创建设计系统规则的指导和模板。
按照工具返回的模板格式来构建您的设计系统规则。

Step 2: Analyze the Codebase

步骤2：分析代码库

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?
在最终确定规则之前，先分析项目以了解现有模式：
组件组织：
  • UI组件存放在哪里？（例如：
    src/components/
    、
    app/ui/
    、
    lib/components/
    ）
  • 是否有专门的设计系统目录？
  • 组件是如何组织的？（按功能、按类型、扁平结构）
样式方案：
  • 使用的是哪种CSS框架或方案？（Tailwind、CSS Modules、styled-components等）
  • 设计令牌定义在何处？（CSS变量、主题文件、配置文件）
  • 是否已有颜色、排版或间距令牌？
组件模式：
  • 使用的是什么命名约定？（大驼峰、短横线分隔、前缀）
  • 组件属性通常如何结构化？
  • 是否有常见的组合模式？
架构决策：
  • 状态管理如何处理？
  • 使用的是什么路由系统？
  • 是否有特定的导入模式或路径别名？

Step 3: Generate Project-Specific Rules

步骤3：生成项目特定规则

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]`
markdown
- 重要提示：尽可能始终使用`[YOUR_PATH]`中的组件
- 将新UI组件放在`[COMPONENT_DIRECTORY]`中
- 组件名称遵循`[NAMING_CONVENTION]`
- 组件必须按`[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]`
markdown
- 使用`[CSS_FRAMEWORK/APPROACH]`进行样式处理
- 设计令牌定义在`[TOKEN_LOCATION]`
- 重要提示：绝对不要硬编码颜色——务必使用`[TOKEN_FILE]`中的令牌
- 间距值必须使用`[SPACING_SYSTEM]`刻度
- 排版遵循`[TYPOGRAPHY_LOCATION]`中定义的刻度

Figma MCP Integration Rules

Figma MCP集成规则

markdown
undefined
markdown
undefined

Figma MCP Integration Rules

Figma MCP集成规则

These rules define how to translate Figma inputs into code for this project and must be followed for every Figma-driven change.
这些规则定义了如何将Figma输入转换为项目代码，所有Figma驱动的变更都必须遵循这些规则。

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
  1. 先运行get_design_context获取对应节点的结构化表示
  2. 如果响应过大或被截断，运行get_metadata获取高级节点映射，然后重新仅获取所需节点的get_design_context
  3. 运行get_screenshot获取要实现的节点变体的视觉参考
  4. 只有在同时获取了get_design_context和get_screenshot之后，再下载所需资源并开始实现
  5. 将输出（通常是React + Tailwind）转换为符合项目约定、样式和框架的代码
  6. 在标记完成前，验证是否与Figma设计在视觉和行为上1:1匹配

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
undefined
  • 将Figma MCP输出（React + Tailwind）视为设计和行为的参考，而非最终代码风格
  • 适用时，将Tailwind工具类替换为
    [YOUR_STYLING_APPROACH]
  • 重用
    [COMPONENT_PATH]
    中的现有组件，不要重复实现功能
  • 始终如一地使用项目的颜色系统、排版刻度和间距令牌
  • 遵循现有的路由、状态管理和数据获取模式
  • 力求与Figma设计在视觉上1:1匹配
  • 针对外观和行为，将最终UI与Figma截图进行验证
undefined

Asset Handling Rules

资源处理规则

markdown
undefined
markdown
undefined

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]
undefined
  • Figma MCP服务器提供资源端点，可提供图片和SVG资源
  • 重要提示：如果Figma MCP服务器返回图片或SVG的localhost源，请直接使用该源
  • 重要提示：请勿导入/添加新的图标包——所有资源都应在Figma负载中
  • 重要提示：如果提供了localhost源，请勿使用或创建占位符
  • 将下载的资源存储在
    [ASSET_DIRECTORY]
    中
undefined

Project-Specific Conventions

项目特定约定

markdown
undefined
markdown
undefined

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]
undefined
  • [添加任何独特的架构模式]
  • [添加任何特殊的导入要求]
  • [添加任何测试要求]
  • [添加任何无障碍标准]
  • [添加任何性能考虑因素]
undefined

Step 4: Save Rules to the Appropriate Rule File

步骤4：将规则保存到相应的规则文件

Detect which AI coding agent the user is working with and save the generated rules to the corresponding file:
AgentRule FileNotes
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.
检测用户正在使用的AI编码代理，并将生成的规则保存到对应的文件：
代理规则文件说明
Claude Code项目根目录下的
CLAUDE.md
Markdown格式。也可使用
.claude/rules/figma-design-system.md
进行模块化组织。
Codex CLI项目根目录下的
AGENTS.md
Markdown格式。如果文件已存在，作为新章节追加。总大小限制为32 KiB。
Cursor
.cursor/rules/figma-design-system.mdc
带有YAML前置元数据（
description
、
globs
、
alwaysApply
）的Markdown文件。
如果不确定用户使用的是哪个代理，请检查项目中是否有现有规则文件，或询问用户。
对于Cursor，请用YAML前置元数据包裹规则：
markdown
---
description: 使用Figma MCP服务器实现Figma设计的规则。涵盖组件组织、样式约定、设计令牌、资源处理和必需的Figma转代码工作流。
globs: "src/components/**"
alwaysApply: false
---

[生成的规则内容]
自定义
globs
模式以匹配项目中Figma衍生代码所在的目录（例如：
"src/**/*.tsx"
或
["src/components/**", "src/pages/**"]
）。
保存后，规则会被代理自动加载，并应用于所有Figma实现任务。

Step 5: Validate and Iterate

步骤5：验证和迭代

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
创建规则后：
  1. 用一个简单的Figma组件实现进行测试
  2. 验证代理是否正确遵循规则
  3. 优化任何未按预期工作的规则
  4. 与团队成员分享以获取反馈
  5. 随着项目发展更新规则

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`
组件发现：
markdown
- UI组件位于`src/components/ui/`
- 功能组件位于`src/components/features/`
- 布局基础组件位于`src/components/layout/`
设计令牌使用：
markdown
- 颜色在`src/styles/tokens.css`中定义为CSS变量
- 绝对不要硬编码十六进制颜色——使用`var(--color-*)`令牌
- 间距使用4px为基础的刻度：`--space-1`（4px）、`--space-2`（8px）等
样式方案：
markdown
- 使用Tailwind工具类进行样式处理
- 自定义样式放在组件级别的CSS Modules中
- 主题自定义在`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
组件模式：
markdown
- 所有组件必须接受`className`属性以支持组合
- 变体属性应使用联合类型：`variant: 'primary' | 'secondary'`
- 图标组件应接受`size`和`color`属性
导入约定：
markdown
- 使用路径别名：`@/components`、`@/styles`、`@/utils`
- 对导入进行分组：React、第三方、内部、类型
- 相对导入不能超出父目录
代码质量：
markdown
- 为导出的组件添加JSDoc注释
- 为所有属性包含PropTypes或TypeScript类型
- 将魔法数字提取为命名常量

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
无障碍性：
markdown
- 所有交互元素必须有aria-labels
- 颜色对比度必须符合WCAG AA标准
- 所有交互都需要支持键盘导航
性能：
markdown
- 使用来自`@/components/Image`的`Image`组件懒加载图片
- 为接收复杂属性的组件使用React.memo
- 图标应使用SVG组件，而非图标字体
测试：
markdown
- 在`__tests__/`目录中为新组件添加单元测试
- 使用Testing Library查询（getByRole、getByLabelText）
- 测试所有交互状态和变体

Examples

示例

Example 1: React + Tailwind Project

示例1：React + Tailwind项目

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
undefined
用户说：“为我的React项目创建设计系统规则”
操作：
  1. 运行
    create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="react")
  2. 分析代码库结构
  3. 生成规则：
markdown
undefined

Figma MCP Integration Rules

Figma MCP集成规则

Component Organization

组件组织

  • UI components are in 
    src/components/ui/
  • Page components are in 
    src/app/
  • Use Tailwind for styling
  • UI组件位于
    src/components/ui/
  • 页面组件位于
    src/app/
  • 使用Tailwind进行样式处理

Figma Implementation Flow

Figma实现流程

  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
  1. 为节点运行get_design_context
  2. 运行get_screenshot获取视觉参考
  3. 将Figma颜色映射到
    tailwind.config.js
    中定义的Tailwind颜色
  4. 尽可能重用
    src/components/ui/
    中的组件
  5. 完成前与截图进行验证

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/
  • 重要提示：使用Tailwind工具类，不要使用内联样式
  • 颜色在
    tailwind.config.js
    的theme.colors中定义
  • 间距使用Tailwind的默认刻度
  • 自定义组件放在
    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.
  • 重要提示：直接使用Figma MCP服务器返回的localhost源
  • 静态资源存储在
    public/assets/
  • 请勿安装新的图标库

4. 将规则保存到对应用户代理的规则文件中
5. 用一个简单的按钮实现进行测试

**结果：** 现在，代理在实现Figma设计时会始终遵循项目约定。

Example 2: Vue + Custom CSS Project

示例2：Vue + 自定义CSS项目

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
undefined
用户说：“为我的Vue应用设置Figma规则”
操作：
  1. 运行
    create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="vue")
  2. 发现项目使用CSS Modules和自定义设计令牌系统
  3. 生成规则：
markdown
undefined

Figma MCP Integration Rules

Figma MCP集成规则

Component Organization

组件组织

  • Components are in 
    src/components/
  • Composables are in 
    src/composables/
  • Vue SFC structure: <script setup>, <template>, <style scoped>
  • 组件位于
    src/components/
  • 组合式函数位于
    src/composables/
  • Vue单文件组件结构：<script setup>、<template>、<style scoped>

Design Tokens

设计令牌

  • IMPORTANT: All colors defined in 
    src/styles/tokens.css
    as CSS variables
  • Use 
    var(--color-primary)
    , 
    var(--color-secondary)
    , etc.
  • Spacing: 
    var(--space-xs)
    through 
    var(--space-xl)
  • Typography: 
    var(--text-sm)
    through 
    var(--text-2xl)
  • 重要提示：所有颜色在
    src/styles/tokens.css
    中定义为CSS变量
  • 使用
    var(--color-primary)
    、
    var(--color-secondary)
    等
  • 间距：
    var(--space-xs)
    到
    var(--space-xl)
  • 排版：
    var(--text-sm)
    到
    var(--text-2xl)

Figma Implementation Flow

Figma实现流程

  1. Run get_design_context and get_screenshot
  2. Translate React output to Vue 3 Composition API
  3. Map Figma colors to CSS variables in 
    src/styles/tokens.css
  4. Use CSS Modules for component styles
  5. Check for existing components in 
    src/components/
    before creating new ones
  1. 获取Figma的设计上下文和截图
  2. 将React输出转换为Vue 3组合式API代码
  3. 将Figma颜色映射到
    src/styles/tokens.css
    中的CSS变量
  4. 使用CSS Modules进行组件样式处理
  5. 在创建新组件前，检查
    src/components/
    中是否有现有组件

Styling Rules

样式规则

  • Use CSS Modules (
    .module.css
    files)
  • IMPORTANT: Reference design tokens, never hardcode values
  • Scoped styles with CSS modules

4. Save to the appropriate rule file for the user's agent
5. Validate with a card component

**Result:** The agent now correctly translates Figma designs to Vue components using the project's design token system.
  • 使用CSS Modules（
    .module.css
    文件）
  • 重要提示：引用设计令牌，绝对不要硬编码值
  • 使用CSS Modules的作用域样式

4. 将规则保存到对应用户代理的规则文件中
5. 用一个卡片组件进行验证

**结果：** 现在，代理会使用项目的设计令牌系统，将Figma设计正确转换为Vue组件。

Example 3: Design System Team

示例3：设计系统团队

User says: "Generate rules for our design system library"
Actions:
  1. Run 
    create_design_system_rules(clientLanguages="typescript", clientFrameworks="react")
  2. Analyze the monorepo structure with design system package
  3. Generate comprehensive rules:
markdown
undefined
用户说：“为我们的设计系统库生成规则”
操作：
  1. 运行
    create_design_system_rules(clientLanguages="typescript", clientFrameworks="react")
  2. 分析包含设计系统包的单体仓库结构
  3. 生成全面的规则：
markdown
undefined

Design System Rules

设计系统规则

Repository Structure

仓库结构

  • Design system components: 
    packages/design-system/src/components/
  • Documentation: 
    packages/docs/
  • Design tokens: 
    packages/tokens/src/
  • 设计系统组件：
    packages/design-system/src/components/
  • 文档：
    packages/docs/
  • 设计令牌：
    packages/tokens/src/

Component Development

组件开发

  • IMPORTANT: All components must be in 
    packages/design-system/src/components/
  • Component file structure: 
    ComponentName/index.tsx
    , 
    ComponentName.stories.tsx
    , 
    ComponentName.test.tsx
  • Export all components from 
    packages/design-system/src/index.ts
  • 重要提示：所有组件必须放在
    packages/design-system/src/components/
  • 组件文件结构：
    ComponentName/index.tsx
    、
    ComponentName.stories.tsx
    、
    ComponentName.test.tsx
  • 从
    packages/design-system/src/index.ts
    导出所有组件

Design Tokens

设计令牌

  • Colors: 
    packages/tokens/src/colors.ts
  • Typography: 
    packages/tokens/src/typography.ts
  • Spacing: 
    packages/tokens/src/spacing.ts
  • IMPORTANT: Never hardcode values - import from tokens package
  • 颜色：
    packages/tokens/src/colors.ts
  • 排版：
    packages/tokens/src/typography.ts
  • 间距：
    packages/tokens/src/spacing.ts
  • 重要提示：绝对不要硬编码值——从令牌包导入

Documentation Requirements

文档要求

  • Add Storybook story for every component
  • Include JSDoc with @example
  • Document all props with descriptions
  • Add accessibility notes
  • 为每个组件添加Storybook故事
  • 包含带@example的JSDoc
  • 记录所有属性及其描述
  • 添加无障碍性说明

Figma Integration

Figma集成

  1. Get design context and screenshot from Figma
  2. Map Figma tokens to design system tokens
  3. Create or extend component in design system package
  4. Add Storybook stories showing all variants
  5. Validate against Figma screenshot
  6. Update documentation

4. Save to the appropriate rule file and share with team
5. Add to team documentation

**Result:** Entire team follows consistent patterns when adding components from Figma to the design system.
  1. 从Figma获取设计上下文和截图
  2. 将Figma令牌映射到设计系统令牌
  3. 在设计系统包中创建或扩展组件
  4. 添加展示所有变体的Storybook故事
  5. 与Figma截图进行验证
  6. 更新文档

4. 将规则保存到相应的规则文件并与团队分享
5. 添加到团队文档中

**结果：** 整个团队在将Figma中的组件添加到设计系统时，都会遵循一致的模式。

Best Practices

最佳实践

Start Simple, Iterate

从简开始，逐步迭代

Don't try to capture every rule upfront. Start with the most important conventions and add rules as you encounter inconsistencies.
不要试图一开始就捕获所有规则。从最重要的约定开始，遇到不一致时再添加规则。

Be Specific

保持具体

Instead of: "Use the design system" Write: "Always use Button components from 
src/components/ui/Button.tsx
with variant prop ('primary' | 'secondary' | 'ghost')"
不要写：“使用设计系统” 而要写：“始终使用
src/components/ui/Button.tsx
中的Button组件，并传入variant属性（'primary' | 'secondary' | 'ghost'）”

Make Rules Actionable

让规则可执行

Each rule should tell the agent exactly what to do, not just what to avoid.
Good: "Colors are defined in 
src/theme/colors.ts
- import and use these constants" Bad: "Don't hardcode colors"
每条规则都应明确告诉代理该做什么，而不只是不能做什么。
好的示例：“颜色在
src/theme/colors.ts
中定义——导入并使用这些常量” 不好的示例：“不要硬编码颜色”

Use IMPORTANT for Critical Rules

用IMPORTANT标记关键规则

Prefix rules that must never be violated with "IMPORTANT:" to ensure the agent prioritizes them.
markdown
- IMPORTANT: Never expose API keys in client-side code
- IMPORTANT: Always sanitize user input before rendering
对绝对不能违反的规则添加“IMPORTANT:”前缀，确保代理优先处理这些规则。
markdown
- 重要提示：绝对不要在客户端代码中暴露API密钥
- 重要提示：在渲染前务必对用户输入进行清理

Document the Why

说明规则的原因

When rules seem arbitrary, explain the reasoning:
markdown
- Place all data-fetching in server components (reduces client bundle size and improves performance)
- Use absolute imports with `@/` alias (makes refactoring easier and prevents broken relative paths)
当规则看起来比较随意时，解释其背后的原因：
markdown
- 将所有数据获取放在服务器组件中（减少客户端包大小并提升性能）
- 使用`@/`别名进行绝对导入（让重构更轻松，避免相对路径断裂）

Common Issues and Solutions

常见问题和解决方案

Issue: The agent isn't following the rules

问题：代理不遵循规则

Cause: Rules may be too vague or not properly loaded by the agent. Solution:
  • Make rules more specific and actionable
  • Verify rules are saved in the correct configuration file
  • Restart your agent or IDE to reload rules
  • Add "IMPORTANT:" prefix to critical rules
原因： 规则可能过于模糊，或者未被代理正确加载。 解决方案：
  • 让规则更具体、更可执行
  • 验证规则是否保存到了正确的配置文件中
  • 重启代理或IDE以重新加载规则
  • 为关键规则添加“IMPORTANT:”前缀

Issue: Rules conflict with each other

问题：规则之间存在冲突

Cause: Contradictory or overlapping rules. Solution:
  • Review all rules for conflicts
  • Establish a clear priority hierarchy
  • Remove redundant rules
  • Consolidate related rules into single, clear statements
原因： 规则相互矛盾或重叠。 解决方案：
  • 检查所有规则是否存在冲突
  • 建立清晰的优先级层次
  • 移除冗余规则
  • 将相关规则合并为清晰的单一语句

Issue: Too many rules increase latency

问题：规则过多导致延迟增加

Cause: Excessive rules increase context size and processing time. Solution:
  • Focus on the 20% of rules that solve 80% of consistency issues
  • Remove overly specific rules that rarely apply
  • Combine related rules
  • Use progressive disclosure (basic rules first, advanced rules in linked files)
原因： 过多的规则会增加上下文大小和处理时间。 解决方案：
  • 专注于能解决80%一致性问题的20%规则
  • 移除过于具体、很少适用的规则
  • 合并相关规则
  • 使用渐进式披露（先提供基础规则，高级规则放在链接文件中）

Issue: Rules become outdated as project evolves

问题：随着项目发展，规则变得过时

Cause: Codebase changes but rules don't. Solution:
  • Schedule periodic rule reviews (monthly or quarterly)
  • Update rules when architectural decisions change
  • Version control your rule files
  • Document rule changes in commit messages
原因： 代码库发生了变化，但规则没有更新。 解决方案：
  • 定期安排规则审查（每月或每季度）
  • 当架构决策变更时更新规则
  • 对规则文件进行版本控制
  • 在提交信息中记录规则变更

Understanding Design System Rules

理解设计系统规则

Design system rules transform how AI coding agents work with your Figma designs:
Before rules:
  • The agent makes assumptions about component structure
  • Inconsistent styling approaches across implementations
  • Hardcoded values that don't match design tokens
  • Components created in random locations
  • Repetitive explanations of project conventions
After rules:
  • The agent automatically follows your conventions
  • Consistent component structure and styling
  • Proper use of design tokens from the start
  • Components organized correctly
  • Zero repetitive prompting
The time invested in creating good rules pays off exponentially across every Figma implementation task.
设计系统规则改变了AI编码代理处理Figma设计的方式：
没有规则之前：
  • 代理对组件结构做出假设
  • 不同实现的样式方案不一致
  • 硬编码的值与设计令牌不匹配
  • 组件被创建在随机位置
  • 需要反复解释项目约定
有了规则之后：
  • 代理会自动遵循您的约定
  • 组件结构和样式保持一致
  • 从一开始就正确使用设计令牌
  • 组件被正确组织
  • 无需重复提示
创建优质规则所投入的时间，会在每个Figma实现任务中得到指数级的回报。

Additional Resources

额外资源