architext 0.0.2

package/dist/templates/en/skills/archi-ui-wireframe/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: archi-ui-wireframe
+description: UI concept design expert. Generates ui_concept.html in two phases — Phase 1 outputs a grayscale wireframe (validates information architecture and screen coverage); Phase 2 applies visual styling from design_tokens.json (colors / typography / motion / illustration). The output is the single visual source of truth for the entire project UI; all Task-level ui.md files reference this file for their screen scope.
+---
+
+# UI Concept Design
+
+## System Flow
+
+```
+/archi.start → roadmap.json + design_tokens.json
+                      ↓
+           [This Skill] archi-ui-wireframe
+           reads: vision.md + roadmap.json + design_tokens.json + 02_tech_stack.md
+           writes: [[__DOCS_DIR__]]/global/ui_concept.html
+                      ↓
+           /archi.plan <ID>
+           reads: ui_concept.html (locates screens/components this task covers)
+           writes: ui.md (scope declaration only — no global layout duplication)
+                      ↓
+           /archi.code → reads spec.md + ui.md + ui_concept.html → writes code
+```
+
+> **Skill boundary**:
+> - Responsible for: visual concept of all user-visible screens (information architecture, layout, states, transitions)
+> - Not responsible for: Task-level interface contracts (spec.md), task steps (plan.json), business code
+
+---
+
+## Invocation Modes
+
+| Mode | Trigger source | Scope |
+|:---|:---|:---|
+| Initial generation | After `/archi.start` completes | Full generation — all screens |
+| Regeneration | Manual user invocation | Full rewrite (global UI redesign) |
+| Append screens | After `/archi.scope` adds new tasks | Add new pages only; existing pages untouched |
+| Plan refinement | `/archi.plan` discovers UI divergence | Update only the affected screen (new states / sub-screens / layout corrections) |
+| Modify screens | After `/archi.edit` changes a task | Update only affected screens; leave others intact |
+| Remove screens | After `/archi.remove` retires a task | Remove corresponding screens and control bar entries |
+
+> **Phase 2 (visual styling) timing**: Phase 2 does not need to immediately follow Phase 1. Recommended to run after core tasks (≥ 50% of Roadmap tasks) have completed planning, ensuring the styled prototype is based on a stable screen structure. If a screen is updated by Plan Refinement after Phase 2, only that screen needs re-styling — a full Phase 2 rerun is not required.
+
+---
+
+## Two-Phase Protocol
+
+### Phase 1 — Wireframe (Low-fi)
+
+**Role**: Information Architect
+
+**Goal**: Validate screen coverage completeness and navigation structure; visual details deferred to Phase 2.
+
+**Action**:
+
+1. **Load context**:
+   - `[[__DOCS_DIR__]]/global/vision.md` → extract: target platform, user roles, north-star metric
+   - `[[__DOCS_DIR__]]/global/roadmap.json` → extract: all [?UI] tasks, map to screen/state list
+   - `[[__DOCS_DIR__]]/global/design_tokens.json` → extract: `mode.default`, `illustration.iconLibrary`
+   - Rule file `02_tech_stack` → extract: target platform (Web/Mobile/Desktop), navigation framework
+
+2. **Plan screen inventory** (internal step, do not output to user):
+
+   | Screen ID | Screen name | Roadmap task | State list |
+   |:---|:---|:---|:---|
+   | S-01 | [name] | [task ID] | default, loading, empty, error |
+   | ... | | | |
+
+   > **Screen ID Stability Rule** (CRITICAL): Screen IDs are permanent once assigned. Deleted screen IDs are retired — new screens must use new IDs (e.g., after S-07 is deleted, the next screen is S-08, not S-07). Never reuse or renumber existing IDs. All `ui.md` files reference screens by ID; any ID change will break those references.
+
+3. **Select HTML skeleton spec** (auto-adapt by target platform):
+
+   | Platform | Viewport | Top bar | Navigation |
+   |:---|:---|:---|:---|
+   | Web / Desktop SaaS | 1280×800px | Fixed header | Left sidebar |
+   | Web / Marketing | 1440×900px | Transparent→fixed header | Top horizontal nav |
+   | Mobile Web / Mini-app | 390×844px | Status bar + nav bar | Bottom TabBar |
+   | Tablet / Dashboard | 1024×768px | Fixed header | Collapsible sidebar |
+
+   > Platform inferred from `02_tech_stack` or vision.md target device; default to Web / Desktop SaaS if unclear.
+
+4. **Generate wireframe HTML** — write to `[[__DOCS_DIR__]]/global/ui_concept.html`:
+
+   **HTML structure spec**:
+   ```
+   <html>
+     <head>
+       <!-- Inline CSS: wireframe style (grayscale, no brand colors) -->
+       <!-- Wireframe palette: bg=#f5f5f5, surface=#fff, border=#d0d0d0,
+            text=#333, muted=#888, accent=#555 -->
+     </head>
+     <body style="margin:0; display:flex; flex-direction:column; height:100vh; overflow:hidden;">
+       <!-- Top bar: project name + current screen path (fixed, not scrollable) -->
+       <header class="wf-topbar">...</header>
+
+       <!-- Content area: scrollable, renders currently active screen -->
+       <main class="wf-content" style="flex:1; overflow:auto;">
+         <!-- Each screen: <section class="wf-screen" id="S-XX" data-states="default,loading,empty,error"> -->
+         <!-- Each state: <div class="wf-state" data-state="default"> -->
+       </main>
+
+       <!-- Control bar: left=state switch, center=file label, right=page switch (fixed bottom, wireframe style) -->
+       <footer class="wf-ctrl-bar">
+         <div class="ctrl-group">
+           <span class="ctrl-lbl">STATE</span>
+           <!-- State pills for current screen, rendered by JS -->
+         </div>
+         <div class="wf-file-label">Low-fi Wireframe · [Project Name]</div>
+         <div class="ctrl-group">
+           <span class="ctrl-lbl">PAGE</span>
+           <!-- All screen page pills, rendered by JS -->
+         </div>
+       </footer>
+     </body>
+   </html>
+   ```
+
+   **Element labeling spec** (`data-el` attribute):
+   - Every interactive element or semantic block must have `data-el="[user-language label]"`
+   - Label language = Brief's primary language (Chinese project → Chinese labels, English project → English)
+   - Labels shown on hover via CSS `::before`, hidden by default
+   - When a parent is hovered, child labels auto-hide via `:has([data-el]:hover)::before { opacity:0 }`
+
+   **Interaction spec** (CSS + minimal JS, no external dependencies):
+   - Page switch: click PAGE pill → toggle `.wf-screen` display; JS syncs STATE pills
+   - State switch: click STATE pill → toggle `.wf-state` display within current screen
+   - Active style: `.pill.on-page` / `.pill.on-state` → `background:#444; color:#fff`
+   - Control bar must stay wireframe-style (grayscale, uppercase label, dashed border-top); no color
+
+   **Wireframe content rules** (Content Wireframe — grayscale with real-feeling content):
+   - Full grayscale; brand colors deferred to Phase 2
+   - **No pure gray rectangle placeholders** — use realistic placeholder content so users can genuinely evaluate whether the layout works:
+
+   | Element type | Rule |
+   |:---|:---|
+   | Headings / nav labels | Use real business names from roadmap task titles, e.g. "Dashboard", "Project List", "Settings" |
+   | Buttons | Write specific action text, e.g. "Create Project", "Sign In", "Save Changes" — never write "[Button]" |
+   | Inputs | Write placeholder text, e.g. "Search project name…", "Enter email address" |
+   | Lists / tables | Generate at least 3–4 rows of example data (realistic fake data in the project's domain: names, dates, statuses) |
+   | Chart / image areas | Use labeled rectangles, but label with the actual content type, e.g. "Line chart: visits last 7 days" not "[Chart]" |
+   | Empty state | Write specific empty state copy, e.g. "No projects yet — click 'Create Project' to get started" |
+   | Error state | Write specific error copy, e.g. "Connection failed. Please check your network and try again" |
+
+   - Typography must have hierarchy: page title large (20–24px) → section heading medium (16px) → body small (14px) → caption smaller (12px)
+   - Spacing must breathe: component gap > element gap > line height (no crowding)
+   - Each screen must include all core interaction entry points from its Roadmap task
+
+5. **Generate AI Index** — write `[[__DOCS_DIR__]]/global/ui_context.md`:
+
+   Extract a structured navigation index from the screen plan in step 2 (the sole AI entry point for UI structure):
+
+   ```markdown
+   # UI Context
+   > Platform: [platform] | Phase: Phase 1 Wireframe (updated after Phase 2 coloring)
+   > Updated: YYYY-MM-DD | Generated by archi-ui-wireframe Skill — do not edit manually
+
+   ## Screen Inventory
+   | ID | Name | Route | States |
+   |:---|:---|:---|:---|
+   | S-01 | [name] | [route] | default, loading, ... |
+
+   ## Navigation Graph
+   S-XX →（[trigger]）→ S-YY
+
+   ## Global Shared Components
+   | Component | Appears On |
+   |:---|:---|
+   | [component] | S-XX, S-YY |
+
+   ## Screen Structure Summary
+   > Extracted from wireframe data-el in Phase 1; refreshed to final layout after Phase 2 coloring.
+   > When writing ui.md Section 2, align with this section — do not invent layout that diverges from confirmed structure.
+
+   ### S-XX · [Screen name]
+   **Layout**: [e.g. "centered single-column max-w-400px" or "240px left sidebar + right content area"]
+   **States**: default ([core entry points]) | loading (skeleton) | empty / error (if applicable)
+   **Key regions**: [semantic blocks + interactive elements from data-el, e.g.: top nav bar, main form area, submit button, error message area]
+   ```
+
+   > `ui_context.md` is the sole entry point for all AI commands reading UI structure; `ui_concept.html` is for human browser preview only.
+
+6. **Output Gate**:
+
+   After generating the wireframe, output screen coverage summary:
+   ```
+   ### ui_concept.html generated (Phase 1 Wireframe)
+   ### ui_context.md generated (AI screen index)
+
+   **Screen coverage** (N screens total):
+   | Screen | Name | States |
+   |:---|:---|:---|
+   | S-01 | [name] | N |
+   | ... | | |
+
+   **Navigation structure**: [e.g. "Left sidebar + top breadcrumb"]
+   **Platform**: [Web Desktop 1280px / Mobile 390px / ...]
+
+   > Open `[[__DOCS_DIR__]]/global/ui_concept.html` in a browser to verify information architecture.
+   > Reply **OK** to proceed to Phase 2 visual styling; or describe layout/screen adjustments needed.
+   ```
+
+   **Gate**: Phase 2 starts only after user replies **OK**; no styling until confirmed.
+
+---
+
+### Phase 1.5 — Wireframe Refinement (optional)
+
+**Role**: Consulting Advisor
+**Trigger**: User reply is not OK — contains layout adjustments, screen additions/removals, navigation changes.
+**Action**: Incorporate feedback, update only the affected parts of `ui_concept.html` (no full rewrite), sync `ui_context.md` (keep screen index consistent with `ui_concept.html`), re-display summary, await confirmation.
+
+---
+
+### Phase 2 — Visual Styling (Hi-fi Coloring)
+
+**Role**: You are a visual designer with a strong personal style. You don't follow conventions — you think in feelings, textures, and rhythm, not components and layouts. You pursue not "correct" but "makes someone stop and look twice." Every decision is intentional: spacing is never arbitrary, colors are never defaults, fonts are never the first in the list. You combine an artist's intuition with an engineer's precision.
+
+**Goal**: Style the confirmed wireframe into a hi-fi prototype that has identity — opening it should immediately signal this was designed for THIS project, not generated from a template.
+
+**Prerequisite check** (must validate before styling):
+
+| Field path | Pass condition | Blocking action |
+|:---|:---|:---|
+| `aestheticDirection.preset` | Non-empty | Warning (non-blocking) — AI infers from project context, notes inference in output |
+| `primitivePalette.brand` | At least 1 non-empty color value | Blocking — prompt user to fill brand color |
+| `semanticTokens.colors` | At least `bg`/`surface`/`text` semantic mappings | Blocking — prompt user to define base semantic colors |
+| `semanticTokens.typography` | At least 1 font family declaration | Warning (non-blocking) — AI picks from aesthetic direction |
+| `motion.preference` | Non-empty | Warning (non-blocking) — defaults to `subtle` |
+| `illustration.iconLibrary` | Non-empty | Warning (non-blocking) — no icon library imported |
+
+> On any blocking item: stop immediately, output the list of missing fields, and wait for the user to fill them before re-running.
+
+**Action**:
+
+1. **Load visual spec**:
+   - `design_tokens.json` → read in full:
+     - `aestheticDirection` → preset + custom description
+     - `primitivePalette` → CSS variable definitions
+     - `semanticTokens.colors` → semantic color mappings
+     - `semanticTokens.typography` → font families / sizes
+     - `mode` → theme mode (light/dark)
+     - `motion` → timing, easing, pattern names
+     - `illustration` → icon style, library
+     - `layout` → radius / shadow / spacing
+   - `vision.md` → extract Visual Reference section (brand colors, competitor screenshot descriptions, forbidden styles)
+
+2. **Aesthetic direction → concrete design parameter mapping**:
+
+   Use `aestheticDirection.preset` to determine baseline values for design parameters (explicit Token values take priority; baselines fill empty Tokens):
+
+   | Preset | Background tone | Radius | Shadow | Font strategy | Layout traits | Reference products |
+   |:---|:---|:---|:---|:---|:---|:---|
+   | `saas-dark` | Dark (#0a-#15 range) | sm:4px md:8px | Near-zero, use borders for layering | Sans-serif, compact | High contrast, sharp edges, tight spacing | Linear, Vercel, Raycast |
+   | `saas-light` | White (#fafafa-#fff) | sm:6px md:12px | Soft (0 1px 3px rgba(0,0,0,0.08)) | System font or sans-serif | Breathing room, thin borders, whitespace | Notion, Stripe, GitHub |
+   | `dashboard` | Dark gray / dark blue | sm:8px md:12px | Card elevation (0 2px 8px) | Tabular nums + sans-serif | Card grids, info-dense, compact tables | Grafana, Datadog |
+   | `marketing` | Gradient / bold color blocks | lg:16px+ | Dramatic (0 8px 32px) | Large display font + refined body font | Big headings, full-width sections, visual narrative | Loom, Framer |
+   | `mobile-app` | Soft background | lg:16px xl:24px | Soft diffused (0 4px 16px) | System font -apple-system | Large touch targets, wide spacing, card-based | Telegram, Bear |
+   | `editorial` | Warm white / cream | Near-zero 0-4px | None or very faint | Serif display + sans-serif body | Narrow column, tall line-height, typography-driven | Medium, Substack |
+   | `brutalist` | Pure white or pure black | 0px | None | Monospace or system font | No decoration, dense, function-first | Craigslist, HN |
+
+   > `custom`: read `aestheticDirection.customDescription`, extract keywords, map to nearest preset, then layer custom adjustments on top.
+
+3. **Anti-AI aesthetic blacklist** (CRITICAL — never violate during styling):
+
+   | Category | Forbidden | Use instead |
+   |:---|:---|:---|
+   | Typography | Inter, Roboto, Arial as heading font | Characterful fonts for headings (e.g. Cal Sans, General Sans, Satoshi, Outfit); body text may use system fonts |
+   | Colors | Purple gradient on white (signature AI default aesthetic) | Derive from `aestheticDirection`; palette must have hierarchy — one dominant color + sharp accent > evenly-distributed timid palette |
+   | Layout | Every screen uses the same centered card layout | Different screen types need layout variation: list vs detail vs form each have distinct character |
+   | Radius | Uniform rounded-lg on everything | Radius must have hierarchy: containers large, buttons medium, badges small (or uniformly 0/sm per aesthetic direction) |
+   | Shadow | Identical shadow-md everywhere | Shadow must match aesthetic direction: dark themes barely use shadow; light themes use layered shadow |
+   | Motion | Scattered transition-all everywhere | Focus on high-impact moments: orchestrated page load (staggered reveals via animation-delay) > scattered micro-interactions |
+   | Overall | Every generation converges to the same look | Each project's styling MUST differ by aesthetic direction — two different projects' ui_concept.html must be instantly distinguishable |
+
+4. **Styling rules** (execute within aesthetic direction baseline + blacklist constraints):
+
+   | Styling dimension | Rule |
+   |:---|:---|
+   | Colors | Replace grayscale with `semanticTokens.colors`; brand from `primitivePalette.brand`; empty tokens filled from aesthetic direction baseline |
+   | Typography | Use declared fonts from `semanticTokens.typography`; if empty, pick from aesthetic direction strategy (Google Fonts CDN), blacklisted fonts forbidden |
+   | Radius/Shadow | Per `layout.radius` / `layout.shadow`; empty values filled from aesthetic direction baseline |
+   | Motion | Apply CSS transition/animation per `motion.patterns`; prioritize orchestrated page-load staggered reveal (animation-delay) |
+   | Icons | Import CDN per `illustration.iconLibrary`; if style=none, no illustrations |
+   | Mode | If `mode.support` includes dark, add CSS `@media (prefers-color-scheme: dark)` + toggle button |
+   | Forbidden | Strictly follow "Forbidden styles" from vision.md Visual Reference |
+   | Space | Create breathing room or controlled density (per aesthetic direction), avoid mechanical uniform spacing |
+   | Background | No flat solid-color fills — add subtle texture/gradient mesh/noise/geometric pattern per aesthetic direction |
+
+5. **Post-styling checklist**:
+   - [ ] All screen colors from semanticTokens or aesthetic direction baseline — no arbitrary hardcoded Hex
+   - [ ] All motion durations from `motion.duration.*` — no magic numbers
+   - [ ] Page/state control bar remains wireframe-style grayscale (no coloring — debug tool identity)
+   - [ ] `data-el` labels fully preserved
+   - [ ] Every state (default/loading/empty/error) of every screen visually implemented
+   - [ ] **Anti-AI aesthetic check**: no blacklisted fonts, no purple-gradient-on-white, layout variety, radius hierarchy
+   - [ ] **Identity check**: opening the HTML, one can instantly tell which aesthetic direction this follows — not a generic template
+
+6. **Output**:
+   - Update `[[__DOCS_DIR__]]/global/ui_concept.html` (colored version overwrites wireframe)
+   - **Sync `ui_context.md` Screen Structure Summary**:
+     - Update phase label from `Phase 1 Wireframe` to `Phase 2 Visual Styling`
+     - Re-extract Layout and Key regions for each screen based on final HTML structure, ensuring summary matches the colored `ui_concept.html`
+     - Screen Inventory / Navigation Graph / Global Shared Components: leave unchanged unless structure changed
+   - Output summary:
+     ```
+     ### ui_concept.html updated (Phase 2 Visual Styling)
+     ### ui_context.md synced (Screen Structure Summary refreshed to Phase 2)
+
+     **Aesthetic direction**: [preset value] — [reference products]
+     **Applied visual spec**:
+     - Primary color: [Primary token value]
+     - Font: [display font + body font]
+     - Radius: [sm/md/lg values]
+     - Motion: [preference value]
+     - Icons: [iconLibrary] / style: [style]
+     - Theme: [default + support list]
+     - Background treatment: [texture/gradient/solid description]
+
+     > Open `[[__DOCS_DIR__]]/global/ui_concept.html` in a browser to review visual output.
+     > `/archi.plan <ID>` will read `ui_context.md` to determine each task's UI scope.
+     ```
+
+---
+
+### Phase 2.5 — Incremental Re-coloring
+
+**Trigger**: After Phase 2 is complete, a screen is updated by Plan Refinement / Edit / Revise and its new content needs to be styled to match the hi-fi standard.
+
+**Role**: Visual Designer
+
+**Action**:
+
+1. Receive the list of screen IDs to re-color from the caller (e.g., `S-03`, `S-07`).
+2. Process only the specified screens:
+   - Locate new wireframe-style additions within `.wf-screen#S-XX`
+   - Apply Phase 2 styling rules (`semanticTokens` / `motion` / `illustration`) to the new additions only
+   - Leave all other screen content untouched
+3. [?new states] If new states are added in this re-color → sync `ui_context.md` to update the states column for the affected screen(s).
+4. Output change summary:
+   - `MODIFIED: ui_concept.html S-XX (incremental re-color, [N] new states/regions)`
+   - `MODIFIED: ui_context.md S-XX (updated states list)` (only if new states were added)
+
+> **Forbidden**: Never re-run the full Phase 2 for incremental re-coloring. Never touch screens not in the specified list.

package/dist/templates/zh/briefs/_base.md

@@ -0,0 +1,116 @@
+# Project Brief: [项目名称]
+
+> 尽量填写，不确定的留空即可。完成后运行 `/archi.start project-brief.md`，AI 会通过选择题补全缺失信息。
+
+---
+
+## 项目概述
+
+**项目名称**: 
+**一句话描述**: [项目是什么、为谁服务、解决什么问题]
+**问题陈述**: [目标用户遇到的核心痛点？现有方案哪里不足？]
+
+**目标用户**:
+- **核心用户**: [角色/群体]
+- **关键特征**: [技术水平、使用场景、行为习惯]
+
+**成功指标**: [怎样算做成了？例：DAU 1000 / 被 100+ 项目采用 / P99 < 200ms]
+
+---
+
+## 核心任务
+
+> MVP 必须实现的任务（建议 3-7 个），每项一句话描述预期行为。
+> 详细 Spec 在 `/archi.plan` 阶段定义，此处只需明确"做什么"。
+
+1. 
+2. 
+3. 
+
+---
+
+## 已有设计决策
+
+> 如果你对某些任务/页面/流程已有明确想法，在此描述。AI 在后续 plan 阶段会以此为准，不会推翻。
+> 没有的话留空即可。
+>
+> 写法参考：
+> - **[任务/页面名]**: 描述具体行为、流程、约束
+> - 可附截图/草图链接
+
+---
+
+## 技术栈
+
+> 已确定的直接填写。不确定的留空或写"推荐"，AI 会基于项目特征推荐。
+
+**项目类型**: [[__PROJECT_TYPE__]]
+<!-- archi init 自动填入；手动填写时参考 templates/archi-decompose-roadmap SKILL 中的类型表 -->
+**语言/运行时**: [例：TypeScript + Node.js 22]
+**核心框架**: [例：Next.js 15 / Fastify / Tauri]
+**包管理器**: [例：pnpm / npm / yarn / cargo]
+**构建工具**: [例：Vite / tsup / Webpack / esbuild / cargo / go build]
+**Linter / Formatter**: [例：ESLint + Prettier / Biome / ruff / clippy + rustfmt]
+<!-- @slot:tech -->
+**部署目标**: [例：Vercel / Docker / npm publish / 二进制分发]
+**关键第三方库**: [例：Zod, TanStack Query, Lucia Auth]
+
+**技术红线** (禁用的技术/方案):
+- [例：不用 jQuery；不用 CSS-in-JS]
+
+---
+
+## 工程规范
+
+> 团队已有的工程约定。不确定的留空，AI 会基于技术栈推荐合理默认值。
+
+**仓库形态**: [Monorepo (Turborepo/Nx/pnpm workspaces) / 单体仓库]
+**架构模式**: [例：MFA / FSD / Clean Architecture / 分层架构 / 无偏好（AI 推荐）]
+**目录结构**: [已有明确结构 → 简述关键目录 / 无（AI 基于架构模式生成）]
+**分支策略**: [例：Trunk-based / Git Flow / GitHub Flow]
+**Commit 规范**: [例：Conventional Commits (feat/fix/chore) / 自定义 → 简述]
+**测试偏好**: [例：Vitest / Jest / pytest / 无特殊要求]
+
+---
+
+## 已有资源与上下文
+
+> AI 需要知道哪些东西已经存在——避免重复造轮子或做出冲突决策。
+
+**项目起点**: [全新项目 / 基于已有代码库（简述现状和技术债）]
+**设计资产**: [Figma 链接 / 设计稿截图 / 无（AI 自行设计）]
+**品牌规范**: [已有 Logo/配色/字体 → 描述或附链接 / 无]
+**已有 API/后端**: [接口文档链接 / 简述可用端点 / 无（需从零搭建）]
+**第三方服务**: [已确定使用的服务，例：Auth0, Stripe, AWS S3, Resend...]
+**现有数据**: [已有数据库/数据源？格式？需要迁移？/ 无]
+
+---
+
+<!-- @slot:style -->
+
+## 边界与约束
+
+**明确不做的事** (反目标):
+- [例：本期不做国际化 / 不做移动端适配 / 不做付费功能]
+
+**硬性约束**:
+- **时间**: [例：4 周 MVP / 无硬性 deadline]
+- **兼容性**: [例：Chrome 90+ / Node 18+ / iOS 15+]
+- **性能**: [例：首屏 < 2s / API P99 < 500ms / 无特殊要求]
+- **合规/无障碍**: [例：WCAG 2.1 AA / GDPR / 无]
+
+---
+
+## 参考与灵感
+
+| 参考项目 | 参考维度 |
+|:---|:---|
+| [例：Linear] | [交互体验、任务管理逻辑] |
+| | |
+
+---
+
+## 补充说明
+
+> 任何上述未涵盖的信息：背景故事、特殊需求、已有决策的原因、团队技术偏好等。
+

package/dist/templates/zh/briefs/_modules.md

@@ -0,0 +1,173 @@
+<!-- @tech:ui -->
+**CSS/UI 方案**: [例：TailwindCSS + Shadcn/UI / Ant Design / 原生 CSS]
+<!-- @end -->
+
+<!-- @tech:data -->
+**数据库**: [例：PostgreSQL / MongoDB / SQLite]
+**ORM / Query Builder**: [例：Prisma / Drizzle / TypeORM]
+<!-- @end -->
+
+<!-- @tech:api -->
+**API 风格**: [例：RESTful / GraphQL / gRPC / tRPC]
+<!-- @end -->
+
+<!-- @tech:cli -->
+**CLI 框架**: [例：cac / commander / clap (Rust) / cobra (Go)]
+**分发方式**: [例：npm publish / GitHub Releases / 二进制]
+<!-- @end -->
+
+<!-- @tech:lib -->
+**模块格式**: [例：ESM / CJS + ESM 双出]
+**目标平台**: [例：浏览器 + Node.js / 仅 Node.js]
+**分发渠道**: [例：npm / PyPI / crates.io]
+<!-- @end -->
+
+<!-- @style:ui -->
+## 风格与调性
+
+**审美方向** (选一个最接近的，不确定就留空让 AI 推荐):
+<!-- 选一个填入，或写 custom 并在下方描述 -->
+<!-- saas-dark    — 类似 Linear/Vercel/Raycast：深色背景、高对比、极简、锐利边缘 -->
+<!-- saas-light   — 类似 Notion/Stripe/GitHub：白底、细边框、系统字体、呼吸感 -->
+<!-- dashboard    — 类似 Grafana/Datadog：信息密集、卡片网格、数据优先 -->
+<!-- marketing    — 类似 Loom/Framer：大标题、渐变、视觉冲击、叙事感 -->
+<!-- mobile-app   — 类似 Telegram/Bear：圆角大、间距宽、触控友好 -->
+<!-- editorial    — 类似 Medium/Substack：排版优先、衬线字体、阅读沉浸 -->
+<!-- brutalist    — 类似 Craigslist/HN：功能极简、无装饰、原始感 -->
+<!-- custom       — 在「自定义描述」中写你想要的风格 -->
+
+**审美方向**: [例：saas-dark / saas-light / dashboard / marketing / mobile-app / editorial / brutalist / custom]
+**自定义描述**: [仅 custom 时填写，例："类似 Spotify 的深色 + 绿色强调 + 卡片式布局"]
+
+**信息密度**: [大留白/沉浸式 / 信息密集/仪表盘风格]
+**动效偏好**: [轻微微交互 / 丰富动画 / 无动画]
+
+### 视觉参考 (Visual Reference)
+
+> 为 AI 提供审美输入，直接影响 `ui_concept.html` 的视觉质量。
+> 以下任填一项即有效，填得越多 AI 越能还原你的期望风格。
+
+**竞品/灵感截图**: [可粘贴图片 / Figma 链接 / URL]
+**品牌色板**: [主色 Hex / 渐变描述 / 无（AI 基于审美方向生成）]
+**字体偏好**: [例：JetBrains Mono + Space Grotesk / Playfair Display / 无偏好（AI 基于审美方向选择）]
+**图标库**: [例：Lucide / Heroicons / Tabler / 无偏好]
+**禁用风格**: [例：禁渐变背景 / 禁卡通插画 / 无限制]
+<!-- @end -->
+
+<!-- @style:cli -->
+## 风格与调性
+
+**输出风格**: [简洁单行 / 结构化彩色 / JSON 机器可读]
+**交互模式**: [纯参数驱动 / 交互式提示 / 混合]
+**错误展示**: [简洁提示 / 详细堆栈 / 分级(--verbose)]
+<!-- @end -->
+
+<!-- @style:api -->
+## 风格与调性
+
+**文档方案**: [OpenAPI/Swagger / GraphQL Schema / 手写文档]
+**错误响应格式**: [RFC 7807 / 自定义 JSON / GraphQL errors]
+**版本策略**: [URL 路径 /v1 / Header / 无版本控制]
+<!-- @end -->
+
+<!-- @tech:mobile -->
+**移动端运行时**: [例：React Native 0.76 / Flutter 3 / Expo SDK 52]
+**UI 组件库**: [例：RN Paper / NativeWind / NativeBase / 原生组件]
+**导航方案**: [例：React Navigation 7 / Expo Router / Go Router]
+**原生能力**: [例：摄像头、推送通知、生物识别——列出需要的]
+**分发渠道**: [例：App Store + Play Store / Expo Go / TestFlight]
+**OTA 热更新**: [例：Expo Updates / CodePush / 不需要]
+<!-- @end -->
+
+<!-- @tech:miniapp -->
+**小程序平台**: [例：微信 / 支付宝 / 抖音 / uni-app（多端）]
+**基础库版本**: [例：微信基础库 3.x / uni-app Vue3]
+**UI 组件库**: [例：Vant Weapp / TDesign MiniProgram / 原生组件]
+**云开发**: [例：微信云开发 / 不使用]
+**分发**: [例：微信公众平台发布 / 审核周期约定]
+<!-- @end -->
+
+<!-- @style:miniapp -->
+## 风格与调性
+
+**视觉规范**: [遵循平台设计规范（微信 Weui / 支付宝 / 抖音）/ 自定义品牌风]
+**色调倾向**: [品牌主色 / 跟随平台默认 / 深色模式（需平台支持）]
+**组件风格**: [原生组件为主 / 定制组件 / 混合]
+**动效偏好**: [系统默认页面切换 / 自定义过渡 / 无特殊要求]
+<!-- @end -->
+
+<!-- @tech:desktop -->
+**桌面运行时**: [例：Tauri 2 / Electron 33]
+**IPC 通信**: [例：Tauri invoke/command / Electron ipcMain+ipcRenderer]
+**系统级能力**: [例：系统托盘、全局热键、文件关联、剪贴板——列出需要的]
+**打包分发**: [例：tauri-bundler (.dmg/.msi/.deb) / electron-builder / GitHub Releases]
+**自动更新**: [例：tauri-updater / electron-updater / 不需要]
+<!-- @end -->
+
+<!-- @tech:extension -->
+**目标浏览器**: [例：Chrome + Edge / Firefox / 全平台]
+**Manifest 版本**: [V3（推荐）/ V2（Firefox 需兼容）]
+**扩展结构**: [例：仅 Popup / Popup + Content Script / Background + Content Script + Popup]
+**权限声明**: [例：storage、tabs、activeTab——列出需要的]
+**发布渠道**: [例：Chrome Web Store / Firefox Add-ons / 私有分发]
+<!-- @end -->
+
+<!-- @tech:realtime -->
+**实时传输方案**: [例：Socket.io / 原生 WebSocket / SSE / WebRTC]
+**实时框架/托管**: [例：Ably / Pusher / Liveblocks / 自建]
+**房间/频道模型**: [例：按用户 ID 订阅 / 按文档 ID 房间 / 广播]
+**[?CRDT] 协作冲突解决**: [例：Yjs / Automerge / 不需要（仅广播）]
+**离线支持**: [例：离线队列 + 重连同步 / 不需要]
+<!-- @end -->
+
+<!-- @tech:ai -->
+**LLM 提供商**: [例：OpenAI GPT-4o / Anthropic Claude / Gemini / 本地 Ollama]
+**AI 框架**: [例：Vercel AI SDK / LangChain / LlamaIndex / 无框架直调 API]
+**Tool/Function Calling**: [例：需要（列出工具名称）/ 不需要]
+**Memory 方案**: [例：向量数据库（pgvector/Pinecone）/ 滑动窗口历史 / 无]
+**[?MCP] MCP 协议**: [例：@modelcontextprotocol/sdk / 不需要]
+**流式输出**: [例：SSE 流式 / 批量返回]
+<!-- @end -->
+
+<!-- @style:mobile -->
+## 风格与调性
+
+**视觉关键词**: [例：原生感、轻量、沉浸式]
+**适配方案**: [例：响应式 dp/sp / 固定设计稿 375pt]
+**深色模式**: [跟随系统 / 仅浅色 / 仅深色]
+**动效偏好**: [系统原生动效 / 自定义过渡 / 无特殊要求]
+**无障碍**: [例：VoiceOver / TalkBack 支持 / 无特殊要求]
+<!-- @end -->
+
+<!-- @style:desktop -->
+## 风格与调性
+
+**视觉风格**: [例：原生系统风（Fluent/HIG）/ 自定义品牌风]
+**窗口管理**: [例：单主窗口 + 托盘 / 多窗口 / 全屏优先]
+**深色模式**: [跟随系统 / 固定深色 / 固定浅色]
+**菜单栏/系统托盘**: [例：菜单栏图标 + 快捷操作 / 仅托盘图标 / 不需要]
+<!-- @end -->
+
+<!-- @style:extension -->
+## 风格与调性
+
+**Popup 尺寸约定**: [例：320×480px / 400×600px / 自适应]
+**视觉风格**: [例：极简卡片 / 与目标网站融合 / 独立品牌]
+**Content Script 注入样式**: [例：悬浮按钮 / 侧边栏 / 高亮遮罩]
+<!-- @end -->
+
+<!-- @style:realtime -->
+## 风格与调性
+
+**协作感知 UI**: [例：实时光标、用户头像列表、打字指示器——列出需要的]
+**冲突/同步状态展示**: [例：乐观更新 + 静默同步 / 明确显示"正在同步"]
+**离线提示**: [例：顶部 Banner 提示 / 静默重连]
+<!-- @end -->
+
+<!-- @style:ai -->
+## 风格与调性
+
+**交互模式**: [对话型（聊天 UI）/ 工具型（命令+结果）/ 混合]
+**流式输出展示**: [例：逐字打印效果 / 分段加载 / 批量返回]
+**错误/降级提示**: [例：显示 fallback 模型 / 重试按钮 / 静默降级]
+<!-- @end -->

package/dist/templates/zh/docs/global/data_snapshot.json

@@ -0,0 +1,31 @@
+{
+  "scope": "[?Data]",
+  "models": [
+    {
+      "name": "[ModelName]",
+      "description": "[一句话说明]",
+      "fields": [
+        {
+          "name": "id",
+          "type": "string",
+          "modifiers": "PK",
+          "description": "唯一标识"
+        },
+        {
+          "name": "[fieldName]",
+          "type": "[type]",
+          "modifiers": "[nullable | unique | index | ...]",
+          "description": "[字段说明]"
+        }
+      ]
+    }
+  ],
+  "relationships": [
+    {
+      "from": "[ModelA]",
+      "to": "[ModelB]",
+      "type": "[1:1 | 1:N | M:N | self-ref]",
+      "description": "[关系说明]"
+    }
+  ]
+}