@bovinphang/frontend-craft 2.6.0 → 2.8.0

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

@@ -1,51 +1,51 @@
 ---
 name: fec-validation-fix
-description: Use when running existing project validation commands and fixing failures after code changes, including lint, type-check, unit/integration test, build, CI, or local script failures. Do not use when the task is to design or author new component/E2E tests; Chinese triggers include 验证, 检查失败, 修复失败, CI 失败.
+description: Use when running existing project validation commands and fixing failures after code changes, including lint, type-check, unit/integration test, build, CI, or local script failures. Do not use when the task is to design or author new component/E2E tests; Chinese triggers include validation, check failures, fix failures, CI failures.
 ---
 
-# 验证并修复
+# Verify and fix
 
 ## Purpose
 
-自动化执行已有验证命令，分析失败原因并安全修复，确保质量门禁达标。
+Automatically execute existing verification commands, analyze the reasons for failure and safely repair them to ensure that quality access control meets standards.
 
 ## Procedure
 
-1. 从 package.json 或仓库文档中识别可用命令。
-2. 优先按以下顺序执行：
+1. Identify available commands from package.json or repository documentation.
+2. Prioritize execution in the following order:
    - lint
    - type-check
    - unit/integration tests
    - build
-3. 仔细阅读失败输出。
-4. 将错误按文件、错误类型和依赖关系分组，优先处理阻塞后续诊断的根因。
-5. 一次只修复一类问题，并显示或记录关键错误上下文。
-6. 每次关键修复后重新执行受影响命令，确认错误是否减少。
-7. 如果同一错误连续三次修复仍失败，停止扩大改动并报告阻塞。
-8. 最后按 `Expected Output` 总结执行结果、修复内容和剩余风险。
+3. Read the failure output carefully.
+4. Group errors by file, error type and dependency, prioritizing root causes that block subsequent diagnosis.
+5. Fix one type of problem at a time and display or log critical error context.
+6. After each critical repair, re-execute the affected command to confirm whether the error is reduced.
+7. If the same error still fails to be repaired three times in a row, stop expanding changes and report blocking.
+8. Finally, press `Expected Output` to summarize the execution results, repair content and remaining risks.
 
 ## Failure Triage
 
-- 先修最早出现且会级联的错误，例如缺失类型、导入失败、配置解析失败。
-- 区分真实产品 bug、测试环境问题、快照漂移、依赖版本变化和 flaky。
-- 对 CI 专属失败记录 Node 版本、包管理器、环境变量、路径大小写和工作目录差异。
-- 修复测试时优先修产品代码或测试等待方式，不用删除断言掩盖真实回归。
+- Fix the earliest errors that will cascade first, such as missing types, import failures, and configuration parsing failures.
+- Differentiate between real product bugs, test environment issues, snapshot drift, dependency version changes and flaky.
+- Log Node version, package manager, environment variables, path case, and working directory differences for CI-specific failures.
+- When fixing tests, give priority to fixing product code or testing waiting methods, instead of deleting assertions to cover up real regressions.
 
 ## Constraints
 
-- 不要盲目关闭规则来消除报错
-- 除非有明确理由，不要为了通过检查而降低类型安全
-- 不要因为附近测试失败就顺手重写无关模块
-- 不要一次性修改多个无关根因
-- 不要删除失败测试来让验证通过
-- 不要只运行失败命令的片段就声称整体验证通过
+- Do not blindly turn off rules to eliminate errors
+- Don't compromise type safety to pass checks unless there is a clear reason to do so
+- Don’t rewrite irrelevant modules just because a nearby test fails
+- Do not modify multiple irrelevant root causes at once
+- Don't remove failing tests to make validation pass
+- Don't just run a fragment of the failed command and claim that the overall validation passed
 
-## 详细参考
+## Detailed reference
 
-撰写验证修复报告时，加载 [references/report-template.md](references/report-template.md)。
+When writing a verification fix report, load [references/report-template.md](references/report-template.md).
 
 ## Expected Output
 
-- lint / type-check / test / build 等验证命令全部通过
-- 失败项已修复或给出明确原因和后续行动
-- 修复报告保存为 `reports/validation-fix-YYYY-MM-DD-HHmmss.md`
+- All verification commands such as lint/type-check/test/build passed
+- Failed items have been fixed or given clear reasons and follow-up actions
+- The fix report is saved as `reports/validation-fix-YYYY-MM-DD-HHmmss.md`

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

