# TakeoutSaaS 原型项目规范 (Prototypes)

> **适用范围**：`TakeoutSaaS.Prototypes/` 下所有 HTML 原型页面。
> **核心原则**：这是原型图项目，不需要真实业务逻辑，只需要**易用性**和**风格统一**。

## 0. AI 交互约束

1. **语言**：必须使用**中文**回复与注释。
2. **只改样式和交互**：不要添加真实的 API 调用、数据校验逻辑、路由跳转。原型只需要视觉呈现和基本交互演示。
3. **不要过度工程化**：不需要 loading 动画的真实计时、不需要真实表单验证、不需要 localStorage 持久化。
4. **保持功能完整**：修改样式时不得破坏现有的抽屉开关、tab 切换、视图切换等交互功能。
5. **使用 ui-ux-pro-max skill**：新建页面或重构页面视觉时，必须先调用 `ui-ux-pro-max` skill 获取设计建议。

## 1. 技术栈

| 组件 | 说明 |
|:--|:--|
| CDN | Tailwind CSS (cdn.tailwindcss.com)、Lucide Icons (unpkg.com/lucide) |
| 框架 | 纯 HTML + 内联 `<style>` + 内联 `<script>`，无构建工具 |
| 图标 | Lucide Icons（`<i data-lucide="icon-name">`），**严禁使用 emoji 作为图标** |
| 入口 | `index.html` 为主框架（侧边栏+顶栏+标签页），各页面通过 iframe 加载 |

## 2. 全局设计系统 (定义在 index.html)

### 2.1 CSS 变量 (Tokens)

| Token | 值 | 用途 |
|:--|:--|:--|
| `--primary` | `hsl(212, 100%, 45%)` | 主色 |
| `--primary-light` | `hsl(212, 100%, 95%)` | 主色浅底 |
| `--g-radius` / `sm` / `lg` | `8px` / `6px` / `12px` | 圆角 |
| `--g-shadow-sm` | `0 1px 2px rgba(0,0,0,.04)` | 微阴影 |
| `--g-shadow` | `0 1px 3px rgba(0,0,0,.06), 0 1px 2px rgba(0,0,0,.04)` | 默认阴影 |
| `--g-shadow-md` | `0 4px 12px rgba(0,0,0,.07), 0 1px 3px rgba(0,0,0,.04)` | 中阴影 (hover) |
| `--g-shadow-lg` | `0 8px 24px rgba(0,0,0,.08), 0 2px 6px rgba(0,0,0,.04)` | 大阴影 (抽屉) |
| `--g-border` | `#f0f0f0` | 默认边框 |
| `--g-text` | `#1f1f1f` | 主文字 |
| `--g-text-secondary` | `#666` | 次要文字 |
| `--g-text-muted` | `#999` | 弱化文字 |
| `--g-danger` | `#f5222d` | 危险色 |
| `--g-success` | `#52c41a` | 成功色 |
| `--g-warning` | `#fa8c16` | 警告色 |
| `--g-transition` | `200ms cubic-bezier(.4,0,.2,1)` | 统一过渡 |

### 2.2 全局组件 class（.g- 前缀）

**必须优先使用以下全局 class，不要在页面内重复定义同类样式：**

| 类别 | Class | 说明 |
|:--|:--|:--|
| 卡片 | `.g-card` `.g-card-title` `.g-card-hd` `.g-card-hd-title` | 白底圆角卡片 |
| 按钮 | `.g-btn` `.g-btn-primary` `.g-btn-danger` `.g-btn-sm` `.g-btn-lg` | 统一按钮 |
| 表单 | `.g-form-group` `.g-form-label` `.g-form-label.required` `.g-input` `.g-select` `.g-textarea` `.g-hint` | 表单控件 |
| 表单行 | `.g-form-row` `.g-form-row-label` `.g-form-ctrl` | 左标签右控件布局 |
| 抽屉 | `.g-drawer-mask` `.g-drawer` `.g-drawer-hd` `.g-drawer-title` `.g-drawer-close` `.g-drawer-bd` `.g-drawer-ft` | 右侧滑入抽屉 |
| 开关 | `.g-toggle` `.g-toggle.on` `.g-toggle-wrap` `.g-toggle-label` | Toggle 开关 |
| 标签 | `.g-tag` `.g-tag-blue/green/orange/red/purple/gray` | 状态标签 |
| 选择 | `.g-pill` `.g-pill.checked` | Pill 单选/多选 |
| 分段 | `.g-seg` `.g-seg-item` `.g-seg-item.active` | 分段控制器 |
| 表格 | `.g-table` | 统一表格 |
| 分页 | `.g-pagination` `.g-page-btn` `.g-page-btn.active` | 分页组件 |
| 上传 | `.g-upload-zone` | 虚线上传区 |
| 操作链接 | `.g-action` `.g-action-danger` | 表格内操作链接 |
| 空状态 | `.g-empty` | 空数据占位 |
| 分割线 | `.g-divider` | 渐变分割线 |

