# Snack UI 0.3.0

零食有鸣面试概念设计的 HTML/CSS/JavaScript 设计系统。已接入首页、假期活动、领券中心、积分商城、商品详情、积分任务、购物车、会员中心及门店选择九个页面。

## 交付范围

- tokens.json：基础值、语义角色与基础尺寸的可读数据。
- tokens.css：供原型和提案共同使用的 CSS 自定义属性。
- components.css：实际共享的按钮、卡片、状态、选项卡与图像布局规则。
- components.js：共享按钮、图标、商品图片与标签的渲染函数。
- ../index.html#system：交互式文档与组件实验室。

当前为代码侧设计系统，未创建 Figma 库。品牌 VI 和正式标志尚未提供；色彩与文案是概念提案，不声称符合完整官方规范。

## 1. Token 分层与命名

基础值使用 `--snack-{family}-{step}`，如 `--snack-orange-700`。
语义值按用途命名，如 `--color-price`、`--color-action-bg`、`--color-success-text`。
组件引用语义 Token，不把品牌橙直接用于每一种状态。

| 角色 | 使用 | 边界 |
|---|---|---|
| color-brand | 主活动和品牌视觉 | 不自动代表成功或错误 |
| color-text / secondary | 标题正文 / 次要说明 | 关键规则不依赖很浅的文字 |
| color-price | 积分门槛和价格 | 不用于普通段落 |
| color-action-bg / text | 主要操作 | 每个决策区域明确一个主要动作 |
| color-action-soft-* | 次级福利与提示 | 不取代主按钮 |
| color-scene-bg | 场景推荐底色 | 不滥用于所有功能卡 |
| color-success-* | 领取与兑换完成 | 颜色之外配文字或图标 |
| color-focus | 键盘焦点 | 不移除焦点样式 |

基础尺寸：4/8/12/16/20/24/32/48px；控件圆角10、卡片16、弹层24、标签999px。主按钮至少44px高，紧凑控件34px。中文使用阿里巴巴普惠体；30/18/14/12/10px为基础字号角色，品牌字与特殊展示允许有记录的例外。

加载顺序：tokens.css → 页面样式 → components.css。页面样式保留模板和个别营销构图；共享组件覆盖公共规则。提案组件示例同样引用 tokens.css 与 components.css。

## 2. 元素和状态

### Button

- primary：关键操作，如领取、确认兑换。
- secondary：替代路径，如查看门店、继续浏览。
- soft：轻量入口，不能与主操作争夺视觉层级。
- compact：空间有限的局部操作，关键动作仍优先使用44px标准高度。
- default / hover / active / focus-visible：CSS原生状态。
- disabled：不可重复签到或领取，使用原生disabled。
- loading：aria-busy=true，暂时禁用，说明当前执行动作。
- success：使用文字和图标反馈结果，不仅改变颜色。

代码示例：

```js
SnackUI.button('redeem', '确认积分兑换');
SnackUI.button('stores', '查看门店', 'secondary');
SnackUI.button('signin', '今日已签到', 'primary', 'disabled');
```

渲染函数仅接收可信项目常量；生产用户输入必须先转义，不能直接插入HTML。

### Icon / Badge / Tabs

图标使用同一组SVG symbol，保持线宽与圆角。标签表达权益或状态，不替代按钮。文档的角色选项卡支持方向键、Home、End；原型中的场景切换使用可聚焦原生按钮。图标独立按钮需提供可访问名称。

## 3. 组件清单与使用指南

| 组件 | 结构 | 主要状态 / 使用边界 |
|---|---|---|
| 商品卡 | 图片 → 角标 → 名称 → 简述 → 积分/价格 | 不在卡片挤入完整资格，详情承接 |
| 优惠券 | 金额+门槛 → 名称 → 时间范围 → 操作 | 未领取 / 已领取；不重复领取 |
| 会员卡 | 身份 → 等级/余额 → 快捷权益 | 不把真实会员码做成装饰图片 |
| 积分任务 | 任务名称 → 奖励 → 状态 → 行动 | 可签到 / 已签到 / 反馈到账 |
| 场景推荐 | 分类切换 → 场景主张 → 商品 → 行动 | 场景切换不改变总体组件结构 |
| 购物车行 | 商品 → 单价 → 数量 → 移除 | 数量变化立即更新合计；零项回空态 |
| 底部导航 | 页面入口 + 扫码入口 | 当前项有文字与颜色变化；扫码不模拟支付 |
| 弹层 | 标题 → 内容 → 主要动作 → 关闭 | 原生dialog，支持Escape与焦点管理 |
| 即时反馈 | 完成文字 / 简短提示 | role=status，关键结果同时留在页面或记录 |

