Knowledge RAG

设计知识库

由社区维护、审核后发布，并在 Agent 页面创作前被 RAG 检索为设计约束。

8 条已发布原则 / 全库 192 条

自定义交互组件在写样式前要先定义 native-first 决策、name/role/value、ARIA/DOM 状态、键盘矩阵、焦点路径、视觉状态和测试断言。

ARIA 不是给 div 补语义的魔法层；组件只有在原生语义、键盘行为、可访问名称、状态属性和视觉状态互相一致时，才是可实现的。

生成或接入组件前，先列出状态矩阵、交互触发、ARIA/DOM 表达、视觉 token 和测试路径，避免只完成静态默认态。

组件质量不是默认态截图，而是所有可达状态在鼠标、键盘、触控、读屏、加载、错误和权限限制下都保持可理解、可恢复、可测试。

手写复杂 widget 前，先从 WAI-ARIA APG 提取角色、状态、属性、键盘表、焦点策略和测试断言；能用原生或成熟 primitive 时不从零造。

ARIA 是语义和交互契约，不是给 div 补魔法属性。自定义 combobox、dialog、tabs、treegrid、menu、listbox 等组件必须先证明它们的键盘、焦点和辅助技术模型成立。

组件响应式不应只跟随 viewport；卡片、侧栏、图表和资源卡应根据自身容器宽度调整密度、层级和操作显隐。

Container queries 把响应式判断从页面级断点推进到组件级上下文，让同一组件能安全放进 grid、sidebar、drawer、modal 和 dashboard 插槽。

当交互包含焦点、键盘、浮层、方向键或屏幕阅读器语义时，优先选择成熟 primitive，再接入本地视觉系统。

复杂交互组件的风险通常不在样式，而在焦点管理、键盘路径、ARIA 语义、portal、碰撞定位和移动端滚动锁定。Primitive 的价值是把底层行为先稳定下来。

设计系统文档页把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。

组件需要明确 props、状态、尺寸和禁止组合，才能在页面间保持一致。

看起来相同的元素应承担相同功能；功能不同的元素必须有清楚差异。