monomind 2.7.5 → 2.7.7

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

@@ -0,0 +1,65 @@
+---
+name: monodesign-harden
+description: Fix accessibility violations, keyboard navigation gaps, semantic HTML issues, ARIA problems, and contrast failures — bring the interface to WCAG AA compliance.
+type: design-sub-command
+argument-hint: "[target page or component]"
+user-invocable: true
+---
+
+# Monodesign: Harden
+
+Fix accessibility and robustness issues. Read `reference/harden.md` from the monodesign skill directory for the full protocol.
+
+## Accessibility Targets
+
+**WCAG AA** is the floor:
+- Body text: ≥4.5:1 contrast ratio
+- Large text (≥18px or bold ≥14px): ≥3:1
+- Interactive element focus indicators: ≥3:1 against adjacent colors
+- No information conveyed by color alone
+
+**Keyboard navigation**
+- Every interactive element reachable by Tab in logical order
+- Visible focus ring on every focused element (never `outline: none` without a replacement)
+- No keyboard traps
+- Escape closes modals and dropdowns
+- Arrow keys navigate within a group (menu items, radio buttons, tabs)
+
+**Semantic HTML**
+- Heading hierarchy is sequential (h1 → h2 → h3, no skipping)
+- Landmark roles present (main, nav, aside, footer)
+- Interactive elements use native elements (button, a, input) not div
+- Forms have labels associated with inputs (via for/id or wrapping label)
+
+**ARIA**
+- Used only when native semantics can't convey the role
+- `aria-label` on icon-only buttons
+- `aria-expanded`, `aria-controls` on toggle buttons
+- `aria-live` on dynamic content that updates without page reload
+- `role="status"` or `role="alert"` on notification areas
+
+**Images**
+- Decorative images: `alt=""`
+- Informative images: alt describes the information (not "image of...")
+- Icon images: alt is the icon's semantic meaning
+
+## Hardening Checklist
+
+```
+[ ] Run automated check: `npx axe <url>` or equivalent
+[ ] Tab through entire page — every interactive element reachable
+[ ] Check all headings form a logical hierarchy
+[ ] Verify all contrast ratios pass
+[ ] Test all interactive elements with keyboard only
+[ ] Verify screen reader announces dynamic content
+[ ] Check all forms have properly associated labels
+[ ] Test at 200% zoom — nothing overlaps or disappears
+[ ] Verify reduced motion preference is respected
+```
+
+## Never
+
+- `outline: none` or `outline: 0` without a replacement focus indicator
+- `tabindex="-1"` on focusable elements without a keyboard alternative
+- Color as the only differentiator between states
+- ARIA roles that contradict the HTML semantics (role="button" on an anchor that navigates)

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

@@ -0,0 +1,34 @@
+---
+name: monodesign-live
+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, route, or app path]"
+user-invocable: true
+---
+
+# Monodesign: Live
+
+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).
+
+## Prerequisites
+
+- 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.
+
+## How it works (summary — the reference is authoritative)
+
+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
+
+- 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/onboard.md

