设计知识库
由社区维护、审核后发布，并在 Agent 页面创作前被 RAG 检索为设计约束。
滚动容器归属契约
长页面、库页面和工作台必须明确唯一主滚动容器；嵌套 `height: 100vh`、`overflow: hidden/auto` 和 sticky 面板前要先声明滚动归属。
滚动不是浏览器附带行为，而是布局契约。谁拥有页面滚动、谁拥有局部滚动、哪些面板 sticky、移动端如何 reflow，都要在实现前确定。97%Frontend Implementationmaterial / glass半透明材质可读性契约
玻璃、acrylic、mica、smoke 和 backdrop blur 不能只是风格滤镜；它们必须明确 surface role、背景可变性、层级、对比度、用户偏好、forced-colors 和 fallback。
半透明材质的价值是把界面层级和背景上下文连接起来；如果它降低阅读、状态识别、键盘焦点或可访问偏好，它就应该退回不透明 surface。96%Frontend Implementationaria / componentsARIA 组件契约
自定义交互组件在写样式前要先定义 native-first 决策、name/role/value、ARIA/DOM 状态、键盘矩阵、焦点路径、视觉状态和测试断言。
ARIA 不是给 div 补语义的魔法层；组件只有在原生语义、键盘行为、可访问名称、状态属性和视觉状态互相一致时，才是可实现的。96%Interaction Responsive Motionoverlay / dialog浮层焦点与滚动锁契约
浮层不是一层遮罩，而是 modality、初始焦点、焦点循环、关闭规则、背景 inert、滚动锁、portal 层级和移动端安全区的联合契约。
只要浮层改变用户可交互范围，就必须同时治理键盘、读屏、指针、滚动和移动端行为；视觉上盖住背景但语义上仍可达，是最危险的假 modal。96%Frontend Implementationupload / dropzone文件上传状态与校验契约
上传组件不是一个虚线框，而是一套从选择、校验、上传、暂停、失败、重试到最终文件记录的状态机器；拖放只能是增强，不能替代可访问文件选择和服务端校验。
文件上传同时涉及交互、网络、隐私、安全和可访问性。健康上传体验先定义文件目的、限制、API、状态和失败恢复，再选择 react-dropzone、Uppy、FilePond、tus-js-client 或原生 input。96%Frontend Implementationcomponents / states组件状态矩阵契约
生成或接入组件前，先列出状态矩阵、交互触发、ARIA/DOM 表达、视觉 token 和测试路径，避免只完成静态默认态。
组件质量不是默认态截图，而是所有可达状态在鼠标、键盘、触控、读屏、加载、错误和权限限制下都保持可理解、可恢复、可测试。95%Frontend Implementationcopy-in / motionCopy-in 动效组件本地化与可访问性
复制外部动效组件、Lottie/Rive 播放器、Motion/GSAP 示例或 registry block 后，要把文字、状态、方向、时长、reduced-motion、pause/stop/hide、键盘路径和授权来源改成本地契约。
动效组件复制进仓库后不再是演示片段，而是本地交互资产。它必须同时满足品牌语气、语言方向、可访问降级、性能预算和来源授权。95%Frontend Implementationaria / apgARIA APG 组件模式契约
手写复杂 widget 前，先从 WAI-ARIA APG 提取角色、状态、属性、键盘表、焦点策略和测试断言；能用原生或成熟 primitive 时不从零造。
ARIA 是语义和交互契约，不是给 div 补魔法属性。自定义 combobox、dialog、tabs、treegrid、menu、listbox 等组件必须先证明它们的键盘、焦点和辅助技术模型成立。95%Interaction Responsive Motionscroll / horizontal横向滚动作品集边界
横向滚动适合有限作品集、画廊和项目序列，不适合长正文、文档和核心任务流程。
横向滚动必须是一种明确内容格式：用户看得见下一项、能用键盘和触控操作、能在窄屏重排，并且核心文字不被藏进横轴。95%Interaction Responsive Motionmotion / scroll滚动叙事章节契约
滚动叙事的基本单位不是动画帧，而是可读章节：每章要有明确问题、文本锚点、视觉状态、静态 fallback 和可验证的滚动行为。
滚动叙事应把复杂机制拆成用户可停留、可跳过、可回到的证据链；动效只负责连接章节和状态，不应成为唯一内容载体。95%Design Systems Page Patternspublic-service / trust公共服务信任锚点与恢复路径
公共服务界面必须把官方身份、负责机构、法定链接、任务标题、表单语义、错误摘要和恢复路径做成可验证的页面结构，而不是只套蓝白政务视觉。
公共服务的信任来自可检查的责任链和可恢复的任务流：用户需要知道是否官方、谁负责、信息是否安全、为什么需要填写、出错后如何修复、以及去哪里查看隐私/无障碍/监督信息。95%Frontend Implementationtables / responsive响应式数据表披露契约
复杂数据表在移动端不能只缩小字号或强塞横向滚动；必须定义主键、列优先级、替代表达、表头关联和批量/行内操作边界。
数据表是一种比较结构。响应式处理要保护比较关系和可访问语义，而不是只保护桌面视觉外观。95%Design Systems Page Patternsinformation-architecture / navigation信息气味与链接标签契约
导航、卡片和正文链接必须让用户在点击前判断目的地、价值和成本；模糊的“了解更多”会削弱查找效率和可访问性。
信息气味来自链接文字、周围语境和用户已有经验。设计系统应把链接标签当成信息架构的一部分，而不是按钮文案的最后填空。95%Data Visualizationmap / poi地图 POI 图标归因边界
Maki 这类 POI 图标集只解决地图符号，不等于解决地图数据、瓦片、样式、底图 provider、地点标签和交互归因。
地图符号是一层视觉编码。agent 必须把 icon set、sprite、地图样式、地理数据、瓦片 provider、图例和可访问标签分开治理，避免把图标许可误当地图许可。95%Data Visualizationmaps / geospatial地图数据归因与替代路径
地图界面必须把运行时库、瓦片、样式、glyph、sprite、地理数据和 provider 归因分别记录，并提供列表/表格替代和键盘可达路径。
地图不是一张背景图。它是复杂数据可视化、交互控件和授权对象的组合；用户必须能理解位置、范围、选中对象、数据来源、更新时间和替代访问方式。95%Data Visualizationaccessibility / charts可访问图表替代说明
图表需要标题结论、文本摘要、冗余编码和数据表替代；Canvas 或 SVG 本身不能自动等于可访问。
数据可视化是一种非文本内容和交互内容。它必须让看不见图、无法辨色、只用键盘、缩放页面或使用屏幕阅读器的人获得等价结论和数据路径。95%Resource Licensingavatar / placeholder确定性头像占位治理
Boring Avatars、DiceBear 这类头像生成器适合做身份占位，但必须记录 seed、样式、授权、隐私输入和可访问名称，不能把生成图当真人肖像或品牌资产。
确定性头像的价值是稳定识别同一对象，而不是提供真实身份。它同时涉及视觉区分、隐私、授权、可访问标签和跨项目复用边界。95%Interaction Responsive Motionforms / validation表单错误状态契约
表单错误状态契约把 label、帮助文本、验证时机、内联错误、错误摘要、提交状态、服务端失败、移动键盘和 ARIA 连接放进同一个可实现模型。
表单错误不是某个红色组件，而是字段契约、状态机和恢复路径的组合；它应路由到更细的错误摘要、可访问反馈、标签持久性和事务型恢复知识。95%Resource Licensingbrand-logo / trademark品牌 Logo 使用边界
品牌 logo 只能在真实品牌引用、集成、支付方式、客户/伙伴证明或授权合作中使用；必须确认商标/品牌指南、不得暗示背书、不得随意改形改色，并提供可访问名称。
品牌 logo 不是普通 icon。开源项目、聚合站或 SVG 包的代码许可，通常不能替代商标、品牌指南、背书语境和使用范围判断。95%Resource Licensingicons / license图标集授权、商标与可访问治理
图标不是可随意混搭的装饰素材；主图标集、聚合图标、品牌 logo 和 icon-only 控件分别需要授权、商标、导入和可访问规则。
图标治理的目标是让界面符号一致、可合法复用、可被读屏理解、可被 tree-shake，并且不把品牌 logo 当作自由装饰或背书。95%Resource Licensingvideo / motionStock Video 首屏与背景治理
免费 stock video 可以让首屏更真实，但必须同时确认具体授权、人物/商标/地点权利、署名、poster、暂停控制、reduced-motion 和移动端性能。
背景视频不是动态壁纸。它只有在服务首屏信号、品牌语气或叙事证据，并且不破坏阅读、可访问性、授权和性能时，才适合进入生产界面。95%Resource Licensingillustration / empty-state友好素材在空状态中的治理
插画、emoji 和 Lottie 可以让空状态更亲切，但必须先服务原因、下一步行动、授权记录、替代文本和 reduced-motion。
友好素材不是空状态的主角。它只能强化语气、降低焦虑或帮助理解；真正的界面价值来自清楚说明为什么为空、用户下一步能做什么、素材是否可合法复用。95%Typography Color Accessibilitycharts / accessibility图表可访问编码
图表可访问编码把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
可访问图表不是给图像加一句 alt，而是让视觉编码、文字总结、交互状态和数据替代路径共同传达同一证据。94%Typography Color Accessibilitybackground / texture装饰背景可读性
纹理、图案、渐变、噪声和媒体背景必须服从文字、控件、语义和性能，而不是把内容压成氛围图。
背景是层级和氛围的支持层；一旦承载信息、影响阅读或移动，它就需要语义替代、对比证据、运动降级和授权记录。94%Interaction Responsive Motionforms / errors事务型表单错误恢复
高信任表单的错误处理不是提示用户错了，而是把用户带回可修复、可继续、无需重填的状态。
事务型服务的错误恢复必须同时处理可见位置、屏幕阅读器、焦点、原始输入、错误文案和下一步行动。94%Frontend Implementationbackground-texture / css背景纹理 CSS 与可访问 fallback
纹理背景应作为次级层级接入 token、CSS/SVG 输出和降级策略；在 forced-colors、打印、移动端和低带宽下仍要保留可读界面。
背景纹理的价值是增加表面深度、品牌语气或冗余编码，不是抢走信息层级。生产实现必须把纹理当作可关闭、可压缩、可替换的 surface layer。94%Frontend Implementationcomponents / radixPrimitive 组件选择
当交互包含焦点、键盘、浮层、方向键或屏幕阅读器语义时，优先选择成熟 primitive，再接入本地视觉系统。
复杂交互组件的风险通常不在样式，而在焦点管理、键盘路径、ARIA 语义、portal、碰撞定位和移动端滚动锁定。Primitive 的价值是把底层行为先稳定下来。92%Typography Color Accessibilitycolor / contrast对比度生成色阶
用目标对比度生成色阶可以提高主题可访问性，但生成结果必须再映射为语义 token 和状态用途。
可访问色彩系统不应在设计结束后才审计对比度，而应把对比度目标前置到色阶生成和 token 命名中。92%Frontend Implementationloading / skeleton加载骨架进度契约
加载状态要按时长、范围和可测进度选择 skeleton、inline loading、spinner、进度条或阶段反馈，并用前端状态机保证可访问、稳定和可恢复。
加载反馈的目标不是让等待更花哨，而是让用户知道系统是否响应、哪里正在变化、是否还能行动、等待是否可估计、失败后如何恢复。不同等待场景需要不同的反馈模式。90%Interaction Responsive Motionmodal / focus弹窗焦点管理
弹窗焦点管理把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
弹窗改变了交互上下文，必须管理焦点、背景可达性和关闭路径。87%Interaction Responsive Motiongesture / mobile触控手势替代路径
触控手势替代路径把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
滑动、捏合和长按不能成为完成任务的唯一方式。86%Interaction Responsive Motiondrag-drop / accessibility拖拽替代控件
拖拽替代控件把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
拖拽适合直接操作，但排序、移动和上传必须有非拖拽路径。86%Interaction Responsive Motionkeyboard / navigation键盘优先导航
键盘优先导航把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
可键盘完成的界面通常也更清晰，因为焦点顺序暴露了真实任务结构。86%Typography Color Accessibilitymotion / reduced-motion减少动效可访问性
减少动效可访问性把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
动画和过渡需要尊重用户的减少动态偏好，并提供不依赖动效的信息路径。86%Typography Color Accessibilityforms / labels表单标签持久可见
表单标签持久可见把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
表单字段标签应在输入前后都可见，帮助用户确认字段含义和上下文。86%Typography Color Accessibilityauthentication / accessibility可访问认证流程
可访问认证流程把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
安全流程也要降低认知负担，帮助用户完成而不是考验用户。86%Typography Color Accessibilityforms / errors错误摘要模式
错误摘要模式把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
用户需要先知道有多少错误、在哪里、如何修复，而不是逐行搜索红字。86%Typography Color Accessibilitytarget-size / touch目标尺寸与间隔
目标尺寸与间隔把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
点击目标要有足够尺寸和间隔，尤其在移动端、工具栏和密集列表中。86%Typography Color Accessibilitylinks / contrast链接对比与可供性
链接对比与可供性把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
链接是导航承诺，用户必须能在阅读流中快速识别可点击文本。85%Typography Color Accessibilitycognitive-load / copy降低认知负担的文案
降低认知负担的文案把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
用户不应该为了完成任务记住系统状态、上一屏信息或隐含规则。84%Typography Color Accessibilitycontent / plain-language清晰语言
清晰语言把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
可理解性是可访问性的一部分，复杂文案会增加所有人的认知负担。84%Typography Color Accessibilityicons / aria图标可访问名称
图标可访问名称把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
只有图标的按钮和状态必须有可访问名称，装饰图标则应从辅助技术中隐藏。84%Typography Color Accessibilitytypography / spacing文本间距韧性
文本间距韧性把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
界面应能承受用户调整行高、字距、字号或浏览器缩放后仍不遮挡内容。84%Typography Color Accessibilityforms / redundant-entry减少重复输入
减少重复输入把一个高频界面判断转成可执行约束，帮助 Agent 在生成前做出更具体的布局、交互或可访问性选择。
重复输入增加认知负担、错误率和放弃率，尤其影响辅助技术用户。84%Interaction Responsive Motionmotion / animation克制且有目的的动效
动效应解释状态变化、空间关系或反馈，而不是单纯制造热闹。
过度动效会打断任务，尤其在高密度工具中。82%Typography Color Accessibilitytouch-target / mobile可访问交互目标
按钮、链接、菜单项和图标按钮需要足够命中区域，移动端尤其不能只看视觉尺寸。
视觉小不等于点击区域小；交互目标需要稳定尺寸和明确反馈。82%Typography Color Accessibilityaccessibility / color颜色不能单独传达含义
状态、风险、分类和选中不能只靠颜色表达，必须有文字、图标、形状或位置辅助。
色盲、低视力、打印和弱光场景都会削弱颜色语义。82%Typography Color Accessibilityfocus / keyboard可见焦点状态
键盘和辅助技术用户需要清楚知道当前焦点在哪里，焦点态不能被 reset 掉。
焦点态是交互路径的一部分，不是浏览器默认样式的瑕疵。82%Typography Color Accessibilityforms / accessibility可访问表单反馈
表单反馈要靠近字段、解释原因，并在提交前后都能被用户理解。
错误信息不是惩罚，而是帮助用户完成任务的导航。82%Typography Color Accessibilitycontrast / accessibility可读性对比
文本对比必须优先服务阅读，尤其是小字号、禁用态、次级说明和按钮文字。
低对比会让精致感变成不可用，特别是在移动端和弱光环境。82%