architext 0.0.5 → 0.0.6

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

@@ -1,50 +1,30 @@
 ---
 name: archi-ui-wireframe
-type: subagent
-description: UI concept design expert. Generates hi-fi ui_concept.html — when tokens are sufficient, outputs colored hi-fi design directly; when tokens are incomplete, guides user to fill them first. Supports adopt mode to reverse-capture UI state from existing code. 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.
+description: Generate UI concept designs and wireframes as multi-file screens/ directory. Do not auto-trigger.
 ---
 
 # UI Concept Design
 
-## System Flow
+## System Flow Position
 
 ```
-/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.inherit → code analysis + design_tokens.json
-                      ↓
-           [This Skill] archi-ui-wireframe (adopt mode)
-           reads: code routes/components/layouts + design_tokens.json
-           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
+/archi.ui → [This Skill] → screens/ (multi-file directory) → /archi.plan → ui.md (task scope)
+/archi.ui (adopt mode) → [This Skill] → screens/ (reverse from 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
+> **Outputs**: `screens/` directory (`index.html` navigation hub + `S-XX.html` independent screens + `_shared.css` shared styles) + `ui_context.md` (AI index)
 
 ---
 
 ## Invocation Modes
 
-| Mode | Trigger source | Scope |
+| Mode | Trigger | Scope |
 |:---|:---|:---|
-| Initial generation | After `/archi.start` completes | Full generation — all screens |
-| Reverse adoption | After `/archi.inherit` completes | Reverse-generate all screens from code routes/components |
-| 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 |
+| Initial | `/archi.ui` | Full — all screens |
+| Adopt | `/archi.ui` (auto-detected when code exists) | Reverse from code routes/components |
+| Regenerate | Manual | Full rewrite (global redesign) |
+| Append/Modify | `/archi.scope/edit` or `/archi.ui` (incremental mode) | Specified screens only |
+| Update | `/archi.plan` divergence | Affected screens only |
 
 ---
 
@@ -52,336 +32,181 @@ description: UI concept design expert. Generates hi-fi ui_concept.html — when
 
 ### Step 1 — Load Context
 
-**Action**:
-- `vision.md` → extract: target platform, user roles, north-star metric
-- `roadmap.json` → extract: all UI tasks, map to screen/state list
-- `design_tokens.json` → extract: `mode.default`, `illustration.iconLibrary`, aesthetic direction
-- Rule file `02_tech_stack` → extract: target platform (Web/Mobile/Desktop), navigation framework
+**Load**: vision.md (platform/users/north-star), roadmap.json (UI tasks → screen mapping),
+design_tokens.json (aesthetic/brand), tech_stack.md (platform/nav framework).
 
 ### Step 2 — Plan Screen Inventory
 
-(Internal step, do not output to user):
+Assign screen IDs (S-01, S-02...), map to Roadmap tasks. IDs are permanent.
 
-| Screen ID | Screen name | Roadmap task | State list |
+| Screen ID | Name | Task | States |
 |:---|:---|:---|:---|
 | 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.
+### Step 3 — Tokens Check + Guidance
 
-### Step 3 — Select HTML Skeleton Spec
+check `design_tokens.json`:
+- `aestheticDirection.preset` empty → guide selection (saas-dark/saas-light/dashboard/marketing/mobile-app/editorial/brutalist)
+- `primitivePalette.brand` empty → guide for Hex
+- Other empty → AI infers, non-blocking
 
-(Auto-adapt by target platform):
+### Step 4 — Generate Multi-file HTML
 
-| 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.
+**Output directory**: `[[__DOCS_DIR__]]/global/screens/`
 
-### Step 4 — Tokens Prerequisite Check + Guidance
+#### 4.1 `_shared.css` — Shared Styles
 
-Read `design_tokens.json` and check key field completeness:
+Extract CSS variables from `design_tokens.json` + base layout + bottom control panel styles. All `S-XX.html` reference via `<link href="_shared.css">`.
 
-| Field path | Pass condition | When insufficient |
-|:---|:---|:---|
-| `aestheticDirection.preset` | Non-empty | Include in guidance Q1 |
-| `primitivePalette.brand` | At least 1 non-empty color value | Include in guidance Q2 |
-| `semanticTokens.colors` | At least `bg`/`surface`/`text` semantic mappings | Include in guidance Q2 |
-| `semanticTokens.typography` | At least 1 font family declaration | AI picks from aesthetic direction (non-blocking) |
-| `motion.preference` | Non-empty | Defaults to `subtle` (non-blocking) |
-| `illustration.iconLibrary` | Non-empty | Fall back to self-drawn inline SVG (non-blocking); emoji substitution forbidden |
+**Bottom Control Panel**: fixed bottom, floating toggle button (60×16px, centered top), ▲/▼ symbols. 3-column: ← index jump | page info | state buttons. Collapsed hides content, button stays visible.
 
-**Tokens sufficient** → proceed directly to Step 5 hi-fi generation.
+#### 4.2 `S-XX.html` — Independent Screen Files
 
-**Tokens insufficient** → output structured guidance questions (max 3), then AI auto-fills tokens after user answers:
+One self-contained HTML file per screen, structure:
 
+```html
+<body>
+  <header class="wf-topbar">...</header>
+  <main class="wf-content">...state divs...</main>
+
+  <!-- Bottom Control Panel -->
+  <aside class="wf-panel" id="wfPanel">
+    <button class="wf-panel-toggle" id="toggleBtn" onclick="togglePanel()">▼</button>
+    <div class="wf-panel-content">
+      <span>Jump</span> <a href="index.html">← Index</a>
+      <span>Page</span> <span>[description]</span>
+      <span>State</span> <div class="wf-states">...</div>
+    </div>
+  </aside>
+
+  <script>
+    function togglePanel() {
+  var panel = document.getElementById('wfPanel');
+  var btn = document.getElementById('toggleBtn');
+  panel.classList.toggle('collapsed');
+  btn.textContent = panel.classList.contains('collapsed') ? '▲' : '▼';
+}
+  </script>
+</body>
 ```
-### Visual Style Confirmation
 
-**[Q1] Aesthetic direction**
-| ID | Option | Reference products |
-|:---|:---|:---|
-| A | saas-dark | Linear, Vercel |
-| B | saas-light [Recommended] | Notion, Stripe |
-| C | dashboard | Grafana, Datadog |
-| D | Other | (Please describe) |
-
-**[Q2] Brand primary color**
-> Enter Hex value (e.g. #4F46E5), or reply "no preference" for AI to generate based on aesthetic direction
-
-**[Q3] Information density**
-| ID | Option |
-|:---|:---|
-| A | Generous whitespace / immersive |
-| B | Moderate [Recommended] |
-| C | Information-dense / dashboard style |
-
-**INPUT**: `Q1 answer | Q2 answer | Q3 answer`
-```
+#### 4.3 `index.html` — Navigation Hub
+
+List all screens, each linking to corresponding `S-XX.html`:
 
