@bovinphang/frontend-craft 2.5.0

package/skills/fec-typescript-type-safety/references/type-safety-patterns.md

@@ -0,0 +1,102 @@
+# 类型安全模式
+
+## 类型边界审查清单
+
+- DTO 应与外部载荷对应，并在 API 边界处进行转换。
+- 领域模型或视图模型使用前端命名和稳定的联合类型。
+- 组件 props 需命名明确，仅在该文件外复用时才导出。
+- 公开函数必须有显式的参数和返回值类型。
+- 外部输入必须从 `unknown` 开始，通过 schema 校验或类型守卫逐步收窄。
+- 配置映射表优先使用 `as const` 和 `satisfies`，避免宽泛断言。
+
+## 使用 `satisfies` 的配置映射表
+
+```ts
+type Tone = "neutral" | "success" | "warning" | "danger";
+
+const STATUS_TONE = {
+  draft: "neutral",
+  paid: "success",
+  overdue: "danger",
+} as const satisfies Record<string, Tone>;
+
+type InvoiceStatus = keyof typeof STATUS_TONE;
+```
+
+这样既保留了字面量值，又验证了映射表符合预期的值域。
+
+## 映射类型用于表单错误
+
+```ts
+type FieldErrors<TValues extends Record<string, unknown>> = {
+  [Key in keyof TValues]?: string;
+};
+
+interface ProfileFormValues {
+  email: string;
+  displayName: string;
+}
+
+type ProfileFormErrors = FieldErrors<ProfileFormValues>;
+```
+
+## 模板字面量类型用于事件命名
+
+```ts
+interface AnalyticsPayloads {
+  checkoutStarted: { cartId: string };
+  checkoutCompleted: { orderId: string };
+}
+
+type AnalyticsEventName = keyof AnalyticsPayloads;
+type AnalyticsHandlerName = `on${Capitalize<string & AnalyticsEventName>}`;
+```
+
+当项目中已有事件命名规范时使用此模式。不要为一次性字符串引入。
+
+## 更安全的泛型组件模式
+
+```tsx
+interface Entity {
+  id: string;
+}
+
+interface EntityPickerProps<TEntity extends Entity> {
+  items: TEntity[];
+  selectedId: string | null;
+  getLabel: (item: TEntity) => string;
+  onSelect: (item: TEntity) => void;
+}
+
+export function EntityPicker<TEntity extends Entity>({
+  items,
+  selectedId,
+  getLabel,
+  onSelect,
+}: EntityPickerProps<TEntity>) {
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>
+          <button
+            aria-pressed={item.id === selectedId}
+            type="button"
+            onClick={() => onSelect(item)}
+          >
+            {getLabel(item)}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## 类型审查反馈
+
+报告类型安全问题时，需包含：
+
+- 过于宽泛、过于狭窄或不合理的类型边界。
+- 尽管通过 TypeScript 但可能在运行时失败的行為。
+- 最小替换类型或守卫方案。
+- 该变更是否需要测试或类型测试。

package/skills/fec-ui-design/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: fec-ui-design
+description: Use when building, reviewing, or improving frontend UI that needs product-specific design direction, design-system generation, Master/Page overrides, distinctive visual identity, anti-generic interface choices, first-screen hierarchy, UI polish, chart UX, interaction states, responsive behavior, or visual QA. When an external design file is authoritative, implement from that source instead of inventing direction; Chinese triggers include UI 设计, 设计系统, 视觉风格, 不要模板化, 高级感, 界面打磨, 交互状态.
+---
+
+# UI 设计
+
+适用于需要把前端界面推进到“符合产品语境、可扫描、可信赖、有辨识度，并且细节稳定”的 UI 任务。需要系统化设计建议时，加载 [design-intelligence.md](references/design-intelligence.md)；需要长期沉淀设计系统时，加载 [master-page-overrides.md](references/master-page-overrides.md)；上线前做 UI/UX QA 时，加载 [pre-delivery-checklist.md](references/pre-delivery-checklist.md)。
+
+可执行设计系统生成器位于 [design-system.mjs](scripts/design-system.mjs)，其原创知识包包括 [product-rules.json](data/product-rules.json)、[style-archetypes.json](data/style-archetypes.json)、[ux-quality-rules.json](data/ux-quality-rules.json) 和 [stack-ui-rules.json](data/stack-ui-rules.json)。
+
+## Purpose
+
+为页面、组件、仪表盘和工具界面建立设计方向，并完成可落地的视觉与交互 polish。
+
+## Procedure
+
+1. 明确界面的工作
+   - 先说清它帮助用户完成什么任务，而不是先选颜色或布局。
+   - 判断这是日常高频工具、营销展示、内容阅读、可视化探索、游戏，还是配置/管理后台。
+   - 如果已有 Figma、Sketch、MasterGo、Pixso、墨刀、摹客或截图是事实来源，优先还原设计上下文，不自行发明方向。
+
+2. 定义审美主张
+   - 写出目标用户、使用场景、可信赖感来源和一个可被记住的视觉锚点。
+   - 视觉锚点可以来自信息结构、真实媒体、数据形态、行业材质、字体性格、交互节奏或空间组织，而不是空泛装饰。
+   - 表现力必须服务业务语境：工具型界面重效率和稳定，展示型页面重主体识别和记忆点。
+   - 为页面类型设定设计拨盘：信息密度、视觉张力、动效强度、内容说服力和媒体真实性；这些拨盘必须随任务变化，而不是沿用同一套模板。
+
+3. 生成或读取设计系统
+   - 若项目还没有设计系统，可运行 `node skills/fec-ui-design/scripts/design-system.mjs "<product audience tone>" --project "<name>"` 生成建议。
+   - 若需要跨会话复用，使用 `--persist` 生成 `design-system/<project>/MASTER.md`；页面差异用 `--page <page>` 写入 `pages/<page>.md`。
+   - 构建具体页面时先读页面 override，再读 Master；页面规则只覆盖差异，不复制全量设计系统。
+
+4. 建立首屏与视觉层级
+   - 工具型界面：首屏直接呈现核心工作区、列表、表格、画布或编辑器。
+   - 落地页：H1 使用品牌、产品、地点、人名或明确品类，价值说明放在辅助文案。
+   - 产品/对象页：首屏必须可见真实产品、对象、状态或可检查媒体。
+   - 首屏应留下一个明确记忆点，但不能遮挡核心任务、导航和状态反馈。
+   - 营销和产品页需要先写清受众、痛点、承诺、证据和行动入口；文案结构服务转化，但不使用夸张、空泛或不可验证的声明。
+
+5. 组织视觉语言
+   - 字体：优先沿用项目字体体系；若任务允许建立新方向，选择能表达产品性格的标题/正文字体组合，并保证可读性。
+   - 色彩：明确主色、功能色、中性色和强调色的角色，避免所有元素平均用力。
+   - 空间：根据任务选择高密度、留白、非对称、分栏、画布式或编辑器式布局，不套用固定卡片模板。
+   - 动效：只为页面入场、层级展开、状态确认、错误反馈和重点引导建立节奏，并尊重 `prefers-reduced-motion`。
+   - 媒体：优先使用真实产品、真实状态、真实图表、可检查截图或本地生成资产；不要用模糊氛围图、占位 URL 或无关插画替代主体信息。
+   - 图表：先判断数据任务是趋势、比较、构成、分布还是流程，再选择图表，不把所有数据都做成卡片或饼图。
+
+6. 对齐设计系统、组件与 token
+   - 先复用项目已有组件、token、图标库、路由和布局约定。
+   - 缺少 token 时集中补齐或明确记录，不要在多个组件里散落硬编码。
+   - 复杂 UI 在实现前写出复用组件、新建组件、响应式策略和状态覆盖。
+   - 设计系统先定义语义 token、组件 API、状态矩阵和使用边界，再落到 Tailwind、CSS Modules、组件库或 CSS 变量实现。
+   - Tailwind 专项 token、variant、dark mode 和 class 治理分流到 Tailwind 设计系统工作流；跨设备布局、容器查询和触摸目标分流到响应式布局工作流。
+   - 组件 API 应区分基础组件、业务组件和页面私有组件；避免让单个 `variant` 同时承担语义、尺寸、密度和权限含义。
+
+7. 打磨几何、文本和状态
+   - 嵌套圆角遵循“外层圆角约等于内层圆角 + 间距”的光学关系。
+   - 非对称图标、播放三角、箭头、星标等需要按视觉中心微调。
+   - 标题和短文本可使用 `text-wrap: balance` 或 `text-wrap: pretty`。
+   - 表格、价格、计数器、计时器使用 `font-variant-numeric: tabular-nums`。
+   - 小控件点击区域至少 40x40px，空间允许时优先 44x44px。
+   - focus ring 用于键盘定位，hover/active 用于鼠标反馈，disabled 不只靠透明度表达。
+
+8. 验证设计结果
+   - 检查 loading、empty、error、disabled、hover、focus、selected 状态。
+   - 在 mobile(375px)、tablet(768px)、desktop(1440px) 检查文案是否溢出或遮挡。
+   - 对依赖图片、图表、画布或 3D 的界面，确认资源真实渲染且承担主体信息。
+   - 复核是否存在默认紫色渐变、空泛 hero、卡片堆叠、单一色相或无语境字体等模板化痕迹。
+   - 检查首屏是否同时具备任务入口、主体识别、可信证据和下一屏内容线索；若只剩装饰，应回到信息架构重做。
+   - 对生产级控件补齐 hover、active、focus-visible、disabled、loading、selected、invalid 和 skeleton 状态。
+   - 对仪表盘、表格、编辑器和配置台检查扫描路径、密度、固定尺寸和重复使用时的疲劳感。
+
+## Constraints
+
+- 不把工具型应用做成营销落地页；首屏应是可用工作区。
+- 不用通用紫色渐变、装饰光斑、堆叠卡片或空泛 hero 作为默认方案。
+- 不使用无语境默认字体、均匀无重点配色、重复圆角卡片和模板化双栏 hero 来替代真实设计判断。
+- 不在卡片里再套大卡片；页面分区优先用全宽区域或无框布局。
+- 不用可见文案解释控件本该表达的功能，常见动作优先用图标和 tooltip。
+- 不为了质感添加大面积装饰、模糊光斑、无语义渐变或无关重写。
+- 不为了统一风格让整个界面落入单一色相；颜色应有层次和语义区分。
+- 不把生成器输出当成不可修改的设计稿；它是决策起点，必须结合项目已有组件、token、用户任务和真实数据校正。
+- 不用不可检查的远程占位图、通用 stock 氛围图或 lorem 文案作为交付主体；缺素材时明确生成、制作或降级为真实结构化内容。
+- 不让视觉 polish 破坏键盘路径、触摸目标、文本可读性或低端设备性能。
+- 不把 Tailwind、组件库或 Storybook 文档等实现载体当成设计方向本身；它们应承接已经明确的产品语境和 token 边界。
+
+## Expected Output
+
+输出应包含明确的设计方向、首屏记忆点、视觉语言策略、组件/布局边界、状态覆盖、响应式策略和验证结果。复核时界面应符合业务语境、视觉层级支持快速扫描、交互状态完整，并避免泛化模板感。

package/skills/fec-ui-design/data/product-rules.json

@@ -0,0 +1,110 @@
+[
+  {
+    "id": "saas",
+    "keywords": ["saas", "b2b", "subscription", "crm", "admin", "console"],
+    "pattern": "Work-first dashboard with concise onboarding and persistent primary action",
+    "style": "data-dense",
+    "colorMood": "trustworthy neutrals with a clear action accent",
+    "typographyMood": "professional, compact, readable",
+    "motion": "quiet transitions for filters, drawers, and state changes",
+    "chart": "stat cards plus line/bar charts for trends and comparisons",
+    "risks": ["marketing hero replacing the workspace", "low-density cards hiding operational detail"],
+    "antiPatterns": ["decorative gradients as primary structure", "unlabeled icon-only tools"]
+  },
+  {
+    "id": "fintech",
+    "keywords": ["fintech", "bank", "finance", "crypto", "wallet", "invoice", "billing"],
+    "pattern": "Trust-first dashboard with balances, risk states, audit trail, and clear next actions",
+    "style": "minimal",
+    "colorMood": "stable blue/green neutrals with strict danger states",
+    "typographyMood": "precise, numeric, high contrast",
+    "motion": "subtle confirmation and risk feedback only",
+    "chart": "time-series, comparison bars, and tabular details with export paths",
+    "risks": ["playful visual language reducing trust", "color-only profit/loss communication"],
+    "antiPatterns": ["neon cyber styling for serious finance", "ambiguous destructive actions"]
+  },
+  {
+    "id": "healthcare",
+    "keywords": ["health", "medical", "clinic", "dental", "pharmacy", "patient", "therapy"],
+    "pattern": "Guided task flow with calm hierarchy, strong labels, and clear recovery paths",
+    "style": "minimal",
+    "colorMood": "calm accessible tones with clear warning and error roles",
+    "typographyMood": "human, readable, low fatigue",
+    "motion": "reassuring transitions, no surprise movement",
+    "chart": "progress trends and summaries with plain-language explanations",
+    "risks": ["low contrast calming palettes", "hidden labels in critical forms"],
+    "antiPatterns": ["decorative medical imagery over task clarity", "tiny touch targets"]
+  },
+  {
+    "id": "ecommerce",
+    "keywords": ["shop", "store", "ecommerce", "marketplace", "cart", "checkout", "product"],
+    "pattern": "Product-led browsing with strong media, filters, comparison, and checkout confidence",
+    "style": "editorial",
+    "colorMood": "brand-forward accents with neutral product surfaces",
+    "typographyMood": "clear commerce hierarchy with readable prices",
+    "motion": "fast hover/tap feedback and cart confirmation",
+    "chart": "only for seller dashboards or comparison analytics",
+    "risks": ["visual effects competing with product inspection", "unclear price/availability states"],
+    "antiPatterns": ["cropped product media", "hidden shipping or error feedback"]
+  },
+  {
+    "id": "creative",
+    "keywords": ["portfolio", "agency", "studio", "creator", "photography", "editorial"],
+    "pattern": "Portfolio-led narrative with memorable first viewport and selective case-study depth",
+    "style": "editorial",
+    "colorMood": "high-contrast neutrals with one expressive accent",
+    "typographyMood": "distinctive display with restrained body",
+    "motion": "purposeful reveals tied to content rhythm",
+    "chart": "rare; use visual timelines or case metrics when needed",
+    "risks": ["style overpowering work samples", "scroll theatrics blocking access"],
+    "antiPatterns": ["generic split hero", "decorative mockups without real work"]
+  },
+  {
+    "id": "wellness",
+    "keywords": ["spa", "beauty", "wellness", "meditation", "fitness", "booking", "lifestyle"],
+    "pattern": "Emotion-led service page with service clarity, trust proof, and low-friction booking",
+    "style": "soft",
+    "colorMood": "warm natural tones with a premium accent",
+    "typographyMood": "calm, elegant, approachable",
+    "motion": "gentle, short transitions with reduced-motion fallback",
+    "chart": "habit streaks or progress charts only when product-led",
+    "risks": ["pastel contrast failures", "luxury styling hiding booking details"],
+    "antiPatterns": ["overly bright wellness gradients", "placeholder stock atmosphere"]
+  },
+  {
+    "id": "education",
+    "keywords": ["education", "learning", "course", "student", "school", "flashcard"],
+    "pattern": "Learning path with progress, next task, feedback loops, and approachable empty states",
+    "style": "bento",
+    "colorMood": "encouraging accents with quiet surfaces",
+    "typographyMood": "friendly, readable, structured",
+    "motion": "reward moments and progress feedback, never distracting from reading",
+    "chart": "progress, mastery, and completion summaries",
+    "risks": ["gamification clutter", "unclear next lesson state"],
+    "antiPatterns": ["dense dashboards for beginners", "reward animation blocking tasks"]
+  },
+  {
+    "id": "gaming",
+    "keywords": ["game", "gaming", "esports", "arcade", "quest", "leaderboard"],
+    "pattern": "Immersive status-first interface with strong feedback and readable controls",
+    "style": "immersive",
+    "colorMood": "high-energy palette balanced by readable surfaces",
+    "typographyMood": "expressive headings with legible UI text",
+    "motion": "high feedback, strict performance budget",
+    "chart": "leaderboards, comparisons, progression, and match history",
+    "risks": ["motion overload", "stylized text reducing readability"],
+    "antiPatterns": ["all-caps tiny labels", "animations that delay input"]
+  },
+  {
+    "id": "data-dashboard",
+    "keywords": ["dashboard", "analytics", "metrics", "kpi", "monitoring", "reporting"],
+    "pattern": "Scan-first analytical workspace with filters, summaries, charts, and drill-down paths",
+    "style": "data-dense",
+    "colorMood": "semantic chart palette with restrained UI chrome",
+    "typographyMood": "compact, tabular, legible",
+    "motion": "state transitions only; no decorative chart animation by default",
+    "chart": "match chart to question: trend, compare, composition, distribution, funnel, timeline",
+    "risks": ["chart decoration hiding insight", "too many equal-weight cards"],
+    "antiPatterns": ["pie charts for many categories", "color-only series distinction"]
+  }
+]

package/skills/fec-ui-design/data/stack-ui-rules.json

@@ -0,0 +1,14 @@
+[
+  { "stack": "react", "keywords": ["react", "vite", "spa"], "guidance": ["Keep visual components pure and prop-driven", "Split expensive lists and charts", "Use existing component and token conventions before adding UI primitives"] },
+  { "stack": "next", "keywords": ["next", "nextjs", "app router"], "guidance": ["Keep route shells and loading/error states explicit", "Prefer server components for static content and data shells", "Use client components only for interaction-heavy UI"] },
+  { "stack": "vue", "keywords": ["vue", "vue3"], "guidance": ["Use scoped components and composables for view logic", "Keep Pinia/global state out of purely local UI state", "Preserve SFC style boundaries"] },
+  { "stack": "nuxt", "keywords": ["nuxt"], "guidance": ["Use layouts for persistent UI chrome", "Align useFetch/useAsyncData states with loading and error UI", "Keep route middleware separate from component display logic"] },
+  { "stack": "svelte", "keywords": ["svelte"], "guidance": ["Use component-local reactivity for UI state", "Keep transitions meaningful and reduced-motion aware", "Avoid global stores for local interaction state"] },
+  { "stack": "astro", "keywords": ["astro"], "guidance": ["Use islands only where interaction is needed", "Keep marketing content fast and mostly static", "Prioritize image optimization and content hierarchy"] },
+  { "stack": "angular", "keywords": ["angular"], "guidance": ["Prefer standalone components", "Keep templates declarative", "Use CDK/a11y patterns for overlays and focus"] },
+  { "stack": "react-native", "keywords": ["react native", "rn", "mobile"], "guidance": ["Respect safe areas and platform gestures", "Use 44/48px touch targets", "Test dynamic type and screen reader labels"] },
+  { "stack": "flutter", "keywords": ["flutter"], "guidance": ["Prefer composition with small widgets", "Use theme tokens instead of per-screen styles", "Respect platform text scaling and safe areas"] },
+  { "stack": "threejs", "keywords": ["three", "threejs", "webgl", "3d"], "guidance": ["Make the primary scene full-bleed when it is the experience", "Provide DOM controls and accessible summaries", "Verify canvas is nonblank and resources dispose cleanly"] },
+  { "stack": "shadcn", "keywords": ["shadcn", "tailwind"], "guidance": ["Use shadcn components as accessible primitives", "Map theme variables before custom styling", "Avoid arbitrary utility soup when a token exists"] },
+  { "stack": "tailwind", "keywords": ["tailwind", "html"], "guidance": ["Keep mobile-first utilities", "Extract repeated class patterns into components", "Use semantic CSS variables for theme-critical color"] }
+]

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

@@ -0,0 +1,74 @@
+[
+  {
+    "id": "minimal",
+    "keywords": ["minimal", "clean", "enterprise", "trust", "calm"],
+    "description": "Quiet surfaces, strong hierarchy, restrained accents, fast scanning.",
+    "tokens": { "radius": "4-8px", "shadow": "low", "density": "medium-high" },
+    "bestFor": ["enterprise", "finance", "healthcare", "documentation"],
+    "avoid": ["empty white space without information priority", "low-contrast gray text"]
+  },
+  {
+    "id": "editorial",
+    "keywords": ["editorial", "magazine", "portfolio", "brand", "luxury"],
+    "description": "Expressive typography, strong media, controlled asymmetry, narrative pacing.",
+    "tokens": { "radius": "0-8px", "shadow": "content-dependent", "density": "medium" },
+    "bestFor": ["creative", "ecommerce", "portfolio", "launch pages"],
+    "avoid": ["decorative text that harms reading", "media that hides the actual product"]
+  },
+  {
+    "id": "glass",
+    "keywords": ["glass", "modern", "ai", "overlay", "depth"],
+    "description": "Layered translucent surfaces used sparingly for hierarchy and focus.",
+    "tokens": { "radius": "12-20px", "shadow": "soft depth", "density": "medium" },
+    "bestFor": ["modern SaaS", "AI tools", "visualization"],
+    "avoid": ["blurred low-contrast text", "using blur as pure decoration"]
+  },
+  {
+    "id": "brutalist",
+    "keywords": ["brutalist", "raw", "bold", "youth", "experimental"],
+    "description": "Hard edges, bold contrast, visible structure, intentionally direct composition.",
+    "tokens": { "radius": "0-4px", "shadow": "hard or none", "density": "variable" },
+    "bestFor": ["creative campaigns", "youth brands", "experimental portfolios"],
+    "avoid": ["serious regulated workflows", "inaccessible contrast or chaotic navigation"]
+  },
+  {
+    "id": "bento",
+    "keywords": ["bento", "cards", "modular", "features", "education"],
+    "description": "Modular information blocks with varied scale and clear grouping.",
+    "tokens": { "radius": "8px or less unless system differs", "shadow": "subtle", "density": "medium" },
+    "bestFor": ["feature overviews", "learning paths", "product summaries"],
+    "avoid": ["card-inside-card layouts", "equal-weight modules that hide priority"]
+  },
+  {
+    "id": "data-dense",
+    "keywords": ["dashboard", "analytics", "table", "monitoring", "dense"],
+    "description": "Operational density, table/chart alignment, semantic color, stable controls.",
+    "tokens": { "radius": "4-8px", "shadow": "minimal", "density": "high" },
+    "bestFor": ["dashboards", "admin", "monitoring", "analytics"],
+    "avoid": ["marketing hero screens", "large decorative cards"]
+  },
+  {
+    "id": "immersive",
+    "keywords": ["immersive", "game", "3d", "canvas", "story", "visualization"],
+    "description": "Full-bleed visual space with controls that remain predictable and readable.",
+    "tokens": { "radius": "contextual", "shadow": "scene-driven", "density": "low-medium" },
+    "bestFor": ["games", "3D previews", "interactive visualization"],
+    "avoid": ["framing the primary scene in a decorative card", "controls hidden by atmosphere"]
+  },
+  {
+    "id": "mobile-native",
+    "keywords": ["mobile", "app", "native", "touch", "safe-area"],
+    "description": "Touch-first layout with platform-safe spacing, clear feedback, and resilient text scaling.",
+    "tokens": { "radius": "platform-consistent", "shadow": "native elevation", "density": "touch-comfortable" },
+    "bestFor": ["mobile apps", "responsive tools", "field workflows"],
+    "avoid": ["hover-only behavior", "content behind safe areas"]
+  },
+  {
+    "id": "soft",
+    "keywords": ["soft", "wellness", "beauty", "calm", "organic"],
+    "description": "Warm surfaces, gentle contrast, tactile spacing, and calm interaction rhythm.",
+    "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"]
+  }
+]

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

@@ -0,0 +1,56 @@
+[
+  {
+    "category": "accessibility",
+    "priority": "critical",
+    "checks": ["Text contrast meets WCAG AA", "Focus rings are visible", "Icon-only controls have names", "Keyboard order follows visual order"],
+    "avoid": ["Removing outlines globally", "Color-only error or success states"]
+  },
+  {
+    "category": "interaction",
+    "priority": "critical",
+    "checks": ["Primary controls respond within 100ms", "Touch targets are at least 44x44px", "Disabled states are semantic and visible"],
+    "avoid": ["Hover-only primary actions", "Tap targets packed without spacing"]
+  },
+  {
+    "category": "performance",
+    "priority": "high",
+    "checks": ["Images reserve dimensions", "Large lists are virtualized", "Animations use transform/opacity", "Heavy visual work is deferred or moved off main thread"],
+    "avoid": ["Animating layout properties", "Unbounded chart or table rendering"]
+  },
+  {
+    "category": "layout",
+    "priority": "high",
+    "checks": ["375/768/1024/1440px layouts are checked", "No horizontal overflow", "Fixed headers/footers reserve content space"],
+    "avoid": ["Desktop-first max-width fixes", "Nested scroll regions without reason"]
+  },
+  {
+    "category": "typography",
+    "priority": "medium",
+    "checks": ["Body text stays readable", "Line length is controlled", "Numbers use tabular figures where alignment matters"],
+    "avoid": ["Tiny low-contrast labels", "Negative tracking on body text"]
+  },
+  {
+    "category": "animation",
+    "priority": "medium",
+    "checks": ["Micro-interactions are 150-300ms", "Exit is faster than enter", "Reduced motion is respected"],
+    "avoid": ["Decorative motion without cause", "Blocking input during transitions"]
+  },
+  {
+    "category": "forms",
+    "priority": "medium",
+    "checks": ["Labels are persistent", "Errors appear near fields", "Submit has loading/success/error feedback", "First invalid field receives focus"],
+    "avoid": ["Placeholder-only labels", "Error summary without field recovery"]
+  },
+  {
+    "category": "navigation",
+    "priority": "high",
+    "checks": ["Current location is visible", "Back behavior preserves state", "Primary navigation remains reachable"],
+    "avoid": ["Mixing multiple primary nav systems", "Using modals for primary navigation"]
+  },
+  {
+    "category": "charts",
+    "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"]
+  }
+]

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

@@ -0,0 +1,37 @@
+# 设计智能参考
+
+本参考用于把模糊的 UI 请求转成可执行设计系统。先识别产品类别，再组合风格原型、色彩角色、字体情绪、动效节奏、图表任务和 UX 风险。
+
+## 决策流程
+
+1. 提取关键词：产品类型、用户、场景、主要任务、内容密度、品牌语气、技术栈。
+2. 匹配产品规则：从 `data/product-rules.json` 选择最接近的类别，记录推荐结构、风险和反模式。
+3. 选择风格原型：从 `data/style-archetypes.json` 选择 1 个主风格和最多 1 个辅助风格，避免风格拼贴。
+4. 建立 token 方向：定义主色、强调色、背景、前景、边框、危险色和 focus ring 的语义角色。
+5. 选择字体情绪：不要只选“好看的字体”，要说明标题和正文各自承担的语气与可读性。
+6. 判断数据表达：趋势用折线/面积，比较用柱状，构成少量类别可用环图，流程用漏斗/步骤，明细必须保留表格替代。
+7. 输出反模式：每个设计建议必须附带“不要做什么”，避免落入通用模板。
+
+## 何时运行生成器
+
+使用以下命令生成设计系统建议：
+
+```bash
+node skills/fec-ui-design/scripts/design-system.mjs "beauty spa booking" --project "Serenity Spa"
+```
+
+输出 Markdown 适合贴入计划或 PR 描述；输出 JSON 适合测试或工具消费：
+
+```bash
+node skills/fec-ui-design/scripts/design-system.mjs "fintech analytics dashboard" --format json --stack next
+```
+
+## 输出必须回答
+
+- 这个界面的主任务是什么？
+- 推荐哪种页面结构或工作区结构？
+- 视觉锚点是什么，为什么贴合业务？
+- 主风格、字体、色彩、动效分别服务什么目标？
+- 图表和数据密度如何处理？
+- 哪些反模式必须避免？
+- 上线前最小 QA 清单是什么？

package/skills/fec-ui-design/references/master-page-overrides.md

@@ -0,0 +1,30 @@
+# 全局/页面级差异覆盖
+
+当项目需要长期保持 UI 一致性时，用 `design-system/MASTER.md` 存放全局设计系统，用 `design-system/pages/<page>.md` 存放页面级差异。
+
+## 读取顺序
+
+1. 先检查当前页面是否有 `design-system/<project>/pages/<page>.md`。
+2. 如果存在，页面文件里的规则覆盖 Master 中相同维度。
+3. 如果不存在，完全遵循 `design-system/<project>/MASTER.md`。
+4. 页面文件只记录差异，不复制 Master 全文。
+
+## 生成命令
+
+```bash
+node skills/fec-ui-design/scripts/design-system.mjs "saas analytics dashboard" --project "Acme Console" --persist --output-dir .
+```
+
+生成页面 overrides：
+
+```bash
+node skills/fec-ui-design/scripts/design-system.mjs "saas analytics dashboard" --project "Acme Console" --page dashboard --persist --output-dir .
+```
+
+## 页面 override 应包含
+
+- 页面任务和信息密度差异
+- 布局差异：工作区、表格、图表、表单、详情页或营销首屏
+- token 差异：只写需要覆盖的语义色、间距、状态或图表色
+- 组件差异：只写当前页面新增或改变的组件行为
+- QA 焦点：当前页面最容易出错的响应式、可访问性、性能或交互风险

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

@@ -0,0 +1,33 @@
+# UI/UX 交付前检查
+
+## 严重
+
+- 文本对比度：正文至少 4.5:1，大字号至少 3:1。
+- 键盘可达：菜单、弹窗、标签页、抽屉和自定义控件都能键盘操作。
+- 焦点可见：focus ring 不能被全局样式移除。
+- 图标按钮：必须有可访问名称。
+- 触摸目标：移动端主要交互至少 44x44px；空间允许时使用 48px。
+
+## 高优先级
+
+- 首屏：工具型界面直接展示核心工作区，不用营销 hero 替代功能。
+- 响应式：375px、768px、1024px、1440px 无水平溢出、遮挡或文本截断。
+- 性能：图片有尺寸或 aspect-ratio；非首屏图片懒加载；列表过大时虚拟化。
+- 动效：只动画 transform/opacity，尊重 `prefers-reduced-motion`。
+- 状态：loading、empty、error、disabled、hover、focus、selected 都有设计。
+
+## 中优先级
+
+- 字体：正文不小于 16px；数字列、金额、计时器使用 tabular nums。
+- 颜色：错误、成功、警告不只靠颜色表达。
+- 表单：label 常驻，错误靠近字段，提交后有 loading/success/error。
+- 导航：当前路由可识别，返回行为可预测，深层页面仍能回到主路径。
+- 图表：有标题、单位、图例、tooltip 或明细表替代，色彩不依赖红绿区分。
+
+## 反模式
+
+- 用装饰光斑、紫色渐变、卡片堆叠掩盖信息结构不足。
+- hover 导致布局位移。
+- `transition: all`、`will-change: all`。
+- 低对比灰字、无意义透明度、单一色相界面。
+- 空状态只有“暂无数据”，没有下一步动作。