卡片自动适应所在容器；原型主体限制在手机宽度，列表使用双列。提案缩略图等比缩小原型视窗；它们不参与真实操作，点击后进入大尺寸原型。窄屏预览按容器宽度显示，可独立滚动。

## 4. 页面模式

- 聚合型：上下文 → 会员权益 → 主活动 → 常用功能 → 推荐。用于首页与会员中心。
- 决策型：商品价值 → 参与成本 → 条件/差额 → 操作。用于商品详情、优惠券。
- 任务型：目标 → 当前状态 → 行动 → 完成反馈 → 返回路径。用于签到与兑换。

恢复规则：积分不足给出差额和获取路径；空券包与空购物车提供下一步；领取和签到防止重复；演示不模拟生产支付成功。

## 5. 使用、贡献和治理（建议流程）

这份概念方案未指定真实团队负责人。进入正式项目后，建议由产品设计与前端共同维护，由品牌团队核实VI。

1. 先检查现有Token和组件是否足够，再提出新增。
2. 新需求说明使用场景、复用范围、状态和边界，不为单个页面添加无意义色值。
3. 修改共享规则后检查九个页面、375px原型、窄屏提案、键盘焦点和异常恢复。
4. 同步代码和交互文档；任何有破坏性的命名/语义变更必须记录替代项和迁移方法。
5. 移除旧规则前先迁移所有消费者，避免页面仍依赖已弃用Token。

版本建议：修复用patch；新增兼容变体用minor；语义或接口破坏性调整用major。当前0.3.0仅为概念版，不是生产稳定承诺。

## 决策记录

- 用深色主按钮：在高饱和活动视觉中保持操作清楚；亮橙负责品牌识别。
- 用深橙显示价格：比亮橙小字更清晰，避免大量高饱和文字。
- 分离商品图片与文字：图片可替换，名称、价格和状态不受生图文字错误影响。
- 共享组件直接接入九个页面：避免文档与实际原型各自一套样式。

## 后续校准

官方Logo与品牌色、真实商品SKU与价格、会员资格和积分规则、支付与履约接口、真实用户测试、Figma组件变量库。未完成的校准不以估计数据填充。


## 0.2.0 展示扩展

新增十个SVG图标规格和复制调用示例、大型首页原型展示台、输入框、复选框、提醒开关、数量步进器、标签、进度与五种页面状态。图标引用现有SVG symbol及SnackUI.icon。新增基础控件为展示页可操作样例，尚未迁移到九个产品页面；样式位于taste-layout.css，演示逻辑位于app.js。

图标采用24×24网格、1.7px圆头线条，独立操作保持至少44px触控区。装饰图标对读屏隐藏，操作提供文字名称。输入保持关联label；原生禁用、checkbox与progress保留语义。数量范围1—9；操作反馈使用aria-live。

空态给出入口，错误给出重试，加载保留布局，成功说明结果，不可用说明原因。重试演示加载到成功；不执行真实请求。


字体更新：阿里巴巴普惠体3.0，Regular / Medium / SemiBold / Bold四字重，字体文件和声明位于assets/fonts。字体Token由提案与原型共享，@font-face定义位于typography.css。


## 0.3.0 原型一致性优化

prototype-patterns.css 为九个手机页面提供统一的页面模式，加载在字体定义之后，消费同一组语义 Token。手机原型正文12px，商品名称13px，模块标题16px，页面展示标题26px，辅助信息10—11px；主要触控44px；金额使用700字重，对应已嵌入字体。展示型海报保留品牌构图。

- 首页积分入口名称和任务页保持一致；签到后余额区同步显示已签到。
- 优惠券统一金额、门槛、范围、操作的顺序；已领取禁用并保留券包入口。
- 商品卡统一图像、标签、名称、描述、积分层级；普通价格显示两位小数。
- 数量步进器迁移到购物车，1—9件；边界按钮禁用，移除是独立操作。
- 成长值使用原生progress，选项卡提供aria-pressed，导航当前页提供aria-current。
- 会员卡使用浅橙底，深色保留为主操作；活动列表用分隔线减少卡片堆叠。

验证：九页×320/375/430px无横向溢出；签到→兑换→余额、领取→券包、数量上下限→移除→空态通过。概念数据与生产接口边界保持不变。


字号微调：手机原型按375px设计宽度定义独立紧凑层级，按钮保持44px触控高度。海报标题24px（窄屏22px）、详情标题22px、页面标题26px，避免所有标题都使用展示字号。提案外层标题不受影响。