monomind 1.10.1 → 1.10.2

package/.claude/skills/monodesign/reference/color-and-contrast.md

@@ -0,0 +1,105 @@
+# Color & Contrast
+
+## Color Spaces: Use OKLCH
+
+**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal, unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.
+
+The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness, but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish.
+
+The hue you pick is a brand decision and should not come from a default. Do not reach for blue (hue 250) or warm orange (hue 60) by reflex; those are the dominant AI-design defaults, not the right answer for any specific brand.
+
+## Building Functional Palettes
+
+### Tinted Neutrals
+
+**Pure gray is dead.** A neutral with zero chroma feels lifeless next to a colored brand. Add a tiny chroma value (0.005-0.015) to all your neutrals, hued toward whatever your brand color is. The chroma is small enough not to read as "tinted" consciously, but it creates subconscious cohesion between brand color and UI surfaces.
+
+The hue you tint toward should come from THIS project's brand, not from a "warm = friendly, cool = tech" formula. If your brand color is teal, your neutrals lean toward teal. If your brand color is amber, they lean toward amber. The point is cohesion with the SPECIFIC brand, not a stock palette.
+
+**Avoid** the trap of always tinting toward warm orange or always tinting toward cool blue. Those are the two laziest defaults and they create their own monoculture across projects.
+
+### Palette Structure
+
+A complete system needs:
+
+| Role | Purpose | Example |
+|------|---------|---------|
+| **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades |
+| **Neutral** | Text, backgrounds, borders | 9-11 shade scale |
+| **Semantic** | Success, error, warning, info | 4 colors, 2-3 shades each |
+| **Surface** | Cards, modals, overlays | 2-3 elevation levels |
+
+**Skip secondary/tertiary unless you need them.** Most apps work fine with one accent color. Adding more creates decision fatigue and visual noise.
+
+### The 60-30-10 Rule (Applied Correctly)
+
+This rule is about **visual weight**, not pixel count:
+
+- **60%**: Neutral backgrounds, white space, base surfaces
+- **30%**: Secondary colors: text, borders, inactive states
+- **10%**: Accent: CTAs, highlights, focus states
+
+The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power.
+
+## Contrast & Accessibility
+
+### WCAG Requirements
+
+| Content Type | AA Minimum | AAA Target |
+|--------------|------------|------------|
+| Body text | 4.5:1 | 7:1 |
+| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 |
+| UI components, icons | 3:1 | 4.5:1 |
+| Non-essential decorations | None | None |
+
+**The gotcha**: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere? Usually fails WCAG.
+
+### Dangerous Color Combinations
+
+These commonly fail contrast or cause readability issues:
+
+- Light gray text on white (the #1 accessibility fail)
+- **Gray text on any colored background**: gray looks washed out and dead on color. Use a darker shade of the background color, or transparency
+- Red text on green background (or vice versa): 8% of men can't distinguish these
+- Blue text on red background (vibrates visually)
+- Yellow text on white (almost always fails)
+- Thin light text on images (unpredictable contrast)
+
+### Never Use Pure Gray or Pure Black
+
+Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature; real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.)
+
+### Testing
+
+Don't trust your eyes. Use tools:
+
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- Browser DevTools → Rendering → Emulate vision deficiencies
+- [Polypane](https://polypane.app/) for real-time testing
+
+## Theming: Light & Dark Mode
+
+### Dark Mode Is Not Inverted Light Mode
+
+You can't just swap colors. Dark mode requires different design decisions:
+
+| Light Mode | Dark Mode |
+|------------|-----------|
+| Shadows for depth | Lighter surfaces for depth (no shadows) |
+| Dark text on light | Light text on dark (reduce font weight) |
+| Vibrant accents | Desaturate accents slightly |
+| White backgrounds | Never pure black; use dark gray (oklch 12-18%) |
+
+In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project; do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light.
+
+### Token Hierarchy
+
+Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer; primitives stay the same.
+
+## Alpha Is A Design Smell
+
+Heavy use of transparency (rgba, hsla) usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency. Define explicit overlay colors for each context instead. Exception: focus rings and interactive states where see-through is needed.
+
+---
+
+**Avoid**: Relying on color alone to convey information. Creating palettes without clear roles for each color. Using pure black (#000) for large areas. Skipping color blindness testing (8% of men affected).

package/.claude/skills/monodesign/reference/colorize.md

@@ -0,0 +1,154 @@
+> **Additional context needed**: existing brand colors.
+
+Replace timid grayscale or single-accent designs with a strategic palette: pick a color strategy, choose a hue family that fits the brand, then apply color with intent. More color ≠ better. Strategic color beats rainbow vomit.
+
+---
+
+## Register
+
+Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule; that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it.
+
+Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators. Not decoration. Every color has a consistent meaning across every screen.
+
+---
+
+## Assess Color Opportunity
+
+Analyze the current state and identify opportunities:
+
+1. **Understand current state**:
+   - **Color absence**: Pure grayscale? Limited neutrals? One timid accent?
+   - **Missed opportunities**: Where could color add meaning, hierarchy, or delight?
+   - **Context**: What's appropriate for this domain and audience?
+   - **Brand**: Are there existing brand colors we should use?
+
+2. **Identify where color adds value**:
+   - **Semantic meaning**: Success (green), error (red), warning (yellow/orange), info (blue)
+   - **Hierarchy**: Drawing attention to important elements
+   - **Categorization**: Different sections, types, or states
+   - **Emotional tone**: Warmth, energy, trust, creativity
+   - **Wayfinding**: Helping users navigate and understand structure
+   - **Delight**: Moments of visual interest and personality
+
+If any of these are unclear from the codebase, Ask the user for clarification before proceeding.
+
+**CRITICAL**: More color ≠ better. Strategic color beats rainbow vomit every time. Every color should have a purpose.
+
+## Plan Color Strategy
+
+Create a purposeful color introduction plan:
+
+- **Color palette**: What colors match the brand/context? (Choose 2-4 colors max beyond neutrals)
+- **Dominant color**: Which color owns 60% of colored elements?
+- **Accent colors**: Which colors provide contrast and highlights? (30% and 10%)
+- **Application strategy**: Where does each color appear and why?
+
+**IMPORTANT**: Color should enhance hierarchy and meaning, not create chaos. Less is more when it matters more.
+
+## Introduce Color Strategically
+
+Add color systematically across these dimensions:
+
+### Semantic Color
+- **State indicators**:
+  - Success: Green tones (emerald, forest, mint)
+  - Error: Red/pink tones (rose, crimson, coral)
+  - Warning: Orange/amber tones
+  - Info: Blue tones (sky, ocean, indigo)
+  - Neutral: Gray/slate for inactive states
+
+- **Status badges**: Colored backgrounds or borders for states (active, pending, completed, etc.)
+- **Progress indicators**: Colored bars, rings, or charts showing completion or health
+
+### Accent Color Application
+- **Primary actions**: Color the most important buttons/CTAs
+- **Links**: Add color to clickable text (maintain accessibility)
+- **Icons**: Colorize key icons for recognition and personality
+- **Headers/titles**: Add color to section headers or key labels
+- **Hover states**: Introduce color on interaction
+
+### Background & Surfaces
+- **Tinted backgrounds**: Replace pure gray (`#f5f5f5`) with warm neutrals (`oklch(97% 0.01 60)`) or cool tints (`oklch(97% 0.01 250)`)
+- **Colored sections**: Use subtle background colors to separate areas
+- **Gradient backgrounds**: Add depth with subtle, intentional gradients (not generic purple-blue)
+- **Cards & surfaces**: Tint cards or surfaces slightly for warmth
+
+**Use OKLCH for color**: It's perceptually uniform, meaning equal steps in lightness *look* equal. Great for generating harmonious scales.
+
+### Data Visualization
+- **Charts & graphs**: Use color to encode categories or values
+- **Heatmaps**: Color intensity shows density or importance
+- **Comparison**: Color coding for different datasets or timeframes
+
+### Borders & Accents
+- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes; see the absolute ban on `border-left/right > 1px`)
+- **Underlines**: Color underlines for emphasis or active states
+- **Dividers**: Subtle colored dividers instead of gray lines
+- **Focus rings**: Colored focus indicators matching brand
+- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe
+
+**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix. Not a side stripe.
+
+### Typography Color
+- **Colored headings**: Use brand colors for section headings (maintain contrast)
+- **Highlight text**: Color for emphasis or categories
+- **Labels & tags**: Small colored labels for metadata or categories
+
+### Decorative Elements
+- **Illustrations**: Add colored illustrations or icons
+- **Shapes**: Geometric shapes in brand colors as background elements
+- **Gradients**: Colorful gradient overlays or mesh backgrounds
+- **Blobs/organic shapes**: Soft colored shapes for visual interest
+
+## Balance & Refinement
+
+Ensure color addition improves rather than overwhelms:
+
+### Maintain Hierarchy
+- **Dominant color** (60%): Primary brand color or most used accent
+- **Secondary color** (30%): Supporting color for variety
+- **Accent color** (10%): High contrast for key moments
+- **Neutrals** (remaining): Gray/black/white for structure
+
+### Accessibility
+- **Contrast ratios**: Ensure WCAG compliance (4.5:1 for text, 3:1 for UI components)
+- **Don't rely on color alone**: Use icons, labels, or patterns alongside color
+- **Test for color blindness**: Verify red/green combinations work for all users
+
+### Cohesion
+- **Consistent palette**: Use colors from defined palette, not arbitrary choices
+- **Systematic application**: Same color meanings throughout (green always = success)
+- **Temperature consistency**: Warm palette stays warm, cool stays cool
+
+**NEVER**:
+- Use every color in the rainbow (choose 2-4 colors beyond neutrals)
+- Apply color randomly without semantic meaning
+- Put gray text on colored backgrounds. It looks washed out; use a darker shade of the background color or transparency instead
+- Use pure gray for neutrals. Add subtle color tint (warm or cool) for depth
+- Use pure black (`#000`) or pure white (`#fff`) for large areas
+- Violate WCAG contrast requirements
+- Use color as the only indicator (accessibility issue)
+- Make everything colorful (defeats the purpose)
+- Default to purple-blue gradients (AI slop aesthetic)
+
+## Verify Color Addition
+
+Test that colorization improves the experience:
+
+- **Better hierarchy**: Does color guide attention appropriately?
+- **Clearer meaning**: Does color help users understand states/categories?
+- **More engaging**: Does the interface feel warmer and more inviting?
+- **Still accessible**: Do all color combinations meet WCAG standards?
+- **Not overwhelming**: Is color balanced and purposeful?
+
+When the palette earns its place, hand off to `/monodesign polish` for the final pass.
+
+## Live-mode signature params
+
+When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)`, typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage.
+
+```json
+{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"}
+```
+
+Layer 1-2 variant-specific params on top: palette selection (`steps` with named options), temperature warmth, or tint vs. true color. See `reference/live.md` for the full params contract.

package/.claude/skills/monodesign/reference/component-specs.md

@@ -0,0 +1,260 @@
+# Component Specifications
+
+Variants, sizes, states, and anatomy for core UI components. Use during `shape`, `critique`, and `extract` workflows to ensure components are fully specified.
+
+For the interactive state system (focus rings, disabled CSS, ARIA patterns), see `component-states.md`. For token references, see `token-architecture.md`. For the Editorial Sanctuary component specs (CTA, nav, card, email input), see `design-principles.md`.
+
+---
+
+## Button
+
+### Variants
+
+| Variant | Background | Text | Border | Use case |
+|---------|------------|------|--------|----------|
+| `default` | `--color-ink` | `--color-surface` | none | Primary actions |
+| `secondary` | `--color-mist` | `--color-ink` | none | Secondary actions |
+| `outline` | transparent | `--color-ink` | `1px --color-border` | Tertiary actions |
+| `ghost` | transparent | `--color-ink` | none | Subtle actions |
+| `link` | transparent | `--color-accent` | none | Inline navigation |
+| `destructive` | `oklch(55% 0.22 27)` | white | none | Dangerous actions |
+
+### Sizes
+
+| Size | Height | Padding X | Padding Y | Font size |
+|------|--------|-----------|-----------|-----------|
+| `sm` | 32px | 12px | 6px | 14px |
+| `default` | 40px | 16px | 8px | 14px |
+| `lg` | 48px | 24px | 12px | 16px |
+| `icon` | 40px | 0 | 0 | — |
+
+### States
+
+| State | Treatment |
+|-------|-----------|
+| default | Base appearance |
+| hover | Background shifts to `--color-accent` (primary variant) |
+| active | Darkest variant — `oklch(42% 0.22 350)` |
+| focus | Focus ring — see `component-states.md` |
+| disabled | 50% opacity + `cursor: not-allowed` + `pointer-events: none` |
+| loading | 70% opacity + spinner, button disabled |
+
+### Anatomy
+
+```
+┌──────────────────────────────────────┐
+│  [icon]   Label Text   [icon]        │
+└──────────────────────────────────────┘
+     ↑                       ↑
+  leading icon          trailing icon
+```
+
+**Editorial Sanctuary CTA note:** Primary CTAs use `border-radius: 0`, uppercase label, `letter-spacing: 0.08em`. See `design-principles.md`.
+
+---
+
+## Input
+
+### Variants
+
+| Variant | Description |
+|---------|-------------|
+| `text` | Standard single-line text |
+| `textarea` | Multi-line text |
+| `select` | Dropdown selection |
+| `checkbox` | Boolean toggle |
+| `radio` | Single-from-group selection |
+| `switch` | On/off toggle |
+
+### Sizes
+
+| Size | Height | Padding | Font size |
+|------|--------|---------|-----------|
+| `sm` | 32px | 8px 12px | 14px |
+| `default` | 40px | 8px 12px | 14px |
+| `lg` | 48px | 12px 16px | 16px |
+
+### States
+
+| State | Border | Ring |
+|-------|--------|------|
+| default | `--color-border` | none |
+| hover | `--color-ash` | none |
+| focus | `--color-accent` | `--color-accent-dim` (3px) |
+| error | `oklch(55% 0.22 27)` | `oklch(55% 0.22 27 / 0.2)` |
+| disabled | `--color-mist` | none |
+
+### Anatomy
+
+```
+Label                    (required marker if applicable)
+┌────────────────────────────────────────┐
+│  [icon]   Placeholder / Value  [clear] │
+└────────────────────────────────────────┘
+Helper text — or error message in error state
+```
+
+**Rule:** Always pair with a `<label>`. Placeholder alone is not a label. Helper text is persistent; error text appears after blur on invalid input.
+
+---
+
+## Card
+
+### Variants
+
+| Variant | Shadow | Border | Use case |
+|---------|--------|--------|----------|
+| `default` | none at rest → `--shadow-md` on hover | `1px --color-border` | Standard container |
+| `elevated` | `--shadow-lg` | none | Prominent / featured content |
+| `outline` | none | `1px --color-border` | Subtle container |
+| `interactive` | none → `--shadow-md` | `1px --color-border` | Clickable card |
+
+**Flat-by-default rule:** Cards have no shadow at rest. Shadow appears only on hover or deliberate elevation. See `design-principles.md` Rule 7.
+
+### Anatomy
+
+```
+┌─────────────────────────────────────┐
+│  Card Header                        │
+│    Title                            │
+│    Description                      │
+├─────────────────────────────────────┤
+│  Card Content                       │
+│    Main content area                │
+│                                     │
+├─────────────────────────────────────┤
+│  Card Footer                        │
+│    Actions                          │
+└─────────────────────────────────────┘
+```
+
+### Spacing
+
+| Area | Padding |
+|------|---------|
+| header | 24px 24px 0 |
+| content | 24px |
+| footer | 0 24px 24px |
+| gap between sections | 16px |
+
+**Never nest cards.** Nested cards are an absolute antipattern. Use a list, section divider, or table instead.
+
+---
+
+## Badge / Tag
+
+### Variants
+
+| Variant | Background | Text |
+|---------|------------|------|
+| `default` | `--color-ink` | white |
+| `secondary` | `--color-mist` | `--color-ink` |
+| `outline` | transparent | `--color-ink` |
+| `success` | `oklch(55% 0.18 145 / 0.15)` | `oklch(40% 0.18 145)` |
+| `warning` | `oklch(72% 0.17 60 / 0.15)` | `oklch(52% 0.17 60)` |
+| `destructive` | `oklch(55% 0.22 27 / 0.15)` | `oklch(40% 0.22 27)` |
+
+### Sizes
+
+| Size | Padding | Font size | Height |
+|------|---------|-----------|--------|
+| `sm` | 2px 6px | 11px | 18px |
+| `default` | 4px 8px | 12px | 22px |
+| `lg` | 4px 10px | 13px | 26px |
+
+**Typography rule:** Badge labels are uppercase, tracked (`letter-spacing: 0.06em`), max 3 words.
+
+---
+
+## Alert / Callout
+
+### Variants
+
+| Variant | Icon | Background | Border |
+|---------|------|------------|--------|
+| `info` | ⓘ | `oklch(92% 0 0)` | `oklch(80% 0 0)` |
+| `success` | ✓ | `oklch(55% 0.18 145 / 0.08)` | `oklch(55% 0.18 145 / 0.3)` |
+| `warning` | ⚠ | `oklch(72% 0.17 60 / 0.08)` | `oklch(72% 0.17 60 / 0.3)` |
+| `destructive` | ✕ | `oklch(55% 0.22 27 / 0.08)` | `oklch(55% 0.22 27 / 0.3)` |
+
+### Anatomy
+
+```
+┌─────────────────────────────────────┐
+│  [icon]  Title                  [×] │
+│          Supporting description     │
+└─────────────────────────────────────┘
+```
+
+**Side-tab rule:** Never use a colored `border-left` stripe on callouts. Use full border + background tint instead. See `antipatterns-catalog.md` (`side-tab`).
+
+---
+
+## Dialog / Modal
+
+### Sizes
+
+| Size | Max-width | Use case |
+|------|-----------|----------|
+| `sm` | 384px | Simple confirmations |
+| `default` | 512px | Standard dialogs |
+| `lg` | 640px | Forms, complex content |
+| `xl` | 768px | Data-heavy dialogs |
+| `full` | 100vw − 32px | Full-screen on mobile |
+
+### Anatomy
+
+```
+┌─────────────────────────────────────────┐
+│  Dialog Header                       [×]│
+│    Title                                │
+│    Description (optional)               │
+├─────────────────────────────────────────┤
+│  Dialog Content                         │
+│    Scrollable area                      │
+│                                         │
+├─────────────────────────────────────────┤
+│  Dialog Footer                          │
+│                        [Cancel] [Action]│
+└─────────────────────────────────────────┘
+```
+
+**Rules:**
+- Always provide a close affordance (✕ button + ESC key)
+- Confirm before closing a dialog with unsaved changes
+- Don't use dialogs for primary navigation flows
+- Destructive confirm dialogs: action button uses destructive variant and is placed right; Cancel is left
+
+---
+
+## Table
+
+### Row States
+
+| State | Background |
+|-------|------------|
+| default | `--color-surface` |
+| hover | `--color-paper` |
+| selected | `oklch(60% 0.25 350 / 0.08)` |
+| striped (alt) | `--color-paper` / `--color-surface` |
+
+### Cell Alignment
+
+| Content type | Alignment |
+|--------------|-----------|
+| Text | Left |
+| Numbers / currency | Right |
+| Status / badges | Center |
+| Actions | Right |
+
+### Spacing
+
+| Element | Value |
+|---------|-------|
+| Cell padding | 12px 16px |
+| Header padding | 12px 16px |
+| Row height (compact) | 40px |
+| Row height (default) | 48px |
+| Row height (comfortable) | 56px |
+
+**Accessibility:** Column headers use `scope="col"`. Sortable columns use `aria-sort="ascending|descending|none"`. Interactive rows have `role="button"` or are wrapped in `<a>`.