## 3. 页面 CSS 命名规范

每个页面的私有样式必须使用**页面前缀**，避免与全局 class 冲突：

| 页面 | 前缀 | 示例 |
|:--|:--|:--|
| product-list | `pl-` | `.pl-toolbar`, `.pl-card` |
| product-detail | `pdt-` | `.pdt-section`, `.pdt-anchor` |
| product-specs | `ps-` | `.ps-card` |
| product-addons | `pa-` | `.pa-group-card` |
| product-combos | `pc-` | `.pc-combo-card` |
| product-labels | `plb-` | `.plb-preview` |
| product-category | `pcat-` | `.pcat-tree` |
| product-schedule | `psch-` | `.psch-timeline` |
| product-batch | `pb-` | `.pb-panel` |
| store-list | `sl-` | `.sl-stat-card` |
| store-hours | `sh-` | `.sh-week-row` |
| store-delivery | `pd-` | `.pd-tier-card` |
| store-pickup | `pp-` | `.pp-slot-cell` |
| store-dinein | `sdi-` | `.sdi-table-card` |
| store-fees | `pf-` | `.pf-fee-card` |
| store-staff | `ss-` | `.ss-schedule-grid` |
| store-qualifications | `sq-` | `.sq-cert-card` |
| dashboard | `db-` | `.db-kpi-card` |

## 4. 强制易用性规范 (UX Mandatory Rules)

以下规则适用于所有页面，**新建或修改页面时必须遵守**：

### 4.1 表单必填字段必须标记

所有必填字段的 label 必须加 `.required` class（自动显示红色星号）。

```html
<label class="g-form-label required">商品名称</label>
```

### 4.2 输入框必须有 placeholder

所有 `<input>` 和 `<textarea>` 必须有有意义的 placeholder 提示，不得留空。placeholder 应为引导性文案，不要用默认值（如 `0.00`）作为 placeholder。

```html
<!-- 正确 -->
<input class="g-input" placeholder="请输入商品名称">
<input class="g-input" type="number" placeholder="如：29.90">

<!-- 错误 -->
<input class="g-input">
<input class="g-input" placeholder="0.00">
```

### 4.3 抽屉底部按钮必须固定可见

抽屉的 footer（`.g-drawer-ft`）已通过 flex 布局固定在底部。**不要**把提交按钮放在 `.g-drawer-bd` 内部，必须放在 `.g-drawer-ft` 中。

```html
<div class="g-drawer">
  <div class="g-drawer-hd">...</div>
  <div class="g-drawer-bd"><!-- 表单内容，可滚动 --></div>
  <div class="g-drawer-ft">
    <button class="g-btn" onclick="closeDrawer()">取消</button>
    <button class="g-btn g-btn-primary">确认</button>
  </div>
</div>
```

### 4.4 操作按钮过多时收入"更多"菜单

表格每行操作链接不超过 3 个。超过 3 个时，保留最常用的 2-3 个，其余收入"更多"下拉菜单。

### 4.5 已禁用/已停用项的视觉区分

已停用、已下架、已离职等非活跃状态的卡片/行，必须有明显的视觉弱化（降低透明度、灰色遮罩、或灰色边框），让用户一眼区分。

### 4.6 编辑与查看的交互一致性

同一页面内，要么全部使用 inline 编辑，要么全部通过抽屉编辑，不要混用两种模式。

