fe-project-init: H5 前端项目从零初始化

从 0 起一个能立即跑起来的 PC / 移动 H5 项目骨架，覆盖端适配 → (可选)多域名拦截器 → Layout/公共组件 → 路由 → 验证。

核心纪律：只问 10 个问题，答完立刻一口气跑到底——脚手架、装依赖、写代码、dev + build + 类型检查，全程不暂停、不二次确认。只有 npm 权限/网络实在跑不通时才停。

框架 × 端 决策表（问答结束后按此执行,冲突时以问题 2「端」为准）

项目类型(问题 3)：纯静态 → 不生成 axios / .env* 域名 / api/request / dev proxy / 会员;有接口 → 生成完整请求层。
PC 移动自适应(问题 4,仅 PC)：是 → viewport + 媒体查询响应式;否 → 固定 1200 居中。移动 H5 不适用此问。
Pinia / Zustand：问题 3=有接口 且 问题 9=是 时装;脚手架 --pinia 同理。
Tailwind / UnoCSS + 移动 H5：禁止 postcss-pxtorem;改 theme.extend 按 750 稿配 spacing/fontSize,或用 rem 直接写。

设计纪律(落地用户级 ~/.claude/CLAUDE.md §3（设计默认）;所有端/框架通用)：

• 字体:Google Fonts 双字族(Inter/Manrope 做正文 + Space Grotesk/DM Serif Display 做标题),<head> 加 preconnect,Tailwind theme.extend.fontFamily 注册 font-sans / font-display。
• 配色:在 tailwind.config 写 theme.extend.colors.brand(占位非紫色,如 #0EA5E9 / #F97316 / #10B981 三选一),色阶必须 50/100/200/300/400/500/600/700/800/900 十档全配(否则渐变/hover fallback 到默认 sky/cyan 会掉对比度);禁默认紫蓝渐变。
• 背景:App.vue / app.vue / 根 layout 用渐变 + SVG 噪点纹理,禁纯白纯灰大面积铺底。
• 动效:交互组件至少一个 transition + hover / :active 反馈,150~400ms,ease-out。
• 响应式:375 / 768 / 1280 三档必须成立。
• 对比度铁律(必查):正文与背景对比度 ≥ 4.5:1,大字号(≥18px 或 14px 加粗)≥ 3:1。落地三条:① 浅底(slate-50/white/渐变浅色)上正文用 text-slate-700 起步、副文用 text-slate-600、标题 text-slate-900,禁 text-slate-300/400/500 当正文;② 渐变文字(bg-clip-text)起止两端都必须落在 brand-600 及以上深色档(from-brand-700 via-brand-600 to-brand-500 是安全模板,禁 to-brand-300/400);③ hover 态颜色变化幅度 ≥ 一档色阶,且变化后仍满足 4.5:1。

Vue Router 5.x 雷区(create-vue 自 2026 起默认拉 v5,非经典 v4):

• 路由全部同步 import,首屏页面禁止 () => import()(scaffold 默认会给 AboutView 加,必须改回)。
• DefaultLayout 用裸 <RouterView />,不默认配 <transition mode="out-in"> 或 <Suspense>(组合会触发路由切换白屏,刷新才正常)。
• 真要切换动画,让用户在确认 router 版本兼容后自行加,并务必 Suspense 包异步组件。

启动：问答收集需求（只此一轮,答完即开工）

用 AskUserQuestion 一次收齐 10 项,答完同一轮开始执行,禁止再确认。信息不全 → 用「默认值」表 + 决策表,写进最终报告。

默认值：端=PC,项目类型=有接口,PC自适应=否,语言=TS,样式=Tailwind,UI=见决策表,域名=main+user 占位,包管理器=npm(失败可试 pnpm)。

步骤 0：代码注释规范（开工前必读）

骨架代码须让后续接手的人不读 SKILL 也能懂。先看完本节再写任何文件。

风格铁律（4 条,与 ~/.claude/CLAUDE.md §5 输出风格一致;本 skill 细化约定）

1. WHY 不 WHAT — 解释为什么这样写(约束、副作用、修改注意),不解释字面在做什么(变量/函数名能看懂的别注)。
2. 中文为主,术语保留英文 — baseURL / interceptor / middleware / token / composable 等不翻译。
3. 文件头三段式 — 职责 + 依赖方(谁读它) + 修改注意点(改这里同步改哪里),缺一不可。
4. 禁废话注释 — "定义变量"/"调用函数"/"导入路由"/"创建 store" 一律不写。

必加注释文件清单（按生成顺序）

风格示例

需要写注释或判断注释是否达标时，读取 references/comment-style.md。

执行清单（全部 ✓ 后再出报告）

□ 1. 脚手架非交互跑通 + npm install
□ 2. .gitignore 含 .env.local / dist
□ 3. config/design.ts 与端/自适应一致
□ 4. 端适配: PC固定1200 | PC+自适应→媒体查询 | 移动 Sass→flexible+pxtorem | 移动 Tailwind→无 pxtorem
□ 5. 设计纪律: Google Fonts 双字族(Inter+Space Grotesk 默认) + tailwind.config 注册 font-sans/font-display + theme.extend.colors.brand **十档全配**(50~900)非紫调色板 + 浅底正文 ≥ slate-700 / 标题 slate-900 / 渐变文字止于 brand-500 不再浅(对比度 ≥ 4.5:1)
□ 6. 有接口: .env.example + .env.development/.production + config/env.ts + api/request + dev proxy
□ 7. 有接口: types/api.d.ts + utils/message.ts;纯静态:仅 utils/message(可选,按 UI 库)
□ 8. UI 库已安装且已在 main.ts / nuxt.config 注册
□ 9. layouts: 根容器渐变+噪点背景 + Header/Footer 或 TabBar(字号/字重层次到位)
□ 10. 路由(router / pages) + 首页样板(渐变 hero + 大字标题 + hover 微动效,非裸 demo);Vue 路由全同步 import + 裸 `<RouterView />`
□ 11. 会员模块(问题 3=有接口 且 问题 9=是)
□ 12. 按「步骤 0」清单逐项加注释(文件头三段式 / 分段标注 / 函数 JSDoc / `.env.example` 行尾 `#`),清单缺一即未通过
□ 13. 项目 README.md(含设计纪律 + 目录导读 cheatsheet)
□ 14. npm run dev + build + 类型检查通过

步骤 1：脚手架 + 基础工程

脚手架命令

非交互 flag 用尽;失败 → 换镜像 / --legacy-peer-deps / 删 lock 重装,仍失败才停。

.gitignore（立刻补）

node_modules / dist / .DS_Store / *.local / .env.local / .env.*.local

纯静态项目可不建 .env*,但 .gitignore 仍保留以备后续扩展。

依赖（按需装,纯静态不装请求相关）

UI 库注册（装完必须能用）

验证:首页或 Header 放一个库组件(如 <el-button>),build 通过且非裸 HTML。

设计 token + Google Fonts

样式=Tailwind 时读取 references/tailwind-design.md，按其中模板落地双字族、brand 十档色阶、背景噪点与对比度检查。

步骤 2：端适配与设计稿

src/config/design.ts

/**
 * 设计稿与端适配约定 — 全项目 UI 单位/布局的单一真相源
 * - 改设计稿宽度或端类型时同步检查 layout 样式与 tailwind 配置
 * - vue-component-gen 会读取本文件,勿随意改名导出字段
 */
export type Platform = 'pc' | 'mobile'
export const DESIGN = {
  platform: 'pc' as Platform,
  designWidth: 1920,      // PC:1920 | 移动:750
  contentWidth: 1200,     // 仅 PC 内容区最大宽度(px)
  responsive: false,      // PC+问题4=是 → true,启用 layout 媒体查询
  unit: 'px' as 'px' | 'px→rem' | 'tailwind-rem',
  hasApi: true,           // 问题3=有接口;纯静态项目改为 false
} as const

PC 固定宽度（问题 4=否）

src/styles/layout.scss:

$content-width: 1200px;
.page-wrapper { width: 100%; min-height: 100vh; }
.page-container { width: 100%; max-width: $content-width; margin: 0 auto; padding: 0 16px; box-sizing: border-box; }

不装 postcss-pxtorem。DESIGN.responsive = false。

PC + 移动端自适应（问题 4=是）

在 PC 固定布局基础上追加响应式,不切 rem(保持 PC 设计 px 体系):

• index.html 加 viewport meta
• layout.scss 追加断点,建议 768px / 1200px:

// 小屏:容器满宽、间距收紧
@media (max-width: 768px) {
  .page-container { max-width: 100%; padding: 0 12px; }
  .app-header { flex-wrap: wrap; }  // 导航可折行或后续改汉堡菜单
}
// 中屏:可选介于满宽与 1200 之间
@media (max-width: 1200px) {
  .page-container { padding: 0 20px; }
}

• Header/Footer 组件内部用 % / flex / min-width:0,避免小屏横向溢出
• DESIGN.responsive = true;报告注明断点与待完善汉堡菜单位

移动 H5 + Sass（750→rem）

• postcss.config.js:rootValue:75; selectorBlackList:['.norem',/^\.van-/]
• src/utils/flexible.ts:根字号 75*(clientWidth/750);宽屏 max-width 750px 居中
• main.ts 顶部 import '@/utils/flexible'
• index.html 加 viewport meta
• layout 追加 .mobile-wrapper / .mobile-container { max-width:750px }

移动 H5 + Tailwind / UnoCSS

不装 pxtorem;按 750 稿配 spacing/fontSize;加 .mobile-container;DESIGN.unit='tailwind-rem'。

步骤 3：环境变量、类型、拦截器、Proxy

有接口（问题 3=有接口）

目录:

src/config/{env,design}.ts  types/api.d.ts  utils/message.ts  api/{request,modules/example}.ts
.env.{development,production,example}

key → VITE_API_<KEY> / NUXT_PUBLIC_API_<KEY> / NEXT_PUBLIC_API_<KEY>

api/request.ts — createRequest(baseKey) 多实例;token/Content-Type/timeout/AbortController;解 ApiResponse;code!==0→showError;401→清登录+跳登录;cancelAllRequests()

Dev Proxy — Vite:/api-{key}→VITE_API_{KEY};Nuxt:nitro.devProxy;Next:rewrites 或 env-cmd

baseURL:import.meta.env.DEV ? '/api-main' : getApiBase('main')

纯静态（问题 3=纯静态）

不生成:api/request.ts、config/env.ts(API 部分)、.env.development/.env.production、dev proxy、types/api.d.ts。

仅保留 config/design.ts、utils/message.ts(若用 UI 库提示)。首页不展示 API 信息。README 注明「纯静态,后续加接口见新增域名四件套」。纯静态仍须 design.ts + Layout + README 目录导读注释。

步骤 4：Layout 与公共组件

src/layouts/DefaultLayout.{vue,tsx}  components/layout/{AppHeader,AppFooter}  components/common/AppPopup.vue

根容器视觉(默认必加,落地"避免纯白纯灰"纪律):.page-wrapper / .mobile-wrapper 必须有渐变 + 噪点纹理背景,禁纯 #fff / #f5f5f5 大面积铺底。<RouterView /> 裸写,不默认套 transition / Suspense(见决策表雷区)。Tailwind 项目示例:

<template>
  <div class="relative min-h-screen bg-slate-50 bg-hero-gradient">
    <div class="pointer-events-none absolute inset-0 opacity-[0.04] [background-image:url('data:image/svg+xml;utf8,<svg xmlns=%22http://www.w3.org/2000/svg%22 width=%22120%22 height=%22120%22><filter id=%22n%22><feTurbulence baseFrequency=%220.9%22/></filter><rect width=%22100%25%22 height=%22100%25%22 filter=%22url(%23n)%22/></svg>')]"></div>
    <AppHeader />
    <main class="page-container relative">
      <RouterView />
    </main>
    <AppFooter />
  </div>
</template>

Sass 项目:.page-wrapper { background: radial-gradient(at 20% 0%, rgba(14,165,233,.12), transparent 50%), radial-gradient(at 80% 100%, rgba(16,185,129,.10), transparent 50%), #F8FAFC; },噪点同上以伪元素 ::before 叠加。

Header 字体层次:logo 用 font-display + text-slate-900,导航默认态 text-slate-700 中等字重(500~600),hover 升到 text-brand-700 + 下划线动效(transition-all duration-200),活跃态 text-brand-800 font-semibold + 底部 2px brand-600 横线。禁 text-slate-400/500 当导航默认态(对比度不够)。

Popup:v-model/title/slots,过渡用 transition 包 opacity + translate-y,150~250ms ease-out。有接口+会员=是:Header 右侧登录/头像下拉。

步骤 5：会员管理（问题 3=有接口 且 问题 9=是）

src/stores/user.ts — state:token/userInfo/isLogin;actions:login/logout/fetchUserInfo;持久化 localStorage / useCookie(Nuxt)。登录页+拦截器带 token,登录走 userRequest。

步骤 6：路由与基础页面

Vue Router 模板（Vue3+Vite，同步 import，覆盖 scaffold 默认）

import { createRouter, createWebHistory } from 'vue-router'
import HomeView from '@/views/HomeView.vue'
import AboutView from '@/views/AboutView.vue'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    { path: '/', name: 'home', component: HomeView },
    { path: '/about', name: 'about', component: AboutView },
  ],
})
export default router

