monomind 1.16.5 → 1.16.7

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

@@ -0,0 +1,59 @@
+---
+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.
+type: design-sub-command
+argument-hint: "[target URL or component]"
+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.
+
+## CLAUDE.md Requirement
+
+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.
+
+## Live Iteration Loop
+
+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.
+
+## 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

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.

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

@@ -0,0 +1,190 @@
+> **Additional context needed**: target platforms/devices and usage contexts.
+
+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.
+
+
+---
+
+## Assess Adaptation Challenge
+
+Understand what needs adaptation and why:
+
+1. **Identify the source context**:
+   - What was it designed for originally? (Desktop web? Mobile app?)
+   - What assumptions were made? (Large screen? Mouse input? Fast connection?)
+   - What works well in current context?
+
+2. **Understand target context**:
+   - **Device**: Mobile, tablet, desktop, TV, watch, print?
+   - **Input method**: Touch, mouse, keyboard, voice, gamepad?
+   - **Screen constraints**: Size, resolution, orientation?
+   - **Connection**: Fast wifi, slow 3G, offline?
+   - **Usage context**: On-the-go vs desk, quick glance vs focused reading?
+   - **User expectations**: What do users expect on this platform?
+
+3. **Identify adaptation challenges**:
+   - What won't fit? (Content, navigation, features)
+   - What won't work? (Hover states on touch, tiny touch targets)
+   - What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)
+
+**CRITICAL**: Adaptation is rethinking the experience for the new context, not scaling pixels.
+
+## Plan Adaptation Strategy
+
+Create context-appropriate strategy:
+
+### Mobile Adaptation (Desktop → Mobile)
+
+**Layout Strategy**:
+- Single column instead of multi-column
+- Vertical stacking instead of side-by-side
+- Full-width components instead of fixed widths
+- Bottom navigation instead of top/side navigation
+
+**Interaction Strategy**:
+- Touch targets 44x44px minimum (not hover-dependent)
+- Swipe gestures where appropriate (lists, carousels)
+- Bottom sheets instead of dropdowns
+- Thumbs-first design (controls within thumb reach)
+- Larger tap areas with more spacing
+
+**Content Strategy**:
+- Progressive disclosure (don't show everything at once)
+- Prioritize primary content (secondary content in tabs/accordions)
+- Shorter text (more concise)
+- Larger text (16px minimum)
+
+**Navigation Strategy**:
+- Hamburger menu or bottom navigation
+- Reduce navigation complexity
+- Sticky headers for context
+- Back button in navigation flow
+
+### Tablet Adaptation (Hybrid Approach)
+
+**Layout Strategy**:
+- Two-column layouts (not single or three-column)
+- Side panels for secondary content
+- Master-detail views (list + detail)
+- Adaptive based on orientation (portrait vs landscape)
+
+**Interaction Strategy**:
+- Support both touch and pointer
+- Touch targets 44x44px but allow denser layouts than phone
+- Side navigation drawers
+- Multi-column forms where appropriate
+
+### Desktop Adaptation (Mobile → Desktop)
+
+**Layout Strategy**:
+- Multi-column layouts (use horizontal space)
+- Side navigation always visible
+- Multiple information panels simultaneously
+- Fixed widths with max-width constraints (don't stretch to 4K)
+
+**Interaction Strategy**:
+- Hover states for additional information
+- Keyboard shortcuts
+- Right-click context menus
+- Drag and drop where helpful
+- Multi-select with Shift/Cmd
+
+**Content Strategy**:
+- Show more information upfront (less progressive disclosure)
+- Data tables with many columns
+- Richer visualizations
+- More detailed descriptions
+
+### Print Adaptation (Screen → Print)
+
+**Layout Strategy**:
+- Page breaks at logical points
+- Remove navigation, footer, interactive elements
+- Black and white (or limited color)
+- Proper margins for binding
+
+**Content Strategy**:
+- Expand shortened content (show full URLs, hidden sections)
+- Add page numbers, headers, footers
+- Include metadata (print date, page title)
+- Convert charts to print-friendly versions
+
+### Email Adaptation (Web → Email)
+
+**Layout Strategy**:
+- Narrow width (600px max)
+- Single column only
+- Inline CSS (no external stylesheets)
+- Table-based layouts (for email client compatibility)
+
+**Interaction Strategy**:
+- Large, obvious CTAs (buttons not text links)
+- No hover states (not reliable)
+- Deep links to web app for complex interactions
+
+## Implement Adaptations
+
+Apply changes systematically:
+
+### Responsive Breakpoints
+
+Choose appropriate breakpoints:
+- Mobile: 320px-767px
+- Tablet: 768px-1023px
+- Desktop: 1024px+
+- Or content-driven breakpoints (where design breaks)
+
+### Layout Adaptation Techniques
+
+- **CSS Grid/Flexbox**: Reflow layouts automatically
+- **Container Queries**: Adapt based on container, not viewport
+- **`clamp()`**: Fluid sizing between min and max
+- **Media queries**: Different styles for different contexts
+- **Display properties**: Show/hide elements per context
+
+### Touch Adaptation
+
+- Increase touch target sizes (44x44px minimum)
+- Add more spacing between interactive elements
+- Remove hover-dependent interactions
+- Add touch feedback (ripples, highlights)
+- Consider thumb zones (easier to reach bottom than top)
+
+### Content Adaptation
+
+- Use `display: none` sparingly (still downloads)
+- Progressive enhancement (core content first, enhancements on larger screens)
+- Lazy loading for off-screen content
+- Responsive images (`srcset`, `picture` element)
+
+### Navigation Adaptation
+
+- Transform complex nav to hamburger/drawer on mobile
+- Bottom nav bar for mobile apps
+- Persistent side navigation on desktop
+- Breadcrumbs on smaller screens for context
+
+**IMPORTANT**: Test on real devices. Device emulation in DevTools is helpful but not perfect.
+
+**NEVER**:
+- Hide core functionality on mobile (if it matters, make it work)
+- Assume desktop = powerful device (consider accessibility, older machines)
+- Use different information architecture across contexts (confusing)
+- Break user expectations for platform (mobile users expect mobile patterns)
+- Forget landscape orientation on mobile/tablet
+- Use generic breakpoints blindly (use content-driven breakpoints)
+- Ignore touch on desktop (many desktop devices have touch)
+
+## Verify Adaptations
+
+Test thoroughly across contexts:
+
+- **Real devices**: Test on actual phones, tablets, desktops
+- **Different orientations**: Portrait and landscape
+- **Different browsers**: Safari, Chrome, Firefox, Edge
+- **Different OS**: iOS, Android, Windows, macOS
+- **Different input methods**: Touch, mouse, keyboard
+- **Edge cases**: Very small screens (320px), very large screens (4K)
+- **Slow connections**: Test on throttled network
+
+When the adaptation feels native to each context, hand off to `/monodesign polish` for the final pass.