### 4.7 危险按钮的视觉区分

"删除"按钮/链接必须使用 `.g-action-danger` 或 `.g-btn-danger`，与普通操作在颜色上明确区分。

## 5. 视觉风格规范

### 5.1 设计方向

Swiss Modernism + Bento Box 风格：干净、留白充足、阴影层次分明、无多余装饰。

### 5.2 色彩层级

| 用途 | 色值 | 变量 |
|:--|:--|:--|
| 主文字 | `#1a1a2e` 或 `#1f1f1f` | `--g-text` |
| 次要文字 | `#4b5563` 或 `#666` | `--g-text-secondary` |
| 弱化文字 | `#9ca3af` 或 `#999` | `--g-text-muted` |
| 边框 | `#e5e7eb` 或 `#f0f0f0` | `--g-border` |
| 表头背景 | `#f8f9fb` 或 `#fafafa` | `--g-bg-subtle` |
| 行分割线 | `#f3f4f6` 或 `#f5f5f5` | — |

### 5.3 阴影使用规则

- 静态卡片：`var(--g-shadow-sm)` 或无阴影 + border
- Hover 状态：`var(--g-shadow-md)`
- 抽屉/弹窗：`var(--g-shadow-lg)`
- **不要**在静态元素上使用 `--g-shadow-lg`

### 5.4 圆角规则

- 大容器/卡片：`10px` 或 `var(--g-radius)`
- 按钮/输入框/小元素：`var(--g-radius-sm)` (6px)
- 上传区/大面板：`var(--g-radius-lg)` (12px)

### 5.5 过渡动画

所有交互元素的 transition 统一使用 `var(--g-transition)`，即 `200ms cubic-bezier(.4,0,.2,1)`。不要使用 `0.3s ease` 或其他自定义值。

### 5.6 Hover 状态

- 卡片 hover：加 `var(--g-shadow-md)`，可选 `translateY(-1px)` 微浮
- 表格行 hover：`background: color-mix(in srgb, var(--primary) 3%, #fff)`
- 按钮 hover：参考 `.g-btn` 已定义的 hover 样式
- **不要**使用 `scale` 变换做 hover（会导致布局抖动）

### 5.7 Section 标题样式

页面内分区标题统一使用左侧 3px 主色竖线 + 加粗文字：

```css
.xx-section-hd {
  font-size: 15px;
  font-weight: 600;
  color: var(--g-text);
  padding-left: 10px;
  border-left: 3px solid var(--primary);
  margin-bottom: 16px;
}
```

## 6. JS 交互规范

### 6.1 抽屉开关模式

```javascript
function openDrawer(mode) {
  document.getElementById('drawerMask').classList.add('open');
  document.getElementById('drawer').classList.add('open');
}
function closeDrawer() {
  document.getElementById('drawerMask').classList.remove('open');
  document.getElementById('drawer').classList.remove('open');
}
```

### 6.2 Toggle 开关

```javascript
function toggleSwitch(el) {
  el.classList.toggle('on');
}
```

### 6.3 Pill 选择

```javascript
function togglePill(el) {
  el.classList.toggle('checked');
}
```

### 6.4 事件绑定注意

使用 `event.currentTarget`（而非 `event.target`）获取绑定事件的元素，避免点击子元素时取到错误的 target。

## 7. 文件结构

```
TakeoutSaaS.Prototypes/
├── index.html          # 主框架（侧边栏+顶栏+标签页+全局CSS设计系统）
└── pages/
    ├── dashboard.html
    ├── product-list.html
    ├── product-detail.html
    ├── product-specs.html
    ├── product-addons.html
    ├── product-combos.html
    ├── product-labels.html
    ├── product-category.html
    ├── product-schedule.html
    ├── product-batch.html
    ├── store-list.html
    ├── store-hours.html
    ├── store-delivery.html
    ├── store-pickup.html
    ├── store-dinein.html
    ├── store-fees.html
    ├── store-staff.html
    └── store-qualifications.html
```

新增页面时，在 `pages/` 下创建 HTML 文件，并在 `index.html` 的侧边栏菜单中添加对应入口。