@@ -1,43 +1,43 @@
-# 验证修复报告模板
+# Verify repair report template
 
 ```markdown
-# 验证修复报告
+# Verify repair report
 
-> 生成时间: YYYY-MM-DD HH:mm
-> 验证范围: lint / type-check / test / build / CI
+> Generation time: YYYY-MM-DD HH:mm
+> Verification scope: lint/type-check/test/build/CI
 
-## 命令状态表
+## Command status table
 
-| 命令 | 初始状态 | 修复后状态 | 备注 |
+| Command | Initial state | Repaired state | Remarks |
 | --- | --- | --- | --- |
-| `npm run type-check` | 失败 / 通过 / 未运行 | 失败 / 通过 / 未运行 | ... |
+| `npm run type-check` | failed/passed/didn’t run | failed/passed/didn’t run | ... |
 
-## 失败摘要
+## Failure summary
 
-- 最早出现且会级联的错误
-- 受影响文件、错误类型和关键日志
-- 是否属于 CI 专属、测试环境、依赖版本或 flaky 问题
+- Errors that occur earliest and cascade
+- Affected files, error types and critical logs
+- Whether it is CI exclusive, test environment, dependent version or flaky issue
 
-## 根因
+## Root cause
 
-- 确认的根本原因
-- 支持该结论的输出、日志或复现证据
+- Confirmed root cause
+- Output, logs, or reproduction evidence to support the conclusion
 
-## 修复内容
+## Fix content
 
-- 修改的文件和行为
-- 为什么没有通过关闭规则、删除断言或降低类型安全来规避失败
+- Modified files and behavior
+- Why the failure was not circumvented by turning off rules, removing assertions, or reducing type safety
 
-## 验证结果
+## Verification results
 
-- 重新执行的命令
-- 命令输出摘要
-- 是否仍有失败项
+- Command to re-execute
+- Summary of command output
+- Are there still failed items?
 
-## 剩余风险
+## Residual risk
 
-- 未覆盖的验证命令
-- 仍需用户决策或外部环境确认的问题
+- Uncovered verification commands
+- Issues that still require user decision-making or external environment confirmation
 ```
 
