monomind 1.16.5 → 1.16.7

package/packages/@monomind/cli/.claude/skills/monodesign/reference/image-prompts.md

@@ -0,0 +1,130 @@
+# Image Prompts for Design
+
+Generate visual assets — hero imagery, product shots, illustrations, textures — that match the design system and pass the AI slop test.
+
+## Prompt Architecture
+
+Every effective prompt has these layers (order matters):
+
+```
+[Subject] + [Action/pose] + [Environment] + [Lighting] + [Technical specs] + [Style/mood] + [Negative constraints]
+```
+
+Example:
+```
+A UX designer in her mid-30s reviewing wireframes on a large monitor in a modern studio — natural diffused window light — shot on Sony A7III, 85mm f/1.8, shallow depth of field — editorial, desaturated warm tones — NOT stock photo pose, NOT overhead, no fake smile, no extra fingers
+```
+
+## Hero Image Patterns
+
+### Editorial/Product
+```
+[Subject doing real work] in [specific setting], photographed from [angle], 
+[focal length] lens, [lighting condition], [color palette descriptor matching design system],
+cinematic framing — NOT generic stock pose, NOT floating on white
+```
+
+### Abstract Texture/Background
+```
+[Material type] surface, [specific color in OKLCH descriptors], 
+macro photography, [lighting angle], 4K detail — 
+grain: subtle, no harsh shadows, no digital artifacts
+```
+
+### Data Visualization / Illustration
+```
+Clean vector-style illustration, [subject], [color palette: limited to 3 colors], 
+flat design with subtle depth, white/cream background, 
+professional technical style — NOT clipart, NOT gradients, NOT beveled edges
+```
+
+## Inclusive Representation
+
+Default to diversity without tokenism. The goal is accuracy, not optics.
+
+**Do:**
+- Specify age ranges explicitly — "42-year-old" not "middle-aged"
+- Anchor subjects in culturally accurate environments (correct architecture, clothing, props)
+- Use natural lighting that accurately renders different skin tones — diffused or golden hour
+- Include disability representation matter-of-factly: "software engineer using a motorized wheelchair at a standing desk"
+
+**Don't:**
+- Use vague descriptors ("diverse team") — they produce clone faces with name tags
+- Use dramatic lighting that washes out melanin
+- Default to stock-photo "multicultural handshake" compositions
+- Let AI guess on cultural specifics — name them explicitly
+
+**Anti-bias constraints (append to any people prompt):**
+```
+NOT stock photo composition, NOT identical faces, NOT exoticized lighting, 
+realistic proportions, authentic environmental context, 
+no performative diversity staging
+```
+
+## Photography Style by Design Register
+
+### Brand register (landing pages, marketing)
+```
+[Subject], editorial photography style, [season/time], 
+[specific film look: Kodak Portra 400 / CineStill 800T / Fuji Pro 400H],
+natural grain, intentional composition — NOT overprocessed, NOT HDR
+```
+
+### Product register (dashboards, apps)
+```
+Person [performing actual task with product], documentary style,
+environment lighting, candid posture, monitor showing [realistic UI content] —
+NOT posed, NOT smiling at camera, NOT showing screen reflection
+```
+
+## Asset Types and When to Generate
+
+| Asset type | When to generate | When to use CSS instead |
+|---|---|---|
+| Hero background | Abstract, textural, atmospheric | Geometric, color-block, gradient |
+| Person photography | Real human context matters | Illustration suffices |
+| Product screenshots | None — always use real screenshots | — |
+| Icons | Never — use an icon library | Always |
+| Decorative marks / badges | Brand/campaign specific | Logo SVG suffices |
+| Pattern / texture | Surface richness needed | CSS noise/grain pattern |
+| Scene illustration | Concept explanation, empty state | CSS + SVG shapes |
+
+## Image Generation Workflow
+
+1. Write the subject and context first, before any style descriptors
+2. Add lighting explicitly — lighting determines if the image reads as editorial or stock
+3. Add technical specs (lens, camera model) only for photography prompts
+4. Append negative constraints last — they filter, not define
+5. Generate 3 variations at minimum; choose by fit to design brief
+6. Check: Does this pass the "could someone tell AI made this?" test?
+
+### Raster Asset Production Workflow
+
+When a design mock has been approved and needs to be broken into clean, production-ready raster assets (crops, cutouts, textures, clean plates), use the **`monodesign-asset-producer`** agent. It provides a structured production workflow that:
+
+- Classifies each visual role into `produce`, `direct`, or `semantic` buckets
+- Applies the prompt pattern above for image-to-image clean-plate generation
+- Removes baked-in UI chrome (nav, buttons, labels, card borders, shadows) from rasters
+- Hands off semantic elements (icons, logos, charts) to HTML/CSS/SVG with concrete implementation notes
+- Returns a full manifest with `qa_status` for every asset
+
+Invoke it from the parent craft agent when raster production work is scoped: provide the approved mock path, crop ids or a contact sheet, output directory, and format/dimension requirements.
+
+## Prompt Anti-Patterns
+
+| Don't write | Write instead |
+|---|---|
+| "A happy team collaborating" | "Three engineers reviewing a pull request diff on a shared monitor, focused expressions, late afternoon office light" |
+| "Modern business professional" | "CPO at a Series B SaaS company, early 50s, during a strategy session, casual attire" |
+| "Beautiful woman using laptop" | "UX researcher, late 20s, conducting a remote usability interview — double monitor setup, notes visible, concentration" |
+| "Diverse people smiling" | "A four-person product team celebrating a launch, candid shot, conference room with big windows" |
+| "Abstract technology" | "Blurred PCB macro, copper traces, shallow depth of field, cool-toned ambient light" |
+
+## Checking Against the Design System
+
+Before using a generated image:
+1. Color temperature matches design system warm/cool bias
+2. Composition leaves space for text overlay if needed (sky, wall, desk surface)
+3. Image subject doesn't compete with the primary CTA
+4. No logos, recognizable brands, or copyright-compromising content
+5. Accessible alt text can describe this image in one sentence

