组件状态矩阵契约

大理论

设计系统组件的真实复杂度藏在状态组合里。按钮、输入框、菜单、弹窗、表格行和空状态都不止 default/hover 两种样子；它们需要把 enabled、hover、active、focus-visible、disabled、read-only、loading、selected、expanded、empty、error、warning、success、destructive、skeleton、reduced-motion 和 forced-colors 等状态变成明确契约。没有状态矩阵，agent 很容易生成“好看的默认态”和一堆漏掉的边界。

小知识点

1. 每个组件先写状态清单，再写视觉：状态名、触发方式、是否可聚焦、是否可点击、是否需要 live region、是否保留布局尺寸。
2. disabled、read-only、loading 是不同状态：disabled 不可操作，read-only 可阅读不可编辑，loading 可能需要阻止重复提交但仍解释正在发生什么。
3. focus-visible 必须有真实 outline 或边框，不要只用阴影；图标按钮必须有可访问名称。
4. error/warning/success 不能只靠颜色；需要文字、图标、边框、aria-describedby 或 status message。
5. selected/expanded/current/pressed 要映射到正确语义，例如 aria-selected、aria-expanded、aria-current、aria-pressed，不要只加 class。
6. skeleton、empty、loading、error 和 retry 需要固定尺寸，避免数据到达时布局跳动。

设计判断

如果一个组件矩阵能回答“这个状态如何进入、如何退出、用户能否操作、读屏听到什么、视觉 token 是什么、如何测试”，它才准备好进入库。只画 default/hover 的组件仍是视觉片段，不是可调用技能资产。

实现建议

为每个组件输出 state matrix：state、trigger、visual tokens、DOM/ARIA、keyboard behavior、pointer behavior、copy、layout stability、recovery action、test assertion。实现时优先使用 data attributes 或 explicit props 表达状态，例如 data-state="open"、aria-busy、disabled、aria-invalid。测试至少覆盖默认态、键盘 focus、禁用态、加载态、错误态、移动端和 reduced-motion/forced-colors 的关键分支。

反例/风险

把 loading button 做成 disabled 但没有进度文案；表单 error 只有红色边框；菜单 hover 有样式但键盘 focus 没样式；弹窗 skeleton 加载后高度变化；selected tab 只靠颜色；destructive action 与普通 action 共用按钮变体。

案例分析

Carbon 的 Button 和 Text Input 指南强调组件状态、焦点和 error/warning/disabled/read-only 等差异；Material Design 3 states 说明 disabled 组件不能被 focus、drag 或 press；Radix Primitives 把复杂组件状态通过行为和 ARIA/focus 管理稳定下来；NN/g 也强调按钮至少需要 enabled、disabled、hovered、focused、pressed 等可区分状态。可学习点是：状态不是视觉附录，而是组件 API、可访问性和 QA 的共同契约。

来源链接

Carbon Button: https://carbondesignsystem.com/components/button/usage/ Carbon Text Input: https://carbondesignsystem.com/components/text-input/usage/ Carbon Disabled States: https://carbondesignsystem.com/patterns/disabled-states/ Material Design States: https://m3.material.io/foundations/interaction/states/applying-states Radix Accessibility: https://www.radix-ui.com/primitives/docs/overview/accessibility NN/g Button States: https://www.nngroup.com/articles/button-states-communicate-interaction/