@zeyue0329/xiaoma-cli 1.12.0 → 1.15.0

package/src/xmc-skills/2-plan-workflows/xiaoma-ux/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: xiaoma-ux
+description: Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"
+---
+# XiaoMa UX
+
+## Overview
+
+You are a master UX facilitator. **Elicit and capture** the user's vision, never impose yours. Probe like a senior practitioner; never volunteer colors, patterns, or directions. Render options via creative tools when seeing helps; the picks are the user's.
+
+Produce two peer contracts: **`DESIGN.md`** (visual identity per the [Google Labs spec](https://github.com/google-labs-code/design.md) — owns *how it looks*) and **`EXPERIENCE.md`** (information architecture, behavior, states, interactions, accessibility, journeys — owns *how it works*). EXPERIENCE.md cross-references DESIGN.md tokens by name using `{path.to.token}` syntax. Both spines win on conflict with any mock, wireframe, or import.
+
+## The DESIGN.md spine
+
+Per the [Google Labs spec](https://github.com/google-labs-code/design.md). YAML frontmatter tokens (**colors** · **typography** · **rounded** · **spacing** · **components**) + markdown body in canonical order: **Brand & Style** · **Colors** · **Typography** · **Layout & Spacing** · **Elevation & Depth** · **Shapes** · **Components** · **Do's and Don'ts**. Sections omittable; order locked when present. Spec rules: `references/design-md-spec.md`. Shape: read every entry in `{workflow.design_md_examples}`.
+
+## The EXPERIENCE.md spine
+
+Always: **Foundation** (form-factor, UI system when present; DESIGN.md is the visual identity reference) · **Information Architecture** · **Voice and Tone** (microcopy — brand voice lives in DESIGN.md.Brand & Style) · **Component Patterns** (behavioral — visual specs live in DESIGN.md.Components) · **State Patterns** · **Interaction Primitives** · **Accessibility Floor** (behavioral — visual contrast lives in DESIGN.md) · **Key Flows** (named-protagonist journeys with a climax beat).
+
+When triggered: **Inspiration & Anti-patterns** · **Responsive & Platform**.
+
+Invent sections for product-specific concerns. Shape: read every entry in `{workflow.experience_md_examples}`.
+
+When Foundation names a UI system (shadcn, MUI, native UIKit, Compose, internal design system), both spines inherit from it; DESIGN.md tokens reference or extend the system's defaults, EXPERIENCE.md specifies only the behavioral delta.
+
+## Sources
+
+UX may lead, follow, or stand alone. Inherit `sources:` by reference; the spines hold design and experience decisions, not duplicates of upstream product content.
+
+## On Activation
+
+1. Resolve customization: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools; consult them alongside generic web research on the same triggers, org tools preferred when their directive matches.
+3. Load `{project-root}/_xiaoma/xmc/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block.
+4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn. In the greeting, let the user know `xiaoma-party-mode` and `xiaoma-advanced-elicitation` are always available. Then scan for misroute on the first message: PRD → `xiaoma-prd`; architecture → `xiaoma-create-architecture`; game UX → XiaoMa GDS; agent/skill → `xiaoma-workflow-builder`; brief → `xiaoma-product-brief`.
+5. Detect intent: **Create**, **Update**, **Validate**. For Create, before binding a fresh workspace, scan `{workflow.ux_output_path}` for prior in-progress runs (folders matching `{workflow.run_folder_pattern}` whose `DESIGN.md` frontmatter `status` is not `final`) and offer to resume rather than starting over.
+
+Run `{workflow.activation_steps_append}`.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## Modes
+
+**Create.** Bind `{doc_workspace}` to `{workflow.ux_output_path}/{workflow.run_folder_pattern}/`. Create `.working/`, `imports/`, `.decision-log.md`, `DESIGN.md` (frontmatter only), and `EXPERIENCE.md` (frontmatter only). Run Discovery → Finalize.
+
+**Update.** Read spines + log + sources. Create the log if missing — this update is entry one. Surface conflicts with prior decisions. Run Finalize.
+
+**Validate.** See `references/validate.md`.
+
+## Discovery
+
+**Capture; do not author.** The spines are distilled at Finalize. Decisions → `.decision-log.md` (canonical). Creative-tool artifacts → `.working/`. User-supplied visuals (Figma, sketches, brand decks, image folders) → `imports/`, one log line per item. Spines win on conflict.
+
+**Source scan.** Glob `{planning_artifacts}/` for candidate input paths; surface paths only — never read content in the parent. User confirms which apply or adds others; subagent-extracts on confirm.
+
+Brain dump first — even when the user opens with paragraphs (that's intake). Subagent-extract big docs. One "anything else?" probe. Stakes: hobby / internal / consumer / regulated.
+
+Working mode:
+
+- **Fast path** — batch gaps, draft both spines with `[ASSUMPTION]` tags, skip creative tools.
+- **Coaching path** — walk decisions; creative tools woven in.
+- **Design handoff** — assemble captured Discovery into a producer-shaped prompt; user runs the external tool and saves outputs to `{doc_workspace}` in whatever format the tool emits. Producer registry: `{workflow.design_handoffs}` (default: Google Stitch). EXPERIENCE.md can follow via Update mode when ready.
+
+Creative tools — scan `{workflow.creative_tools}`, invoke when seeing helps. Defaults: HTML color themes, design directions, Excalidraw wireframes; key-screen HTML mocks at Finalize. See `references/creative-tools.md`. Research subagents on demand; consult `{workflow.external_sources}` when entries match.
+
+Concern scan — name what the UX carries: accessibility, platforms, brand, regulated language, motion, i18n, dark mode, offline, content density, input modalities, notifications. Open list; drives invented sections.
+
+Journeys: user narrates a real session with a named protagonist (Mary, mom of three, kids asleep — not "the user"); structure into numbered steps with a climax beat. Mirror source-spec names verbatim when defined.
+
+Form-factor: mobile / web / desktop / multi-surface must resolve before IA closes. Named-protagonist journeys often derive it (Pary on iPad implies an iPad surface; Skeeter on Android adds a multi-surface need); when journeys don't disambiguate, probe.
+
+Surface closure: stated needs become screens through journeys. IA closes when every stated need has a surface that delivers it, and every surface has a journey that lands there. When closure fails, probe — never invent the missing piece.
+
+## Reviewer Gate
+
+Used by Validate and Finalize. **Opt-in, lens-selectable** — reviewers are costly (parallel subagents, substantial token spend). At **Finalize**, first ask whether to run validation at all; default offered, easy skip. At **Validate** intent the user already opted in — skip that question. In both cases, present the lens menu and let the user pick all / a subset / none. Menu: rubric walker (`references/validate.md`) + `{workflow.finalize_reviewers}` + ad-hoc (accessibility for consumer / regulated; others by stakes and content). Picked lenses dispatch as parallel subagents → each writes `review-{slug}.md`, returns a compact summary. If any lens ran, run the synthesis pipeline in `references/validate.md`.
+
+## Finalize
+
+Outcomes, in order:
+
+- **Spines distilled.** Subagent reads `.decision-log.md`, `.working/`, `imports/`, sources; produces `DESIGN.md` against `## The DESIGN.md spine` + `{workflow.design_md_examples}` and `EXPERIENCE.md` against `## The EXPERIENCE.md spine` + `{workflow.experience_md_examples}`. Runs the rubric walker's Pass 1 coverage checks proactively (see `references/validate.md`). Surface gaps; never invent.
+- **Inputs reconciled.** Subagent per user-supplied input → `reconcile-{slug}.md`. Surface dropped qualitative ideas.
+- **Reviewer Gate offered.** Ask whether to run validation; if yes, present the lens menu (see `## Reviewer Gate`) and let the user pick. If any lens ran, resolve findings before polish; otherwise proceed.
+- **Open items triaged.** Open Questions, `[ASSUMPTION]`, `[NOTE FOR UX]`. Phase-blockers one at a time; non-blockers → log.
+- **Key-screen mocks rendered.** Key-screens tool → `.working/` for surfaces where layout drives behavior or anchors visual language.
+- **Mock coverage confirmed.** Walk every IA surface; classify *mocked* vs *spine-only*. Ask: *"These will be built from spine tables alone — any need a visual reference?"* Render more if named; log spine-only choices.
+- **Layout extracted, artifacts promoted.** Distill subagent re-reads each `.working/` and `imports/` artifact; lifts visual decisions into DESIGN.md and behavioral decisions into EXPERIENCE.md. Promote `.working/` keepers to `mockups/` (HTML) or `wireframes/` (Excalidraw); imports stay. Inline relative links at relevant spine sections; state spines-win-on-conflict once.
+- **Polished, handed off, closed.** Apply `{workflow.doc_standards}` in order. Execute `{workflow.external_handoffs}`; surface URLs. Set both files' `status: final`, `updated: {date}`. Log finalization. Share paths. Common next: `xiaoma-create-architecture`, `xiaoma-create-epics-and-stories`, `xiaoma-dev-story`. Run `{workflow.on_complete}`.

package/src/xmc-skills/2-plan-workflows/xiaoma-ux/assets/color-themes.md

@@ -0,0 +1,9 @@
+# Color Themes Renderer
+
+Subagent prompt. Produce one self-contained HTML page at the supplied `.working/color-themes-{n}.html` path showing 4-6 distinct theme variations side by side so the user can pick.
+
+Each variation: header (name + one-line emotional register), token chips for every semantic role decided so far, and one realistic UI snippet using the palette (content drawn from the conversation, not lorem). Include light and dark side-by-side when both modes are in scope. Avoid near-identical pastels — variations must differ in register, not just hue.
+
+Inline CSS only, system font stack, no JS, no network. Document concrete hex values in `<style>` comments per variation so the user can lift them if they pick that theme. The spine itself stays semantic.
+
+Return to the parent: file path, one-line per variation, mode coverage. Do not dump HTML into the parent context. If interactive, open the file in your browser.

package/src/xmc-skills/2-plan-workflows/xiaoma-ux/assets/design-directions.md

@@ -0,0 +1,9 @@
+# Design Directions Renderer
+
+Subagent prompt. Produce 3-6 distinct visual directions for the product's hero screen, each a separate self-contained HTML file at `.working/direction-{slug}.html` (or one combined `directions-{n}.html` if the parent's intent says side-by-side).
+
+Each direction is a *complete visual personality* applied to the same key screen — not a palette swap. Differ on density, type weight, motion implication, brand register. Each file: 2-3 sentence rationale, near-1:1 hero screen mockup in a phone or browser frame, ideally a secondary screen, at least one state variant visible (aging row, empty state, etc).
+
+Use real product content from the conversation. Voice/tone from `.decision-log.md` applied to every visible string — no lorem. Inline CSS, system fonts, no JS or network. Document hex values in `<style>` comments per direction.
+
+Return to the parent: file paths, one-line personality summary per direction, what hero screen was depicted. Do not dump HTML into parent context. If interactive, open each file in the browser.

package/src/xmc-skills/2-plan-workflows/xiaoma-ux/assets/design-example-editorial.md

@@ -0,0 +1,158 @@
+---
+name: Linen & Logic
+colors:
+  surface: '#fbf9f4'
+  surface-dim: '#dbdad5'
+  surface-bright: '#fbf9f4'
+  surface-container-lowest: '#ffffff'
+  surface-container-low: '#f5f3ee'
+  surface-container: '#f0eee9'
+  surface-container-high: '#eae8e3'
+  surface-container-highest: '#e4e2dd'
+  on-surface: '#1b1c19'
+  on-surface-variant: '#4e453d'
+  inverse-surface: '#30312e'
+  inverse-on-surface: '#f2f1ec'
+  outline: '#80756b'
+  outline-variant: '#d1c4b9'
+  surface-tint: '#715a3f'
+  primary: '#59452b'
+  on-primary: '#ffffff'
+  primary-container: '#735c41'
+  on-primary-container: '#f5d6b4'
+  inverse-primary: '#e0c1a1'
+  secondary: '#a43b2c'
+  on-secondary: '#ffffff'
+  secondary-container: '#fd7d69'
+  on-secondary-container: '#71160b'
+  tertiary: '#374a5f'
+  on-tertiary: '#ffffff'
+  tertiary-container: '#4f6278'
+  on-tertiary-container: '#caddf8'
+  error: '#ba1a1a'
+  on-error: '#ffffff'
+  error-container: '#ffdad6'
+  on-error-container: '#93000a'
+  primary-fixed: '#fdddbb'
+  primary-fixed-dim: '#e0c1a1'
+  on-primary-fixed: '#281804'
+  on-primary-fixed-variant: '#58432a'
+  secondary-fixed: '#ffdad4'
+  secondary-fixed-dim: '#ffb4a7'
+  on-secondary-fixed: '#400200'
+  on-secondary-fixed-variant: '#842417'
+  tertiary-fixed: '#d0e4ff'
+  tertiary-fixed-dim: '#b4c8e2'
+  on-tertiary-fixed: '#071d30'
+  on-tertiary-fixed-variant: '#35485d'
+  background: '#fbf9f4'
+  on-background: '#1b1c19'
+  surface-variant: '#e4e2dd'
+typography:
+  display-lg:
+    fontFamily: Libre Caslon Text
+    fontSize: 48px
+    fontWeight: '400'
+    lineHeight: '1.1'
+    letterSpacing: -0.02em
+  display-lg-mobile:
+    fontFamily: Libre Caslon Text
+    fontSize: 36px
+    fontWeight: '400'
+    lineHeight: '1.1'
+  headline-md:
+    fontFamily: Libre Caslon Text
+    fontSize: 32px
+    fontWeight: '400'
+    lineHeight: '1.2'
+  headline-sm:
+    fontFamily: Libre Caslon Text
+    fontSize: 24px
+    fontWeight: '400'
+    lineHeight: '1.3'
+  body-lg:
+    fontFamily: DM Sans
+    fontSize: 18px
+    fontWeight: '400'
+    lineHeight: '1.6'
+    letterSpacing: 0.01em
+  body-md:
+    fontFamily: DM Sans
+    fontSize: 16px
+    fontWeight: '400'
+    lineHeight: '1.6'
+  label-caps:
+    fontFamily: DM Sans
+    fontSize: 12px
+    fontWeight: '500'
+    lineHeight: '1.4'
+    letterSpacing: 0.1em
+  caption:
+    fontFamily: DM Sans
+    fontSize: 13px
+    fontWeight: '400'
+    lineHeight: '1.4'
+rounded:
+  sm: 0.125rem
+  DEFAULT: 0.25rem
+  md: 0.375rem
+  lg: 0.5rem
+  xl: 0.75rem
+  full: 9999px
+spacing:
+  unit: 8px
+  gutter: 24px
+  margin-mobile: 20px
+  margin-desktop: 64px
+  editorial-gap: 80px
+---
+
+## Brand & Style
+
+The design system is rooted in the philosophy of "Slow Design"—an intentional departure from the frantic pace of fast fashion. It evokes a tactile, "linen-weight" sensation through high-end editorial layouts and a restrained aesthetic. The target audience values provenance over presence, seeking a reflective and sophisticated discovery experience that feels as much like a boutique magazine as a digital marketplace.
+
+The style is **Editorial Minimalism** with **Tactile** accents. It prioritizes breathable white space, asymmetrical layouts that mimic printed lookbooks, and a soft, sun-faded palette. Every interaction is designed to be deliberate and "anti-hype," eschewing aggressive animations for subtle transitions and quiet confidence.
+
+## Colors
+
+The palette is inspired by natural fibers and weathered landscapes. 
+- **Warm White (#F9F7F2)** serves as the primary canvas, providing a soft, non-clinical background that reduces eye strain.
+- **Bone (#E3DED1)** and **Dust (#C2B9A7)** are used for structural depth, subtle dividers, and secondary surfaces.
+- **Tobacco (#735C41)** is the primary ink color, used for high-contrast typography and essential UI elements.
+- **Sun-faded Red (#B84A39)** and **Wool Blanket Blue (#4A5D73)** are used sparingly as "organic accents"—highlighting editorial picks or signifying subtle state changes without disrupting the tranquil atmosphere.
+
+## Typography
+
+Typography is the primary vehicle for the brand’s sophisticated voice. 
+- **Libre Caslon Text** is the voice of the curator. Its classic proportions and elegant serifs provide the editorial weight required for discovery and storytelling.
+- **DM Sans** provides a quiet, functional counterpoint. It is used for body copy and navigational elements, ensuring clarity without competing with the headlines. 
+
+Large display titles should often use "optical sizing" logic—tighter leading and slightly negative letter spacing to create a cohesive visual block. Labels are always tracked out (0.1em) to maintain a sense of airy premiumness.
+
+## Layout & Spacing
+
+This design system employs a **Fluid Editorial Grid**. While it follows a 12-column structure on desktop, it encourages "asymmetrical breathing room"—intentionally leaving columns empty to direct focus toward high-quality imagery.
+
+Spacing is generous. The `editorial-gap` (80px+) should be used between major content sections to allow the user to pause and reflect. Mobile layouts should maintain a minimum of 20px side margins to ensure the content feels framed like a page, rather than bleeding to the edges of the device. Elements should lean toward vertical stacks to mimic the scroll of a digital journal.
+
+## Elevation & Depth
+
+Depth is communicated through **Tonal Layering** and **Ambient Shadows** rather than sharp borders.
+- **Surfaces:** Use the "Bone" color to define containers against the "Warm White" base. 
+- **Shadows:** Shadows are highly diffused and tinted with the "Tobacco" hue (`rgba(115, 92, 65, 0.08)`). They should feel like a soft glow of light hitting fabric, with large blur radii (20px+) and very low opacity.
+- **Borders:** When borders are necessary, they are 1px thick and rendered in "Dust," creating a "ghost" outline that barely separates elements from the background.
+
+## Shapes
+
+The shape language is **Soft (0.25rem)**. While a sharp edge feels too aggressive and a pill-shape feels too digital/tech-heavy, a subtle rounding of corners mimics the natural softening of woven textiles over time. 
+
+Larger containers (Cards, Modals) may use `rounded-lg` (0.5rem) to emphasize their tactile, object-like quality. Imagery should always follow these corner radii to maintain a cohesive, "framed" appearance.
+
+## Components
+
+- **Buttons:** Primary buttons use a solid "Tobacco" fill with "Warm White" text. Secondary buttons are "Bone" with "Tobacco" text or simply "Tobacco" text with a 1px "Dust" border. Padding is generous horizontally to create an elegant, elongated silhouette.
+- **Cards:** Editorial cards feature large imagery, a "headline-sm" title, and a "caption" subline. Shadows are only applied on hover to simulate a gentle lift.
+- **Inputs:** Minimalist underlines in "Dust" that transition to "Tobacco" on focus. Label text remains in "label-caps" above the field.
+- **Chips/Tags:** Used for material types (e.g., "100% Linen"). These are rendered in "Bone" backgrounds with "Tobacco" text, using the "Soft" corner radius.
+- **Icons:** Must be "Hand-drawn" or "Fine-line" style. Lines should have slight imperfections and vary in weight to reinforce the tactile, artisanal nature of the fashion being discovered.
+- **Navigation:** A simple, centered bottom bar or a top-weighted "Ghost" header that disappears on scroll to maximize the editorial viewport.

package/src/xmc-skills/2-plan-workflows/xiaoma-ux/assets/design-example-mobile.md

@@ -0,0 +1,93 @@
+---
+name: Quill
+description: Daily writing companion. Calm, intentional, dark-mode-by-default. No streaks, no gamification.
+colors:
+  surface-base: '#FAF9F7'
+  surface-raised: '#FFFFFF'
+  ink-primary: '#1A1B1F'
+  ink-secondary: '#6B655A'
+  ink-disabled: '#B5AFA5'
+  accent: '#A87434'
+  border-hairline: '#E8E4DD'
+  surface-base-dark: '#1A1B1F'
+  surface-raised-dark: '#23252B'
+  ink-primary-dark: '#F0EDE8'
+  ink-secondary-dark: '#A39E94'
+  ink-disabled-dark: '#5E5A53'
+  accent-dark: '#D4A574'
+  border-hairline-dark: '#2E3036'
+typography:
+  title:
+    note: 'Platform native — iOS Title 1 · Android Headline Small'
+  body:
+    note: 'Platform native — iOS Body · Android Body Large'
+  meta:
+    note: 'Platform native — iOS Footnote · Android Body Small'
+rounded:
+  sm: 6px
+  md: 12px
+spacing:
+  '1': 4px
+  '2': 8px
+  '3': 12px
+  '4': 16px
+  '5': 24px
+  '6': 32px
+---
+
+## Brand & Style
+
+Quill is designed against the grain of contemporary habit apps. Where most products weaponize the user's calendar with streak counters and re-engagement nudges, Quill insists on something quieter — a daily prompt, a place to write, and the unspoken assurance that today's entry is enough. Showing up is the point, not the streak.
+
+The visual language follows. Calm surfaces in warm off-white (light) or deep ink (dark, the default). Generous breathing room. No chromatic color competing for attention except a single warm tobacco that signals save-and-send. Text-first. Hand-on-paper, not buzz-on-screen.
+
+## Colors
+
+The palette is restrained on purpose — a writing surface should not compete with the writing.
+
+- **Warm White (`#FAF9F7`)** is the primary canvas in light mode. Slightly warm to reduce eye strain and keep the surface from feeling clinical.
+- **Deep Ink (`#1A1B1F`)** is the dark-mode canvas and the primary body text color in light mode. Quill defaults to dark because most writing happens at night.
+- **Tobacco (`#A87434` light / `#D4A574` dark)** is the only chromatic color. Used exclusively for the save indicator and primary action — never for decoration, never for state badges.
+- **Hairline (`#E8E4DD` light / `#2E3036` dark)** separates list items at the lowest possible contrast. Anything heavier feels like UI rather than paper.
+
+Avoid: red error fills (Quill is a journal, not a form), gradients (the surface is paper), and saturated accent variants — one accent, used sparingly.
+
+## Typography
+
+Platform conventions are the spec. iOS uses Title 1 / Body / Footnote; Android uses Headline Small / Body Large / Body Small. Dynamic type honored at every level — the largest accessibility setting must still render legibly without truncation.
+
+Headlines are rare. The Today prompt is set in `title`; everything else is `body` or `meta`. No display sizes, no all-caps labels.
+
+## Layout & Spacing
+
+Scale: 4 / 8 / 12 / 16 / 24 / 32 px. The largest gaps land between major surfaces; the smallest sit between tightly related elements. Vertical rhythm follows a hard rule: composer breathes, list items don't.
+
+Mobile margins follow platform conventions (iOS 16pt, Android 16dp). Single-column always; modal stacks one level deep, never two.
+
+## Elevation & Depth
+
+Quill avoids elevation as a visual device. Cards and composer surfaces sit on `surface-raised`, distinguished from `surface-base` only by tone. Shadows are reserved for the rare moment of literal physical metaphor — never for hierarchy. Hierarchy comes from layout and typography, not shadow.
+
+## Shapes
+
+`rounded/sm` (6px) for inputs, list rows, and small surfaces. `rounded/md` (12px) for cards and the composer. Nothing fully rounded; no pills, no perfect circles for surfaces. The aesthetic is paper-with-soft-corners, not iOS-button-pill.
+
+Imagery follows container corners exactly.
+
+## Components
+
+- **Prompt card** — `surface-raised`. One per day. Today's prompt in `title`. Tap to open composer. No icon, no decoration; the prompt itself is the affordance.
+- **Composer** — Full-screen text view. Clean text field, generous vertical padding, single-line save indicator in the header.
+- **Save indicator** — Text only. Uses `ink-secondary`, never a checkmark icon, never a colored badge.
+- **Entry row** (Library) — Date in `meta`, first line of body in `body` (truncated to one line). Hairline divider only, no fill.
+- **Settings row** — Label left, value or chevron right. Tobacco accent only on destructive confirmations.
+
+## Do's and Don'ts
+
+| Do | Don't |
+|---|---|
+| Single accent color, used sparingly on save & primary action | Color-code by sentiment, mood, or category |
+| Text-only state indicators (`Saved.`) | Iconography for state (✓, ⚠, ●) |
+| Hairline dividers at lowest legible contrast | Card shadows, gradient fills, accent fills behind text |
+| Generous vertical rhythm in composer | Compress to fit more on screen |
+| Honor platform conventions for navigation | Override platform nav with custom drawer or hamburger |

package/src/xmc-skills/2-plan-workflows/xiaoma-ux/assets/design-example-shadcn.md

@@ -0,0 +1,109 @@
+---
+name: Drift
+description: Focused task tracker for solo founders and small async teams. shadcn/ui on Next.js + Tailwind; this DESIGN.md specifies the brand-layer delta only.
+colors:
+  # Brand overrides on top of shadcn defaults. All unlisted tokens inherit
+  # from shadcn (background, foreground, muted, muted-foreground, popover,
+  # popover-foreground, card, card-foreground, border, input, ring, destructive).
+  primary: '#0F4C81'
+  primary-foreground: '#FFFFFF'
+  accent: '#F59E0B'
+  accent-foreground: '#1A1208'
+  primary-dark: '#5C8AC2'
+  primary-foreground-dark: '#0A1A2A'
+  accent-dark: '#FBC470'
+  accent-foreground-dark: '#1A1208'
+typography:
+  # Body, label, and muted inherit from shadcn (Geist Sans). Only display is overridden.
+  display:
+    fontFamily: 'Instrument Serif'
+    fontSize: 36px
+    fontWeight: '400'
+    lineHeight: '1.15'
+    letterSpacing: -0.01em
+  display-sm:
+    fontFamily: 'Instrument Serif'
+    fontSize: 24px
+    fontWeight: '400'
+    lineHeight: '1.2'
+rounded:
+  # Tighter than shadcn defaults — Drift reads sharper.
+  sm: 4px
+  md: 6px
+  lg: 8px
+spacing:
+  # shadcn / Tailwind defaults inherited; no overrides.
+components:
+  button-primary:
+    background: '{colors.primary}'
+    foreground: '{colors.primary-foreground}'
+    radius: '{rounded.md}'
+  focus-card:
+    background: '{colors.accent}'
+    foreground: '{colors.accent-foreground}'
+    radius: '{rounded.md}'
+    border: 'none'
+  command-palette-result-active:
+    background: '{colors.accent}'
+    foreground: '{colors.accent-foreground}'
+---
+
+## Brand & Style
+
+Drift is a focused task tracker for solo founders and small async teams. The product premise is that *work is a moving thing* — momentum matters more than perfectly groomed backlogs, and the right tool surfaces what you're working on *now* without making you administer a system to find it. The brand expression follows: a serif display moment in an otherwise sober sans-serif surface, a single warm accent that means *this is what's live*, and visual restraint everywhere else.
+
+Drift inherits shadcn/ui defaults wholesale. This DESIGN.md specifies only the brand-layer deltas — primary color, accent color, display typography, slightly tighter corners, and a handful of brand-specific components. The 80% of components that ship from shadcn (Button, Card, Dialog, Sheet, Command, Popover, Toast) inherit shadcn's visual specs as-is. Customizing those is *explicitly* against the brand discipline — shadcn's defaults are the contract.
+
+## Colors
+
+The Drift palette is two colors of brand-layer plus shadcn defaults for everything else.
+
+- **Primary Navy (`#0F4C81` light / `#5C8AC2` dark)** is the brand color. Used on primary buttons, active nav items, link underlines, and the "current week" indicator. Replaces shadcn's default `primary`.
+- **Focus Amber (`#F59E0B` light / `#FBC470` dark)** is the accent. Used exclusively to indicate the task or project currently in focus — the one you're working on *right now*. Never used for chrome, never used decoratively, never used for state badges. Amber means "live."
+- **All other tokens** (`background`, `foreground`, `muted`, `muted-foreground`, `border`, `input`, `ring`, `card`, `popover`, `destructive`) inherit from shadcn defaults. If the brand can't justify overriding a token, it doesn't override it.
+
+Avoid: chromatic flourishes, gradient surfaces, custom destructive colors (use shadcn's), more than two brand colors. The discipline is two-colors-and-stop.
+
+## Typography
+
+Body / label / caption inherit shadcn's Geist Sans ramp. Only the `display` role is brand-overridden, set in **Instrument Serif** at 36px (24px small variant). The serif moment appears in:
+
+- Empty-state hero text on Today and project surfaces
+- Project titles in the project detail header
+- The "Welcome back, {name}" greeting at first session of the day
+
+Everything else stays in Geist Sans. The serif is a punctuation mark, not a default voice.
+
+## Layout & Spacing
+
+shadcn / Tailwind spacing scale inherited as-is (the 4-based scale: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64). Maximum content width: `max-w-3xl` (768px) — Drift is not a wide-table product, and forcing one-column reading keeps the surface focused.
+
+Single-column layout. Sidebar nav on `lg` (1024px+); on smaller viewports, the sidebar becomes a sheet triggered from the top bar.
+
+## Elevation & Depth
+
+Inherited from shadcn — subtle shadow on hover/active states, no elevation as a visual hierarchy device. Drift adds nothing on top of this; brand discipline is "shadcn's shadows are correct."
+
+## Shapes
+
+Tighter than shadcn defaults: `rounded/sm` (4px) for inputs, `rounded/md` (6px) for cards and buttons, `rounded/lg` (8px) for dialogs and the command palette. The crispness reads "tool" rather than "consumer app." Pill shapes (`rounded/full`) appear only on status badges.
+
+## Components
+
+Drift uses the following shadcn components as-is, unchanged: `Button`, `Card`, `Dialog`, `Sheet`, `Popover`, `DropdownMenu`, `Toast`, `Tabs`, `Avatar`, `Separator`. The contract: don't customize these.
+
+Brand-layer-overridden components:
+
+- **Button (primary variant)** — `{colors.primary}` fill, `{colors.primary-foreground}` text, `{rounded.md}` corner. Other variants (secondary, outline, ghost, destructive) inherit shadcn defaults.
+- **Focus card** — Custom Drift component. The "this is what you're working on now" card on Today and project detail. `{colors.accent}` fill, no border, slightly elevated. Appears at most once per surface.
+- **Command palette result (active)** — Override on shadcn's `Command` component: the highlighted/keyboard-selected result row uses `{colors.accent}` instead of shadcn's default `accent` token. Reinforces "this is what will fire if you hit Enter."
+
+## Do's and Don'ts
+
+| Do | Don't |
+|---|---|
+| Inherit shadcn defaults for everything not in the brand layer | Override shadcn's color tokens beyond `primary` and `accent` |
+| Use `{colors.accent}` only for "live / now / in-focus" | Use accent for state, chrome, or hover affordances |
+| `display` typography sparingly — empty states, hero greetings | Set body text in `display` to "make it pretty" |
+| Tighter corners than shadcn (4 / 6 / 8) | Use shadcn's default 6/8/12 (Drift reads sharper) |
+| Single-column layouts inside `max-w-3xl` | Wide multi-column tables (Drift is not a spreadsheet) |

package/src/xmc-skills/2-plan-workflows/xiaoma-ux/assets/excalidraw-wireframe.md

@@ -0,0 +1,19 @@
+# Excalidraw Wireframe Renderer
+
+Subagent prompt. Produce one `.excalidraw` file at `.working/ia-{date}.excalidraw` (IA diagram) or `.working/flow-{name}-{date}.excalidraw` (flow wireframe).
+
+## CRITICAL: two-character `index` fields only
+
+Every element's `index` field must be **exactly two characters** (`a0`, `aZ`, `b3`, ...). Three-character indices cause a silent *"Error: invalid file"* with no diagnostic output. Assign sequentially across all elements; advance the leading letter when the trailing alphanumeric exhausts (`a0..a9, aA..aZ`, then `b0..`). Verify before writing.
+
+## Shape
+
+Valid Excalidraw file: `{type: "excalidraw", version: 2, source: "https://excalidraw.com", elements: [...], appState: {gridSize: null, viewBackgroundColor: "#ffffff"}, files: {}}`. Each element needs the standard Excalidraw element fields (`id, type, x, y, width, height, angle, strokeColor, backgroundColor, fillStyle, strokeWidth, strokeStyle, roughness, opacity, groupIds, frameId, roundness, seed, version, versionNonce, isDeleted, boundElements, updated, link, locked, index`). Text elements add `text, fontSize, fontFamily, textAlign, verticalAlign, baseline, containerId, originalText, lineHeight`.
+
+## Content
+
+**IA diagram:** boxes-and-arrows of auth stack, main app surfaces, modal routes, settings stack, cross-cutting affordances. Color sparingly to distinguish category. Layout for human legibility, not graph correctness.
+
+**Flow wireframe:** screen-by-screen rectangles left-to-right, simple shapes inside (nav bar, CTA, content blocks) at low fidelity. Arrows labeled with the user action that causes transition. Annotations alongside for climax and edge-case beats.
+
+Return to the parent: file path, kind, one-line subject, element count, confirmation that all indices are two-character. Do not dump JSON into parent context. Tell the user to open in Excalidraw desktop or excalidraw.com.

package/src/xmc-skills/2-plan-workflows/xiaoma-ux/assets/experience-example-mobile.md

@@ -0,0 +1,112 @@
+---
+name: Quill
+status: final
+sources:
+  - {planning_artifacts}/prds/quill-2025-08-15/prd.md
+updated: 2025-09-02
+---
+
+# Quill — Experience Spine
+
+> Illustrative example. Single-surface mobile (iOS + Android parity). Consumer posture, calm by default. Paired with `design-example-mobile.md` (Quill DESIGN.md). Demonstrates: microcopy as gating discipline, Inspiration & Anti-patterns earning its place, Responsive & Platform omitted (single-surface).
+
+## Foundation
+
+Single-surface mobile, iOS + Android with parity. No UI system named — inherits platform conventions for navigation, system gestures, dynamic type. `DESIGN.md` is the visual identity reference; this spine is the experience. Dark mode is the default surface; light is a setting.
+
+## Information Architecture
+
+| Surface | Reached from | Purpose |
+|---|---|---|
+| Today | App open (cold) | Today's prompt + entry composer |
+| Library | Tab bar | Past entries, searchable |
+| Entry detail | Library row tap | Read / edit one entry |
+| Settings | Today header gear | Account, export, theme |
+
+Bottom tab bar (Today / Library / Settings). No drawer. Modal stacks one level deep, never two.
+
+→ Composition reference: `mockups/today-cold.html`, `mockups/composer.html`. Spine wins on conflict.
+
+## Voice and Tone
+
+Microcopy. Brand voice and aesthetic posture live in `DESIGN.md`.
+
+| Do | Don't |
+|---|---|
+| "Today's prompt." | "Time to write!" |
+| "Saved." | "✓ Auto-saved successfully" |
+| "We couldn't reach the cloud — your work is on this device." | "Network error" |
+| Short, complete sentences. | Streak counters, encouragement, exclamation marks. |
+
+## Component Patterns
+
+Behavioral. Visual specs live in `DESIGN.md.Components`.
+
+| Component | Use | Behavioral rules |
+|---|---|---|
+| Prompt card | Today | One per day. Tap opens composer. |
+| Composer | Today + entry detail | No formatting toolbar in v1. Autosave on pause ≥ 600ms. |
+| Entry row | Library list | Tap → entry detail. Long-press reserved for system text selection. |
+| Save indicator | Composer header | Cycles `Editing…` → `Saved.` (≥ 800ms visible). |
+| Settings row | Settings list | Tap → detail or toggle. |
+
+## State Patterns
+
+| State | Surface | Treatment |
+|---|---|---|
+| Cold open | Today | Show today's prompt (cached). If no cache, `Today's prompt is loading.` with skeleton. |
+| Empty library | Library | `No entries yet — Today's prompt is your first.` Link to Today. |
+| Search empty | Library search | `No matches.` No suggestions. |
+| Offline write | Composer | Save locally. No banner. Sync on next foreground. |
+| Sync error | Settings → Account | Surfaced here only. Never block writing. |
+| Focus | Composer | Native cursor + keyboard. No custom focus chrome. |
+
+## Interaction Primitives
+
+- Tap to act. Long-press reserved for system text selection.
+- Swipe-to-delete on entry rows (native pattern, confirm sheet).
+- Pull-to-refresh on Library only.
+- **Banned:** carousels, hero animations on open, badge counts, streaks, push-notification re-engagement.
+
+## Accessibility Floor
+
+Behavioral. Visual contrast lives in `DESIGN.md`.
+
+- VoiceOver / TalkBack: every interactive element labeled with role + state. Save indicator announces `Saved` on transition.
+- Dynamic type honored through `DESIGN.md` typography tokens. UI must remain legible at largest setting — no truncated controls.
+- Reduce Motion: skip the save-indicator fade; show `Saved.` immediately.
+- Tap targets ≥ 44pt (iOS) / 48dp (Android).
+- Focus traversal follows reading order on every surface.
+
+## Inspiration & Anti-patterns
+
+- **Lifted from Day One:** the single daily entry framing — one prompt, one composer, no inbox.
+- **Lifted from iA Writer:** the no-toolbar composer; formatting is a settings-level decision, not a per-entry one.
+- **Rejected — Streaks (Duolingo, most habit apps):** streaks weaponize the user's calendar. Quill's value is showing up *today*, not punishing missed days.
+- **Rejected — AI prompt suggestions inside the composer:** the composer is for writing, not negotiating with a model. AI lives only in the daily prompt generation.
+
+## Key Flows
+
+### Flow 1 — Daily write (Mira, late evening, after work)
+
+1. Mira opens app.
+2. Today surface shows today's prompt (cached if offline).
+3. She taps the composer entry point.
+4. Composer opens, keyboard active.
+5. She writes; autosave fires on pause.
+6. She taps Back.
+7. **Climax:** Today surface shows `Saved.` and the entry's first line below the prompt — proof the day is captured.
+
+Failure: cold prompt fetch fails → composer still opens with cached generic prompt; banner on Today only after Mira returns.
+
+### Flow 2 — Recall past entry (Mira, three weeks later, looking for what she wrote about her mother)
+
+1. Mira taps Library.
+2. Scrolls or searches.
+3. Taps entry row.
+4. Entry detail opens in read mode.
+5. She taps anywhere to enter edit mode (cursor at tap point).
+6. Edits autosave.
+7. **Climax:** `Saved.` visible in entry header — the older self and the present self are in continuous conversation.
+
+Empty state: no entries → message routes back to Today.