monomind 1.16.6 → 1.16.8

package/packages/@monomind/cli/.claude/skills/monodesign/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: monodesign
+description: "Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, research users, build a component system, generate design images, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, reusable design systems, tokens, brand identity, visual storytelling, UX research, usability testing, image generation prompts, and inclusive representation. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks."
+version: 1.1.0
+argument-hint: "[command] [target]"
+user-invocable: true
+triggers:
+  - /monodesign
+  - /design
+  - /frontend-design
+  - design the ui
+  - redesign this
+  - improve the ui
+  - make this look better
+  - add polish
+  - audit the design
+  - critique this ui
+  - animate this component
+  - fix the layout
+  - colorize this
+  - typeset this
+  - design system
+  - component system
+  - component library
+  - ui tokens
+  - antipattern
+  - anti-pattern
+  - design review
+  - ux review
+  - visual design
+  - brand identity
+  - brand strategy
+  - brand voice
+  - visual storytelling
+  - ux research
+  - user research
+  - usability testing
+  - user persona
+  - user journey
+  - image prompt
+  - generate image
+  - hero image
+  - design image
+  - inclusive design
+  - diverse imagery
+  - whimsy
+  - delight
+  - brand personality
+  - css architecture
+  - theme toggle
+  - dark mode
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - WebSearch
+  - WebFetch
+license: Apache 2.0. Based on Anthropic's frontend-design skill and the Impeccable design system. See reference/NOTICE.md for attribution.
+---
+
+Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
+
+## Setup (non-optional)
+
+Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
+
+| Gate | Required check | If fail |
+|---|---|---|
+| Context | PRODUCT.md and DESIGN.md are read from the project root (or `docs/`, `.agents/context/`). | Read both files before continuing. |
+| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `/monodesign teach`, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. |
+| Command | The matching command reference is loaded when a sub-command is used. | Load `reference/<command>.md` before continuing. |
+| Craft | `/monodesign craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `/monodesign shape` and wait for explicit brief confirmation. |
+| Mutation | All active gates above pass. | Do not edit project files yet. |
+
+### 1. Context gathering
+
+Two files, case-insensitive. Look at the project root first, then fall back to `.agents/context/` and `docs/`.
+
+- **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles.
+- **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components.
+
+Read both files directly using the Read tool. If both are already in this session's context, don't re-read them.
+
+If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `/monodesign teach`, then resume the user's original task with the fresh context. If the original task was `/monodesign craft`, resume into `/monodesign shape` before any implementation work.
+
+If DESIGN.md is missing: nudge once per session (*"Run `/monodesign document` for more on-brand output"*), then proceed.
+
+### 2. Register
+
+Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product).
+
+Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus; (3) `register` field in PRODUCT.md. First match wins.
+
+Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both.
+
+## Shared design laws
+
+Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. Claude is capable of extraordinary work. Don't hold back.
+
+### Color
+
+- Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish.
+- Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).
+- Pick a **color strategy** before picking colors. Four steps on the commitment axis:
+  - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism.
+  - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
+  - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
+  - **Drenched**: the surface IS the color. Brand heroes, campaign pages.
+- The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.
+
+### Theme
+
+Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."
+
+Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does.
+
+"Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.
+
+### Typography
+
+- Cap body line length at 65–75ch.
+- Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.
+
+### Layout
+
+- Vary spacing for rhythm. Same padding everywhere is monotony.
+- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
+- Don't wrap everything in a container. Most things don't need one.
+
+### Motion
+
+- Don't animate CSS layout properties.
+- Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.
+- Always respect `prefers-reduced-motion`.
+
+### Absolute bans
+
+Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
+
+- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
+- **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.
+- **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
+- **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché.
+- **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly.
+- **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first.
+
+### Copy
+
+- Every word earns its place. No restated headings, no intros that repeat the title.
+- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
+
+### The AI slop test
+
+If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
+
+**Category-reflex check.** Run at two altitudes:
+- **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal"), it's the first training-data reflex. Rework.
+- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families.
+
+## Antipattern Detection
+
+Before finalizing any design, run the antipattern detector. It checks for 46 known design antipatterns across two categories:
+
+- **slop** — AI tells that signal lack of intentional design (purple palettes, side-tabs, identical card grids, italic-serif heroes, overused fonts)
+- **quality** — Design principle violations (spacing, hierarchy, readability, contrast, motion, typography)
+
+To run detection on HTML/CSS files:
+```bash
+monomind design detect <file-or-dir>
+```
+
+Or use `npx impeccable detect` directly as an alternative:
+```bash
+npx impeccable detect <file-or-dir>
+```
+
+If `impeccable` is not installed:
+```bash
+npm install -g impeccable
+# or use npx:
+npx impeccable@latest detect <file-or-dir>
+```
+
+For machine-readable output (e.g. CI pipelines):
+```bash
+monomind design detect --json <file-or-dir>
+```
+
+For the full antipattern catalog with detection rules and remediation, see [reference/antipatterns-catalog.md](reference/antipatterns-catalog.md).
+
+## OKLCH Palette Seed
+
+Before composing a brand palette, seed the anchor color from the curated OKLCH library (129 hand-curated seeds):
+
+```bash
+monomind design palette                              # random seed (hue-zone weighted)
+monomind design palette --from "my-product-name"    # deterministic seed from product name
+monomind design palette --id seed-021               # specific seed by ID
+monomind design palette --json                      # machine-readable output
+```
+
+Each seed returns:
+- **Anchor color** — the single OKLCH value your primary brand color derives from
+- **Mood** — one evocative phrase describing the register this hue inhabits
+- **Strategy** — a concrete composition hint (bg choice, accent pairing, surface treatment)
+
+The seed is the start, not the recipe. Compose the full 5-role palette (bg, surface, ink, accent, muted) using your brief and the color-strategy guidance in this skill. The same seed can produce a dark-mode jazz club or a light-mode clinical brand depending on what the brief calls for.
+
+## UX Quality Gate
+
+Antipatterns catch aesthetic and visual issues. For implementation-level UX quality — accessibility, touch interaction, form feedback, navigation patterns, animation timing, performance — load:
+
+- [reference/ux-rules.md](reference/ux-rules.md) — 170+ rules across 10 categories, priority-ordered. Use during `audit`, `critique`, and `review` workflows.
+- [reference/pre-delivery-checklist.md](reference/pre-delivery-checklist.md) — final-gate checklist before shipping. Run before declaring any UI complete.
+
+## Design System & Brand
+
+For building or auditing token systems and brand identity:
+
+- [reference/token-architecture.md](reference/token-architecture.md) — three-layer token system (primitive → semantic → component). Load during `extract` and `document` workflows when building design systems.
+- [reference/component-specs.md](reference/component-specs.md) — Button, Input, Card, Badge, Alert, Dialog, and Table: variants, sizes, states, and anatomy.
+- [reference/component-states.md](reference/component-states.md) — interactive state system: state priority, focus ring CSS, disabled/loading/error patterns, and full ARIA attribute reference.
+- [reference/brand-workflow.md](reference/brand-workflow.md) — brand → tokens → CSS pipeline, visual identity spec, and brand consistency audit. Load for brand identity work.
+
+## Copy
+
+For UI copy, labels, and error messages:
+
+- [reference/copy-formulas.md](reference/copy-formulas.md) — PAS, AIDA, FAB, BAB, and Cost of Inaction frameworks mapped to UI surfaces (empty states, CTAs, error messages, confirmations, onboarding). Load during `clarify` and `harden` workflows.
+
+### Design Token System
+
+Use OKLCH-based tokens for every new design. Reference system:
+
+```css
+:root {
+  /* Typography */
+  --font-display: 'Cormorant Garamond', Georgia, serif;
+  --font-body: 'Instrument Sans', system-ui, sans-serif;
+  --font-mono: 'Space Grotesk', monospace;
+
+  /* Spacing (8px base grid) */
+  --space-xs: 8px;
+  --space-sm: 16px;
+  --space-md: 24px;
+  --space-lg: 32px;
+  --space-xl: 48px;
+  --space-2xl: 80px;
+  --space-3xl: 120px;
+
+  /* Motion */
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);       /* Primary — expo-out */
+  --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Sharper variant */
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+  --duration-fast: 0.15s;    /* Color/opacity */
+  --duration-base: 0.3s;     /* Default transforms */
+  --duration-slow: 0.6s;     /* Orchestrated entrances */
+  --duration-slower: 0.8s;
+  --duration-slowest: 1.2s;
+
+  /* Colors (OKLCH) */
+  --color-ink: oklch(10% 0 0);
+  --color-paper: oklch(98% 0 0);
+  --color-cream: oklch(96% 0.005 350);    /* Warm off-white bg */
+  --color-charcoal: oklch(25% 0 0);
+  --color-ash: oklch(55% 0 0);
+  --color-mist: oklch(92% 0 0);
+  --color-accent: oklch(60% 0.25 350);          /* Editorial Magenta */
+  --color-accent-hover: oklch(52% 0.25 350);
+  --color-accent-dim: oklch(60% 0.25 350 / 0.15);
+  --color-accent-soft: oklch(60% 0.25 350 / 0.25);
+}
+```
+
+### Shadow System
+
+```css
+/* Soft hover lift */
+box-shadow: 0 4px 24px -4px rgba(0,0,0,0.12), 0 1px 3px rgba(0,0,0,0.06);
+
+/* Lifted card */
+box-shadow: 0 20px 40px rgba(0,0,0,0.08);
+
+/* Accent glow (rare — accent-tinted) */
+box-shadow: 0 20px 60px oklch(60% 0.25 350 / 0.15);
+```
+
+Shadows max at 0.15 alpha. No heavy drop shadows.
+
+## Commands
+
+| Command | Category | Description | Reference |
+|---|---|---|---|
+| `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) |
+| `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) |
+| `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) |
+| `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
+| `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
+| `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
+| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) |
+| `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
+| `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
+| `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
+| `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) |
+| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) |
+| `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) |
+| `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) |
+| `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) |
+| `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) |
+| `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) |
+| `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
+| `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
+| `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
+| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) |
+| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
+| `live` | Iterate | Visual variant mode: iterate on elements in the browser | [reference/live.md](reference/live.md) |
+| `components [target]` | Build | Build component systems, token foundations, theme toggles | [reference/component-system.md](reference/component-system.md) |
+| `research [target]` | Evaluate | UX research, usability testing, personas, journey mapping | [reference/ux-research.md](reference/ux-research.md) |
+| `images [target]` | Build | Generate design images, hero photography, inclusive prompts | [reference/image-prompts.md](reference/image-prompts.md) |
+| `hooks [action]` | Config | Manage the impeccable design detector hook per project | [reference/hooks.md](reference/hooks.md) |
+| `detect [file-or-dir]` | Evaluate | Run design anti-pattern detection on HTML/CSS files | (inline) |
+| `palette [--from name]` | Build | Seed a brand palette from the OKLCH library (129 seeds) | (inline) |
+
+### Routing rules
+
+1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
+2. **First word matches a command**: load its reference file (`Read` the `reference/<command>.md` file) and follow its instructions. Everything after the command name is the target.
+3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
+
+Setup (context gathering, register) runs first; sub-commands don't re-invoke `/monodesign`.
+
+If the first word is `craft`, setup still runs first, but `reference/craft.md` owns the rest of the flow.

package/packages/@monomind/cli/.claude/skills/monodesign/adapt.md

@@ -0,0 +1,53 @@
+---
+name: monodesign-adapt
+description: Adapt an existing design to a new context — different device, market, audience, brand, or constraint — while preserving what works and redesigning what doesn't transfer.
+type: design-sub-command
+argument-hint: "[source design] [→ target context]"
+user-invocable: true
+---
+
+# Monodesign: Adapt
+
+Adapt an existing design to a new context. Read `reference/adapt.md` from the monodesign skill directory for the full protocol.
+
+## Adaptation Contexts
+
+**Device / viewport adaptation**
+- Desktop → mobile: not just scaling down, but rethinking information priority and touch targets
+- Mobile → desktop: not just scaling up, but leveraging the additional space meaningfully
+- Read `reference/responsive-design.md` for the full responsive protocol
+
+**Brand adaptation**
+- Same product, updated visual identity
+- Preserve brand equity (recognition, trust) while updating the expression
+- Map old tokens → new tokens; don't just swap colors
+
+**Market/locale adaptation**
+- Text expansion/contraction for translated content (German strings are ~30% longer than English)
+- RTL adaptation: mirror layouts, flip directional icons, adjust text alignment
+- Cultural color associations (white = mourning in some cultures, luck in others)
+
+**Audience adaptation**
+- Consumer → enterprise: more density, more data, less marketing
+- Expert → beginner: more guidance, less assumed knowledge, more white space
+- Accessibility adaptation: meeting WCAG AAA, or serving a specific disability need
+
+**Constraint adaptation**
+- High performance: remove animations, reduce image weight, simplify components
+- Reduced-color: grayscale or high-contrast mode
+- Print: remove interactive elements, adjust typography for print
+
+## Adaptation Protocol
+
+1. **Document what transfers**: list everything from the original that works in the new context
+2. **Document what doesn't transfer**: list what breaks, looks wrong, or becomes inaccessible
+3. **Identify the preservation priorities**: what is most essential to carry over (brand recognition, key interactions, data structures)?
+4. **Redesign for the new context**: don't just modify — actively ask "what would we design if we started here?"
+5. **Validate against the target context**: test on the actual device/locale/audience constraint
+
+## Output
+
+The adapted design with:
+- Changed CSS/tokens documented in comments
+- Preserved brand tokens unchanged
+- New context-specific overrides in a separate file or scope

package/packages/@monomind/cli/.claude/skills/monodesign/agents/monodesign-asset-producer.md

@@ -0,0 +1,100 @@
+---
+name: monodesign-asset-producer
+codex-name: monodesign_asset_producer
+description: Produces clean reusable raster assets from approved monodesign mock references without redesigning the direction.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: inherit
+effort: medium
+max-turns: 12
+nickname-candidates:
+  - Asset Plate
+  - Clean Plate
+  - Crop Cutter
+---
+
+# Monodesign Asset Producer
+
+You are the asset production agent for monodesign craft.
+
+Your job is production cleanup, not new art direction. Work only from the approved mock, assigned crops, contact sheets, and constraints the parent agent gives you. The assets you create will be used to build a real site, so treat every raster as a raw ingredient that HTML, CSS, SVG, canvas, and component code will compose.
+
+## Core Rule
+
+Do not redesign. Preserve the reference's visual role, silhouette, palette, lighting, material, texture, camera angle, and composition unless the parent explicitly asks for a change. Preserve perspective only when it belongs to the object or scene itself; if CSS should create the card transform, shadow, rounded clipping, border, or layout, remove that presentation chrome from the raster.
+
+## Input Contract
+
+Expect:
+
+- Approved mock path or screenshot reference.
+- Crop paths or a contact sheet with crop ids.
+- Output directory.
+- Required dimensions, format, transparency needs, and avoid list.
+- Notes on what should remain semantic HTML/CSS/SVG instead of raster.
+
+If the source mock is attached but has no filesystem path, use it for visual planning. Ask for a path only before cropping or writing assets.
+
+Use defaults unless contradicted:
+
+- `.webp` for opaque photos, backgrounds, and textures.
+- `.png` for transparent cutouts, seals, tickets, and illustrations.
+- Target production size or at least 2x display size when dimensions are known. Do not use small full-page mock crop size as the default shipping size.
+- Remove UI text, navigation, buttons, labels, and body copy by default.
+- Keep physical marks only when the parent says they are part of the asset.
+- Remove letterboxing, empty padding, baked card corners, borders, shadows, caption bands, and layout background unless the parent says those pixels are intrinsic to the asset.
+- Keep the final assets directory clean: only files the build will consume belong there. Put source crops, reference crops, masks, and contact sheets in a sibling `_sources`, `sources`, or review folder.
+
+Ask blockers once, globally. Missing source path/crops or output directory blocks production. Exact dimensions, compression targets, retina variants, and format preferences do not block; choose defaults and report them.
+
+## Workflow
+
+1. Inventory the full approved mock or every assigned crop.
+2. Put each visual role in exactly one bucket:
+   - `produce`: needs generation, image editing, cleanup, cutout work, or a clean plate before it can ship.
+   - `direct`: can ship as a crop, format conversion, compression pass, or sourced replacement with no generative cleanup.
+   - `semantic`: build in HTML/CSS/SVG/canvas, no raster output.
+3. Treat full-page mock crops as references, not production-resolution source assets. Put a role in `direct` only when the provided source is already a clean, sufficiently large source asset with no semantic text or presentation chrome.
+4. Give the parent an execution order for the `produce` bucket.
+5. For produced assets, choose the least inventive strategy: image-to-image clean plate, faithful regeneration from crop reference, transparent cutout, texture/pattern reconstruction, stock/project source, or semantic HTML/CSS/SVG recommendation if raster is wrong.
+6. Treat every crop as binding reference. Use the image generation capability available in the current environment (e.g. native image_gen, `/monodesign` image-prompts patterns) when generation or editing is needed.
+7. Remove baked-in UI text, navigation, buttons, body copy, and mock chrome unless the text is part of the asset.
+8. Think through the final DOM/CSS representation before generating. If CSS will own radius, clipping, shadows, borders, perspective, responsive cropping, captions, or card frames, do not bake those into the bitmap.
+9. Save outputs non-destructively in the requested project directory.
+10. Compare each output against its source crop. If a review/QA tool is available, run it before the final manifest, then retry each major/fatal finding once before finalizing.
+
+Use `direct` only for provided source assets that can already ship after crop tightening, conversion, compression, or naming. Do not ship a small crop from the full-page mock as `direct` just because it looks close.
+
+Use `texture/pattern extraction` only when the source region is already clean enough to sample as texture. If UI, cards, labels, headings, body copy, or footer chrome must be removed to make a reusable texture or background, classify it as crop-derived cleanup or clean-plate work.
+
+Use `semantic` for dashboards, charts, controls, screenshots of whole UI sections, data widgets, card chrome, app frames, icon toolbars, logos, wordmarks, and anything the final implementation can render crisply in HTML/CSS/SVG/canvas. Only ship a screenshot raster when the parent explicitly says the screenshot itself is the final asset.
+
+Semantic does not mean ignored. For every semantic role, write a concrete implementation handoff for the parent craft agent: name the DOM/component layers, CSS-owned visual treatment, SVG/canvas/icon-library pieces, responsive behavior, and which nearby produced raster assets it should compose with. For logos and icons, prefer inline SVG/vector or icon-library implementation unless the parent provides a production logo raster.
+
+For transparency, prefer true alpha output when the tool supports it. If it does not, request a flat chroma-key background in a color that cannot appear in the subject, then post-process that color to alpha before shipping a PNG/WebP. Do not ship the keyed background as the final asset.
+
+## Prompt Pattern
+
+Use this shape for image-to-image work:
+
+```text
+Use the provided crop as the approved visual reference.
+Recreate the same asset as a clean reusable production image at the target component aspect ratio and at least 2x display resolution.
+Preserve silhouette, object/scene perspective, camera angle, palette, lighting, material, texture, and visual role.
+Remove baked-in UI copy, navigation, buttons, labels, body text, watermarks, and mock chrome unless explicitly part of the asset.
+Remove letterboxing, padding, card borders, rounded clipping, CSS shadows, perspective transforms, caption bands, and layout backgrounds that the implementation should create in code.
+Do not add new objects. Do not change the concept. Do not redesign the composition.
+```
+
+For transparent cutouts, use a chroma-key workflow (flat background in a color that cannot appear in the subject, then post-process to alpha) unless the parent explicitly authorizes native transparency.
+
+## Output Contract
+
+Return a complete manifest, grouped by `produce`, `direct`, and `semantic`. For each asset include: `id`, `source_crop`, `output_path` when applicable, `strategy`, `prompt_used` when applicable, `dimensions`, `format`, `transparency`, `deviations`, and `qa_status`.
+
+For each semantic row include `id`, `implementation`, `notes`, and `qa_status`. The `implementation` must be a concrete build handoff, not a short explanation that no asset was produced. It should name the likely HTML/CSS/SVG/canvas/icon/component pieces and the visual responsibilities that code owns.
+
+`qa_status` must be `accepted`, `needs_parent_review`, or `blocked`. Use `accepted` only after visual comparison passes. Use `needs_parent_review` for cut-off subjects, unwanted borders or rounded-card chrome, letterboxing, baked semantic text, low-resolution output, perspective that should have been CSS, missing transparency, or drift from the crop. Use `blocked` when inputs, permissions, image capability, or asset source quality prevent a credible result.
+
+End with `execution_order`, `blockers`, and `assumptions` sections. Keep blockers global and minimal. Do not repeat missing inputs in every row; per-asset rows should carry only asset-specific risks or decisions.
+
+Do not modify implementation code. Do not edit the approved mock. Do not produce final page copy. The parent craft agent owns implementation and final mock fidelity.

package/packages/@monomind/cli/.claude/skills/monodesign/animate.md

@@ -0,0 +1,65 @@
+---
+name: monodesign-animate
+description: Add intentional, purposeful motion to interfaces — scroll-driven reveals, state transitions, micro-interactions, page transitions, and advanced motion effects using CSS and JS libraries.
+type: design-sub-command
+argument-hint: "[target component or page]"
+user-invocable: true
+---
+
+# Monodesign: Animate
+
+Add intentional motion to interfaces. Every animation must earn its place. Read `reference/animate.md` and `reference/motion-design.md` from the monodesign skill directory for the full protocol.
+
+## Motion Rules (non-negotiable)
+
+- **Do not animate CSS layout properties** (width, height, padding, margin, top, left) unless truly needed — causes layout thrashing
+- **Ease out with exponential curves**: ease-out-quart / quint / expo. No bounce, no elastic
+- **`prefers-reduced-motion` is not optional** — every animation needs a fallback (typically crossfade or instant transition)
+- **Reveal animations must enhance an already-visible default** — don't gate content visibility on a class-triggered transition; content ships blank if the transition doesn't fire
+- Use libraries for advanced motion (motion.dev, GSAP, anime.js, Lenis for smooth scroll)
+- Staggering items in one list is legitimate — uniform section fades on every section are not
+
+## Motion Premium Materials
+
+Not just transform/opacity. When they materially improve the effect and stay smooth:
+- Blur, backdrop-filter
+- clip-path, mask
+- shadow/glow transitions
+- View Transitions API for page/component morphing
+
+## Animation Categories
+
+**Entrance/reveal** — elements entering the viewport or DOM. Use IntersectionObserver + CSS transitions. Keep under 400ms. Stagger lists (50–80ms per item).
+
+**State transitions** — loading, success, error, empty. Should feel instantaneous for actions the user triggered. Confirmation animations: 200–400ms.
+
+**Micro-interactions** — button press feedback, toggle switches, checkbox check marks. Sub-200ms. Should feel physical.
+
+**Page/route transitions** — View Transitions API when available. Morphing elements from one state to another feels cinematic without heavy libraries.
+
+**Ambient/background** — scroll-driven effects, parallax, cursor-tracking. Use `animation-timeline: scroll()` for pure CSS scroll-driven. Performance-test before shipping.
+
+## Implementation Pattern
+
+```css
+/* Always start with the safe version */
+@media (prefers-reduced-motion: no-preference) {
+  .element {
+    animation: slide-in 400ms ease-out-quart both;
+  }
+}
+
+/* Explicit reduced-motion fallback */
+@media (prefers-reduced-motion: reduce) {
+  .element {
+    animation: fade-in 200ms ease both;
+  }
+}
+```
+
+## Verify in Browser
+
+Use browser automation to watch the animation play. Check:
+- Does it look smooth at 60fps?
+- Does the timing feel right (not too fast, not too slow)?
+- Does the reduced-motion version make sense?

package/packages/@monomind/cli/.claude/skills/monodesign/audit.md

@@ -0,0 +1,89 @@
+---
+name: monodesign-audit
+description: Run systematic technical quality checks across accessibility, performance, theming, motion, and interaction — generate a scored report with specific findings. Documents issues; does not fix them.
+type: design-sub-command
+argument-hint: "[target file, route, or component]"
+user-invocable: true
+---
+
+# Monodesign: Audit
+
+Run systematic **technical** quality checks and generate a comprehensive scored report. This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. **Does not fix issues** — documents them for other commands to address.
+
+Read `reference/audit.md` from the monodesign skill directory for the full scoring rubric.
+
+## Diagnostic Scan — 5 Dimensions (score 0–4 each)
+
+### 1. Accessibility (A11y)
+- Contrast ratios (≥4.5:1 body, ≥3:1 large text)
+- ARIA: interactive elements with proper roles, labels, states
+- Keyboard navigation: focus indicators, logical tab order
+- Semantic HTML: heading hierarchy, landmarks, divs vs. buttons
+- Alt text quality; form labels; error messaging
+
+### 2. Performance
+- Layout thrashing (read/write layout properties in loops)
+- Expensive animations (layout-property animation, unbounded blur/filter)
+- Missing optimization (lazy loading, unoptimized assets, missing will-change)
+- Bundle size: unnecessary imports, unused dependencies
+- Unnecessary re-renders, missing memoization
+
+### 3. Theming
+- Hard-coded colors not using design tokens
+- Broken dark mode: missing variants, poor contrast
+- Inconsistent token usage; values that don't update on theme change
+
+### 4. Motion
+- Violations of `prefers-reduced-motion`
+- Inappropriate motion: layout-property animation, bounce/elastic
+- Reveal animations that gate content visibility (content ships blank if transition fails)
+- Motion that adds no information (hover-scale on non-interactive elements)
+
+### 5. Interaction
+- Dropdown clipping (inside overflow:hidden — use popover API or position:fixed)
+- Missing hover/focus/active/disabled states
+- Form UX: validation feedback, error recovery, submission state
+
+## Scoring
+
+| Score | Meaning |
+|---|---|
+| 0 | Broken / inaccessible |
+| 1 | Major gaps |
+| 2 | Partial — effort exists, significant gaps remain |
+| 3 | Good — mostly correct, minor improvements |
+| 4 | Excellent |
+
+## Output Format
+
+```markdown
+# Design Audit Report
+
+**Target**: [file or route]
+**Date**: [date]
+
+## Scores
+| Dimension | Score | Status |
+|---|---|---|
+| Accessibility | X/4 | [PASS/WARN/FAIL] |
+| Performance | X/4 | ... |
+| Theming | X/4 | ... |
+| Motion | X/4 | ... |
+| Interaction | X/4 | ... |
+| **Total** | X/20 | |
+
+## Findings by Priority
+
+### Critical (fix before ship)
+- [finding with file:line reference]
+
+### High
+- ...
+
+### Medium
+- ...
+
+## Recommended next commands
+- `/monodesign harden` — accessibility issues
+- `/monodesign polish` — theming drift and interaction gaps
+```