@bovinphang/frontend-craft 2.5.0 → 2.7.0

package/skills/fec-ui-design/data/style-archetypes.json

@@ -70,5 +70,45 @@
     "tokens": { "radius": "8-16px", "shadow": "soft", "density": "low-medium" },
     "bestFor": ["wellness", "beauty", "lifestyle", "care services"],
     "avoid": ["pastel contrast failures", "vague atmospheric imagery over real services"]
+  },
+  {
+    "id": "editorial-premium",
+    "keywords": ["premium", "luxury", "fashion", "magazine", "launch", "campaign"],
+    "description": "Image-led composition, restrained copy, high-contrast typography, and deliberate negative space.",
+    "tokens": { "radius": "0-8px", "shadow": "minimal", "density": "low-medium" },
+    "bestFor": ["brand launches", "premium ecommerce", "editorial landing pages", "portfolio features"],
+    "avoid": ["beige luxury defaults without brand evidence", "serif decoration that weakens readability", "hero copy that pushes the CTA below the first viewport"]
+  },
+  {
+    "id": "industrial-brutalist",
+    "keywords": ["industrial", "brutalist", "mechanical", "terminal", "tactical", "blueprint"],
+    "description": "Visible grids, hard edges, strong type scale contrast, and utilitarian metadata used with clear purpose.",
+    "tokens": { "radius": "0-2px", "shadow": "none", "density": "medium-high" },
+    "bestFor": ["technical portfolios", "developer tools", "editorial experiments", "telemetry interfaces"],
+    "avoid": ["regulated consumer flows", "tiny all-caps body copy", "decorative terminal chrome without real information"]
+  },
+  {
+    "id": "minimal-utilitarian",
+    "keywords": ["utilitarian", "document", "linear", "notion", "workspace", "minimalist"],
+    "description": "Quiet document-like surfaces, precise structure, low ornament, and typography doing most of the hierarchy work.",
+    "tokens": { "radius": "4-8px", "shadow": "none-low", "density": "medium" },
+    "bestFor": ["SaaS settings", "docs", "team workspaces", "productivity tools"],
+    "avoid": ["empty white expanses with no task priority", "low-contrast gray on gray", "identical flat cards for every section"]
+  },
+  {
+    "id": "image-led-landing",
+    "keywords": ["landing", "website", "hero", "visual", "image-led", "marketing"],
+    "description": "A clear conversion path carried by real or generated media, varied section structure, and inspectable visual assets.",
+    "tokens": { "radius": "contextual", "shadow": "media-dependent", "density": "low-medium" },
+    "bestFor": ["marketing sites", "product pages", "event pages", "agency sites"],
+    "avoid": ["text plus gradient-only hero", "fake screenshots", "repeating left-text/right-image sections", "CTA labels that wrap on desktop"]
+  },
+  {
+    "id": "brand-system-board",
+    "keywords": ["brand", "brandkit", "identity", "logo", "guidelines", "visual system"],
+    "description": "Presentation-grid identity boards that show logo logic, palette, typography, applications, and visual world coherently.",
+    "tokens": { "radius": "system-defined", "shadow": "presentation-dependent", "density": "medium" },
+    "bestFor": ["brand exploration", "identity systems", "design direction handoff", "visual language proposals"],
+    "avoid": ["random moodboards", "generic logos", "panels that do not explain the brand idea"]
   }
 ]

package/skills/fec-ui-design/data/ux-quality-rules.json

@@ -52,5 +52,40 @@
     "priority": "medium",
     "checks": ["Chart type matches data question", "Units and legends are visible", "Data has text/table fallback", "Color is supplemented by shape or labels"],
     "avoid": ["Pie charts for many categories", "Color-only series distinction"]
