@morya-ui/setup 0.3.5 → 0.3.6

package/template/.agents/skills/morya-ui-pages/references/review-checklist.md

@@ -1,63 +1,76 @@
-# Review checklist
-
-## Contract (all lanes)
-
-- [ ] Only `morya-ui` UI primitives (no second kit)
-- [ ] `morya-ui/styles.css` imported at app/demo entry
-- [ ] `MConfigProvider` at a sensible root when building a full screen
-- [ ] No invented props / events / slots (MCP `get_component` / docs checked)
-- [ ] MCP **`validate_usage`** run; no unresolved `unknown-prop` / `unknown-event`
-- [ ] Select vs Dropdown roles correct
-- [ ] `MTable` uses `rows` (not `data`)
-- [ ] One-line results use `message`; summary+detail / async use `toast`
-- [ ] Destructive flows use confirm dialogs
-- [ ] MCP **`validate_page`** run when generating a full page (advisory suggestions addressed or consciously waived)
-
-## Craft (all lanes — default pass)
-
-- [ ] Style direction resolved: followed user reference/description, or inferred from clear cues, or **asked** when uncertain — never silent invent; **no preset catalog**
-- [ ] Lane craft from [visual-craft.md](visual-craft.md) applied
-- [ ] If companions ran: still only `M*` + `--m-*`; no second kit ([optional-companions.md](optional-companions.md))
-- [ ] At most one primary filled button in the main viewport
-- [ ] Copy is domain-real; empty / error states say what to do next
-- [ ] No AI-default look clusters unless the user/reference asked for them
-- [ ] No unearned atmosphere: stacked radial+linear washes, purple mesh, frosted glass, neon glow stacks
-- [ ] Motion (if any) is 1–3 intentional moments and follows `useMotion` / `data-m-motion`
-
-## Ops
-
-- [ ] Matches [page-layouts.md](page-layouts.md) block order (snippets composed; golden page optional check only)
-- [ ] `MPage*` used instead of ad-hoc page chrome where applicable
-- [ ] List height: if this is a full-viewport main data list, consider `MPageContent fill` + `MTable fill`; if embedded/short/document-scroll, skip `fill`
-- [ ] Tables not wrapped in decorative `MCard` solely for borders
-- [ ] Filters / toolbar / form actions follow documented patterns
-- [ ] Sider `MMenu` items have icons; status cells use `MStatus` (not decorative `MTag`)
-- [ ] Empty table uses `MEmpty` (or equivalent next-action empty)
-- [ ] No marketing hero bolted onto a CRUD shell
-
-## Account / Flow / System
-
-- [ ] Primary CTA obvious; escape paths present (back / home / support)
-- [ ] Auth errors stay on the form via field `errorMessage` or a token `role="alert"`
-- [ ] Empty uses `MEmpty`; success / HTTP errors use `MResult`
-- [ ] Brand / empty atmosphere follows the **resolved direction** (defaults are flat token shells)
-- [ ] Wizard steps: one job each; actions labeled clearly
-
-## Express
-
-- [ ] Short design plan existed (subject, palette roles, signature)
-- [ ] First viewport has one job
-- [ ] Controls still `M*`; colors/spacing map to `--m-*`
-- [ ] Avoided AI-default looks unless user/reference requested them
-- [ ] Motion limited and gated by `useMotion` / `data-m-motion`
-
-## Tokens, a11y, responsive
-
-- [ ] No raw hex/rgb theme colors in new CSS (control widths OK inline; `color-mix` from `--m-*` OK)
-- [ ] Labels visible; icon buttons have `aria-label`
-- [ ] Usable on a narrow viewport
-- [ ] Focus visible on interactive elements
-
-When MCP is available, contract checks (**`validate_usage`** / **`validate_page`**) are required.
-
-If the project has `pnpm check:colors`, suggest running it after edits.
+# Review checklist
+
+## Contract (all lanes)
+
+- [ ] Only `morya-ui` UI primitives (no second kit)
+- [ ] `morya-ui/styles.css` imported at app/demo entry
+- [ ] `MConfigProvider` at a sensible root when building a full screen
+- [ ] No invented props / events / slots (MCP `get_component` / docs checked)
+- [ ] MCP **`validate_usage`** run; no unresolved `unknown-prop` / `unknown-event`
+- [ ] Select vs Dropdown roles correct
+- [ ] `MTable` uses `rows` (not `data`)
+- [ ] One-line results use `message`; summary+detail / async use `toast`
+- [ ] Destructive flows use confirm dialogs
+- [ ] MCP **`validate_page`** run when generating a full page — **`ok` must be true** (contract); craft suggestions addressed or consciously waived
+- [ ] Same **`brief`** as `map_reference` / `recommend_page` passed into `validate_page` when a reference exists
+
+## Craft (all lanes — default pass)
+
+- [ ] Style direction resolved: followed user reference/description, or inferred from clear cues, or **asked** when uncertain — never silent invent; **no preset catalog**
+- [ ] Reference fidelity: `map_reference` mapping blocks present (filters/table/status/… as required)
+- [ ] Signature shell from `get_style_shells` when Account / Express / Flow need presence
+- [ ] Lane craft from [visual-craft.md](visual-craft.md) applied
+- [ ] If companions ran: still only `M*` + `--m-*`; no second kit ([optional-companions.md](optional-companions.md))
+- [ ] At most one primary filled button in the main viewport
+- [ ] Copy is domain-real; empty / error states say what to do next
+- [ ] Numeric table columns use `align: 'end'` + tabular nums when amounts/counts are shown
+- [ ] No AI-default look clusters unless the user/reference asked for them
+- [ ] No unearned atmosphere: stacked radial+linear washes, purple mesh, frosted glass, neon glow stacks
+- [ ] Motion (if any) is 1–3 intentional moments and follows `useMotion` / `data-m-motion`
+- [ ] Brand differences via theme `--m-*` overrides, not page hex
+
+## Screenshot self-check (optional — when user gave a visual reference)
+
+1. Start the consumer app locally (Vite / Nuxt preview).
+2. Open the generated route; capture the first viewport.
+3. Compare to the reference: block order, primary CTA, density, status treatment — not pixel-perfect chrome.
+4. If blocks are missing, fix via snippets + re-run `validate_page({ brief })`.
+
+If Playwright / `webapp-testing` is available in the project, prefer an automated screenshot; otherwise a manual capture is enough.
+## Ops
+
+- [ ] Matches [page-layouts.md](page-layouts.md) block order (snippets composed; golden page optional check only)
+- [ ] `MPage*` used instead of ad-hoc page chrome where applicable
+- [ ] List height: if this is a full-viewport main data list, consider `MPageContent fill` + `MTable fill`; if embedded/short/document-scroll, skip `fill`
+- [ ] Tables not wrapped in decorative `MCard` solely for borders
+- [ ] Filters / toolbar / form actions follow documented patterns
+- [ ] Sider `MMenu` items have icons; status cells use `MStatus` (not decorative `MTag`)
+- [ ] Empty table uses `MEmpty` (or equivalent next-action empty)
+- [ ] No marketing hero bolted onto a CRUD shell
+
+## Account / Flow / System
+
+- [ ] Primary CTA obvious; escape paths present (back / home / support)
+- [ ] Auth errors stay on the form via field `errorMessage` or a token `role="alert"`
+- [ ] Empty uses `MEmpty`; success / HTTP errors use `MResult`
+- [ ] Brand / empty atmosphere follows the **resolved direction** (defaults are flat token shells)
+- [ ] Wizard steps: one job each; actions labeled clearly
+
+## Express
+
+- [ ] Short design plan existed (subject, palette roles, signature)
+- [ ] First viewport has one job
+- [ ] Controls still `M*`; colors/spacing map to `--m-*`
+- [ ] Avoided AI-default looks unless user/reference requested them
+- [ ] Motion limited and gated by `useMotion` / `data-m-motion`
+
+## Tokens, a11y, responsive
+
+- [ ] No raw hex/rgb theme colors in new CSS (control widths OK inline; `color-mix` from `--m-*` OK)
+- [ ] Labels visible; icon buttons have `aria-label`
+- [ ] Usable on a narrow viewport
+- [ ] Focus visible on interactive elements
+
+When MCP is available, contract checks (**`validate_usage`** / **`validate_page`**) are required.
+
+If the project has `pnpm check:colors`, suggest running it after edits.