create-vue 默认把 AboutView 写成 () => import(...),必须改回同步(v5 + transition 组合白屏)。仅深层非首屏大体积页面才考虑懒加载,且 layout 必须 <Suspense> 兜底。

DefaultLayout 里 <RouterView /> 裸写即可,默认不加 transition / Suspense。

首页 demo(默认必做,禁止裸文字 demo)

落地"有审美的样板首页",必须包含:

1. Hero 区:大字标题(font-display + text-4xl md:text-6xl + tracking-tight)。渐变文字必须 from-brand-800 via-brand-600 to-brand-500(三停止点全在深色档,浅底对比度 ≥ 4.5:1);禁 to-brand-300/400(实测在 bg-slate-50 上对比度跌到 3:1 以下,主标题读不清)。副标题用 text-slate-700 正文字族,禁 text-slate-400/500。CTA 按钮 bg-brand-700 text-white hover:bg-brand-800 + hover:-translate-y-0.5 hover:shadow-lg transition-all duration-200(白字在 brand-700 底上对比度达标)。
2. Feature Grid:3 张卡片,bg-white/90 backdrop-blur 底(渐变背景透出但保证文字底色),圆角 rounded-2xl,shadow-sm + hover:shadow-xl + hover:-translate-y-1 + transition,卡片内图标(用 text-brand-700,非 text-brand-400) + 标题(text-slate-900 font-semibold) + 描述(text-slate-600),字号至少两层。
3. 响应式:grid-cols-1 md:grid-cols-3,375 / 768 / 1280 三档不溢出。
4. 有接口 + dev 模式 才在页脚 <details> 折叠区里展示 API_BASE + DESIGN(if (import.meta.env.DEV) 包裹),不污染审美。纯静态首页不展示这些。

