monomind 2.5.1 → 2.5.2

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

@@ -8,7 +8,7 @@ user-invocable: true
 
 # Monodesign: Critique
 
-Provide an expert design critique. Honest, specific, and prioritized. Read `reference/critique.md` from the monodesign skill directory for the full protocol.
+Provide an expert design critique. Honest, specific, and prioritized. Read `reference/critique.md` from the monodesign skill directory for the full protocol. Critiques are persisted via the bundled `critique-storage.mjs` helper (resolve a slug for the target, write the critique body, and query the trend across the last runs) so repeat critiques of the same target track progress over time — follow the reference's storage steps rather than emitting a one-off report.
 
 ## Voice
 

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

@@ -0,0 +1,30 @@
+---
+name: monodesign-init
+description: Set up a project for monodesign — one codebase crawl plus a short interview produces PRODUCT.md (strategic context), optionally DESIGN.md (visual system), and pre-configures live mode. The required first step that anchors all other monodesign commands.
+type: design-sub-command
+argument-hint: "[project path or description]"
+user-invocable: true
+---
+
+# Monodesign: Init
+
+Set up a project for monodesign. Read `reference/init.md` from the monodesign skill directory for the full flow — it is the authoritative protocol. (`/monodesign teach` is the historical alias; it behaves identically.)
+
+## What init produces
+
+- **PRODUCT.md** (strategic): register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual, offered via `/monodesign document`): visual theme, color palette, typography, components, layout. Answers "how it looks".
+- **`.monodesign/live/config.json`**: pre-configured live mode so `/monodesign live` boots straight into variant mode.
+
+## Flow summary (the reference is authoritative)
+
+1. **Load current state**: check for existing PRODUCT.md / DESIGN.md (project root, `.agents/context/`, `docs/`). Never silently overwrite — confirm which file to refresh. A legacy `.monodesign.md` is auto-renamed to PRODUCT.md by the loader.
+2. **Explore the codebase**: one thorough crawl — README/docs, package.json and framework detection, existing components, brand assets, design tokens. Form a register hypothesis (brand vs product vs both) and a platform hypothesis (`web` / `ios` / `android` / `adaptive`).
+3. **Interview**: ask strategic questions to fill PRODUCT.md — register and platform confirmation, users, purpose, positioning, brand personality, anti-references, accessibility needs (plus conversion & proof for the brand register). Never synthesize PRODUCT.md from the task prompt alone; the user confirms before you write.
+4. **Write PRODUCT.md** with only what the user confirmed.
+5. **Offer DESIGN.md** via `/monodesign document` — scan mode when code exists, seed mode for empty projects.
+6. **Pre-configure live mode** when the project has HTML entries and a dev server.
+
+## Blocker behavior
+
+If init was invoked as a setup blocker by another command (e.g. `/monodesign craft` with no PRODUCT.md), complete init, then resume the original command with the fresh context.

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