package/template/.agents/skills/morya-ui-pages/references/style-presets.md

@@ -1,45 +1,68 @@
-# Style direction (no preset catalog)
-
-Golden pages lock **block order and APIs**. They are **not** the only allowed look. There is **no** named style-preset table (`simple` / `glass` / …). Resolve the look from the **user**, then map onto `M*` + `--m-*`.
-
-## Resolution order (required)
-
-1. **User reference or explicit description (highest)**  
-   Screenshot / mock / existing page / URL / “像 XX”, or clear words (“毛玻璃一点”、“深蓝科技风”).  
-   **Must follow.** Remap to `--m-*` + `M*`. Do not switch kits, do not “improve” into another face.
-
-2. **Clear prompt cues (when not explicit)**  
-   Industry / mood words in the brief → infer and **state your reading in one sentence**.  
-   Decorative glass / neon / full-page gradients only when the prompt clearly asks.
-
-3. **Uncertain → ask (required)**  
-   No reference, vague cues → **ask once** for a short description or a reference.  
-   Do not invent the full look in silence.
-
-4. **Only if user declines**  
-   “你看着办 / 直接写” with still no cues → quiet flat on-token admin face, **say so**, continue.  
-   Never default to aurora / neon / unsolicited glass / cream-serif-terracotta.
-
-MCP: `get_style_direction` / `recommend_page({ style? })` → `styleDirection`.  
-`resolution: "ask"` means **ask the user**, not free-style.
-
-## What `style` means
-
-- Free-text from the user (or a short paraphrase of their reference).  
-- **Not** a preset id.  
-- Optional craft cues for list goldens only: words like `dense` / `compact` / `高密` → `list-page-dense`; `rail` / `品牌侧栏` → `list-page-rail`.
-
-## Anti-defaults (unless user/reference asks)
-
-- Purple→indigo / aurora / mesh washes  
-- Warm cream + serif + terracotta kit  
-- Broadsheet newspaper columns  
-- Unsolicited glassmorphism, neon glow stacks, neumorph on dense tables  
-- Companion “atmosphere” that overrides the user’s words  
-
-## How to apply
-
-1. Mirror golden **structure** via `recommend_page` / `get_golden_page`.  
-2. Apply the resolved direction with tokens + layout/type — see [visual-craft.md](visual-craft.md).  
-3. Run Ops polish when on Operate surfaces.  
-4. Companions deepen **inside** the resolved direction only ([optional-companions.md](optional-companions.md)).
+# Style direction (no preset catalog)
+
+Golden pages lock **block order and APIs**. They are **not** the only allowed look. There is **no** named style-preset table (`simple` / `glass` / …). Resolve the look from the **user**, then map onto `M*` + `--m-*`.
+
+## Resolution order (required)
+
+1. **User reference or explicit description (highest)**  
+   Screenshot / mock / existing page / URL / “像 XX”, or clear words (“毛玻璃一点”、“深蓝科技风”).  
+   **Must follow.** Remap to `--m-*` + `M*`. Do not switch kits, do not “improve” into another face.
+
+2. **Clear prompt cues (when not explicit)**  
+   Industry / mood words in the brief → infer and **state your reading in one sentence**.  
+   Decorative glass / neon / full-page gradients only when the prompt clearly asks.
+
+3. **Uncertain → ask (required)**  
+   No reference, vague cues → **ask once** for a short description or a reference.  
+   Do not invent the full look in silence.
+
+4. **Only if user declines**  
+   “你看着办 / 直接写” with still no cues → quiet flat on-token admin face, **say so**, continue.  
+   Never default to aurora / neon / unsolicited glass / cream-serif-terracotta.
+
+MCP: `get_style_direction` / `recommend_page({ style?, density?, brief? })` → `styleDirection` + optional `referenceMapping`.  
+`map_reference` turns a reference description / required blocks into snippet + shell mapping.  
+`resolution: "ask"` means **ask the user**, not free-style.
+
+## Density (explicit)
+
+Pass `density` to `recommend_page` / `map_reference` — do not rely only on regex in the intent string:
+
+| Value | Effect |
+| --- | --- |
+| `compact` | Prefer `list-filters-dense` / `list-page-dense` cues |
+| `default` | Standard Ops polish |
+| `spacious` | More section gap; avoid packing |
+
+## What `style` means
+
+- Free-text from the user (or a short paraphrase of their reference).  
+- **Not** a preset id.  
+- Optional craft cues for list goldens only: words like `dense` / `compact` / `高密` → `list-page-dense`; `rail` / `品牌侧栏` → `list-page-rail`.
+
+## Reference brief (fidelity)
+
+When the user provides a screenshot / mock / “像 XX”, call **`map_reference`** (or pass `brief` into `recommend_page`) with:
+
+- `description` — what you see (layout, density, primary CTA)
+- `requiredBlocks` — e.g. `filters`, `table`, `status`, `kpi`, `auth`
+- `requiredComponents` — e.g. `Table`, `Status`
+- `density` / `primaryAction` when visible
+
+Then compose **only** via returned `mapping[].snippetId`. Pass the **same brief** to `validate_page` so missing blocks fail as contract issues.
+
+## Anti-defaults (unless user/reference asks)
+
+- Purple→indigo / aurora / mesh washes  
+- Warm cream + serif + terracotta kit  
+- Broadsheet newspaper columns  
+- Unsolicited glassmorphism, neon glow stacks, neumorph on dense tables  
+- Companion “atmosphere” that overrides the user’s words  
+
+## How to apply
+
+1. Map reference → snippets (`map_reference` / `recommend_page.referenceMapping`).  
+2. Apply a signature shell when Account / Express / Flow need presence (`get_style_shells`).  
+3. Brand color via theme `--m-color-primary` (DESIGN.md § 主题覆盖), not page hex.  
+4. Run Ops polish when on Operate surfaces.  
+5. Companions deepen **inside** the resolved direction only ([optional-companions.md](optional-companions.md)).

