create-design-system-rules

创建设计系统规则

概述

此技能可帮助你生成针对项目特定需求定制的设计系统规则。这些规则可指导 AI 编码 Agent 在实现 Figma 设计时生成一致、高质量的代码，并确保团队的约定、组件模式和架构决策得到自动遵循。

支持的规则文件

Agent	规则文件
Claude Code	CLAUDE.md
Codex CLI	AGENTS.md
Cursor	.cursor/rules/figma-design-system.mdc

什么是设计系统规则？

设计系统规则是项目级指令，用于记录代码库中那些“未成文的知识”——也就是经验丰富的开发者所掌握、并会传授给新团队成员的专业知识：

• 应使用哪些布局基元和组件
• 组件文件应放在哪里
• 组件应如何命名和组织
• 哪些内容绝不能硬编码
• 如何处理设计令牌和样式
• 项目特有的架构模式

定义这些规则后，可以大幅减少重复提示，并确保所有 Figma 实现任务的输出保持一致。

先决条件

• 必须已连接并可访问 Figma MCP 服务
  • 继续之前，请检查 Figma MCP 工具（例如 create_design_system_rules）是否可用，以确认 Figma MCP 服务已连接。
  • 如果工具不可用，则可能尚未启用 Figma MCP 服务。请引导用户启用插件附带的 Figma MCP 服务。之后可能需要重启 MCP 客户端。
• 可访问项目代码库以进行分析
• 了解团队的组件约定（或愿意建立这些约定）

何时使用此技能

在以下情况下使用此技能：

• 开始一个将使用 Figma 设计的新项目
• 将 AI 编码 Agent 引入具有既定模式的现有项目
• 在团队中统一 Figma 到代码的工作流
• 更新或完善现有设计系统约定
• 用户明确提出：“创建设计系统规则”、“设置 Figma 指南”、“为我的项目定制规则”

必需的工作流

请按顺序执行以下步骤。不要跳过任何步骤。

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

调用 Figma MCP 服务的 create_design_system_rules 工具，以获取基础提示词和模板。

参数：

• clientLanguages：项目中使用的语言列表，以逗号分隔（例如 “typescript,javascript”、“python”、“javascript”）
• clientFrameworks：项目使用的框架（例如 “react”、“vue”、“svelte”、“angular”、“unknown”）

此工具会返回用于创建设计系统规则的指南和模板。

请按照工具响应中提供的模板格式编写设计系统规则。

步骤 2：分析代码库

在最终确定规则之前，请分析项目以了解现有模式：

组件组织方式：

• UI 组件位于何处？（例如 src/components/、app/ui/、lib/components/）
• 是否有专门的设计系统目录？
• 组件如何组织？（按功能、按类型、扁平结构）

样式方案：

• 使用了哪种 CSS 框架或方案？（Tailwind、CSS Modules、styled-components 等）
• 设计令牌定义在哪里？（CSS 变量、主题文件、配置文件）
• 是否已有颜色、排版或间距令牌？

组件模式：

• 使用了哪些命名约定？（PascalCase、kebab-case、前缀）
• 组件属性通常如何组织？
• 是否有常见的组合模式？

架构决策：

• 如何管理状态？
• 使用了哪种路由系统？
• 是否有特定的导入模式或路径别名？

步骤 3：生成项目专属规则

根据对代码库的分析，创建一套全面的规则。包括：

通用组件规则

- 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]`

样式规则

- 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 集成规则

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

- 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

- [Add any unique architectural patterns]
- [Add any special import requirements]
- [Add any testing requirements]
- [Add any accessibility standards]
- [Add any performance considerations]

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

检测用户正在使用哪种 AI 编码 Agent，并将生成的规则保存到相应文件：

Agent	规则文件	备注
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 frontmatter（description、globs、alwaysApply）的 Markdown。

如果不确定用户正在使用哪种 Agent，请检查项目中是否已有规则文件，或询问用户。

对于 Cursor，请使用 YAML frontmatter 包裹规则：

---
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]

自定义 globs 模式，使其匹配项目中存放 Figma 派生代码的目录（例如 "src/**/*.tsx" 或 ["src/components/**", "src/pages/**"]）。

保存后，Agent 将自动加载这些规则，并将其应用于所有 Figma 实现任务。

第 5 步：验证并迭代

创建规则后：

1. 使用简单的 Figma 组件实现进行测试
2. 验证 Agent 是否正确遵循规则
3. 优化未能按预期生效的规则
4. 与团队成员分享并征求反馈
5. 随着项目发展更新规则

规则类别和示例

必备规则（始终包含）

组件发现：

- UI components are located in `src/components/ui/`
- Feature components are in `src/components/features/`
- Layout primitives are in `src/components/layout/`

设计令牌用法：

- 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.

样式处理方式：

- Use Tailwind utility classes for styling
- Custom styles go in component-level CSS modules
- Theme customization is in `tailwind.config.js`

推荐规则（非常实用）

组件模式：

- 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

导入约定：

- Use path aliases: `@/components`, `@/styles`, `@/utils`
- Group imports: React, third-party, internal, types
- No relative imports beyond parent directory

代码质量：

- Add JSDoc comments for exported components
- Include PropTypes or TypeScript types for all props
- Extract magic numbers to named constants

可选规则（项目专属）

无障碍：

- All interactive elements must have aria-labels
- Color contrast must meet WCAG AA standards
- Keyboard navigation required for all interactions

性能：

- 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

测试：

- Include unit tests for new components in `__tests__/` directory
- Use Testing Library queries (getByRole, getByLabelText)
- Test all interactive states and variants

示例

示例 1：React + Tailwind 项目

用户说：“为我的 React 项目创建设计系统规则”

操作：

1. 运行 create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="react")
2. 分析代码库结构
3. 生成规则：

# 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. 将规则保存到适用于用户所用 Agent 的规则文件
5. 使用简单的按钮实现进行测试

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

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

用户说：“为我的 Vue 应用设置 Figma 规则”

操作：

1. 运行 create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="vue")
2. 发现项目使用 CSS modules 和自定义设计令牌系统
3. 生成规则：

# Figma MCP Integration Rules

## Component Organization

- Components are in `src/components/`
- Composables are in `src/composables/`
- Vue SFC structure: <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)`

