figma-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 设计的新项目
• 为已有既定模式的项目配置 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 前置内容（description、globs、alwaysApply）的 Markdown。

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

对于 Cursor，请使用 YAML 前置内容包裹规则：

---
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 组件，并设置变体属性（'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 变量和设计令牌