报告中提示:首页为审美样板,正式开发可整体替换。

步骤 7：项目 README.md

生成 25~50 行 README:启动命令、设计稿约定、项目类型(纯静态/有接口)、PC 是否自适应、域名(有接口时 .env.example→.env.local)、后续用 vue-component-gen,以及 设计纪律 cheatsheet + 目录导读:

## 目录导读(给后续开发者)
| 路径 | 职责 |
|------|------|
| src/config/design.ts | 设计稿/端/单位约定,改 UI 先看 |
| src/config/env.ts | 域名与 getApiBase(有接口时) |
| src/api/request.ts | 统一请求与拦截器,页面勿裸 axios |
| src/layouts/ | 全局布局,PC/移动结构差异见文件头注释 |
| src/stores/user.ts | 登录态(有会员时) |

## 设计纪律(继承自 ~/.claude/CLAUDE.md §3（设计默认）)
- 字体:Inter(正文) + Space Grotesk(标题),已通过 Google Fonts 注入
- 主色:占位 brand 色阶(50~900 十档)在 tailwind.config(或 main.scss),按品牌替换;**禁紫色**
- 文字对比度:浅底正文 `text-slate-700`、副文 `text-slate-600`、标题 `text-slate-900`,渐变文字 `from-brand-800 via-brand-600 to-brand-500`,**对比度 ≥ 4.5:1**
- 背景:渐变 + 噪点,禁纯白纯灰大面积铺底
- 动效:交互组件 hover/active 微动效,150~400ms ease-out
- 响应式:375 / 768 / 1280 三断点必须成立
- 禁:紫色背景或主题色、默认系统字体、SaaS 模板风、零动效静态页、`text-slate-300/400/500` 当正文、`to-brand-300/400` 当主标题色