## Figma Implementation Flow

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

## Styling Rules

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

4. 将规则保存到适用于用户所用 Agent 的规则文件
5. 使用卡片组件进行验证

结果： Agent 现在可以正确地将 Figma 设计转换为 Vue 组件，并使用项目的设计令牌系统。

示例 3：设计系统团队

用户说：“为我们的设计系统库生成规则”

操作：

1. 运行 create_design_system_rules(clientLanguages="typescript", clientFrameworks="react")
2. 分析包含设计系统包的 monorepo 结构
3. 生成全面的规则：

# Design System Rules

## Repository Structure

- Design system components: `packages/design-system/src/components/`
- Documentation: `packages/docs/`
- Design tokens: `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`

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

## Documentation Requirements

- Add Storybook story for every component
- Include JSDoc with @example
- Document all props with descriptions
- Add accessibility notes

## Figma Integration

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. 将规则保存到相应的规则文件并与团队分享
5. 将规则添加到团队文档中

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

最佳实践

从简单开始，逐步迭代

不要试图一开始就涵盖所有规则。从最重要的约定入手，遇到不一致时再添加规则。

明确具体

不要写：“使用设计系统” 应写：“始终使用 src/components/ui/Button.tsx 中的 Button 组件，并设置 variant 属性（'primary' | 'secondary' | 'ghost'）”

让规则具有可执行性

每条规则都应明确告诉 Agent 该做什么，而不只是说明要避免什么。

正确示例：“颜色定义在 src/theme/colors.ts 中——导入并使用这些常量” 错误示例：“不要硬编码颜色”

对关键规则使用 IMPORTANT

对于绝不可违反的规则，请添加前缀“IMPORTANT:”，确保 Agent 优先遵循。

- IMPORTANT: Never expose API keys in client-side code
- IMPORTANT: Always sanitize user input before rendering

说明原因

如果规则看起来不合理，请解释原因：

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

常见问题及解决方案

问题：Agent 不遵循规则

**原因：**规则可能过于模糊，或未被 Agent 正确加载。 解决方案：

• 让规则更具体、更具可执行性
• 确认规则已保存在正确的配置文件中
• 重启 Agent 或 IDE 以重新加载规则
• 为关键规则添加“IMPORTANT:”前缀

问题：规则相互冲突

**原因：**规则之间存在矛盾或重叠。 解决方案：

• 检查所有规则是否存在冲突
• 建立明确的优先级层次
• 删除冗余规则
• 将相关规则合并为简洁、清晰的单条规则

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

**原因：**过多的规则会增加上下文大小和处理时间。 解决方案：

• 聚焦于解决 80% 一致性问题的那 20% 规则
• 删除很少适用的过于具体的规则
• 合并相关规则
• 使用渐进式披露（先提供基本规则，再通过链接文件提供高级规则）

问题：随着项目演进，规则逐渐过时

**原因：**代码库发生变化，但规则没有更新。 解决方案：

• 定期安排规则审查（每月或每季度）
• 在架构决策发生变化时更新规则
• 对规则文件进行版本控制
• 在提交说明中记录规则变更

了解设计系统规则

设计系统规则将改变 AI 编码 Agent 使用 Figma 设计稿的方式：

使用规则之前：

• Agent 会自行假设组件结构
• 不同实现之间的样式处理方式不一致
• 硬编码的值与设计令牌不匹配
• 组件被创建在随意的位置
• 反复解释项目约定

使用规则之后：

• Agent 会自动遵循你的约定
• 组件结构和样式保持一致
• 从一开始就正确使用设计令牌
• 组件组织得当
• 无需反复提供提示词

投入时间制定优质规则，就能在每一项 Figma 实现任务中获得成倍回报。

更多资源

• Figma MCP 服务文档
• Figma 变量和设计令牌