TakeoutSaaS.Prototypes/CLAUDE.md

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（自动显示红色星号）。

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

4.2 输入框必须有 placeholder

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

<!-- 正确 -->
<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 中。

<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 主色竖线 + 加粗文字：

.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 抽屉开关模式

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 开关

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

6.3 Pill 选择

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 的侧边栏菜单中添加对应入口。