步骤 8：验证

cd <project> && npm install && npm run dev && npm run build && npm run typecheck

失败 → 自行修到 build + typecheck 通过。

完成报告（只输出一次）

✅ 项目 {名称} 已初始化
📦 技术栈 + 端 + 项目类型(纯静态/有接口) + PC自适应(是/否/不适用)
🧭 vue-router: <从 package.json 读出>(v5.x 时附"路由已全同步 import + 裸 RouterView,规避白屏")
🌐 域名列表(dev/prod) — 纯静态则标注「无」
📁 关键文件清单
📝 已加多人协作注释 + README 目录导读
🎨 设计纪律: 字族(Inter+Space Grotesk) / brand 占位色 / 渐变背景 / 已落地
🚀 启动命令
🖱️ 路由切换请手测(SPA 客户端行为,build 验不到)
⚠️ 待替换:域名 / 业务壳 / logo导航 / 备案 / brand 主题色(占位非紫,按品牌换)
📋 采用的默认值
🔗 后续组件 → /vue-component-gen

铁律

1. 10 问收齐 → 一口气跑完清单,中间不确认;问题 4/8/9 按条件跳过时用默认值并记入报告。
2. 冲突以「端」为准;有接口+会员=是才加 Pinia/Zustand / --pinia。
3. 纯静态 YAGNI — 不加 axios/env/proxy/request/会员/登录页。
4. PC+自适应 — viewport+媒体查询,不引入 rem 体系;移动 H5 Sass 必须 flexible+pxtorem(75)。
5. 有接口 — .env*+env.ts+request 多实例+dev proxy 四件套齐全。
6. UI 装必注册;DefaultLayout+路由按框架落地。
7. 设计纪律必落地 — Google Fonts 双字族 + brand 十档全配非紫色阶 + 根容器渐变噪点 + 首页样板含微动效 + 正文/标题/渐变文字浅底对比度 ≥ 4.5:1(slate-700 起步,渐变止于 brand-500);禁紫色 / 默认系统字体 / 纯白铺底 / 零动效 / text-slate-300/400/500 当正文 / to-brand-300/400 当主标题色。
8. Vue 路由保底 — 路由全同步 import(覆盖 scaffold 默认懒加载),DefaultLayout 用裸 <RouterView />,默认不上 transition/Suspense(vue-router 5.x 组合会白屏)。
9. 交付前 dev+build+typecheck 必须通过;SPA 路由切换属客户端行为,显式告知用户手测。
10. 骨架必带中文注释 — 严格按「步骤 0」清单与示例风格落地:WHY 不 WHAT、中文为主、文件头三段式、禁废话注释;清单缺一视为未完成。
11. 输出风格 — 中文回复 / 进度更新 / 完成报告 / README 一律避免使用斜体(*文字* / _文字_);需要强调统一用粗体,引用文件 / 命令 / 字段名用反引号。代码注释里也不要用斜体强调。