+  },
+  {
+    "category": "first-viewport",
+    "label": "First viewport",
+    "priority": "high",
+    "checks": ["Hero or workspace fits common laptop heights", "Primary CTA or task entry is visible without scrolling", "Desktop navigation stays on one line", "The next section leaves a readable cue when the page is promotional"],
+    "avoid": ["Oversized top padding", "Hero copy pushing actions below the fold", "Two-line desktop nav"]
+  },
+  {
+    "category": "cta-quality",
+    "label": "CTA quality",
+    "priority": "high",
+    "checks": ["CTA text contrast meets WCAG AA", "Primary CTA label stays on one line at desktop", "Each CTA intent uses one consistent label", "Ghost buttons remain visible over media backgrounds"],
+    "avoid": ["White text on light buttons", "Multiple contact labels for the same action", "Transparent buttons over busy imagery"]
+  },
+  {
+    "category": "section-variety",
+    "label": "Section variety",
+    "priority": "medium",
+    "checks": ["Adjacent sections use distinct layout jobs", "Bento cell count matches real content", "Feature grids have clear visual priority", "Small uppercase eyebrow labels are used sparingly"],
+    "avoid": ["Three equal cards as the default rhythm", "Three or more zigzag sections in a row", "Empty bento cells for decoration"]
+  },
+  {
+    "category": "media-authenticity",
+    "label": "Media authenticity",
+    "priority": "high",
+    "checks": ["Visual pages use real or generated assets with a clear role", "Product pages show inspectable product or state", "Screenshots represent real UI or are labeled as concepts", "Images reserve aspect ratio and have meaningful alt text when informative"],
+    "avoid": ["Text-only promotional pages", "Fake dashboard rectangles", "Blurred stock atmosphere as the main subject"]
+  },
+  {
+    "category": "state-completeness",
+    "label": "State completeness",
+    "priority": "critical",
+    "checks": ["Loading shape matches final layout", "Empty states include a useful next action", "Errors are recoverable and close to the source", "Selected, invalid, disabled, hover, focus, and reduced-motion states are covered"],
+    "avoid": ["Generic spinners everywhere", "Empty states that only say no data", "Disabled controls communicated only by opacity"]
   }
 ]

package/skills/fec-ui-design/references/design-intelligence.md

@@ -5,12 +5,71 @@
 ## 决策流程
 
 1. 提取关键词：产品类型、用户、场景、主要任务、内容密度、品牌语气、技术栈。
