选择 UI 资源与控件

在实现或替换任意可见前端元素前，请先执行本工作流。

核心原则

禁止将行为、动态数据或可编辑文本编码进图片中。 当受控视觉资源（controlled visual asset）为事实来源（source of truth）时，禁止使用 CSS 重新构建丰富的品牌视觉素材。

🔴 检查点 — 在将任何行为、动态数据或可编辑文本编码进图片前，🛑 立即停止，并改用真实控件或 HTML/CSS 实现。图片仅应用于静态品牌/内容媒体。

工作流

1. 对元素进行分类

记录该元素属于以下哪一类：

• 品牌或编辑类视觉素材；
• 内容媒体；
• 操作或输入控件；
• 状态指示器；
• 简单符号；
• 动态可视化图表；
• 装饰性动效；
• 复杂交互式场景。

2. 核查其必需的行为特性

请思考并确认：

• 它是否会随后端数据变化而更新？
• 是否必须支持点击、获得焦点、被选中、禁用或校验？
• 其中的文本是否必须保持可搜索、可选中或可编辑？
• 是否需在不同视口宽度下清晰缩放？
• 辅助技术（assistive technology）是否必须能正确识别它？
• 是否需要动画或指针交互能力？
• 精确的品牌外观表现，是否比结构上的灵活性更重要？

查阅 references/decision-matrix.md，从中选择满足全部必需行为的、复杂度最低的实现方案。

3. 定义资源契约（Asset Contract）

针对每个外部资源，须明确定义以下内容：

• 用途及所属方（owner）；
• 原始尺寸与宽高比；
• 显示尺寸及响应式行为；
• 透明度要求；
• 裁剪行为（crop behavior）；
• 最大文件大小及首选格式；
• 加载逻辑与缺失资源回退策略（fallback）；
• 是否允许在资源内部嵌入文本。

在请求或接收生产环境资源前，请务必阅读 references/asset-contracts.md。 如需参考当前项目中已验证的案例，请查阅 references/project-decisions.md。

4. 保障交互语义完整性

对所有操作与输入类元素，必须使用真实控件（real controls），并确保保留以下特性：

• 焦点管理与键盘操作行为；
• 禁用（disabled）、加载中（loading）、已选中（selected）、错误（error）及空状态（empty）等完整状态；
• 符合规范的触控目标尺寸（adequate touch targets）；
• 无障碍可访问的标签（accessible labels）；
• 稳定尺寸：状态变更时不得发生布局偏移（dimension shift）。

5. 验证

使用以下各类边界条件对所选实现方案进行验证：

• 最长的动态文本内容；
• 资源缺失或加载缓慢的情形；
• 桌面端与窄屏移动设备视口；
• 高像素密度屏幕（high-density screens）；
• 启用“减少动画”系统偏好设置（reduced-motion preference）时的动效表现；
• 由后端驱动的状态变更；
• 真实的触控交互操作。

默认决策指南

• 品牌 Logo、游戏美术、产品图、真实横幅、二维码：使用图片资源（image assets）。
• 按钮、标签页、开关、输入框、下拉菜单、步进器：使用真实 UI 控件（real UI controls）。
• 简单且可无损缩放的符号：优先选用可信图标库（trusted icon library）、CSS 或 SVG。
• 实时标签、行情跑马灯、轻量动效、带状态的可视化组件：使用 HTML/CSS/JS 实现。
• 粒子密集型或空间化交互场景：使用 canvas 或 Three.js。
• 复杂的非交互式宣传动效：使用优化后的视频（optimized video）。

常见失效模式与应对策略

定位触发原因 → 应用一线修复措施 → 仅当仍不奏效时再升级处理。

禁止事项（红线行为）

• 禁止将行为、动态数据或可编辑文本编码进图片中。
• 当受控资源为事实来源时，禁止使用 CSS 重建丰富的品牌视觉素材。
• 禁止使用缺乏真实状态行为的图片来模拟操作或输入控件。
• 禁止选择超出实际行为需求的、过度复杂的实现方案。
• 禁止允许元素在状态变更时发生尺寸变化（导致布局偏移）。
• 禁止在未明确定义尺寸、格式、最大文件大小及回退策略前交付任何资源。

交付格式

需提交如下信息：

• 选定的实现类型；
• 被否决的替代方案及其原因；
• 资源尺寸与行为契约（asset dimensions and behavior contract）；
• 动态性与无障碍（accessibility）相关要求；
• 移动端适配与各类失效场景下的验证结果。