package/packages/@monomind/cli/.claude/skills/monodesign/reference/interaction-design.md

@@ -0,0 +1,195 @@
+# Interaction Design
+
+## The Eight Interactive States
+
+Every interactive element needs these states designed:
+
+| State | When | Visual Treatment |
+|-------|------|------------------|
+| **Default** | At rest | Base styling |
+| **Hover** | Pointer over (not touch) | Subtle lift, color shift |
+| **Focus** | Keyboard/programmatic focus | Visible ring (see below) |
+| **Active** | Being pressed | Pressed in, darker |
+| **Disabled** | Not interactive | Reduced opacity, no pointer |
+| **Loading** | Processing | Spinner, skeleton |
+| **Error** | Invalid state | Red border, icon, message |
+| **Success** | Completed | Green check, confirmation |
+
+**The common miss**: Designing hover without focus, or vice versa. They're different. Keyboard users never see hover states.
+
+## Focus Rings: Do Them Right
+
+**Never `outline: none` without replacement.** It's an accessibility violation. Instead, use `:focus-visible` to show focus only for keyboard users:
+
+```css
+/* Hide focus ring for mouse/touch */
+button:focus {
+  outline: none;
+}
+
+/* Show focus ring for keyboard */
+button:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}
+```
+
+**Focus ring design**:
+- High contrast (3:1 minimum against adjacent colors)
+- 2-3px thick
+- Offset from element (not inside it)
+- Consistent across all interactive elements
+
+## Form Design: The Non-Obvious
+
+**Placeholders aren't labels.** They disappear on input. Always use visible `<label>` elements. **Validate on blur**, not on every keystroke (exception: password strength). Place errors **below** fields with `aria-describedby` connecting them.
+
+## Loading States
+
+**Optimistic updates**: Show success immediately, rollback on failure. Use for low-stakes actions (likes, follows), not payments or destructive actions. **Skeleton screens > spinners**: they preview content shape and feel faster than generic spinners.
+
+## Modals: The Inert Approach
+
+Focus trapping in modals used to require complex JavaScript. Now use the `inert` attribute:
+
+```html
+<!-- When modal is open -->
+<main inert>
+  <!-- Content behind modal can't be focused or clicked -->
+</main>
+<dialog open>
+  <h2>Modal Title</h2>
+  <!-- Focus stays inside modal -->
+</dialog>
+```
+
+Or use the native `<dialog>` element:
+
+```javascript
+const dialog = document.querySelector('dialog');
+dialog.showModal();  // Opens with focus trap, closes on Escape
+```
+
+## The Popover API
+
+For tooltips, dropdowns, and non-modal overlays, use native popovers:
+
+```html
+<button popovertarget="menu">Open menu</button>
+<div id="menu" popover>
+  <button>Option 1</button>
+  <button>Option 2</button>
+</div>
+```
+
+**Benefits**: Light-dismiss (click outside closes), proper stacking, no z-index wars, accessible by default.
+
+## Dropdown & Overlay Positioning
+
+Dropdowns rendered with `position: absolute` inside a container that has `overflow: hidden` or `overflow: auto` will be clipped. This is the single most common dropdown bug in generated code.
+
+### CSS Anchor Positioning
+
+The modern solution uses the CSS Anchor Positioning API to tether an overlay to its trigger without JavaScript:
+
+```css
+.trigger {
+  anchor-name: --menu-trigger;
+}
+
+.dropdown {
+  position: fixed;
+  position-anchor: --menu-trigger;
+  position-area: block-end span-inline-end;
+  margin-top: 4px;
+}
+
+/* Flip above if no room below */
+@position-try --flip-above {
+  position-area: block-start span-inline-end;
+  margin-bottom: 4px;
+}
+```
+
+Because the dropdown uses `position: fixed`, it escapes any `overflow` clipping on ancestor elements. The `@position-try` block handles viewport edges automatically. **Browser support**: Chrome 125+, Edge 125+. Not yet in Firefox or Safari - use a fallback for those browsers.
+
+### Popover + Anchor Combo
+
+Combining the Popover API with anchor positioning gives you stacking, light-dismiss, accessibility, and correct positioning in one pattern:
+
+```html
+<button popovertarget="menu" class="trigger">Open</button>
+<div id="menu" popover class="dropdown">
+  <button>Option 1</button>
+  <button>Option 2</button>
+</div>
+```
+
+The `popover` attribute places the element in the **top layer**, which sits above all other content regardless of z-index or overflow. No portal needed.
+
+### Portal / Teleport Pattern
+
+In component frameworks, render the dropdown at the document root and position it with JavaScript:
+
+- **React**: `createPortal(dropdown, document.body)`
+- **Vue**: `<Teleport to="body">`
+- **Svelte**: Use a portal library or mount to `document.body`
+
+Calculate position from the trigger's `getBoundingClientRect()`, then apply `position: fixed` with `top` and `left` values. Recalculate on scroll and resize.
+
+### Fixed Positioning Fallback
+
+For browsers without anchor positioning support, `position: fixed` with manual coordinates avoids overflow clipping:
+
+```css
+.dropdown {
+  position: fixed;
+  /* top/left set via JS from trigger's getBoundingClientRect() */
+}
+```
+
+Check viewport boundaries before rendering. If the dropdown would overflow the bottom edge, flip it above the trigger. If it would overflow the right edge, align it to the trigger's right side instead.
+
+### Anti-Patterns
+
+- **`position: absolute` inside `overflow: hidden`** - The dropdown will be clipped. Use `position: fixed` or the top layer instead.
+- **Arbitrary z-index values** like `z-index: 9999` - Use a semantic z-index scale: `dropdown (100) -> sticky (200) -> modal-backdrop (300) -> modal (400) -> toast (500) -> tooltip (600)`.
+- **Rendering dropdown markup inline** without an escape hatch from the parent's stacking context. Either use `popover` (top layer), a portal, or `position: fixed`.
+
+## Destructive Actions: Undo > Confirm
+
+**Undo is better than confirmation dialogs.** Users click through confirmations mindlessly. Remove from UI immediately, show undo toast, actually delete after toast expires. Use confirmation only for truly irreversible actions (account deletion), high-cost actions, or batch operations.
+
+## Keyboard Navigation Patterns
+
+### Roving Tabindex
+
+For component groups (tabs, menu items, radio groups), one item is tabbable; arrow keys move within:
+
+```html
+<div role="tablist">
+  <button role="tab" tabindex="0">Tab 1</button>
+  <button role="tab" tabindex="-1">Tab 2</button>
+  <button role="tab" tabindex="-1">Tab 3</button>
+</div>
+```
+
+Arrow keys move `tabindex="0"` between items. Tab moves to the next component entirely.
+
+### Skip Links
+
+Provide skip links (`<a href="#main-content">Skip to main content</a>`) for keyboard users to jump past navigation. Hide off-screen, show on focus.
+
+## Gesture Discoverability
+
+Swipe-to-delete and similar gestures are invisible. Hint at their existence:
+
+- **Partially reveal**: Show delete button peeking from edge
+- **Onboarding**: Coach marks on first use
+- **Alternative**: Always provide a visible fallback (menu with "Delete")
+
+Don't rely on gestures as the only way to perform actions.
+
+---
+
+**Avoid**: Removing focus indicators without alternatives. Using placeholder text as labels. Touch targets <44x44px. Generic error messages. Custom controls without ARIA/keyboard support.

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