-2. 匹配产品规则：从 `data/product-rules.json` 选择最接近的类别，记录推荐结构、风险和反模式。
-3. 选择风格原型：从 `data/style-archetypes.json` 选择 1 个主风格和最多 1 个辅助风格，避免风格拼贴。
-4. 建立 token 方向：定义主色、强调色、背景、前景、边框、危险色和 focus ring 的语义角色。
-5. 选择字体情绪：不要只选“好看的字体”，要说明标题和正文各自承担的语气与可读性。
-6. 判断数据表达：趋势用折线/面积，比较用柱状，构成少量类别可用环图，流程用漏斗/步骤，明细必须保留表格替代。
-7. 输出反模式：每个设计建议必须附带“不要做什么”，避免落入通用模板。
+2. 写出设计读取：页面类型、受众、主任务、品牌约束和可信赖感来源。
+3. 匹配产品规则：从 `data/product-rules.json` 选择最接近的类别，记录推荐结构、风险和反模式。
+4. 选择风格原型：从 `data/style-archetypes.json` 选择 1 个主风格和最多 1 个辅助风格，避免风格拼贴。
+5. 设定设计拨盘：视觉张力、动效强度、信息密度、媒体真实性、内容说服力都用 1-10 表达，并随页面类型变化。
+6. 建立 token 方向：定义主色、强调色、背景、前景、边框、危险色和 focus ring 的语义角色。
+7. 选择字体情绪：不要只选“好看的字体”，要说明标题和正文各自承担的语气与可读性。
+8. 判断数据表达：趋势用折线/面积，比较用柱状，构成少量类别可用环图，流程用漏斗/步骤，明细必须保留表格替代。
+9. 输出反模式和质量门禁：每个设计建议必须附带“不要做什么”，并根据页面类型补充首屏、CTA、媒体真实性、section 变化和状态完整度检查。
+
+## 方向 Advisor
+
+当用户只说“好看一点”“给几个方向”“我也不知道什么风格”且没有权威设计稿时，不要连续追问泛泛口味问题。先给 3 个差异明显的方向，让用户能判断取舍。
+
+每个方向必须包含：
+
+- 适用场景：为什么适合当前产品、受众和任务。
+- 视觉锚点：信息结构、真实媒体、数据形态、材质、字体性格、空间组织或交互节奏。
+- 关键 token：主色、强调色、背景、字体情绪、圆角/边框/阴影倾向。
+- 避免项：这个方向最容易滑向的模板化错误。
+
+三个方向应来自不同设计逻辑，例如：
+
+- 信息架构型：高密度、理性、数据优先，适合 B2B、运营、金融、工程工具。
+- 编辑叙事型：版式、留白、强文字层级，适合品牌故事、内容产品、作品集。
+- 产品实证型：真实截图、对象、状态、流程证据优先，适合 SaaS、硬件、开发者工具。
+- 表现实验型：强动效、空间感、生成视觉，适合发布页、活动页、艺术/创意项目。
+- 温暖人本型：低攻击性色彩、可亲近插画或真实人物，适合教育、健康、生活方式。
+
+用户选择方向后，再把它落成设计系统和页面结构；不要把 3 个方向拼贴成一个混杂系统。
+
+## 真实资产优先
+
+品牌或产品相关 UI 的识别度来自真实资产，而不是颜色猜测。优先级：
+
+1. Logo、产品图、真实 UI 截图、实体照片、品牌应用图。
+2. 项目内已有 icon、组件、数据状态、图表和截图。
+3. 为当前任务生成的专用资产。
+4. 明确标记的结构化 placeholder。
+
+不要用 CSS 轮廓、通用插画、假截图或远程占位图替代用户需要识别的主体。缺少关键资产时，先标记资产缺口并给替代路线；若 logo 或主体产品是首屏识别核心，应暂停确认或改为不依赖品牌识别的结构方案。
+
+## v0 校准
+
+视觉风险高、方向不明确或页面影响面较大时，先交付一个可看的 v0，而不是一次性做完整页面。
+
+v0 应包含：
+
+- 核心布局、首屏层级、主要 token 和一个关键模块。
+- 明确 placeholder 和资产缺口。
+- 1-2 个可替换方向点，例如密度、色彩温度或媒体策略。
+- 不包含完整状态矩阵、所有内容细节或生产级动效。
+
+v0 通过后再补齐组件、状态、响应式和交互动效。
+
+## 设计 Critique
+
+当用户要求“评审 UI”“好不好看”“再高级一点”或交付前需要自检时，按 5 个维度输出具体问题，而不是只给主观形容：
+
+- 方向一致性：视觉选择是否服务设计读取和产品任务。
+- 层级与扫描：首屏、标题、CTA、数据、状态是否有清楚主次。
+- 工艺质量：间距、对齐、色彩数量、文字换行、圆角/边框/阴影是否稳定。
+- 功能完整度：loading、empty、error、disabled、hover、focus、selected 是否覆盖。
+- 原创性与识别度：是否摆脱通用渐变、三卡片、假截图、无主体 hero。
+
+输出应按严重程度给出可执行修复，不评价设计者本人。
 
 ## 何时运行生成器
 
@@ -29,6 +88,7 @@ node skills/fec-ui-design/scripts/design-system.mjs "fintech analytics dashboard
 ## 输出必须回答
 
 - 这个界面的主任务是什么？
+- 设计读取和五个设计拨盘分别是什么？
 - 推荐哪种页面结构或工作区结构？
 - 视觉锚点是什么，为什么贴合业务？
 - 主风格、字体、色彩、动效分别服务什么目标？

package/skills/fec-ui-design/references/pre-delivery-checklist.md

@@ -11,6 +11,9 @@
 ## 高优先级
 
 - 首屏：工具型界面直接展示核心工作区，不用营销 hero 替代功能。
+- 首屏：营销、作品集和品牌页在常见小笔记本高度内显示主体、CTA 和下一屏线索。
+- CTA：按钮文案在桌面端不换行，对比度合格，同一意图使用一致标签。
+- 导航：桌面端保持单行，移动端折叠后仍能到达主要路径。
 - 响应式：375px、768px、1024px、1440px 无水平溢出、遮挡或文本截断。
 - 性能：图片有尺寸或 aspect-ratio；非首屏图片懒加载；列表过大时虚拟化。
 - 动效：只动画 transform/opacity，尊重 `prefers-reduced-motion`。