@@ -0,0 +1,50 @@
+---
+name: monodesign-onboard
+description: Design or improve user onboarding — first-run experiences, empty states, progressive disclosure, setup wizards, and the "aha moment" path for new users.
+type: design-sub-command
+argument-hint: "[target product or feature to onboard]"
+user-invocable: true
+---
+
+# Monodesign: Onboard
+
+Design or improve user onboarding. Read `reference/onboard.md` from the monodesign skill directory for the full protocol.
+
+## Onboarding Philosophy
+
+The goal of onboarding is not to explain the product. It's to get the user to their first moment of value as fast as possible. Everything that doesn't serve that goal is a liability.
+
+## The Aha Moment Map
+
+Before designing anything, identify:
+1. **What is the first moment of genuine value for a new user?** (Not "they understand the product" — what specific thing makes them say "oh, this is useful")
+2. **What is the shortest path to that moment?** (Every step that isn't required is a step where the user can drop off)
+3. **What does the user need to know before they can get there?** (Only these things — nothing more)
+
+## Onboarding Patterns
+
+**Empty state onboarding**
+The most overlooked opportunity. When a user first arrives at a feature with no data, the empty state is their first experience of that feature. It should:
+- Describe what will appear here (not be blank)
+- Show a CTA to add the first item
+- Optionally show a preview of what it will look like when populated
+
+**Progressive disclosure onboarding**
+Start with the minimal useful version of the product. Reveal additional features only when the user's behavior signals readiness (they've used the basic feature N times, or they've hit a limitation).
+
+**Contextual tooltips**
+Not a tour. Tooltips that appear at the right moment (user hovers a new feature, user completes an action) and disappear when dismissed. Never a forced 10-step tour.
+
+**Setup wizard**
+When the product genuinely requires configuration before it's useful (API keys, workspace settings, integrations), a wizard is appropriate. Keep it short: 3 steps max, each with a clear benefit statement ("After this, you can...").
+
+## Copy Principles for Onboarding
+
+- Frame every step as a benefit: "Connect your calendar to automatically block focus time" not "Calendar integration step 2 of 3"
+- Progress indicators: show how far they've come, not how far they have to go
+- Skip options: always provide a way to skip or come back later
+- No dead ends: every empty state has an action, every error has a recovery path
+
+## Output
+
+Design decisions + code for the specific onboarding surface: empty states, tooltip content, wizard steps, or first-run flow — with copy, layout, and interaction states.

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

@@ -0,0 +1,64 @@
+---
+name: monodesign-optimize
+description: Improve frontend performance — animation smoothness, bundle size, rendering, image optimization, and Core Web Vitals — without sacrificing design quality.
+type: design-sub-command
+argument-hint: "[target page or component]"
+user-invocable: true
+---
+
+# Monodesign: Optimize
+
+Improve frontend performance. Read `reference/optimize.md` from the monodesign skill directory for the full protocol.
+
+## Performance Target: Core Web Vitals
+
+- **LCP** (Largest Contentful Paint): ≤2.5s
+- **INP** (Interaction to Next Paint): ≤200ms
+- **CLS** (Cumulative Layout Shift): ≤0.1
+
+## Common Design-Layer Performance Issues
+
+**Animation performance**
+- Animating layout properties (`width`, `height`, `padding`, `margin`, `top`, `left`) causes layout recalculation on every frame — replace with `transform` and `opacity` only
+- Unbounded blur: `blur(20px)` on many elements is expensive — test and cap
+- `will-change: transform` tells the browser to promote to its own layer — use sparingly (memory cost)
+- Too many simultaneous animations — stagger rather than launch all at once
+
+**Image optimization**
+- `loading="lazy"` on all images below the fold
+- `width` + `height` attributes on all images to prevent CLS
+- Modern formats: WebP/AVIF > JPEG/PNG for photos
+- `srcset` for responsive images
+- CSS background images: consider whether an `<img>` with `loading="lazy"` would be faster
+
+**Font loading**
+- `font-display: swap` to prevent invisible text during font load
+- Preload critical fonts: `<link rel="preload" as="font">`
+- Subset fonts if using a custom typeface (Google Fonts does this automatically)
+
+**CSS performance**
+- Avoid `@import` in CSS (render-blocking)
+- Don't use `:nth-child()` in hot paths with many elements
+- CSS containment: `contain: layout style` on isolated components prevents unintended reflows
+
+**JavaScript**
+- Defer non-critical scripts: `<script defer>` or `<script type="module">`
+- Code-split by route if using a framework
+- Avoid inline event handlers at scale (use event delegation)
+
+## Measurement
+
+```bash
+# Lighthouse in CLI
+npx lighthouse <url> --output json --output html
+
+# Web Vitals in DevTools
+# Performance tab → Core Web Vitals section
+
+# Bundle analysis (if Vite)
+npx vite-bundle-analyzer
+```
+
+## Output
+
+Specific optimizations with before/after measurements where measurable. Each change should cite the metric it improves.

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

@@ -0,0 +1,56 @@
+---
+name: monodesign-overdrive
+description: Push an interface past conventional limits — cinematic page transitions, GPU-accelerated data visualization, physics-based interactions, generative art, extraordinary technical effects that make users say "wow".
+type: design-sub-command
+argument-hint: "[target interface or specific effect goal]"
+user-invocable: true
+---
+
+# Monodesign: Overdrive
+
+Push an interface past conventional limits.
+
+**Start your response with:**
+```
+──────────── ⚡ OVERDRIVE ─────────────
+》》》 Entering overdrive mode...
+```
+
+Read `reference/overdrive.md` from the monodesign skill directory for the full protocol.
+
+## Context Determines "Extraordinary"
+
+A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. Before choosing a technique, ask: **what would make a user of THIS specific interface say "wow, that's nice"?**
+
+- **Visual/marketing surfaces**: sensory — scroll-driven reveals, shader backgrounds, cinematic page transitions, generative art responding to cursor
+- **Functional UI**: felt — dialog morphing from its trigger via View Transitions, data table rendering 100k rows at 60fps via virtual scrolling, form with streaming validation that feels instant, drag-and-drop with spring physics
+- **Performance-critical UI**: invisible — search that filters 50k items without a flicker, image editor that processes near-real-time
+- **Data-heavy interfaces**: fluid — GPU-accelerated rendering via Canvas/WebGL, animated transitions between data states
+
+**The common thread**: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience.
+
+## Propose Before Building
+
+Do NOT jump straight to implementation. You MUST:
+
+1. Think through **2–3 different directions**: technique, level of ambition, aesthetic approach
+2. **Ask the user** to pick before writing code. Explain trade-offs (browser support, performance cost, complexity)
+3. Only proceed with the confirmed direction
+
+## The Toolkit
+
+**Cinematic transitions**: View Transitions API, shared element transitions, `::view-transition-group`
+
+**Scroll-driven**: `animation-timeline: scroll()`, Intersection Observer with CSS transitions, parallax via transform
+
+**Generative/ambient**: CSS custom properties + JS, Canvas 2D for simple generative art, WebGL/Three.js for shaders
+
+**Physics**: spring animations via motion.dev, GSAP with ease functions, Popmotion
+
+**Data at scale**: virtual scrolling (TanStack Virtual), Canvas/WebGL rendering, Web Workers for computation
+
+**GPU compositing**: `transform` + `opacity` only, `will-change` on animated layers, `contain: strict` for isolation
+
+## Iterate in Browser
+
+Technically ambitious effects almost never look right on the first try. Use browser automation to watch the effect play. Expect multiple rounds of refinement. The gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.

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

@@ -0,0 +1,68 @@
+---
+name: monodesign-polish
+description: Perform a meticulous final pass to catch all the small details that separate good work from great work — design system alignment, interaction states, spacing precision, copy consistency, edge cases.
+type: design-sub-command
+argument-hint: "[target component, page, or feature]"
+user-invocable: true
+---
+
+# Monodesign: Polish
+
+Perform a meticulous final pass. The difference between shipped and polished. Read `reference/polish.md` from the monodesign skill directory for the full protocol.
+
+## Design System Discovery (required first step)
+
+1. **Find the design system**: Look for documentation, component libraries, style guides, token definitions
+2. **Note the conventions**: spacing scale, color tokens, motion patterns, component API
+3. **Identify drift, then name the root cause**: classify each deviation as:
+   - **Missing token** — value should exist in the system but doesn't
+   - **One-off implementation** — shared component exists but wasn't used
+   - **Conceptual misalignment** — flow, IA, or hierarchy doesn't match neighboring features
+
+Polish **must** align the feature with the design system. If none exists, polish against visible codebase conventions.
+
+## Pre-Polish Assessment
+
+1. **Review completeness**: Is it functionally complete? Are there known issues to preserve (mark TODOs)?
+2. **Think experience-first**: Walk the path from the user's perspective before opening DevTools
+3. **Identify polish areas**:
+   - Visual inconsistencies
+   - Spacing and alignment issues
+   - Interaction state gaps (hover, focus, active, disabled, loading)
+   - Copy inconsistencies and redundancies
+   - Edge cases and error states
+   - Loading and transition smoothness
+   - Information architecture drift
+
+## Polish Checklist
+
+**Visual**
+- [ ] Consistent spacing using the design system scale
+- [ ] Typography hierarchy visible at a glance (size + weight contrast)
+- [ ] Color contrast meets WCAG AA minimums
+- [ ] All interactive elements have hover + focus states
+- [ ] Loading/skeleton states for async content
+- [ ] Empty states designed (not blank)
+
+**Copy**
+- [ ] No restated headings or intros that repeat the title
+- [ ] Error messages are actionable (not "Something went wrong")
+- [ ] No em dashes — use commas, colons, or semicolons
+- [ ] Consistent voice with PRODUCT.md
+
+**Motion**
+- [ ] Transitions feel intentional, not added by reflex
+- [ ] All animations have `prefers-reduced-motion` fallback
+- [ ] No layout-property animation
+
+**Responsive**
+- [ ] All text within viewport, no overflow at any breakpoint
+- [ ] Touch targets ≥44×44px on mobile
+
+## Browser Verification
+
+Use browser automation to verify the live result — don't assume the CSS is correct. Check:
+- The actual user path (not just the happy state)
+- Mobile viewport
+- Dark/light mode switch
+- Keyboard navigation

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

@@ -0,0 +1,57 @@
+---
+name: monodesign-quieter
+description: Reduce visual intensity in designs that are too loud, aggressive, or overstimulating — without losing personality or making the result generic.
+type: design-sub-command
+argument-hint: "[target page, component, or design]"
+user-invocable: true
+---
+
+# Monodesign: Quieter
+
+Quiet design is harder than bold design. Subtlety needs precision. Read `reference/quieter.md` from the monodesign skill directory for the full protocol.
+
+## Register
+
+**Brand**: "quieter" means more restrained palette, more whitespace, more typographic air. Drama is reduced, not eliminated — the POV stays intact.
+
+**Product**: "quieter" means reducing visual noise. Fewer background accents, flatter cards, less color, less motion. The tool should disappear more completely into the task.
+
+## Assess What's Too Loud
+
+1. **Color saturation**: Overly bright or saturated colors competing for attention
+2. **Contrast extremes**: Too much high-contrast juxtaposition without hierarchy
+3. **Visual weight**: Too many bold, heavy elements with no quiet counterweight
+4. **Animation excess**: Too much motion or overly dramatic effects
+5. **Complexity**: Too many visual elements, patterns, or decorations
+6. **Scale**: Everything is large with no moments of relief
+
+## Quieting Interventions
+
+**Reduce color intensity**
+- Lower chroma on accents (oklab(L, less-C, H))
+- Move from Committed/Full palette to Restrained strategy
+- Replace colored backgrounds with tinted neutrals
+
+**Add breathing room**
+- Increase whitespace between sections
+- Reduce the number of distinct visual elements per screen
+- Let one element be the hero; everything else serves it
+
+**Calm the type**
+- Reduce heading sizes (headline at 3rem vs. 5rem)
+- Use a lighter weight for headings (500 instead of 800)
+- Increase line height and letter-spacing slightly
+
+**Flatten the cards**
+- Remove drop shadows or reduce them to near-invisible (0 1px 2px oklch(0% 0 0 / 0.05))
+- Replace filled card backgrounds with subtle borders or no container at all
+- Reduce border-radius
+
+**Calm the motion**
+- Remove section-fade animations that fire on every element
+- Reduce animation duration by 30–50%
+- Remove hover effects that aren't informative
+
+## The Constraint
+
+Quieter ≠ generic. The goal is precision and restraint, not the absence of a design point of view. If the result could be any brand's product, it's not quieter — it's erased. Preserve the brand's distinctive voice while removing the excess.