设计知识库
由社区维护、审核后发布，并在 Agent 页面创作前被 RAG 检索为设计约束。
半透明材质可读性契约
玻璃、acrylic、mica、smoke 和 backdrop blur 不能只是风格滤镜；它们必须明确 surface role、背景可变性、层级、对比度、用户偏好、forced-colors 和 fallback。
半透明材质的价值是把界面层级和背景上下文连接起来；如果它降低阅读、状态识别、键盘焦点或可访问偏好，它就应该退回不透明 surface。96%Frontend Implementationai-ui / citationsAI 答案引用与证据面契约
AI/RAG 答案的引用不是页脚装饰，而是 claim、source、snippet、权限、streaming 状态、复制/分享和审计行为共同组成的证据面。
可信 AI 界面要让用户知道哪些结论有来源、来源是否可访问、证据何时生成、如何打开或复制，以及缺失/过期/低置信来源如何处理。96%Frontend Implementationapi-reference / openapiAPI Reference 端点页面契约
API 端点页应把 method/path、鉴权、参数、请求体、响应/错误矩阵、示例、try-it 安全和移动端 schema 阅读收敛成一个可执行文档契约。
API reference 不是把 OpenAPI schema 渲染出来就结束。它是开发者执行任务的操作面，必须同时服务发现、首次调用、鉴权配置、错误恢复、复制示例、试运行安全和版本信任。96%Frontend Implementationdeveloper-docs / code-block开发者文档代码示例与复制契约
开发者文档中的代码块不仅要高亮好看，还要说明任务、可安全复制、反馈清楚、tabs 可键盘操作、移动端不破坏页面滚动。
代码示例是产品操作面。它同时承担教学、配置、API 调用、信任和执行成本，因此必须把语法高亮、复制、占位符、tabs、playground、响应式和可访问反馈作为一套组件契约。96%Frontend Implementationaria / componentsARIA 组件契约
自定义交互组件在写样式前要先定义 native-first 决策、name/role/value、ARIA/DOM 状态、键盘矩阵、焦点路径、视觉状态和测试断言。
ARIA 不是给 div 补语义的魔法层；组件只有在原生语义、键盘行为、可访问名称、状态属性和视觉状态互相一致时，才是可实现的。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%Frontend Implementationscroll / motion滚动联动动效实现边界
滚动动效要区分 CSS scroll timeline、GSAP ScrollTrigger、Lenis smooth scroll 和普通原生滚动；不要为了沉浸感破坏阅读、锚点、键盘和移动端手感。
滚动是用户控制阅读节奏的输入，不是动画导演的时间轴。实现应优先保留原生滚动语义，再为确有价值的局部段落绑定轻量动效。95%Frontend Implementationtables / responsive响应式数据表披露契约
复杂数据表在移动端不能只缩小字号或强塞横向滚动；必须定义主键、列优先级、替代表达、表头关联和批量/行内操作边界。
数据表是一种比较结构。响应式处理要保护比较关系和可访问语义，而不是只保护桌面视觉外观。95%Frontend Implementationcontainer-query / responsiveContainer Query 组件响应式契约
组件响应式不应只跟随 viewport；卡片、侧栏、图表和资源卡应根据自身容器宽度调整密度、层级和操作显隐。
Container queries 把响应式判断从页面级断点推进到组件级上下文，让同一组件能安全放进 grid、sidebar、drawer、modal 和 dashboard 插槽。95%Frontend Implementation3d / three.jsWeb 3D 素材运行时管线
Three.js 页面不是只放一个 canvas；3D 素材要同时定义来源授权、glTF 优化、纹理压缩、加载状态、交互目标、fallback 和验证证据。
Web 3D 是设计、素材、运行时和性能预算的组合。agent 只有先治理模型来源、几何复杂度、纹理格式、降级路径和可访问说明，才能安全生成 3D 体验。95%Frontend Implementationview-transition / navigationView Transition 路由连续性
View Transition API 能让路由、筛选和详情切换更连续，但必须保留 URL、焦点、滚动、reduced-motion 和渐进增强边界。
页面转场的目标不是炫技，而是让用户理解同一对象在列表、详情、筛选和状态变化之间的连续关系。94%Frontend Implementationa11y-testing / axe-core自动化可访问性工具分诊
axe-core、Storybook a11y、Pa11y、Lighthouse、Accessibility Insights 和 WAVE 应分层使用：自动化先抓常见问题，人工再验证任务流。
自动化可访问性测试是早期预警系统，不是完整合规证明。健康流程会把工具结果转成可复现、可修复、可复测的产品任务缺陷。94%Frontend Implementationbackground-texture / css背景纹理 CSS 与可访问 fallback
纹理背景应作为次级层级接入 token、CSS/SVG 输出和降级策略；在 forced-colors、打印、移动端和低带宽下仍要保留可读界面。
背景纹理的价值是增加表面深度、品牌语气或冗余编码，不是抢走信息层级。生产实现必须把纹理当作可关闭、可压缩、可替换的 surface layer。94%Frontend Implementationcss-color / oklchCSS 色彩空间与色域回退
现代 CSS 支持 OKLCH、P3 和相对颜色，但生产 token 仍要照顾 sRGB、旧工具链、截图测试和第三方渲染器。
前端色彩实现要区分设计源、现代 CSS 输出和兼容 fallback；不能把浏览器支持当作所有工具链都支持。93%Frontend Implementationcomponents / radixPrimitive 组件选择
当交互包含焦点、键盘、浮层、方向键或屏幕阅读器语义时，优先选择成熟 primitive，再接入本地视觉系统。
复杂交互组件的风险通常不在样式，而在焦点管理、键盘路径、ARIA 语义、portal、碰撞定位和移动端滚动锁定。Primitive 的价值是把底层行为先稳定下来。92%Frontend Implementationshadcn / component-governanceCopy-in 组件治理
shadcn/ui 这类复制源码组件进入项目后就变成本地资产，必须有 token 映射、状态矩阵、升级策略和授权记录。
复制源码组件的优势是可控和可改，代价是项目团队自己承担一致性、升级、授权声明和设计系统适配。91%Frontend Implementationloading / skeleton加载骨架进度契约
加载状态要按时长、范围和可测进度选择 skeleton、inline loading、spinner、进度条或阶段反馈，并用前端状态机保证可访问、稳定和可恢复。
加载反馈的目标不是让等待更花哨，而是让用户知道系统是否响应、哪里正在变化、是否还能行动、等待是否可估计、失败后如何恢复。不同等待场景需要不同的反馈模式。90%