@@ -27,6 +30,9 @@
 ## 反模式
 
 - 用装饰光斑、紫色渐变、卡片堆叠掩盖信息结构不足。
+- 连续三段以上复用三卡片、左右交错、split header 或同一种 reveal 动效。
+- 视觉型页面只有文字和渐变，没有真实产品、真实状态、品牌应用或可检查媒体。
+- Bento 用空格子补构图，或 feature grid 每个格子同权重、同背景、同节奏。
 - hover 导致布局位移。
 - `transition: all`、`will-change: all`。
 - 低对比灰字、无意义透明度、单一色相界面。

package/skills/fec-ui-design/scripts/design-system.mjs

@@ -67,6 +67,14 @@ import { fileURLToPath } from "node:url";
  *   project: string;
  *   page: string;
  *   query: string;
+ *   designRead: string;
+ *   designDials: {
+ *     visualTension: number;
+ *     motionIntensity: number;
+ *     informationDensity: number;
+ *     mediaAuthenticity: number;
+ *     contentPersuasion: number;
+ *   };
  *   product: { id: string; label: string; pattern: string; risks: string[] };
  *   style: { id: string; label: string; usage: string | undefined; risks: string[] };
  *   tokens: { color: string; typography: string; space: string; components: string[] };
@@ -230,6 +238,7 @@ function buildRecommendation(args) {
   const tokens = tokenize([query, args.project, args.page, args.stack].filter(Boolean).join(" "));
   const product = chooseProduct(tokens);
   const style = chooseStyle(tokens, product);
+  const designDials = deriveDesignDials(tokens, product, style);
   const checklist = chooseChecklist(tokens, product);
   const stackGuidance = chooseStack(args.stack, tokens);
   const pattern = product.pattern ?? product.patterns?.[0] ?? "Task-first interface with explicit states and durable visual hierarchy";
@@ -238,6 +247,8 @@ function buildRecommendation(args) {
     project: args.project || titleCase(query),
     page: args.page || "",
     query,
+    designRead: renderDesignRead(product, style, designDials),
+    designDials,
     product: {
       id: product.id,
       label: product.label ?? labelFromId(product.id),
@@ -312,11 +323,17 @@ function chooseStyle(tokens, product) {
  * @returns {ChecklistGroup[]}
  */
 function chooseChecklist(tokens, product) {
-  const priority = new Set(["accessibility", "interaction", "layout", "typography", "animation"]);
+  const priority = new Set(["accessibility", "interaction", "layout", "typography", "animation", "state-completeness"]);
   if (product.id === "data-dashboard" || tokens.has("dashboard") || tokens.has("chart")) priority.add("charts");
   if (tokens.has("form") || tokens.has("booking") || tokens.has("checkout")) priority.add("forms");
   if (tokens.has("mobile") || tokens.has("app")) priority.add("navigation");
   if (tokens.has("performance") || tokens.has("canvas") || tokens.has("three")) priority.add("performance");
+  if (isPromotional(tokens, product)) {
+    priority.add("first-viewport");
+    priority.add("cta-quality");
+    priority.add("section-variety");
+    priority.add("media-authenticity");
+  }
 
   return uxQualityRules
     .filter((rule) => {
@@ -333,6 +350,96 @@ function chooseChecklist(tokens, product) {
     });
 }
 
+/**
+ * @param {Set<string>} tokens
+ * @param {ProductRule} product
+ * @param {StyleArchetype} style
+ * @returns {Recommendation["designDials"]}
+ */
+function deriveDesignDials(tokens, product, style) {
+  /** @type {Recommendation["designDials"]} */
+  const dials = {
+    visualTension: 5,
+    motionIntensity: 3,
+    informationDensity: 5,
+    mediaAuthenticity: 5,
+    contentPersuasion: 5,
+  };
+
+  if (["data-dashboard", "saas", "fintech", "healthcare"].includes(product.id)) {
+    dials.visualTension = 3;
+    dials.motionIntensity = product.id === "saas" ? 3 : 2;
+    dials.informationDensity = product.id === "data-dashboard" ? 8 : 6;
+    dials.mediaAuthenticity = 4;
+    dials.contentPersuasion = 4;
+  }
+
+  if (["ecommerce", "creative", "wellness"].includes(product.id) || isPromotional(tokens, product)) {
+    dials.visualTension = product.id === "creative" ? 8 : 7;
+    dials.motionIntensity = product.id === "creative" ? 6 : 5;
+    dials.informationDensity = 4;
+    dials.mediaAuthenticity = 8;
+    dials.contentPersuasion = 8;
+  }
+
+  if (product.id === "gaming" || style.id === "immersive") {
+    dials.visualTension = 8;
+    dials.motionIntensity = 7;
+    dials.informationDensity = 6;
+    dials.mediaAuthenticity = 7;
+    dials.contentPersuasion = 5;
+  }
+
+  if (["minimal", "minimal-utilitarian"].includes(style.id)) {
+    dials.visualTension = Math.min(dials.visualTension, 4);
+    dials.motionIntensity = Math.min(dials.motionIntensity, 3);
+  }
+
+  if (["editorial-premium", "image-led-landing", "brand-system-board"].includes(style.id)) {
+    dials.visualTension = Math.max(dials.visualTension, 7);
+    dials.mediaAuthenticity = Math.max(dials.mediaAuthenticity, 8);
+    dials.contentPersuasion = Math.max(dials.contentPersuasion, 7);
+  }
+
+  if (tokens.has("regulated") || tokens.has("public") || tokens.has("government") || tokens.has("accessibility")) {
+    dials.visualTension = Math.min(dials.visualTension, 3);
+    dials.motionIntensity = Math.min(dials.motionIntensity, 2);
+    dials.informationDensity = Math.max(dials.informationDensity, 5);
+  }
+
+  return dials;
+}
+
+/**
+ * @param {ProductRule} product
+ * @param {StyleArchetype} style
+ * @param {Recommendation["designDials"]} dials
+ * @returns {string}
+ */
+function renderDesignRead(product, style, dials) {
+  return [
+    `Reading this as ${product.label ?? labelFromId(product.id)} work`,
+    `with a ${style.label ?? labelFromId(style.id)} visual direction`,
+    `and dial targets ${dials.visualTension}/${dials.motionIntensity}/${dials.informationDensity}/${dials.mediaAuthenticity}/${dials.contentPersuasion}`,
+  ].join(", ");
+}
+
+/**
+ * @param {Set<string>} tokens
+ * @param {ProductRule} product
+ * @returns {boolean}
+ */
+function isPromotional(tokens, product) {
+  return product.id === "creative"
+    || product.id === "ecommerce"
+    || tokens.has("landing")
+    || tokens.has("marketing")
+    || tokens.has("portfolio")
+    || tokens.has("brand")
+    || tokens.has("website")
+    || tokens.has("hero");
+}
+
 /**
  * @param {string} stack
  * @param {Set<string>} tokens
@@ -364,10 +471,19 @@ function renderMarkdown(model) {
   const lines = [
     `# Design System Recommendation: ${model.project}`,
     "",
+    `- Design read: ${model.designRead}`,
     `- Product category: ${model.product.label} (${model.product.id})`,
     `- Recommended pattern: ${model.product.pattern}`,
     `- Style archetype: ${model.style.label} (${model.style.id})`,
     "",
+    "## Design Dials",
+    "",
+    `- Visual tension: ${model.designDials.visualTension}/10`,
+    `- Motion intensity: ${model.designDials.motionIntensity}/10`,
+    `- Information density: ${model.designDials.informationDensity}/10`,
+    `- Media authenticity: ${model.designDials.mediaAuthenticity}/10`,
+    `- Content persuasion: ${model.designDials.contentPersuasion}/10`,
+    "",
     "## Token Direction",
     "",
     `- Color: ${model.tokens.color}`,
@@ -416,10 +532,12 @@ function renderPageOverride(model) {
     "## Page Intent",
     "",
     `Use the Master direction, then adapt layout and component density for ${pageName}. Keep overrides narrow and delete any rule that merely repeats the Master.`,
+    `Design read: ${model.designRead}.`,
     "",
     "## Override Strategy",
     "",
     `- Primary pattern: ${model.product.pattern}`,
+    `- Dials: visual ${model.designDials.visualTension}/10, motion ${model.designDials.motionIntensity}/10, density ${model.designDials.informationDensity}/10, media ${model.designDials.mediaAuthenticity}/10, persuasion ${model.designDials.contentPersuasion}/10`,
     `- Visual emphasis: ${model.style.usage}`,
     `- Chart behavior: ${model.chart}`,
     "",

package/skills/fec-validation-fix/SKILL.md

@@ -31,7 +31,7 @@ description: Use when running existing project validation commands and fixing fa
 - 对 CI 专属失败记录 Node 版本、包管理器、环境变量、路径大小写和工作目录差异。
 - 修复测试时优先修产品代码或测试等待方式，不用删除断言掩盖真实回归。
 
-## 强约束
+## Constraints
 
 - 不要盲目关闭规则来消除报错
 - 除非有明确理由，不要为了通过检查而降低类型安全
@@ -40,9 +40,12 @@ description: Use when running existing project validation commands and fixing fa
 - 不要删除失败测试来让验证通过
 - 不要只运行失败命令的片段就声称整体验证通过
 
+## 详细参考
+
+撰写验证修复报告时，加载 [references/report-template.md](references/report-template.md)。
+
 ## Expected Output
 
 - lint / type-check / test / build 等验证命令全部通过
 - 失败项已修复或给出明确原因和后续行动
 - 修复报告保存为 `reports/validation-fix-YYYY-MM-DD-HHmmss.md`
-- 报告包含命令状态表、问题根因、修复说明、变更文件和剩余风险

package/skills/fec-validation-fix/references/report-template.md

@@ -0,0 +1,43 @@
+# 验证修复报告模板
+
+```markdown
+# 验证修复报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 验证范围: lint / type-check / test / build / CI
+
+## 命令状态表
+
+| 命令 | 初始状态 | 修复后状态 | 备注 |
+| --- | --- | --- | --- |
+| `npm run type-check` | 失败 / 通过 / 未运行 | 失败 / 通过 / 未运行 | ... |
+
+## 失败摘要
+
+- 最早出现且会级联的错误
+- 受影响文件、错误类型和关键日志
+- 是否属于 CI 专属、测试环境、依赖版本或 flaky 问题
+
+## 根因
+
+- 确认的根本原因
+- 支持该结论的输出、日志或复现证据
+
+## 修复内容
+
+- 修改的文件和行为
+- 为什么没有通过关闭规则、删除断言或降低类型安全来规避失败
+
+## 验证结果
+
+- 重新执行的命令
+- 命令输出摘要
+- 是否仍有失败项
+
+## 剩余风险
+
+- 未覆盖的验证命令
+- 仍需用户决策或外部环境确认的问题
+```
+
+验证修复完成后，将报告保存到 `reports/validation-fix-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/skills/fec-vue3-project-standard/SKILL.md

@@ -19,11 +19,17 @@ description: Use when designing or reviewing Vue 3 + TypeScript project structur
 4. 输出时补齐状态归属、API 层、错误处理、样式隔离和专项 skill 分流。
 5. 页面和模块要有可恢复错误 UI；全局 `errorHandler`、`onErrorCaptured`、请求错误映射和路由错误页分工明确。
 6. Tailwind token/variant 或响应式布局需求应分流到对应专项 skill，避免把样式系统规则塞进 Vue 组件规范。
-5. 状态归属复杂时先做状态清单；DTO、公共 props 或泛型 composable 复杂时先收敛 TypeScript 类型契约。
+7. 状态归属复杂时先做状态清单；DTO、公共 props、泛型 composable 或 `tsconfig` 边界复杂时，先使用 TypeScript 项目规范流程收敛跨框架类型契约。
+8. 设计可复用 composable 时明确输入是否支持 plain value、ref、computed 或 getter；测试 Vue 组件时覆盖 Pinia、Router、Teleport、Suspense 和 async setup 的常见边界。
 
-## Detailed References
+## 详细参考
 
-需要具体 Vue 3 项目结构、组件模式、Composables、slots、Provide/Inject、路由、Pinia、API 层、错误处理、指令、样式、TypeScript、测试、性能或审查清单时，加载 [references/vue3-project-details.md](references/vue3-project-details.md)。
+按需要加载更细的参考文件：
+
+- 项目目录、组件分层、组件规范、注释和 TypeScript：加载 [references/vue3-project-structure.md](references/vue3-project-structure.md)。
+- Composables、slots、Provide/Inject 和路由组织：加载 [references/vue3-composables-routing.md](references/vue3-composables-routing.md)。
+- Pinia、API 层、错误处理、指令、样式、测试、反模式和输出检查清单：加载 [references/vue3-state-api-quality.md](references/vue3-state-api-quality.md)。
+- Vue 项目规范层面的轻量性能约定：加载 [references/vue3-performance-patterns.md](references/vue3-performance-patterns.md)。
 
 ## Constraints
 
@@ -36,6 +42,8 @@ description: Use when designing or reviewing Vue 3 + TypeScript project structur
 - 避免在 `v-for` 中使用 `v-if`（提取为 computed 过滤）
 - 禁止直接从 feature 内部深层路径导入，绕过 `index.ts`
 - 不用全局错误处理吞掉组件内可恢复的 API、表单或权限错误。
+- 不把函数型参数误当 getter 自动调用；composable 参数若可能是回调，应避免使用 getter 型输入约定。
+- 不依赖快照作为 Vue 组件唯一断言；异步组件、Teleport 和 Pinia 场景要有用户可见行为断言。
 
 ## Expected Output
 
@@ -47,3 +55,4 @@ description: Use when designing or reviewing Vue 3 + TypeScript project structur
 - API 调用有类型约束和统一错误处理
 - 样式使用 scoped 隔离，关键行为有测试覆盖
 - 文件结构与项目约定一致（pages / features / components 分离）
+- 可复用 composable 的输入响应性、Pinia/Router 边界和异步组件测试策略已说明

package/skills/fec-vue3-project-standard/references/vue3-composables-routing.md

@@ -0,0 +1,163 @@
+# Vue 3 composables and routing patterns
+
+## Composables 规范
+
+### 设计原则
+
+- 以 `use` 前缀命名
+- 返回值使用对象，明确标注类型
+- 内部处理 loading / error / data 三态
+- 支持参数响应式（接受 `Ref` 或 getter）
+- 库级 composable 要明确参数是否支持普通值、`Ref`、`computed` 或 getter，并在副作用内部解析最新值
+
+```typescript
+export function useUserList(params: MaybeRef<QueryParams>) {
+  const data = ref<User[]>([]);
+  const loading = ref(false);
+  const error = ref<Error | null>(null);
+
+  async function fetch() {
+    loading.value = true;
+    error.value = null;
+    try {
+      const res = await getUserList(toValue(params));
+      data.value = res.list;
+    } catch (e) {
+      error.value = e as Error;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  watchEffect(() => {
+    fetch();
+  });
+
+  return {
+    data: readonly(data),
+    loading: readonly(loading),
+    error: readonly(error),
+    refetch: fetch,
+  };
+}
+```
+
+### Composable 使用原则
+
+- 返回 `readonly` 引用防止外部意外修改
+- 数据请求场景优先使用 VueQuery / VueUse 等库（如项目已引入）
+- `onUnmounted` 中清理定时器、事件监听等副作用
+- 避免在 composable 中直接操作 DOM
+- 只读输入可接受普通值、ref、computed 或 getter；需要双向写入的输入只接受可写 ref 或明确的 setter。
+- 如果参数本身是回调、比较器或 predicate，不要把它设计成 getter 型输入，否则解析时可能误调用业务函数。
+
+### Vue Router / Pinia / 测试常见边界
+
+- 路由参数变化不会重新创建同一个路由组件；依赖 `route.params` 的数据要 watch 明确字段，并处理取消和竞态。
+- 导航守卫中避免旧式 `next()` 多分支重复调用；优先返回 `false`、重定向对象或抛出可处理错误。
+- Pinia store 解构会丢失响应性时使用 `storeToRefs`；setup store 必须返回需要被外部追踪的 state、getter 和 action。
+- UI 临时状态、表单输入、弹窗开关不进入全局 store；URL 查询、服务端缓存和本地组件状态先各归其位。
+- Vue Test Utils 测试优先断言用户可见行为，不把快照作为唯一证明；异步更新使用 `await`、`flushPromises` 或框架推荐的等待方式。
+- 测试使用 Pinia、Router、Teleport、Suspense、async setup 或 `defineAsyncComponent` 时，在测试夹具中显式安装插件、挂载目标容器并等待异步稳定。
+
+## Slots 与 Provide/Inject
+
+### Slots
+
+- 用 `<slot>` 实现组件组合，而非过多 props
+- 具名 slot 用于明确的布局区域
+- 作用域 slot 传递数据给父组件自定义渲染
+
+```vue
+<template>
+  <div class="card">
+    <div class="card-header">
+      <slot name="header">{{ title }}</slot>
+    </div>
+    <div class="card-body">
+      <slot :data="processedData" :loading="loading" />
+    </div>
+  </div>
+</template>
+```
+
+### Provide/Inject
+
+- 用于跨多层级的上下文共享（主题、配置、权限）
+- 提供 InjectionKey 保证类型安全
+- 不要用 provide/inject 替代 props 传递直接父子数据
+
+```typescript
+// keys.ts
+export const ThemeKey: InjectionKey<Ref<Theme>> = Symbol("theme");
+
+// Provider.vue
+provide(ThemeKey, theme);
+
+// Consumer.vue
+const theme = inject(ThemeKey);
+```
+
+## 路由规范
+
+### 路由组织
+
+```typescript
+// app/router.ts
+const routes: RouteRecordRaw[] = [
+  {
+    path: "/",
+    component: MainLayout,
+    children: [
+      {
+        path: "",
+        name: "Dashboard",
+        component: () => import("@/pages/Dashboard/DashboardPage.vue"),
+      },
+      {
+        path: "users",
+        name: "UserList",
+        component: () => import("@/pages/UserList/UserListPage.vue"),
+      },
+      {
+        path: "users/:id",
+        name: "UserDetail",
+        component: () => import("@/pages/UserDetail/UserDetailPage.vue"),
+      },
+      {
+        path: "settings",
+        name: "Settings",
+        component: () => import("@/pages/Settings/SettingsPage.vue"),
+      },
+    ],
+  },
+  {
+    path: "/login",
+    name: "Login",
+    component: () => import("@/pages/Login/LoginPage.vue"),
+  },
+  {
+    path: "/:pathMatch(.*)*",
+    name: "NotFound",
+    component: () => import("@/pages/NotFound.vue"),
+  },
+];
+```
+
+### 路由原则
+
+- 路由配置集中管理，每个路由必须有 `name`
+- 页面组件使用动态 `import()` 按需加载
+- 权限控制使用路由守卫（`beforeEach`），而非在每个页面内判断
+- URL 参数（分页、筛选、排序）与路由状态同步
+
+```typescript
+// 导航守卫
+router.beforeEach((to) => {
+  const authStore = useAuthStore();
+  if (to.meta.requiresAuth && !authStore.isLoggedIn) {
+    return { name: "Login", query: { redirect: to.fullPath } };
+  }
+});
+```
+

package/skills/fec-vue3-project-standard/references/vue3-performance-patterns.md

@@ -0,0 +1,13 @@
+# Vue 3 performance patterns
+
+This file keeps lightweight Vue project-standard performance guidance. Use the frontend performance workflow when the task needs metrics, traces, profiles, bundle analysis, network evidence, or a formal performance report.
+
+## 性能
+
+- 使用 `shallowRef` / `shallowReactive` 优化大型对象
+- 大列表使用虚拟滚动
+- 避免在 `v-for` 中使用 `v-if`（提取为 computed 过滤）
+- 使用 `defineAsyncComponent` 懒加载重型组件
+- `v-for` 必须有稳定的 `:key`
+- 路由组件使用动态 `import()` 按需加载
+