package/template/.agents/skills/morya-ui-pages/references/surfaces.md

@@ -1,91 +1,91 @@
-# Surface taxonomy
-
-Pick a lane, then a surface. Prefer project golden pages for **Ops**; use the recipes below for everything else. Always implement interactive controls with `morya-ui`.
-
-## Ops (admin / console)
-
-| Surface | Job | Compose from |
-| --- | --- | --- |
-| List | Scan, filter, act on many rows | Golden list + [page-layouts.md](page-layouts.md); **create/edit with ≤~8 fields → `MDialog` on the list** |
-| Form | Create / edit one entity as a **dedicated page** | Golden form — only when multi-section, many fields, or user asked for an independent form route |
-| Dashboard | Orient + jump to work | Golden dashboard |
-| Detail | Read-heavy record + secondary actions | `MPageHeader` + sections via `MCard`/`MPageSection`; edit via `MDialog` / `MDrawer` (prefer over a second form route) |
-| Settings | Grouped preferences | Narrow `MPageContent` + stacked `MPageSection` / `MTabs` + `MForm` |
-| Hybrid list | List + drawer/dialog | **Default Ops CRUD pattern**: list golden + `MDialog`/`MDrawer` form |
-
-## Account
-
-| Surface | Job | Recipe |
-| --- | --- | --- |
-| Login / register | Authenticate with trust | Golden: MCP `get_golden_page` `login-page` — split brand + `MForm` (`MInput`, `MInputPassword`); form-level errors via token `role="alert"` (not Toast). Brand wash: [visual-craft.md](visual-craft.md) § Atmosphere |
-| Invite / accept | Join org | Same shell; show org name clearly |
-| Forgot / reset | Recover access | Short form + success state with next step |
-| Profile / account | Edit self | Settings-like sections; avatar via `MAvatar` |
-
-Keep credential forms quiet: one primary CTA, clear labels, no decorative noise beside the brand panel.
-
-## Flow
-
-| Surface | Job | Recipe |
-| --- | --- | --- |
-| Empty state | Invite first action | Golden: MCP `get_golden_page` `empty-state` — `MEmpty` + primary/secondary `MButton` in `#extra`; dashed shell + radial wash from visual-craft |
-| Onboarding | Teach the product path | `MStepper` or paced cards; one decision per step; finish → Ops home |
-| Wizard | Multi-step create | `MStepper` + `MForm` per step + sticky actions (`上一步` / `下一步` / `提交`) |
-| Success / result | Confirm completion | `MResult status="success"` / `error` + `#footer` next actions (`查看详情` / `返回列表`); same shell idea as `result-page` |
-
-Copy must tell the user **what to do next**, not celebrate the system.
-
-## System
-
-| Surface | Job | Recipe |
-| --- | --- | --- |
-| Permission denied | Explain + escape | Golden: MCP `get_golden_page` `result-page` — `MResult status="403"` + `#footer` (not `#extra`) |
-| 404 / not found | Reorient | `MResult status="404"` + `返回首页` / `返回上一页` (mirror `result-page` shell) |
-| Maintenance / error | Honest status | `MResult status="500"`; what happened + retry + support. Persistent form errors: field `errorMessage` or a token `role="alert"`, not `<MMessage>` as an alert |
-
-Avoid witty 404 essays that hide the exit paths.
-
-## Express (marketing / public)
-
-Use when the brief is landing, pricing, launch, or docs marketing — **not** for Ops CRUD shells.
-
-| Surface | Job | Recipe |
-| --- | --- | --- |
-| Landing | Convert / explain product | Golden: MCP `get_golden_page` `landing-page` — one-job hero; CTAs → `MButton`; chips → `MTag`; FAQ → `MAccordion` |
-| Pricing | Choose a plan | Clear plan cards (`MCard`) + primary CTA; highlight recommended plan without clutter |
-| Feature showcase | Prove capability | Alternating media/copy; live `M*` demo only if lightweight |
-| Docs marketing chrome | Frame documentation | Header + nav using `M*` where suitable; content area stays readable |
-
-Before coding Express: short design plan in [visual-craft.md](visual-craft.md). Map colors to `--m-*` / theme overrides; do not paste a second kit.
-
-**Anti-patterns for Express:** inset hero cards instead of a full-bleed thesis; pill-stat strips in the first viewport; purple aurora / cream-terracotta / broadsheet / unsolicited glass-neon when the user did not ask.
-
-## Overlay
-
-When the dialog/drawer **is** the task:
-
-| Surface | Recipe |
-| --- | --- |
-| Edit / create dialog | `MDialog` + compact `MForm` + footer actions |
-| Detail drawer | `MDrawer` + header + sections + optional edit |
-| Confirm | `MConfirmDialog` / `MConfirmPopup` — do not reinvent |
-| Command menu | `MCommandMenu` for keyboard-first jump / actions |
-
-Host page stays stable; focus management comes from the overlay component.
-
-## Lane mixing
-
-| Ask | Treat as |
-| --- | --- |
-| “后台列表 + 好看一点” | Ops + ask once what “好看” means, or follow any reference they give |
-| “像附件截图一样” | Reference-first style resolution; still M* + `--m-*` |
-| “登录页有品牌感” | Account + Express craft on brand panel only |
-| “产品官网” | Express; Ops patterns do not apply |
-| “空状态设计精致一点” | Flow empty + visual-craft signature (one risk) |
-
-## MCP hints
-
-- Ops whole page: `recommend_page({ style? })` → `get_golden_page` → apply `styleDirection` / reference
-- Style: `get_style_direction` (no preset catalog)
-- Section: `get_page_snippet`
-- Any lane: `search` / `get_component` before unfamiliar APIs
+# Surface taxonomy
+
+Pick a lane, then a surface. Prefer project golden pages for **Ops**; use the recipes below for everything else. Always implement interactive controls with `morya-ui`.
+
+## Ops (admin / console)
+
+| Surface | Job | Compose from |
+| --- | --- | --- |
+| List | Scan, filter, act on many rows | Golden list + [page-layouts.md](page-layouts.md); **create/edit with ≤~8 fields → `MDialog` on the list** |
+| Form | Create / edit one entity as a **dedicated page** | Golden form — only when multi-section, many fields, or user asked for an independent form route |
+| Dashboard | Orient + jump to work | Golden dashboard |
+| Detail | Read-heavy record + secondary actions | `MPageHeader` + sections via `MCard`/`MPageSection`; edit via `MDialog` / `MDrawer` (prefer over a second form route) |
+| Settings | Grouped preferences | Narrow `MPageContent` + stacked `MPageSection` / `MTabs` + `MForm` |
+| Hybrid list | List + drawer/dialog | **Default Ops CRUD pattern**: list golden + `MDialog`/`MDrawer` form |
+
+## Account
+
+| Surface | Job | Recipe |
+| --- | --- | --- |
+| Login / register | Authenticate with trust | Golden: MCP `get_golden_page` `login-page` — split brand + `MForm` (`MInput`, `MInputPassword`); form-level errors via token `role="alert"` (not Toast). Brand wash: [visual-craft.md](visual-craft.md) § Atmosphere |
+| Invite / accept | Join org | Same shell; show org name clearly |
+| Forgot / reset | Recover access | Short form + success state with next step |
+| Profile / account | Edit self | Settings-like sections; avatar via `MAvatar` |
+
+Keep credential forms quiet: one primary CTA, clear labels, no decorative noise beside the brand panel.
+
+## Flow
+
+| Surface | Job | Recipe |
+| --- | --- | --- |
+| Empty state | Invite first action | Golden: MCP `get_golden_page` `empty-state` — `MEmpty` + primary/secondary `MButton` in `#extra`; dashed shell + radial wash from visual-craft |
+| Onboarding | Teach the product path | `MStepper` or paced cards; one decision per step; finish → Ops home |
+| Wizard | Multi-step create | `MStepper` + `MForm` per step + sticky actions (`上一步` / `下一步` / `提交`) |
+| Success / result | Confirm completion | `MResult status="success"` / `error` + `#footer` next actions (`查看详情` / `返回列表`); same shell idea as `result-page` |
+
+Copy must tell the user **what to do next**, not celebrate the system.
+
+## System
+
+| Surface | Job | Recipe |
+| --- | --- | --- |
+| Permission denied | Explain + escape | Golden: MCP `get_golden_page` `result-page` — `MResult status="403"` + `#footer` (not `#extra`) |
+| 404 / not found | Reorient | `MResult status="404"` + `返回首页` / `返回上一页` (mirror `result-page` shell) |
+| Maintenance / error | Honest status | `MResult status="500"`; what happened + retry + support. Persistent form errors: field `errorMessage` or a token `role="alert"`, not `<MMessage>` as an alert |
+
+Avoid witty 404 essays that hide the exit paths.
+
+## Express (marketing / public)
+
+Use when the brief is landing, pricing, launch, or docs marketing — **not** for Ops CRUD shells.
+
+| Surface | Job | Recipe |
+| --- | --- | --- |
+| Landing | Convert / explain product | Golden: MCP `get_golden_page` `landing-page` — one-job hero; CTAs → `MButton`; chips → `MTag`; FAQ → `MAccordion` |
+| Pricing | Choose a plan | Clear plan cards (`MCard`) + primary CTA; highlight recommended plan without clutter |
+| Feature showcase | Prove capability | Alternating media/copy; live `M*` demo only if lightweight |
+| Docs marketing chrome | Frame documentation | Header + nav using `M*` where suitable; content area stays readable |
+
+Before coding Express: short design plan in [visual-craft.md](visual-craft.md). Map colors to `--m-*` / theme overrides; do not paste a second kit.
+
+**Anti-patterns for Express:** inset hero cards instead of a full-bleed thesis; pill-stat strips in the first viewport; purple aurora / cream-terracotta / broadsheet / unsolicited glass-neon when the user did not ask.
+
+## Overlay
+
+When the dialog/drawer **is** the task:
+
+| Surface | Recipe |
+| --- | --- |
+| Edit / create dialog | `MDialog` + compact `MForm` + footer actions |
+| Detail drawer | `MDrawer` + header + sections + optional edit |
+| Confirm | `MConfirmDialog` / `MConfirmPopup` — do not reinvent |
+| Command menu | `MCommandMenu` for keyboard-first jump / actions |
+
+Host page stays stable; focus management comes from the overlay component.
+
+## Lane mixing
+
+| Ask | Treat as |
+| --- | --- |
+| “后台列表 + 好看一点” | Ops + ask once what “好看” means, or follow any reference they give |
+| “像附件截图一样” | Reference-first style resolution; still M* + `--m-*` |
+| “登录页有品牌感” | Account + Express craft on brand panel only |
+| “产品官网” | Express; Ops patterns do not apply |
+| “空状态设计精致一点” | Flow empty + visual-craft signature (one risk) |
+
+## MCP hints
+
+- Ops whole page: `recommend_page({ style? })` → `get_golden_page` → apply `styleDirection` / reference
+- Style: `get_style_direction` (no preset catalog)
+- Section: `get_page_snippet`
+- Any lane: `search` / `get_component` before unfamiliar APIs