Knowledge RAG

设计知识库

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

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

玻璃、acrylic、mica、smoke 和 backdrop blur 不能只是风格滤镜；它们必须明确 surface role、背景可变性、层级、对比度、用户偏好、forced-colors 和 fallback。

半透明材质的价值是把界面层级和背景上下文连接起来；如果它降低阅读、状态识别、键盘焦点或可访问偏好，它就应该退回不透明 surface。

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

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

上传组件不是一个虚线框，而是一套从选择、校验、上传、暂停、失败、重试到最终文件记录的状态机器；拖放只能是增强，不能替代可访问文件选择和服务端校验。

文件上传同时涉及交互、网络、隐私、安全和可访问性。健康上传体验先定义文件目的、限制、API、状态和失败恢复，再选择 react-dropzone、Uppy、FilePond、tus-js-client 或原生 input。

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

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

复制外部动效组件、Lottie/Rive 播放器、Motion/GSAP 示例或 registry block 后，要把文字、状态、方向、时长、reduced-motion、pause/stop/hide、键盘路径和授权来源改成本地契约。

动效组件复制进仓库后不再是演示片段，而是本地交互资产。它必须同时满足品牌语气、语言方向、可访问降级、性能预算和来源授权。

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

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

复杂数据表在移动端不能只缩小字号或强塞横向滚动；必须定义主键、列优先级、替代表达、表头关联和批量/行内操作边界。

数据表是一种比较结构。响应式处理要保护比较关系和可访问语义，而不是只保护桌面视觉外观。

纹理背景应作为次级层级接入 token、CSS/SVG 输出和降级策略；在 forced-colors、打印、移动端和低带宽下仍要保留可读界面。

背景纹理的价值是增加表面深度、品牌语气或冗余编码，不是抢走信息层级。生产实现必须把纹理当作可关闭、可压缩、可替换的 surface layer。

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

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

加载状态要按时长、范围和可测进度选择 skeleton、inline loading、spinner、进度条或阶段反馈，并用前端状态机保证可访问、稳定和可恢复。

加载反馈的目标不是让等待更花哨，而是让用户知道系统是否响应、哪里正在变化、是否还能行动、等待是否可估计、失败后如何恢复。不同等待场景需要不同的反馈模式。