-AI fills `design_tokens.json` (writes to file) based on answers, then continues generation. Fields already extracted from code CSS variables/theme are preserved, not overwritten.
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>[Project Name] — UI Concept Design</title>
+  <link rel="stylesheet" href="_shared.css">
+</head>
+<body>
+  <header class="wf-topbar">
+    <span>[Project Name] — UI Concept Design Index</span>
+  </header>
+  <main class="wf-index">
+    <div class="wf-screen-card">
+      <a href="S-01.html">S-01 · [Screen Name]</a>
+      <p>[One-line description]</p>
+    </div>
+    <!-- More screen cards -->
+  </main>
+</body>
+</html>
+```
 
-### Step 5 — Generate Hi-fi HTML
+**Interactive Display Principles** (visual feedback, NOT real business logic):
+- Buttons/links/inputs drawn with click events
+- Click triggers **visual feedback** (modal show/hide, panel expand, state switch), NOT **real business logic**
+- **Cross-screen navigation**: Sidebar, tabs, breadcrumbs, card clicks → link to corresponding `S-XX.html`
+- **Modal forms**: Focusable, clickable, but submission doesn't process data
+- **Goal**: complete display of interaction flow and interface in various states
 
-Write to `[[__DOCS_DIR__]]/global/ui_concept.html`:
+**Built-in Validation & Self-Repair Loop** (AI self-checks and fixes until all pass):
 
-**HTML structure spec**:
+| Check | Pass Criteria | Repair Action |
+|:---|:---|:---|
+| **Clickability** | All elements with `onclick` must have `cursor: pointer` | Add CSS `cursor: pointer` |
+| **data-el completeness** | All interactive elements must have `data-el` | Add `data-el` description |
+| **State coverage** | Each screen must include default/loading/empty (as applicable) | Add missing state divs |
+| **Cross-file link validity** | `index.html` links point to existing `S-XX.html`; each `S-XX.html` contains back-to-index link | Fix link paths |
+| **Anti-pattern red lines** | No purple gradient, no emoji, not pure black/white | Replace with aesthetic-compliant colors |
+| **Spacing consistency** | Use CSS variables, no hardcoded magic numbers | Replace with `var(--space-*)` |
+
+**Repair Loop** (internal execution):
 ```
