AIOZ UI Skills

核心用法

AIOZ UI V3 Skill 是专为 Figma MCP → React 代码 翻译场景设计的开发辅助工具。核心工作流程包括：

1. 解析Figma MCP输出：接收带有斜杠分隔符的令牌（如 Onsf/Error/Default、Button/01），通过查表映射为对应的设计系统资源
2. 组件智能映射：根据Figma节点名称（如 Button/Primary、Fields/Default）自动匹配 @aioz-ui/core-v3/components 中的React组件
3. 变体转Props：将Figma变体字符串（Type=Primary, Size=Medium）转换为React组件props（variant="primary" size="md"）
4. 严格导入管控：区分三大导入路径——图表组件走 @aioz-ui/core/components，UI组件走 @aioz-ui/core-v3/components，图标统一使用 @aioz-ui/icon-react

显著优点

• 零猜测开发：所有令牌、类名、导入路径均通过查表确定，杜绝凭直觉编写
• 设计一致性保障：强制使用 text-content-sec、bg-sf-screen 等语义化令牌，禁止裸写 text-gray-500
• Figma到代码无缝衔接：直接消费Figma MCP的原生输出格式，无需人工转换
• 完整的组件覆盖：涵盖Button、Input、Badge、Table、Dialog、DatePicker等20+核心组件
• 图表专项支持：内置LineChart、AreaChart、BarChart、DonutChart的专用导入路径和封装规范

潜在局限性与风险

• 版本锁定依赖：严格绑定AIOZ UI V3特定版本，若设计系统升级可能导致映射表失效
• Figma MCP依赖：输出质量完全取决于Figma MCP工具的解析准确度，复杂嵌套结构可能识别偏差
• Tailwind耦合：深度依赖Tailwind CSS框架，非Tailwind项目无法直接使用
• 令牌学习成本：开发者需熟悉 --sf-neu-block、--text-neu-bold 等专有命名体系
• 图表路径陷阱：图表与普通组件分属不同包，极易误导入导致运行时错误

适合人群

• 使用AIOZ UI V3设计系统的React前端开发团队
• 需要快速将Figma设计稿转化为可交付代码的工程师
• 追求设计-开发严格一致性的中后台产品团队
• 熟悉Tailwind CSS且愿意遵循令牌优先规范的开发者

常规风险提示

1. 切勿混用导入路径：@aioz-ui/core/components 与 @aioz-ui/core-v3/components 不可混用，图表组件是唯一例外
2. 图标命名规范：必须使用PascalCase + "Icon"后缀（如 Search01Icon），禁止直接使用SVG或emoji
3. 状态委托CSS：State=Hover/Focused/Pressed 等变体不生成props，由CSS伪类处理，避免在React中手动管理
4. Typography原子性：text-body-02 等类已封装完整字体属性，禁止叠加额外font-size或font-weight工具类

核心用法

AIOZ UI V3 Skill 是专为前端开发者打造的 Figma → Code 转换工具，核心功能是将 Figma MCP 输出的设计数据映射为可直接运行的 React 组件代码。使用时，当用户上传 Figma 设计稿或描述 UI 需求，Agent 会自动解析节点名称、颜色令牌（如 Sf/Pri/Pri）、排版样式（如 Button/01）和变体参数（Type=Primary, Size=Medium），并输出精确的 import 语句和组件代码。

关键特性包括：

• 双路径导入体系：常规组件来自 @aioz-ui/core-v3/components，图表组件来自 @aioz-ui/core/components，图标统一从 @aioz-ui/icon-react 导入
• 完整组件映射表：覆盖 Button、Input、Badge、Table、Dialog、DatePicker 等 20+ 基础组件
• 设计令牌优先：强制使用 text-content-sec、bg-sf-screen 等语义化类名，禁止裸写 Tailwind 原始值
• 图表专项支持：内置 LineChart、AreaChart、BarChart、DonutChart 及配套 Legend、SeriesVisibility 钩子

显著优点

1. 零猜测开发：通过严格的映射表消除"该用哪个 token"的决策负担，确保代码与设计稿像素级一致
2. 企业级规范落地：内置 Token-First、Component-First、Typography-Atomic 三大铁律，从工具层面杜绝随意编写样式
3. Figma 生态闭环：直接消费 Figma MCP 的标准输出格式（slash-path tokens），无需手动转换变量名
4. 图表能力完备：区别于普通 UI 库技能，额外提供数据可视化组件的专用导入路径和配置规范
5. 纯文档零依赖：无可执行代码，不引入任何运行时风险，可放心接入 CI/CD 流程

潜在缺点与局限性

1. 生态绑定较深：强制依赖 @aioz-ui/core-v3 私有包体系，若项目未接入 AIOZ UI 则完全无法使用
2. 图表版本分裂：图表与常规组件分属两个 npm 包（core vs core-v3），版本同步维护成本较高
3. Figma MCP 依赖：需配合 Figma MCP Agent 使用，离线场景或设计稿解析失败时失去核心价值
4. 定制化受限：严格禁止裸写 Tailwind 类名，对于需要突破设计系统的边缘场景支持不足
5. 社区维护属性：T3 来源可信度，文档更新频率依赖个人开发者（datnguyen26730），缺乏商业 SLA 保障

适合的目标群体

• AIOZ 生态开发者：已使用或计划接入 AIOZ UI V3 的企业前端团队
• 设计系统落地工程师：负责将 Figma 设计稿转化为生产代码的 UI 开发岗位
• React + Tailwind 技术栈团队：寻求比原生 Tailwind 更严格的 Token 管理体系的项目
• 数据可视化需求场景：需要快速产出符合设计规范的图表页面的中后台产品

使用风险

| 风险类别 | 说明 |

|---------|------|

| **依赖可用性** | 需确保 `@aioz-ui/core-v3/components` 和 `@aioz-ui/icon-react` 已在项目正确安装，否则生成的代码无法运行 |

| **版本漂移** | AIOZ UI 设计令牌变更后，Skill 文档若未及时同步，可能导致生成的类名在新版本中失效 |

| **图表配置复杂度** | 图表组件要求必须提供 `categories` 和 `overwriteCategories`，遗漏会导致渲染失败，需额外阅读 `references/charts.md` |

| **图标命名陷阱** | 图标导入需严格遵循 PascalCase + "Icon" 后缀（如 `Wallet01Icon`），大小写错误将导致构建失败 |

| **设计系统冲突** | 若项目同时存在其他 UI 库（如 Ant Design、Material-UI），混合使用可能引发样式冲突 |