@@ -0,0 +1,36 @@
+---
+name: monodesign-layout
+description: Fix the structure, not the surface — diagnose a layout's actual problem (monotone spacing, weak hierarchy, identical card grids) and restructure spacing, grids, and composition for the project's register.
+type: design-sub-command
+argument-hint: "[target file, route, or component]"
+user-invocable: true
+---
+
+# Monodesign: Layout
+
+Space is the most underused design tool. Find the layout's actual problem and fix the structure, not the surface. Read `reference/layout.md` from the monodesign skill directory for the full protocol.
+
+## Register-aware structure
+
+- **Brand**: asymmetric compositions, fluid spacing with `clamp()`, intentional grid-breaking for emphasis. Rhythm through contrast — tight groupings paired with generous separations.
+- **Product**: predictable grids, consistent densities, familiar navigation patterns. Responsive behavior is structural (collapse sidebar, responsive table), not fluid typography. Consistency IS an affordance.
+- **Native** (`ios` / `android` / `adaptive`): follow the Layout section of `reference/ios.md` / `reference/android.md` — platform navigation, insets, and touch targets, never web CSS tooling.
+
+## Two isolated assessments (required)
+
+Spawn two parallel sub-agents (isolation is the point — neither sees the other's output):
+
+1. **Layout assessment**: works through the full "Assess Current Layout" checklist from the reference, returning per-item findings that cite file, selector, or value.
+2. **Mechanical pre-scan**: runs the bundled detector scoped to layout:
+
+   ```bash
+   node .claude/skills/monodesign/scripts/detect.mjs --json --scope layout [target files or dirs]
+   ```
+
+   When the project documents a spacing scale, also grep arbitrary Tailwind spacing (`gap-[`, `p-[`, `m-[`, `z-[`) and judge those hits against it.
+
+If no sub-agent tool is available, run both yourself — assessment first, pre-scan second, so deterministic findings can't anchor the visual judgment.
+
+## Then
+
+Synthesize both assessments, propose the structural fix (spacing rhythm, grid restructure, hierarchy weight), apply it, and re-run the detector to confirm the layout-scope findings are resolved.

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

@@ -1,59 +1,34 @@
 ---
 name: monodesign-live
-description: Iterate on the UI directly in the browser — screenshot, identify issues, apply targeted CSS fixes, verify, repeat — until the live result matches the design intent.
+description: Interactive live variant mode — select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via the dev server's HMR. Iterate until the live result matches the design intent.
 type: design-sub-command
-argument-hint: "[target URL or component]"
+argument-hint: "[target URL, route, or app path]"
 user-invocable: true
 ---
 
 # Monodesign: Live
 
-Iterate on the UI directly in the browser. Read `reference/live.md` from the monodesign skill directory for the full protocol.
+Interactive live variant mode. This is a fully functional, script-driven flow — not a manual screenshot loop. Read `reference/live.md` from the monodesign skill directory for the full protocol and follow its contract exactly (boot, poll, generate, steer, accept/discard, exit).
 
-## CLAUDE.md Requirement
+## Prerequisites
 
-This command requires browser automation. Before proceeding, verify that `npx monomind browse` is available (`Skill("agent-browser-testing")`). If not, the `/monodesign live` flow falls back to editing CSS files and asking the user to refresh.
+- A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser.
+- Node available on PATH (the flow runs the bundled live helper scripts).
+- If `.monodesign/live/config.json` exists (written by `/monodesign init`), live boots straight into variant mode with no first-time setup detour.
 
-## Live Iteration Loop
+## How it works (summary — the reference is authoritative)
 
-The loop runs until the user confirms the design is right or cancels.
-
-### 1. Screenshot
-Capture the current state of the target URL or component. No assumptions — look at what's actually rendered.
-
-### 2. Diagnose
-Look at the screenshot with fresh eyes. Identify the top 3 issues:
-- Visual hierarchy problems
-- Spacing inconsistencies
-- Color contrast issues
-- Typography rendering
-- Interaction state gaps
-- Alignment problems
-
-State the issues clearly before touching any code.
-
-### 3. Apply targeted fix
-Edit the CSS for the specific issue identified. Keep each fix surgical — change one thing at a time.
-
-```css
-/* Targeted fix: heading weight is too light — can't distinguish from body */
-.hero-heading {
-  font-weight: 800;
-  font-size: clamp(2.5rem, 5vw, 4rem);
-  letter-spacing: -0.03em;
-}
-```
-
-### 4. Screenshot again
-Verify the fix had the intended effect. Check for regressions on neighboring elements.
-
-### 5. Confirm or continue
-If the target issue is resolved, state what was fixed and move to the next. If the fix introduced a regression, roll back and try a different approach.
+1. **Boot**: run `live.mjs` (with `--target <path>` when the request names a specific file, route, or monorepo app). It starts the live helper server and injects the in-page toolbar.
+2. **Open the app URL** that serves the page (the app's own dev-server URL — never the helper's `serverPort`).
+3. **Poll loop**: long-poll with `live-poll.mjs` (default long timeout). The user selects elements in the browser and picks a design action from the toolbar.
+4. **On `generate`**: read the screenshot if present, load the action's reference file, plan three distinct directions, write all variants in one edit, reply done, poll again.
+5. **On `steer`**: handle the user's free-text instruction, reply, poll again.
+6. **On `accept` / `discard`**: the accepted variant is committed to source (carbonize accepts have a cleanup step via `live-complete.mjs`); discards roll back.
+7. **If interrupted**: run `live-status.mjs` or `live-resume.mjs` — the durable journal replays unacknowledged work.
+8. **On `exit`**: run the cleanup steps at the bottom of the reference.
 
 ## Guidelines
 
-- Fix the most visually impactful issue first
-- Don't batch multiple fixes — screenshot after each change
-- State what you're about to change and why before changing it
-- If the same area has been fixed 3+ times without convergence, step back and assess whether the problem is structural (wrong layout approach) vs. cosmetic
-- Deliver final CSS that can be committed, not just live browser overrides
+- Never pass a short poll timeout; restart the poll immediately after every event.
+- Variants are written as real source edits hot-swapped by HMR — deliver code that can be committed, not browser-only overrides.
+- Manual in-browser edits are captured and can be committed or discarded via `live-commit-manual-edits.mjs` / `live-discard-manual-edits.mjs`.

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

@@ -2,6 +2,7 @@
 
 Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context.
 
+**Web only** (mobile web included). Native platforms (`ios` / `android` / `adaptive`) route to [adapt.native.md](adapt.native.md) instead; if the project is native, switch to it now.
 
 ---
 
@@ -188,3 +189,124 @@ Test thoroughly across contexts:
 - **Slow connections**: Test on throttled network
 
 When the adaptation feels native to each context, hand off to `/monodesign polish` for the final pass.
+
+---
+
+## Reference Material
+
+The sections below were previously `responsive-design.md` and live inline now so the adapt flow has its deep responsive reference in one place.
+
+### Responsive Design
+
+#### Mobile-First: Write It Right
+
+Start with base styles for mobile, use `min-width` queries to layer complexity. Desktop-first (`max-width`) means mobile loads unnecessary styles first.
+
+#### Breakpoints: Content-Driven
+
+Don't chase device sizes; let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice (640, 768, 1024px). Use `clamp()` for fluid values without breakpoints.
+
+#### Detect Input Method, Not Just Screen Size
+
+**Screen size doesn't tell you input method.** A laptop with touchscreen, a tablet with keyboard. Use pointer and hover queries:
+
+```css
+/* Fine pointer (mouse, trackpad) */
+@media (pointer: fine) {
+  .button { padding: 8px 16px; }
+}
+
+/* Coarse pointer (touch, stylus) */
+@media (pointer: coarse) {
+  .button { padding: 12px 20px; }  /* Larger touch target */
+}
+
+/* Device supports hover */
+@media (hover: hover) {
+  .card:hover { transform: translateY(-2px); }
+}
+
+/* Device doesn't support hover (touch) */
+@media (hover: none) {
+  .card { /* No hover state - use active instead */ }
+}
+```
+
+**Critical**: Don't rely on hover for functionality. Touch users can't hover.
+
+#### Safe Areas: Handle the Notch
+
+Modern phones have notches, rounded corners, and home indicators. Use `env()`:
+
+```css
+body {
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+
+/* With fallback */
+.footer {
+  padding-bottom: max(1rem, env(safe-area-inset-bottom));
+}
+```
+
+**Enable viewport-fit** in your meta tag:
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+```
+
+#### Responsive Images: Get It Right
+
+##### srcset with Width Descriptors
+
+```html
+<img
+  src="hero-800.jpg"
+  srcset="
+    hero-400.jpg 400w,
+    hero-800.jpg 800w,
+    hero-1200.jpg 1200w
+  "
+  sizes="(max-width: 768px) 100vw, 50vw"
+  alt="Hero image"
+>
+```
+
+**How it works**:
+- `srcset` lists available images with their actual widths (`w` descriptors)
+- `sizes` tells the browser how wide the image will display
+- Browser picks the best file based on viewport width AND device pixel ratio
+
+##### Picture Element for Art Direction
+
+When you need different crops/compositions (not just resolutions):
+
+```html
+<picture>
+  <source media="(min-width: 768px)" srcset="wide.jpg">
+  <source media="(max-width: 767px)" srcset="tall.jpg">
+  <img src="fallback.jpg" alt="...">
+</picture>
+```
+
+#### Layout Adaptation Patterns
+
+**Navigation**: Three stages: hamburger + drawer on mobile, horizontal compact on tablet, full with labels on desktop. **Tables**: Transform to cards on mobile using `display: block` and `data-label` attributes. **Progressive disclosure**: Use `<details>/<summary>` for content that can collapse on mobile.
+
+#### Testing: Don't Trust DevTools Alone
+
+DevTools device emulation is useful for layout but misses:
+
+- Actual touch interactions
+- Real CPU/memory constraints
+- Network latency patterns
+- Font rendering differences
+- Browser chrome/keyboard appearances
+
+**Test on at least**: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you'll never see on simulators.
+
+---
+
+**Avoid**: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.

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

@@ -0,0 +1,58 @@
+> **Additional context needed**: target platforms/devices and usage contexts.
+
+Adapt an existing **native** design (`ios` / `android` / `adaptive`) to a different context: another device class, orientation, platform, or origin. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context, inside the platform conventions of [ios.md](ios.md) / [android.md](android.md); read the target platform's reference before planning if Setup hasn't already.
+
+## Assess Adaptation Challenge
+
+1. **Source context**: what was it designed for, and what assumptions did it make? (Phone-only? Portrait-only? One platform's idioms? A website?)
+2. **Target context**: which device class (phone, tablet, foldable), orientation, platform, and usage posture (one-handed on the go vs two-handed at rest)?
+3. **What breaks**: navigation that doesn't fit the target, layouts that stretch instead of restructure, gestures or controls that don't exist there?
+
+## Adaptation Strategies
+
+### Phone → Tablet (iPad / large screens)
+
+- **Restructure, don't stretch.** A scaled-up phone UI on a tablet is the failure mode. Use size classes (iOS) / window size classes (Android) to switch structure.
+- **Navigation changes shape**: tab bar stays or becomes a sidebar on iPad; Android navigation bar becomes a rail or drawer on expanded width.
+- **Use the width**: split view / master-detail (list + detail side by side), multi-column grids, popovers where phones used sheets.
+- **Multitasking is a size, not an edge case**: iPad Split View and Android multi-window can hand you a phone-width window on a tablet; size-class-driven layout handles both for free.
+
+### Orientation & foldables
+
+- Landscape restructures (side-by-side panes, repositioned controls); never clip or letterbox. Lock orientation only when the task truly demands it.
+- Foldables (Android): react to posture and hinge via window size classes; test folded, unfolded, and tabletop.
+
+### Platform → platform (iOS ↔ Android)
+
+Translate idioms; never transplant them:
+
+| iOS | Android |
+|---|---|
+| Tab bar | Navigation bar / rail / drawer |
+| Edge-swipe back, back chevron | Predictive Back gesture / button |
+| Switch, segmented control, system pickers | Material switch, chips, Material pickers |
+| Action sheet | Bottom sheet / Material dialog |
+| SF Symbols, SF Pro, Dynamic Type | Material Symbols, Roboto, sp scaling |
+| Semantic system colors, materials | Material color roles, tonal elevation |
+| System push/sheet transitions | Container transform, shared-axis, fade-through |
+
+Rebuild navigation and controls in the target's vocabulary; carry over the brand's expressive layer (palette intent, type accent, motion personality) through the target's theming system.
+
+### Web → native (porting a website or web app)
+
+Reconform, don't reflow. Replace web navigation with the platform's model, HTML-shaped controls with platform controls, hover affordances with touch-first ones, and px-based type with Dynamic Type / sp. Then treat the result to the full platform reference; the slop test there is the acceptance bar.
+
+## Implement & Verify
+
+- Drive structure from **size classes / window size classes**, never from device-model checks.
+- Respect safe areas and window insets in every new configuration (notch, hinge, status bar, keyboard).
+- Test on simulators for breadth, then real hardware for truth: at least one phone and one tablet per shipped platform, both orientations, split-screen where supported.
+
+When the adaptation feels native to each context, hand off to `/monodesign polish` for the final pass.
+
+**NEVER**:
+- Ship a stretched phone layout on a tablet
+- Port one platform's controls or navigation onto the other
+- Hide core functionality on smaller devices (if it matters, make it work)
+- Lock orientation to dodge a layout bug
+- Trust simulators alone (posture, gestures, and performance need hardware)

package/packages/@monomind/cli/.claude/skills/monodesign/reference/android.md

@@ -0,0 +1,40 @@
+# Android platform
+
+For native Android apps: Jetpack Compose, Android Views, React Native, Expo, Flutter shipping to Android hardware.
+
+On native, register narrows. Material Design 3 governs structure, navigation, and interaction whatever the register; brand expresses through Material's theming (color roles, type scale, shape, motion). A Material-everywhere cross-platform app that also ships to iPhone still owes iOS its OS guarantees on that hardware: safe-area insets, Reduce Motion, edge-swipe back.
+
+## The Android slop test
+
+Would a fluent Android user trust this app, or trip on off-spec components? The most common tell is an iOS app wearing Android's skin: a bottom-only navigation copied from iPhone, a back arrow that ignores the system Back gesture, Cupertino-shaped switches and dialogs. Material 3 is the rulebook; follow its components and theme the brand through it.
+
+## Layout & structure
+
+- **Material navigation, matched to size.** Navigation bar (bottom, 3–5 destinations) on compact width; navigation rail or drawer on expanded width. Never ship a phone bottom-bar untouched on a tablet.
+- **System Back always works.** Honor the predictive Back gesture and Back button; never trap the user or hijack the gesture.
+- **Edge-to-edge with window insets.** Apply the status bar, navigation bar, display cutout, and IME insets so content never hides behind system bars or the keyboard.
+- **Top app bar for screen context**; pair with a FAB when the screen has a single primary action.
+
+## Touch targets
+
+- **48×48 dp minimum** for every touch target, with at least 8 dp between them.
+
+## Typography
+
+- **Material type scale.** Display, Headline, Title, Body, Label roles (large/medium/small each). Map text to roles; never hand-pick sizes per screen.
+- **Roboto is the system face**; theme a brand face in through the type scale, keeping body, labels, and controls legible and consistent.
+- **sp units, never fixed px**, so type follows the system font-size setting.
+
+## Color & theming
+
+- **Material color roles** (primary, on-primary, surface, surface-variant, secondary-container, outline, error). Role tokens resolve light/dark and contrast variants automatically; raw hex breaks there.
+- **Dynamic Color (Material You)** where it fits: derive the scheme from the user's wallpaper on Android 12+, with a static fallback.
+- **Dark theme is a first-class scheme.** Design and test it; never a quick invert.
+- **Tonal elevation.** Convey elevation through the standard surface tonal levels (plus shadow where appropriate); no arbitrary drop shadows.
+
+## Components & motion
+
+- **Material components.** Buttons (filled / tonal / outlined / text), FAB, switches, chips, snackbars, bottom sheets, Material dialogs, navigation bar/rail/drawer. Never port iOS controls or invent equivalents.
+- **One FAB, one primary action.** Never stack FABs or spend one on a secondary task.
+- **Snackbars for transient feedback** (actionable when useful, never a toast for that); dialogs only for decisions that must interrupt.
+- **Material motion patterns.** Container transform, shared-axis, fade-through, with standard easing and durations; honor the system Remove animations setting with a crossfade or instant cut.

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

@@ -6,10 +6,12 @@ Add motion that conveys state, gives feedback, and clarifies hierarchy. Cut moti
 
 ## Register
 
-Brand: orchestrated page-load sequences, staggered reveals, scroll-driven animation. Motion is part of the voice; one well-rehearsed entrance beats scattered micro-interactions.
+Brand: motion is part of the voice; one well-rehearsed entrance beats scattered micro-interactions. The saturated AI default is fade-and-rise reveals on every scrolled section; that's a tell, not a choreography. Reserve scroll-triggered motion for moments that earn it.
 
 Product: 150–250 ms on most transitions. Motion conveys state: feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it.
 
+Native (`ios` / `android` / `adaptive`): implementation follows the Motion section of [ios.md](ios.md) / [android.md](android.md) (read it first if Setup hasn't already): system transitions and OS Reduce Motion, never the web tooling below.
+
 ---
 
 ## Assess Animation Opportunities
@@ -29,7 +31,7 @@ Analyze where motion would improve the experience:
    - Who's the audience? (Motion-sensitive users? Power users who want speed?)
    - What matters most? (One hero animation vs many micro-interactions?)
 
-If any of these are unclear from the codebase, Ask the user for clarification before proceeding.
+If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify.
 
 **CRITICAL**: Respect `prefers-reduced-motion`. Always provide non-animated alternatives for users who need them.
 
@@ -49,10 +51,11 @@ Create a purposeful animation plan:
 Add motion systematically across these categories:
 
 ### Entrance Animations
-- **Page load choreography**: Stagger element reveals (100-150ms delays), fade + slide combinations
 - **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects)
-- **Content reveals**: Scroll-triggered animations using intersection observer
 - **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management
+- **List rhythm**: Sibling stagger is legitimate for cards-in-a-grid or list-items-appearing. Whole-section fade-on-scroll is not a list and is not legitimate. Cap total stagger time: 10 items at 50ms each = 500ms total. For more items, reduce per-item delay or cap the staggered count.
+
+  Use CSS custom properties for clean stagger: `animation-delay: calc(var(--i, 0) * 50ms)` with `style="--i: 0"`, `style="--i: 1"`, etc. on each item.
 
 ### Micro-interactions
 - **Button feedback**:
@@ -97,11 +100,14 @@ Use appropriate techniques for each animation:
 
 ### Timing & Easing
 
-**Durations by purpose:**
-- **100-150ms**: Instant feedback (button press, toggle)
-- **200-300ms**: State changes (hover, menu open)
-- **300-500ms**: Layout changes (accordion, modal)
-- **500-800ms**: Entrance animations (page load)
+**Duration: the 100/300/500 rule.** Timing matters more than easing for "feels right":
+
+| Duration | Use Case | Examples |
+|----------|----------|----------|
+| **100–150ms** | Instant feedback | Button press, toggle, color change |
+| **200–300ms** | State changes | Menu open, tooltip, hover state |
+| **300–500ms** | Layout changes | Accordion, modal, drawer |
+| **500–800ms** | Entrance animations | Page load, hero reveal |
 
 **Easing curves (use these, not CSS defaults):**
 ```css
@@ -134,13 +140,35 @@ Use appropriate techniques for each animation:
 - GSAP for complex sequences
 ```
 
+### Motion Materials
+
+Transform and opacity are reliable defaults, not the whole palette. Premium interfaces often need atmospheric properties. Match material to effect:
+
+- **Transform / opacity**: movement, press feedback, simple reveals, list choreography
+- **Blur / filter / backdrop-filter**: focus pulls, depth, glass or lens effects, softened entrances
+- **Clip-path / masks**: wipes, reveals, editorial cropping, product-like transitions
+- **Shadow / glow / color filters**: energy, affordance, focus, warmth, active state
+- **Grid-template-rows or FLIP-style transforms**: expanding and reflowing layout without animating `height` directly
+
+The hard rule isn't "transform and opacity only." It's: avoid animating layout-driving properties casually (`width`, `height`, `top`, `left`, margins), keep expensive effects bounded to small or isolated areas, and verify smoothness in-browser on target viewports.
+
 ### Performance
-- **Motion materials**: Use transform/opacity for reliable movement, but use blur, filters, masks, shadows, and color shifts when they materially improve the effect
 - **Layout safety**: Avoid casual animation of layout-driving properties (`width`, `height`, `top`, `left`, margins)
-- **will-change**: Add sparingly for known expensive animations
+- **will-change**: Add sparingly for known expensive animations only (e.g. on `:hover` or an `.animating` class), never preemptively across the whole page
+- **Scroll triggers**: Use Intersection Observer instead of scroll event listeners; unobserve after the animation fires once
 - **Bound expensive effects**: Keep blur/filter/shadow areas small or isolated, use `contain` where appropriate
 - **Monitor FPS**: Ensure 60fps on target devices
 
+### Perceived Performance
+
+Nobody cares how fast your site *is*, only how fast it feels. The 80ms threshold: anything under ~80ms feels instant because our brains buffer sensory input for that long to synchronize perception. Target this for micro-interactions.
+
+- **Preemptive start**: Begin transitions immediately while loading (iOS app zoom, skeleton UI). Users perceive work happening.
+- **Early completion**: Show content progressively, don't wait for everything (progressive images, streaming HTML, skeleton fade-ins).
+- **Optimistic UI**: Update the interface immediately, handle failures gracefully. Use for low-stakes actions (likes, follows). Avoid for payments or destructive operations.
+- **Easing affects perceived duration**: Ease-in (accelerating toward completion) makes tasks feel shorter because the peak-end effect weights final moments heavily. Ease-out feels satisfying for entrances.
+- **Caution**: Too-fast responses can decrease perceived value for complex operations (search, analysis). Sometimes a brief delay signals "real work" is happening.
+
 ### Accessibility
 ```css
 @media (prefers-reduced-motion: reduce) {

package/packages/@monomind/cli/.claude/skills/monodesign/reference/antipatterns-catalog.md

@@ -1,11 +1,11 @@
-<!-- Synced from impeccable v3.1.0 registry. Source of truth: cli/engine/registry/antipatterns.mjs -->
+<!-- Synced from the monodesign v3.2.1 registry. Source of truth: cli/engine/registry/antipatterns.mjs -->
 # Antipatterns Catalog
 
-All 46 known design antipatterns with detection rules and remediation. These are what `npx impeccable detect` checks. Run this on any HTML/CSS target before presenting work.
+All 46 known design antipatterns with detection rules and remediation. These are what `monomind design detect` checks. Run this on any HTML/CSS target before presenting work.
 
 ## Categories
 
-These are the two categories the `impeccable detect` engine uses:
+These are the two categories the `monomind design detect` engine uses:
 
 - **slop** — AI tells that signal lack of intentional design (27 patterns)
 - **quality** — Design principle violations including contrast, motion, readability, and semantic structure (19 patterns)
@@ -37,6 +37,14 @@ These are the two categories the `impeccable detect` engine uses:
 **Why it's wrong:** Bounce easing is a 2013 trend that reads as playful-in-a-bad-way on professional interfaces. It also tends to cause layout shift.  
 **Fix:** Use expo-out (`cubic-bezier(0.16, 1, 0.3, 1)`) for snappy exits, quint-out for softer landings. No overshoot.
 
+### `codex-grid-background` — Decorative grid-line background
+
+**Detect**: A two-axis grid drawn with hairline `linear-gradient` layers (`1px, transparent 1px` on both axes) used as surface decoration. Opt-in via `--gpt` (gated off by default).
+
+**Why it's wrong**: A decorative hairline grid overlay is a recurring generated-UI signature. It adds visual noise without communicating structure.
+
+**Fix**: Reserve grid overlays for actual canvas, map, blueprint, or measurement surfaces; elsewhere use product structure or a plain surface.
+
 ### `cream-palette` — Cream / beige palette
 
 **Detect**: Warm cream or beige page background (`#fdf6e3`, `#faf8f5`, or equivalent warm off-white) with no other distinguishing palette element.
@@ -58,11 +66,6 @@ These are the two categories the `impeccable detect` engine uses:
 
 **Fix**: Use commas, colons, periods, or parentheses instead. Reserve em-dashes for strong breaks where no other punctuation works.
 
-### `everything-centered` — Everything centered
-**Detect:** More than 3 consecutive sections all use `text-align: center` or centered flex/grid layout.  
-**Why it's wrong:** Center alignment works for short content (headings, CTAs) but becomes monotonous for long sections. It also reduces readability for multi-line copy.  
-**Fix:** Mix alignment. Left-align body copy. Center only headings and CTAs. Alternate center and left-aligned sections.
-
 ### `extreme-negative-tracking` — Crushed letter spacing
 
 **Detect**: `letter-spacing` pulled below `-0.05em` on display or body type.
@@ -239,6 +242,14 @@ These are the two categories the `impeccable detect` engine uses:
 
 **Fix**: Use the documented type system or update `DESIGN.md` if this is an intentional brand addition. Never silently add a typeface without updating the system.
 
+### `design-system-font-size` — Font size outside DESIGN.md
+
+**Detect**: A literal `font-size` used in CSS that is off the type ramp documented in the project's `DESIGN.md` typography section.
+
+**Why it's wrong**: Off-ramp font sizes are type-system drift. Each undeclared size step erodes the typographic scale and makes the hierarchy inconsistent.
+
+**Fix**: Use a documented size step or update the design system if the new step is intentional.
+
 ### `design-system-radius` — Radius outside DESIGN.md
 
 **Detect**: A `border-radius` value used in CSS that is not in the project's `DESIGN.md` rounded-corner scale.
@@ -270,12 +281,7 @@ These are the two categories the `impeccable detect` engine uses:
 ### `low-contrast` — Low contrast text
 **Detect:** Text color does not achieve 4.5:1 contrast ratio against its background for normal text, or 3:1 for large text (18px+ regular or 14px+ bold), as measured by the WCAG relative luminance formula.  
 **Why it's wrong:** Low contrast text fails WCAG AA requirements and creates genuine barriers for users with low vision, in bright ambient light, or on low-quality displays.  
-**Fix:** Increase the contrast between text and background. Use white or a high-lightness neutral on dark backgrounds; use Deep Graphite (`oklch(10% 0 0)`) or Soft Charcoal (`oklch(25% 0 0)`) on light ones. Tool: check with `npx impeccable detect` or the WebAIM contrast checker.
-
-### `pure-black-white` — Pure black or white background
-**Detect:** `background: #000`, `background: #000000`, or `background: black` on any surface.  
-**Why it's wrong:** Pure black reads as low quality on most displays. Tinted dark (e.g., `oklch(8% 0.005 350)`) reads as intentional.  
-**Fix:** Tint every neutral toward the brand hue. Chroma 0.003–0.01 is enough to remove pure-black/pure-white.
+**Fix:** Increase the contrast between text and background. Use white or a high-lightness neutral on dark backgrounds; use Deep Graphite (`oklch(10% 0 0)`) or Soft Charcoal (`oklch(25% 0 0)`) on light ones. Tool: check with `monomind design detect` or the WebAIM contrast checker.
 
 ### `skipped-heading` — Skipped heading level
 **Detect:** An `h3` or deeper element that is not preceded by an `h2` in the same section, or an `h2` not preceded by an `h1`.  
@@ -317,8 +323,8 @@ These are the two categories the `impeccable detect` engine uses:
 | `bounce-easing` | slop | expo-out curve |
 | `cream-palette` | slop | Deliberate palette, not default warm off-white |
 | `dark-glow` | slop | Shadow lift + border |
+| `codex-grid-background` | slop | Grid overlays only on canvas/map surfaces |
 | `em-dash-overuse` | slop | Commas, colons, periods instead |
-| `everything-centered` | slop | Mix alignment |
 | `extreme-negative-tracking` | slop | No tighter than -0.03em |
 | `flat-type-hierarchy` | slop | 1.25× scale minimum |
 | `gpt-thin-border-wide-shadow` | slop | Border or shadow — not both |
@@ -345,13 +351,13 @@ These are the two categories the `impeccable detect` engine uses:
 | `cramped-padding` | quality | 16px minimum |
 | `design-system-color` | quality | Use palette token or update DESIGN.md |
 | `design-system-font` | quality | Use type system or update DESIGN.md |
+| `design-system-font-size` | quality | Use type-ramp step or update DESIGN.md |
 | `design-system-radius` | quality | Use radius token or update DESIGN.md |
 | `gray-on-color` | quality | White or appropriate ramp tone |
 | `justified-text` | quality | text-align: left |
 | `layout-transition` | quality | transform + opacity only |
 | `line-length` | quality | max-width: 65ch |
 | `low-contrast` | quality | 4.5:1 normal, 3:1 large text |
-| `pure-black-white` | quality | Tinted neutral (chroma 0.005) |
 | `skipped-heading` | quality | Sequential h1→h2→h3 |
 | `text-overflow` | quality | overflow-wrap + constrained widths |
 | `tight-leading` | quality | line-height: 1.6 |

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

@@ -2,6 +2,8 @@ Run systematic **technical** quality checks and generate a comprehensive report.
 
 This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.
 
+**Web only.** Native platforms (`ios` / `android` / `adaptive`) route to [audit.native.md](audit.native.md) instead; if the project is native, switch to it now.
+
 ## Diagnostic Scan
 
 Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.
@@ -52,7 +54,7 @@ Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the
 
 ### 5. Anti-Patterns (CRITICAL)
 
-Check against ALL the **DON'T** guidelines from the parent impeccable skill (already loaded in this context). Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy).
+Check against ALL the **DON'T** guidelines from the parent monodesign skill (already loaded in this context). Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy).
 
 **Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design)
 
@@ -95,7 +97,7 @@ For each issue, document:
 - **Impact**: How it affects users
 - **WCAG/Standard**: Which standard it violates (if applicable)
 - **Recommendation**: How to fix it
-- **Suggested command**: Which command to use (prefer: craft, shape, critique, audit, polish, bolder, quieter, distill, harden, onboard, animate, colorize, typeset, layout, delight, overdrive, clarify, adapt, optimize, live, components, research, images, teach, document, extract)
+- **Suggested command**: Which command to use (prefer: /monodesign craft, /monodesign init, /monodesign document, /monodesign extract, /monodesign live, /monodesign adapt, /monodesign animate, /monodesign audit, /monodesign bolder, /monodesign clarify, /monodesign colorize, /monodesign critique, /monodesign delight, /monodesign distill, /monodesign harden, /monodesign onboard, /monodesign layout, /monodesign optimize, /monodesign overdrive, /monodesign polish, /monodesign quieter, /monodesign shape, /monodesign typeset)
 
 ### Patterns & Systemic Issues
 
@@ -114,7 +116,7 @@ List recommended commands in priority order (P0 first, then P1, then P2):
 1. **[P?] `/command-name`**: Brief description (specific context from audit findings)
 2. **[P?] `/command-name`**: Brief description (specific context)
 
-**Rules**: Only recommend commands from: craft, shape, critique, audit, polish, bolder, quieter, distill, harden, onboard, animate, colorize, typeset, layout, delight, overdrive, clarify, adapt, optimize, live, components, research, images, teach, document, extract. Map findings to the most appropriate command. End with `/monodesign polish` as the final step if any fixes were recommended.
+**Rules**: Only recommend commands from: /monodesign craft, /monodesign init, /monodesign document, /monodesign extract, /monodesign live, /monodesign adapt, /monodesign animate, /monodesign audit, /monodesign bolder, /monodesign clarify, /monodesign colorize, /monodesign critique, /monodesign delight, /monodesign distill, /monodesign harden, /monodesign onboard, /monodesign layout, /monodesign optimize, /monodesign overdrive, /monodesign polish, /monodesign quieter, /monodesign shape, /monodesign typeset. Map findings to the most appropriate command. End with `/monodesign polish` as the final step if any fixes were recommended.
 
 After presenting the summary, tell the user: