frontend-component-build

Frontend Component Build 是一个专注于“把组件实现好”的技能，采用与具体框架无关的原则，大多数模式可迁移到 React、Vue、Svelte 或原生 Web Components。它强调组件实现层面的质量，而非更宏观的系统设计或日常视觉决策。

用途

该技能适用于以下场景：从零构建新组件；重构现有组件；设计组件 API（props、slots、events）；为现有组件添加无障碍支持；依据设计稿实现组件。

它不适用于：构建完整设计系统；页面级设计决策；后端或数据工作；仅做性能优化。

主要能力：框架的六个维度

该技能认为一个完整组件需要处理六个维度，缺少任何一个都算不完整。

解剖结构（Anatomy）：在编写任何标记之前，先识别组成组件的各个部分。常见解剖结构包括：Button（容器 + 标签 + 可选图标 + 可选加载指示器）、Modal（背景遮罩 + 容器 + 头部 + 主体 + 底部 + 关闭入口）、Form input（标签 + 输入框 + 可选帮助文本 + 可选错误消息）、Card（容器 + 可选头部 + 主体 + 可选底部 + 可选媒体）。提前命名各部分能让 API 更清晰。
变体（Variants）：组件支持哪些变化？包括视觉变体（primary、secondary、ghost、danger）、尺寸变体（small、medium、large）、功能变体（带图标、不带图标、仅图标）。变体应是一组受管理的集合，而非随意扩展；应记录支持的集合，并在没有真实用例时拒绝新增变体。
状态（States）：组件必须处理哪些状态？包括默认、悬停（支持指针时）、聚焦（始终需要，键盘导航依赖它）、激活/按下、禁用、加载（适用时）、错误（用于输入、表单、校验绑定组件）、空状态（用于展示数据的组件）。每个状态都需要视觉处理和无障碍处理。
Props / API：设计组件的契约。API 设计原则包括：必需 props 尽量少；布尔 props 是危险信号，三个布尔意味着七种组合，优先使用枚举字符串，例如 variant: "primary" | "secondary" | "ghost"，而不是 primary={true} ghost={false}；子内容优先于 props，内容就是内容时应接受 children，不要用 slots 能解决的事却发明 headerText 和 bodyText；组合优先于配置，一个通过 12 个 props 做 5 件事的组件，往往应该拆成 5 个更小的组件；为 props 添加类型，TypeScript、PropTypes 或 JSDoc 皆可，类型是不会过期的文档。
无障碍（Accessibility）：从一开始就构建无障碍，后期添加难度会高 5 倍。通用要求包括：使用语义化 HTML 元素（<button>、<a>、<nav>、<form> 等）而非通用 <div>；可键盘导航（Tab、Shift+Tab、按钮的 Enter/Space）；聚焦可见；点击目标最小 44×44 像素；仅在语义 HTML 不足时使用 ARIA。组件特定要求包括：Button 使用 <button>，不要用 <div> 伪造；Modal 需要焦点陷阱、ESC 关闭、关闭后焦点返回触发元素、role="dialog" 和 aria-labelledby；Form input 通过 for/id 或 aria-labelledby 关联标签，错误消息通过 aria-describedby 关联，错误状态使用 aria-invalid；Toggles 使用带 aria-pressed 的 <button> 表示两态，或使用 role="switch" 表示开关；Tabs 使用 role="tablist" / role="tab" / role="tabpanel"，配合 aria-selected 和方向键导航；Tooltips 和 popovers 需同时由聚焦和悬停触发，并可用 ESC 关闭；加载状态用 aria-live 宣告，让屏幕阅读器知道发生了变化。
测试（Tests）：在宣布完成前验证组件可用。按优先级排列的测试类型包括：视觉回归（在各变体和状态下正确渲染，可用 Storybook + 视觉差异工具或手动截图）；无障碍（通过 axe 或等效自动化检查）；键盘导航（Tab、Enter、Escape、方向键均按预期工作）；组件逻辑（props 产生预期输出，事件正确触发，单元测试）；集成（组件在预期的父级上下文中正常工作）。没有至少自动化无障碍测试的组件不算完成。

使用方式：工作流程

理解用例：该组件服务什么 UI 需求？会出现在哪里？相邻组件是什么？2. 勾勒解剖结构：命名各部分。3. 列出变体和状态：匹配设计系统，必要时定义新的。4. 设计 API：必需 props、可选 props、children、events，并添加类型。5. 用语义 HTML 构建标记：选择正确元素，避免用通用 <div> 做交互。6. 用 token 设置样式：不要硬编码颜色、间距或尺寸。7. 添加交互：焦点管理、键盘处理器、ARIA。8. 添加状态：悬停、聚焦、激活、禁用、加载、错误。9. 测试：自动化无障碍、键盘导航、视觉回归。10. 文档：用法、API、示例、反模式。

适用场景与限制

该技能适合组件实现层面的工作，包括新组件开发、重构、API 设计、无障碍增强和设计稿落地。它明确不覆盖完整设计系统构建、页面级设计决策、后端或数据工作以及纯性能优化。其原则与框架无关，但具体实现需结合所选框架。

失败模式

技能列出了常见失败模式：用 <div onClick> 构建，丢失键盘无障碍、屏幕阅读器语义和焦点，应使用 <button> 或 <a>；硬编码颜色和尺寸，抵抗主题化和一致性；布尔 prop 爆炸，例如 <Button primary large rounded fullWidth disabled icon />，过多布尔意味着需要更少但更经过深思的变体；忘记聚焦状态，悬停受关注而聚焦被忽视，键盘用户会看到不可见的按钮；跳过禁用状态思考，禁用按钮应看起来明显禁用、具有 aria-disabled 且不响应点击；发明 ARIA，ARIA 角色和属性有特定行为，编造的 ARIA 比没有 ARIA 更糟，应优先使用语义 HTML；加载状态不宣告，屏幕阅读器不知道 spinner 出现，应使用 aria-live="polite" 或 role="status"；仅靠 tooltip 承载关键内容，仅悬停内容对键盘和触摸用户不可见，关键内容应放在可见 UI 中；组件没有文档，未来的自己、队友或下一位维护者无法使用他们无法理解的东西。

输出格式

完整的组件交付包括：组件代码（使用适当框架）；Storybook（或等效物）条目，展示所有变体和状态；文档（解剖图或描述、Props/API 表、用法示例包括基础/高级/边界情况、何时使用与何时使用替代方案、反模式、无障碍说明）；测试（视觉回归 + 无障碍 + 逻辑）。

参考文件

references/component-spec-template.md：在构建前记录组件（props、状态、无障碍、边界情况）的模板。references/component-api-patterns.md：设计灵活组件 API 的常见模式（复合组件、受控与非受控、多态 as prop、render props、slots）。references/accessibility-patterns.md：常见交互组件的 ARIA 模式。

技能介绍