-验证修复完成后，将报告保存到 `reports/validation-fix-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。
+After the verification fix is completed, save the report to `reports/validation-fix-YYYY-MM-DD-HHmmss.md` and inform the user of the report path.

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

@@ -1,44 +1,44 @@
 ---
 name: fec-vite-project-standard
-description: Use when creating, configuring, reviewing, or debugging Vite-based frontend projects, vite.config.ts, env variables, dev server proxy, HMR, plugin ordering, library mode, dependency pre-bundling, bundle splitting, or Vite build performance. Use framework-specific skills for React/Vue component architecture; Chinese triggers include Vite 配置, vite.config, Vite 构建, Vite 性能.
+description: Use when creating, configuring, reviewing, or debugging Vite-based frontend projects, vite.config.ts, env variables, dev server proxy, HMR, plugin ordering, library mode, dependency pre-bundling, bundle splitting, or Vite build performance. Use framework-specific skills for React/Vue component architecture; Chinese triggers include Vite configuration, vite.config, Vite build, Vite performance.
 ---
 
-# Vite 项目规范
+# Vite Project Specifications
 
-适用于 Vite 应用、组件库、开发服务器和构建配置的设计与审查。
+Design and review of Vite applications, component libraries, development servers, and build configurations.
 
 ## Purpose
 
-规范 Vite 配置、安全边界和构建性能，避免开发环境与生产构建的常见陷阱。
+Standardize Vite configurations, security boundaries, and build performance to avoid common pitfalls of development environments and production builds.
 
 ## Procedure
 
-1. 识别项目类型
-   - 应用项目优先检查 `root`、`base`、`server.proxy`、`envPrefix`、`build` 和框架插件。
-   - 组件库项目优先检查 `build.lib`、类型产物、peer dependencies external 和导出入口。
-   - Monorepo 额外检查 `server.fs.allow`、路径别名和包依赖边界。
-
-2. 选择插件
-   - React 默认优先 `@vitejs/plugin-react-swc`；需要 Babel 插件时才用 `@vitejs/plugin-react`。
-   - Vue 项目使用 `@vitejs/plugin-vue`，路径别名优先交给 `vite-tsconfig-paths`。
-   - TypeScript 项目必须通过 `tsc --noEmit`、CI 或 `vite-plugin-checker` 补齐类型检查。
-
-3. 管理环境变量
-   - 客户端只读取明确公开的前缀，如 `VITE_`。
-   - `loadEnv` 第三个参数使用显式前缀数组，不使用空字符串加载全部变量。
-   - 密钥、数据库地址、私有 token 必须留在服务端或构建系统，不进入客户端 bundle。
-
-4. 优化开发体验
-   - 慢启动先用 `vite --profile` 定位插件、解析或预构建瓶颈。
-   - 对 CJS/UMD 依赖用 `optimizeDeps.include` 处理互操作问题。
-   - 大项目可用 `server.warmup.clientFiles` 预热核心入口。
-
-5. 优化生产构建
-   - 发布前运行 `vite build`，并用 `vite preview` 做本地构建烟测。
-   - 手动分包使用稳定的对象形式优先，避免把每个依赖拆成独立小 chunk。
-   - 生产 sourcemap 默认关闭；若上传错误追踪平台，上传后不随站点公开。
-   - 动效、3D、图表、编辑器、地图和音视频处理库优先通过动态导入或路由级拆包隔离。
-   - 检查静态资源是否进入正确目录、是否被 hash/cache、是否存在占位 URL 或过大的未压缩媒体。
+1. Identify the project type
+   - Application projects check `root`, `base`, `server.proxy`, `envPrefix`, `build` and framework plugins first.
+   - Component library projects check `build.lib`, type products, peer dependencies external and export entries first.
+   - Monorepo additional checks for `server.fs.allow`, path aliases and package dependency boundaries.
+
+2. Select plugin
+   - React gives priority to `@vitejs/plugin-react-swc` by default; use `@vitejs/plugin-react` only when the Babel plug-in is required.
+   - The Vue project uses `@vitejs/plugin-vue`, and path aliases are given priority to `vite-tsconfig-paths`.
+   - TypeScript projects must complete type checking via `tsc --noEmit`, CI or `vite-plugin-checker`.
+
+3. Manage environment variables
+   - Clients only read explicitly exposed prefixes, such as `VITE_`.
+   - The third parameter of `loadEnv` uses an explicit prefix array and does not use an empty string to load all variables.
+   - Keys, database addresses, and private tokens must stay on the server or build system and not enter the client bundle.
+
+4. Optimize development experience
+   - Use `vite --profile` to locate plug-in, parsing or pre-built bottlenecks before slow start.
+   - Use `optimizeDeps.include` for CJS/UMD dependencies to handle interop issues.
+   - Large projects can use `server.warmup.clientFiles` to warm up the core entrance.
+
+5. Optimize production builds
+   - Run `vite build` before release and use `vite preview` to do local build smoke testing.
+   - Prioritize manual subcontracting by using stable object forms to avoid splitting each dependency into independent small chunks.
+   - The production sourcemap is turned off by default; if uploaded to the error tracking platform, it will not be published with the site after uploading.
+   - Motion effects, 3D, charts, editors, maps, and audio and video processing libraries are prioritized for isolation through dynamic import or route-level unpacking.
+   - Check whether static resources go into the correct directory, have been hashed/cache, have placeholder URLs, or are too large uncompressed media.
 
 ## Minimal Config
 
@@ -69,15 +69,15 @@ export default defineConfig(({ mode }) => {
 
 ## Constraints
 
-- `vite build` 只转译和打包，不等于类型检查；CI 必须另跑 typecheck。
-- `VITE_` 不是安全边界；任何 `VITE_` 变量都会进入客户端包。
-- 不设置 `envPrefix: ""`，不使用 `loadEnv(mode, root, "")` 后再随意 `define`。
-- 不默认引入 legacy 插件；只有真实用户数据需要时再启用。
-- 不用 `vite preview` 作为生产服务器。
-- 组件库必须 externalize peer dependencies，并单独产出 `.d.ts`。
-- 不把服务端密钥通过 `define`、`import.meta.env` 或空前缀 `loadEnv` 注入客户端。
-- 不把 GSAP、Three.js、Lottie、Monaco、地图 SDK 等重型库放进所有页面共享入口；先评估 async chunk 和首屏影响。
+- `vite build` only translates and packages, not type checking; CI must run typecheck separately.
+- `VITE_` is not a security boundary; any `VITE_` variable goes into the client package.
+- Do not set `envPrefix: ""`, do not use `loadEnv(mode, root, "")` and then `define` at will.
+- Legacy plugins are not introduced by default; only enable them when needed for real user data.
+- Don't use `vite preview` as a production server.
+- Component libraries must externalize peer dependencies and produce `.d.ts` separately.
+- Do not inject server keys into clients via `define`, `import.meta.env` or empty prefix `loadEnv`.
+- Do not put heavy libraries such as GSAP, Three.js, Lottie, Monaco, and Map SDK into all page sharing entries; first evaluate the impact of async chunk and first screen.
 
 ## Expected Output
 
-输出应包含项目类型判断、关键配置变更、环境变量安全说明、构建/开发性能验证方式。完成后 Vite 配置应可类型检查、可构建、密钥不泄露，并能解释 dev 与 build 的差异。
+The output should include project type judgment, key configuration changes, environment variable security instructions, and build/development performance verification methods. When completed, the Vite configuration should be type-checked, buildable, secret-secure, and explain the differences between dev and build.

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

@@ -1,49 +1,58 @@
 ---
 name: fec-vue3-project-standard
-description: Use when designing or reviewing Vue 3 + TypeScript project structure, SFC/component boundaries, composables organization, route composition, Pinia ownership, API/error/styling defaults, directives, or repository-wide Vue conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include Vue 3 项目规范, Vue 组件架构.
+description: Use when designing or reviewing Vue 3 + TypeScript project structure, SFC/component boundaries, composables organization, route composition, Pinia ownership, API/error/styling defaults, directives, or repository-wide Vue conventions. Prefer narrower skills for forms, data fetching, tests, accessibility, virtualization, animation, or security deep dives; Chinese triggers include Vue 3 project specification, Vue component architecture.
 ---
 
-# Vue 3 项目规范
+# Vue 3 project specifications
 
-适用于使用 Vue 3 + TypeScript 的仓库。
+For repositories using Vue 3 + TypeScript.
 
 ## Purpose
 
-为 Vue 3 + TypeScript 项目提供工程结构、组件边界、Composables 和默认实现约定，确保约定式开发和类型安全。
+Provides project structure, component boundaries, Composables, and default implementation conventions for Vue 3 + TypeScript projects to ensure conventional development and type safety.
 
 ## Procedure
 
-1. 识别仓库已有 Vue 约定：目录、路由、Pinia、请求层、样式体系、组件库和测试框架。
-2. 划分页面、业务组件、通用组件、composables、stores、services 和 utils 的边界。
-3. 优先沿用 `<script setup lang="ts">`、组合式 API 和仓库现有自动导入/模块出口约定。
-4. 输出时补齐状态归属、API 层、错误处理、样式隔离和专项 skill 分流。
-5. 页面和模块要有可恢复错误 UI；全局 `errorHandler`、`onErrorCaptured`、请求错误映射和路由错误页分工明确。
-6. Tailwind token/variant 或响应式布局需求应分流到对应专项 skill，避免把样式系统规则塞进 Vue 组件规范。
-5. 状态归属复杂时先做状态清单；DTO、公共 props 或泛型 composable 复杂时先收敛 TypeScript 类型契约。
+1. Identify the existing Vue conventions in the warehouse: directory, routing, Pinia, request layer, style system, component library and test framework.
+2. Demarcate the boundaries between pages, business components, common components, composables, stores, services and utils.
+3. Prioritize the existing automatic import/module export conventions of `<script setup lang="ts">`, composite API and warehouse.
+4. Complete state ownership, API layer, error handling, style isolation and special skill offloading when outputting.
+5. Pages and modules must have recoverable error UI; global `errorHandler`, `onErrorCaptured`, request error mapping and routing error page have clear division of labor.
+6. Tailwind token/variant or responsive layout requirements should be diverted to corresponding special skills to avoid stuffing style system rules into Vue component specifications.
+7. When the state ownership is complex, first make a state list; when the boundaries of DTO, public props, generic composable or `tsconfig` are complex, first use the TypeScript project specification process to converge cross-framework type contracts.
+8. When designing reusable composables, clarify whether the input supports plain value, ref, computed or getter; when testing Vue components, cover the common boundaries of Pinia, Router, Teleport, Suspense and async setup.
 
-## 详细参考
+## Detailed reference
 
-需要具体 Vue 3 项目结构、组件模式、Composables、slots、Provide/Inject、路由、Pinia、API 层、错误处理、指令、样式、TypeScript、测试、性能或审查清单时，加载 [references/vue3-project-details.md](references/vue3-project-details.md)。
+Load more detailed reference files as needed:
+
+- Project directory, component layering, component specifications, annotations, and TypeScript: Load [references/vue3-project-structure.md](references/vue3-project-structure.md).
+- Composables, slots, Provide/Inject and routing organizations: Load [references/vue3-composables-routing.md](references/vue3-composables-routing.md).
+- Pinia, API layer, error handling, directives, styles, tests, anti-patterns and output checklist: Loading [references/vue3-state-api-quality.md](references/vue3-state-api-quality.md).
+- Lightweight performance conventions at the Vue project specification level: Load [references/vue3-performance-patterns.md](references/vue3-performance-patterns.md).
 
 ## Constraints
 
-- 使用 `<script setup lang="ts">`，禁止使用 Options API 新增组件
-- 组件文件规模宜约 **300 行**内；逾 **500 行**或复杂度过高须拆子组件与 Composables
-- Props / Emits 必须使用 TypeScript interface 定义，禁止使用 `any`
-- Composable 返回 `readonly` 引用，防止外部意外修改
-- 不要在 store 中存放 UI 临时状态（modal 开关、表单输入等）
-- 服务端数据优先用请求库管理，而非手动存入 Pinia
-- 避免在 `v-for` 中使用 `v-if`（提取为 computed 过滤）
-- 禁止直接从 feature 内部深层路径导入，绕过 `index.ts`
-- 不用全局错误处理吞掉组件内可恢复的 API、表单或权限错误。
+- Use `<script setup lang="ts">` to disable using Options API to add new components
+- The size of the component file should be approximately **300 lines**; if it exceeds **500 lines** or is too complex, sub-components and Composables must be separated
+- Props / Emits must be defined using the TypeScript interface, and `any` is prohibited
+- Composable returns a `readonly` reference to prevent accidental external modifications
+- Do not store UI temporary states (modal switches, form inputs, etc.) in the store
+- Server-side data is first managed by the request library rather than manually stored in Pinia
+- Avoid using `v-if` in `v-for` (extract to computed filtering)
+- It is forbidden to import directly from the deep path inside the feature, bypassing `index.ts`
+- No need for global error handling to swallow recoverable API, form or permission errors within components.
+- Do not mistake function parameters for getter automatic calls; if composable parameters may be callbacks, avoid using getter input conventions.
+- Do not rely on snapshots as the only assertions for Vue components; asynchronous components, Teleport and Pinia scenes must have user-visible behavior assertions.
 
 ## Expected Output
 
-- 组件使用 `<script setup lang="ts">`，Props / Emits 类型完整
-- 可复用逻辑已提取到 composable，返回 `readonly` 引用
-- Loading / Error / Empty / Data 状态均已处理
-- 路由组件使用动态 import 加载，状态管理符合就近原则
-- URL 状态、服务端状态、表单状态和 Pinia 全局状态边界明确
-- API 调用有类型约束和统一错误处理
-- 样式使用 scoped 隔离，关键行为有测试覆盖
-- 文件结构与项目约定一致（pages / features / components 分离）
+- The component uses `<script setup lang="ts">`, and the Props/Emits type is complete
+- Reusable logic has been extracted to composable, returning `readonly` reference
+- Loading / Error / Empty / Data status have been processed
+- Routing components are loaded using dynamic import, and state management conforms to the proximity principle
+- URL status, server status, form status and Pinia global status have clear boundaries
+- API calls have type constraints and unified error handling
+- Styles are isolated using scoped, and key behaviors are covered by tests
+- The file structure is consistent with the project convention (pages/features/components are separated)
+- Input responsiveness, Pinia/Router boundaries and asynchronous component testing strategies for reusable composables explained