create-design-system-rules

创建设计系统规则

概述

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

什么是设计系统规则？

设计系统规则是项目级指令，用于记录代码库中「未成文的知识」——也就是资深开发者掌握并会传授给新团队成员的经验：

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

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

前提条件

• 必须已连接并可访问 Figma MCP 服务
• 可以访问项目代码库以进行分析
• 了解团队的组件约定（或愿意建立这些约定）

何时使用此技能

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

• 启动一个将使用 Figma 设计的新项目
• 将 Claude 引入已有成熟模式的项目
• 在团队中统一 Figma 到代码的工作流
• 更新或优化现有设计系统约定
• 用户明确提出：「创建设计系统规则」「设置 Figma 指南」「为我的项目自定义规则」

必需工作流

按顺序完成以下步骤。请勿跳过任何步骤。

第 1 步：运行 Create Design System Rules 工具

调用 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 步：将规则保存到 CLAUDE.md

指导用户将生成的规则保存到项目根目录中的 CLAUDE.md 文件：

# MCP Servers

## Figma MCP Server Rules

[Paste generated rules here]

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

第 5 步：验证并迭代

创建规则后：

1. 使用简单的 Figma 组件实现进行测试
2. 验证 Claude 是否正确遵循规则
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. 保存到项目根目录下的 CLAUDE.md
5. 使用简单的按钮实现进行测试

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

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

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

操作：

1. 运行 create_design_system_rules(clientLanguages="typescript,javascript", clientFrameworks="vue")
2. 发现项目使用 CSS 模块和自定义设计令牌系统
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. 保存到项目根目录下的 CLAUDE.md
5. 使用卡片组件进行验证

结果： Claude 现在能够使用项目的设计令牌系统，正确地将 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. 保存到 CLAUDE.md 并与团队分享
5. 添加到团队文档中

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

最佳实践

从简单开始，逐步迭代

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

具体明确

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

让规则可执行

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

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

对关键规则使用 IMPORTANT

在绝不可违反的规则前加上“IMPORTANT:”，以确保 Claude 优先遵循这些规则。

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

常见问题和解决方案

问题：Claude 没有遵循规则

原因： 规则可能过于含糊，或者未正确加载到 IDE/MCP 客户端中。

解决方案：

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

问题：规则彼此冲突

原因： 规则相互矛盾或存在重叠。

解决方案：

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

问题：规则太多导致 Claude 变慢

原因： 规则过多会增加上下文大小和处理时间。

解决方案：

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

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

原因： 代码库发生变化，但规则没有更新。

解决方案：

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

了解设计系统规则

设计系统规则会改变 Claude 使用 Figma 设计稿的方式：

使用规则前：

• Claude 会对组件结构做出假设
• 不同实现采用的样式方式不一致
• 硬编码的值与设计令牌不匹配
• 组件被创建在随意的位置
• 需要反复解释项目约定

使用规则后：

• Claude 会自动遵循你的约定
• 组件结构和样式保持一致
• 从一开始就正确使用设计令牌
• 组件会被妥善组织
• 无需重复提示

在制定优质规则上投入的时间，会在每一项 Figma 实现任务中带来成倍回报。

其他资源

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