-<html>
-  <head>
-    <!-- Inline CSS: hi-fi visual style based on design_tokens.json -->
-  </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">UI Concept · [Project Name]</div>
-      <div class="ctrl-group">
-        <span class="ctrl-lbl">PAGE</span>
-        <!-- All screen page pills, rendered by JS -->
-      </div>
-    </footer>
-  </body>
-</html>
+Generate HTML → Run checks → Any failures?
+  ├── Yes → Repair → Regenerate → Check again
+  └── No → Passed
 ```
 
-**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
-
-**UI Quality Standards** (CRITICAL):
-
-| Dimension | Requirement |
-|:---|:---|
-| Positioning | Hi-fi interface, polished enough for developer handoff — not a wireframe |
-| Card hierarchy | Use soft shadows for depth; do not substitute hard borders for shadows |
-| Primary color usage | Only for CTAs and key status feedback; no more than 10% of total area |
-| Global consistency | Border radius, icon sizes, spacing must be globally uniform |
-| Typography | Ample whitespace, clear font size hierarchy (at least 3 levels of contrast) |
-| Interaction states | All interactive elements must have hover / focus / disabled styles |
-| Content fill | Use realistic content; no Lorem ipsum / "Title" / placeholder text |
-
-**Content rules**:
-
-| 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" |
-
-**Aesthetic direction → 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.
-
-**Anti-AI aesthetic blacklist** (CRITICAL — never violate during generation):
-
-| 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 |
-| Emoji | Using emoji as icons (🔔📁⚙️✅ etc.) → inconsistent cross-platform rendering, clashes with the overall design language | Use the icon library declared in `illustration.iconLibrary`, or plain text/symbols with `data-el` annotation |
-| Overall | Every generation converges to the same look | Each project's design MUST differ by aesthetic direction — two different projects' ui_concept.html must be instantly distinguishable |
-
-**Styling rules** (execute within aesthetic direction baseline + blacklist constraints):
-
-| Styling dimension | Rule |
-|:---|:---|
-| Colors | Map 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 | `illustration.iconLibrary` set → import CDN; not set or style=none → self-drawn inline SVG (see spec below); **emoji as icons is forbidden** |
-| Mode | If `mode.support` includes dark, add CSS `@media (prefers-color-scheme: dark)` + toggle button |
-| Forbidden | 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 |
-
-**Self-drawn SVG spec** (use only when no `illustration.iconLibrary` is set):
+**Check Method**: Scan HTML file elements, verify against checklist, output to comment (`<!-- Check: 6/6 passed -->`), repair if failed.
 
-```html
-<!-- Stroke style (saas-dark / saas-light / dashboard) -->
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none"
-     stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"
-     style="width:1em;height:1em;vertical-align:-0.125em">…</svg>
-
-<!-- Fill style (mobile-app / marketing) -->
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"
-     fill="currentColor" style="width:1em;height:1em;vertical-align:-0.125em">…</svg>
-```
+[[INCLUDE: shared/ui-redlines.md]]
 
-Rules: ① Color 100% via `currentColor`, controlled by parent CSS `color`; ② Size follows font size (`1em`), no hardcoded px; ③ stroke-width: saas-dark/brutalist → `2`, all others → `1.5`; ④ When a complex icon is too hard to draw, use the simplest geometric substitute — emoji as fallback is forbidden.
+**Content Fill**:
+- Real business names from roadmap, never "Title" placeholders
+- Buttons with specific actions, never "[Button]"
+- Lists/tables with 3-4 rows realistic fake data
+- Empty states with specific copy, never "No data"
 
-### Step 6 — Generate AI Index
+**Self-drawn SVG** (no icon library): stroke="currentColor", stroke-width 1.5-2, fill="currentColor", width="1em" height="1em"
 
-Write `[[__DOCS_DIR__]]/global/ui_context.md`:
+### Step 5 — Generate AI Index
+
+**Output**: `[[__DOCS_DIR__]]/global/ui_context.md`
 
 ```markdown
 # UI Context