@@ -0,0 +1,141 @@
+Space is the most underused design tool. Find the layout's actual problem (monotone spacing, weak hierarchy, identical card grids, the centered-stack default) and fix the structure, not the surface.
+
+---
+
+## Register
+
+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.
+
+---
+
+## Assess Current Layout
+
+Analyze what's weak about the current spatial design:
+
+1. **Spacing**:
+   - Is spacing consistent or arbitrary? (Random padding/margin values)
+   - Is all spacing the same? (Equal padding everywhere = no rhythm)
+   - Are related elements grouped tightly, with generous space between groups?
+
+2. **Visual hierarchy**:
+   - Apply the squint test: blur your (metaphorical) eyes. Can you still identify the most important element, second most important, and clear groupings?
+   - Is hierarchy achieved effectively? (Space and weight alone can be enough; is the current approach working?)
+   - Does whitespace guide the eye to what matters?
+
+3. **Grid & structure**:
+   - Is there a clear underlying structure, or does the layout feel random?
+   - Are identical card grids used everywhere? (Icon + heading + text, repeated endlessly)
+   - Is everything centered? (Left-aligned with asymmetric layouts feels more designed, but not a hard and fast rule)
+
+4. **Rhythm & variety**:
+   - Does the layout have visual rhythm? (Alternating tight/generous spacing)
+   - Is every section structured the same way? (Monotonous repetition)
+   - Are there intentional moments of surprise or emphasis?
+
+5. **Density**:
+   - Is the layout too cramped? (Not enough breathing room)
+   - Is the layout too sparse? (Excessive whitespace without purpose)
+   - Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air)
+
+**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material; use it with intention.
+
+## Plan Layout Improvements
+
+Consult the [spatial design reference](spatial-design.md) for detailed guidance on grids, rhythm, and container queries.
+
+Create a systematic plan:
+
+- **Spacing system**: Use a consistent scale (a framework's built-in scale like Tailwind's, rem-based tokens, or a custom system). The specific values matter less than consistency.
+- **Hierarchy strategy**: How will space communicate importance?
+- **Layout approach**: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts.
+- **Rhythm**: Where should spacing be tight vs generous?
+
+## Improve Layout Systematically
+
+### Establish a Spacing System
+
+- Use a consistent spacing scale (framework scales like Tailwind, rem-based tokens, or a custom scale all work). What matters is that values come from a defined set, not arbitrary numbers.
+- Name tokens semantically if using custom properties: `--space-xs` through `--space-xl`, not `--spacing-8`
+- Use `gap` for sibling spacing instead of margins; eliminates margin collapse hacks
+- Apply `clamp()` for fluid spacing that breathes on larger screens
+
+### Create Visual Rhythm
+
+- **Tight grouping** for related elements (8-12px between siblings)
+- **Generous separation** between distinct sections (48-96px)
+- **Varied spacing** within sections (not every row needs the same gap)
+- **Asymmetric compositions**: break the predictable centered-content pattern when it makes sense
+
+### Choose the Right Layout Tool
+
+- **Use Flexbox for 1D layouts**: Rows of items, nav bars, button groups, card contents, most component internals. Flex is simpler and more appropriate for the majority of layout tasks.
+- **Use Grid for 2D layouts**: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control.
+- **Don't default to Grid** when Flexbox with `flex-wrap` would be simpler and more flexible.
+- Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints.
+- Use named grid areas (`grid-template-areas`) for complex page layouts; redefine at breakpoints.
+
+### Break Card Grid Monotony
+
+- Don't default to card grids for everything; spacing and alignment create visual grouping naturally
+- Use cards only when content is truly distinct and actionable. Never nest cards inside cards
+- Vary card sizes, span columns, or mix cards with non-card content to break repetition
+
+### Strengthen Visual Hierarchy
+
+- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough; generous whitespace around an element draws the eye. Some of the most polished designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means aren't sufficient.
+- Be aware of reading flow: in LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
+- Create clear content groupings through proximity and separation.
+
+### Manage Depth & Elevation
+
+- Create a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip)
+- Build a consistent shadow scale (sm → md → lg → xl); shadows should be subtle
+- Use elevation to reinforce hierarchy, not as decoration
+
+### Optical Adjustments
+
+- If an icon looks visually off-center despite being geometrically centered, nudge it. But only if you're confident it actually looks wrong. Don't adjust speculatively.
+
+**NEVER**:
+- Use arbitrary spacing values outside your scale
+- Make all spacing equal (variety creates hierarchy)
+- Wrap everything in cards (not everything needs a container)
+- Nest cards inside cards (use spacing and dividers for hierarchy within)
+- Use identical card grids everywhere (icon + heading + text, repeated)
+- Center everything (left-aligned with asymmetry feels more designed)
+- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work, but it should display actual data, not decorative numbers.
+- Default to CSS Grid when Flexbox would be simpler; use the simplest tool for the job
+- Use arbitrary z-index values (999, 9999); build a semantic scale
+
+## Verify Layout Improvements
+
+- **Squint test**: Can you identify primary, secondary, and groupings with blurred vision?
+- **Rhythm**: Does the page have a satisfying beat of tight and generous spacing?
+- **Hierarchy**: Is the most important content obvious within 2 seconds?
+- **Breathing room**: Does the layout feel comfortable, not cramped or wasteful?
+- **Consistency**: Is the spacing system applied uniformly?
+- **Responsiveness**: Does the layout adapt gracefully across screen sizes?
+
+When the rhythm and hierarchy land, hand off to `/monodesign polish` for the final pass.
+
+## Live-mode signature params
+
+Each variant MUST declare a `density` param. Drive all spacing tokens in the variant's scoped CSS through `calc(var(--p-density, 1) * <base>)`: paddings, gaps, column widths. Users slide from airy to packed and see layout re-breathe with no regeneration.
+
+```json
+{"id":"density","kind":"range","min":0.6,"max":1.4,"step":0.05,"default":1,"label":"Density"}
+```
+
+For variants whose topology genuinely changes (stacked vs. side-by-side, grid vs. bento), use a `steps` param whose scoped CSS branches via `:scope[data-p-structure="X"]`. One structure param + one density param is a powerful combo; resist adding a third.
+
+```json
+{"id":"structure","kind":"steps","default":"grid","label":"Structure","options":[
+  {"value":"stacked","label":"Stacked"},
+  {"value":"grid","label":"Grid"},
+  {"value":"bento","label":"Bento"}
+]}
+```
+
+See `reference/live.md` for the full params contract.