-> Platform: [platform] | Generated by archi-ui-wireframe Skill
-> Updated: YYYY-MM-DD | Do not edit manually
+> Platform: [type] | Generated: YYYY-MM-DD
 
 ## Screen Inventory
-| ID | Name | Route | States |
-|:---|:---|:---|:---|
-| S-01 | [name] | [route] | default, loading, ... |
+| ID | Name | Route | File | States |
+|:---|:---|:---|:---|:---|
+| S-01 | [name] | [route] | screens/S-01.html | default, loading, empty, error |
 
 ## Navigation Graph
-S-XX →（[trigger]）→ S-YY
-
-## Global Shared Components
-| Component | Appears On |
-|:---|:---|
-| [component] | S-XX, S-YY |
+S-XX →（trigger）→ S-YY
 
 ## Screen Structure Summary
-> Extracted from ui_concept.html data-el. 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]
+**Layout**: [e.g. "240px left sidebar + right content"]
+**File**: screens/S-XX.html
+**States**: default (core actions) | loading (skeleton) | empty | error
+**Key regions**: [from data-el: top nav, main form, submit button, error 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.
+### Step 6 — Output Gate
 
-### Step 7 — Verification Checklist
+Output summary: aesthetic direction + reference products, screen coverage list (N screens), visual spec, navigation structure.
 
-- [ ] 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
-- [ ] **Icon check**: icon library set → CDN used; no icon library → self-drawn SVG used; **zero emoji**
-- [ ] **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
-- [ ] **UI quality check**: no pure black text, layered backgrounds, soft card shadows, primary color ≤10%, interaction states complete, realistic content fill
+**User confirmation**: Reply **OK** to complete; otherwise enter Refinement.
 
-### Step 8 — Output Gate
+## Output Verification
 
-Output coverage summary:
-
-```
-### ui_concept.html generated
-### ui_context.md generated (AI screen index)
-
-**Aesthetic direction**: [preset value] — [reference products]
-**Screen coverage** (N screens total):
-| Screen | Name | States |
-|:---|:---|:---|
-| S-01 | [name] | N |
-| ... | | |
-
-**Applied visual spec**:
-- Primary color: [Primary token value]
-- Font: [display font + body font]
-- Radius: [sm/md/lg values]
-- Motion: [preference value]
-- Theme: [default + support list]
-
-**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 review layout and visual output.
-> Reply **OK** to confirm; or describe screen/layout/visual adjustments needed.
-```
-
-**Gate**: Complete after user replies **OK**; otherwise enter Refinement.
+□ `global/screens/index.html` generated with all screen links listed
+□ `global/screens/_shared.css` generated with design_tokens CSS variables
+□ `global/screens/S-XX.html` independent file generated for each screen
+□ `global/ui_context.md` generated with screen inventory containing `screens/S-XX.html` paths
 
 ---
 
-### Refinement — Iterative Polish (optional)
+## Refinement (User Feedback)
 
-**Trigger**: User reply is not OK — contains layout adjustments, screen additions/removals, navigation changes, visual modifications.
-**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.
+User reply contains layout/visual adjustments → partial update corresponding `screens/S-XX.html` + sync `ui_context.md` → re-display summary, await confirmation.
 
 ---
 
-### Incremental Update
+## Incremental Update
 
-**Trigger**: A screen is updated by Plan Refinement / Edit / Revise and new content needs to match the current visual spec.
+Input screen ID list → process specified screens only: preserve existing files, generate new/updated `S-XX.html` per current visual spec; if new states → sync update `ui_context.md`. Update `index.html` navigation list.
 
-**Action**:
-
-1. Receive the list of screen IDs to update from the caller (e.g., `S-03`, `S-07`).
-2. Process only the specified screens:
-   - Preserve existing content within `.wf-screen#S-XX`
-   - Generate new additions per current visual spec (`semanticTokens` / `motion` / `illustration`)
-   - Leave all other screen content untouched
-3. If new states added → 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 update, [N] new states/regions)`
-   - `MODIFIED: ui_context.md S-XX (updated states list)` (only if new states were added)
-
-> **Forbidden**: Never do a full rewrite for incremental updates. Never touch screens not in the specified list.
+Output: `MODIFIED: screens/S-XX.html` (annotated per file)
 
 ---
 
-### Adopt — Reverse Adoption (Legacy UI Capture)
-
-**Trigger**: After `/archi.inherit` completes, invoked for UI projects.
-**Input**: Existing code (route definitions, page components, layout files) + design_tokens.json (may be incomplete)
-
-**Action**:
-
-1. **Scan UI structure**:
-   - Extract page list from route definitions (React Router / Vue Router / Next.js pages / SvelteKit routes etc.)
-   - Identify navigation structure from layout components (sidebar / navbar / tabbar)
-   - Identify core regions and states from page components
-
-2. **Plan screen inventory**: Same as standard flow Step 2 (assign S-XX IDs, map to LEG-xx tasks)
-
-3. **Tokens check + guidance**: Same as standard flow Step 4
-   - Prioritize extracting CSS variables / Tailwind config / theme files from existing code
-   - Run guidance question flow for insufficient fields
-
-4. **Generate HTML**: Same as standard flow Step 5 (hi-fi quality standards)
-   - Use existing code UI structure as layout reference (restore, not invent from scratch)
-   - Details and states may be supplemented (e.g. original code lacks empty/error states)
-
-5. **Generate ui_context.md**: Same as standard flow Step 6
+## Adopt (Reverse from Code)
 
-6. **Output**: Same as standard flow Step 8
+Input existing code + design_tokens.json → extract: routes → screen inventory, layout components → navigation structure, page components → core regions and states → generate `screens/` directory + ui_context.md per standard flow.

package/dist/templates/icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <!-- Background -->
+  <rect width="32" height="32" rx="7" fill="#141210"/>
+
+  <!-- Corner registration marks (architectural reference) -->
+  <circle cx="5"  cy="5"  r="1.2" fill="#b88a3f" opacity="0.5"/>
+  <circle cx="27" cy="5"  r="1.2" fill="#b88a3f" opacity="0.5"/>
+  <circle cx="5"  cy="27" r="1.2" fill="#b88a3f" opacity="0.5"/>
+  <circle cx="27" cy="27" r="1.2" fill="#b88a3f" opacity="0.5"/>
+
+  <!-- Geometric "A" letterform -->
+  <path d="M 8 25 L 16 7 L 24 25" stroke="#b88a3f" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+
+  <!-- Crossbar -->
+  <line x1="11.5" y1="19" x2="20.5" y2="19" stroke="#b88a3f" stroke-width="2" stroke-linecap="round"/>
+</svg>

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

@@ -18,14 +18,14 @@
 
 ---
 
-## 核心任务
+## 功能需求
 
-> 必须实现的任务，每项一段话描述预期行为。
-> 详细 Spec 在 `/archi.plan` 阶段定义，此处只需明确"做什么"。
+> 必须实现的核心能力，描述"做什么"而非"怎么做"。
+> AI 会据此分解为具体的实现任务，此处只需明确业务目标。
 
-1.
-2.
-3.
+-
+-
+-
 
 ---
 
@@ -33,7 +33,7 @@
 
 > 如果你的项目有明确的用户旅程或核心工作流，在此描述。
 > 不需要画图——用文字描述步骤即可，AI 会据此理解系统行为。
-> 没有的话留空，AI 会从核心任务中推导。
+> 没有的话留空，AI 会从核心功能中推导。
 
 <!-- 写法参考：
 ### [流程名称]
@@ -46,11 +46,11 @@
 
 ## 已有设计决策
 
-> 如果你对某些任务/页面/流程已有明确想法，在此描述。AI 在后续 plan 阶段会以此为准，不会推翻。
+> 如果你对某些功能/页面/流程已有明确想法，在此描述。AI 在后续 plan 阶段会以此为准，不会推翻。
 > 没有的话留空即可。
 >
 > 写法参考：
-> - **[任务/页面名]**: 描述具体行为、流程、约束
+> - **[功能/页面名]**: 描述具体行为、流程、约束
 > - 可附截图/草图（见下方"设计资产"）
 
 ---
@@ -84,6 +84,13 @@
 **目录结构**: [已有明确结构 → 简述关键目录 / 无（AI 基于架构模式生成）]
 **分支策略**: [例：Trunk-based / Git Flow / GitHub Flow]
 **Commit 规范**: [例：Conventional Commits (feat/fix/chore) / 自定义 → 简述]
+
+**AI Git 工作流** (AI 执行 `/archi.code` 时的提交约定):
+- **自动提交**: [是 - 每个 Task 完成后自动 git commit / 否 - 仅生成 commit message，用户手动提交]
+- **提交粒度**: [Per Task - 每个 Task 一个 commit / Per Phase - 每个 Phase 一个 commit / 按需]
+- **分支策略**: [直接在 main 分支工作 / 每个 Task 新建分支 `feat/{task-id}`]
+- **自动推送**: [是 / 否]
+
 **测试偏好**: [例：Vitest / Jest / pytest / 无特殊要求]
 
 ---
@@ -138,7 +145,7 @@
 
 | 参考项目 | 参考维度 |
 |:---|:---|
-| [例：Linear] | [交互体验、任务管理逻辑] |
+| [例：Linear] | [交互体验、功能管理逻辑] |
 | | |
 
 ---

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

@@ -10,7 +10,7 @@
 
 > 如果你已经知道核心数据实体和关系，在此描述。不需要写完整 Schema——列出实体名和关键字段即可。
 > AI 会在 `/archi.plan` 阶段据此生成详细的数据模型，此处只需明确"有什么数据"。
-> 没有的话留空，AI 会从核心任务中推导。
+> 没有的话留空，AI 会从核心功能中推导。
 
 <!-- 写法参考：
 - **用户 (User)**: email, name, role (admin/user), avatar
@@ -71,7 +71,7 @@
 
 ### 视觉参考 (Visual Reference)
 
-> 为 AI 提供审美输入，直接影响 `ui_concept.html` 的视觉质量。
+> 为 AI 提供审美输入，直接影响 `screens/` 目录下各屏幕原型的视觉质量。
 > 以下任填一项即有效，填得越多 AI 越能还原你的期望风格。
 
 **竞品/灵感截图**: [可粘贴图片 / Figma 链接 / URL]