monomind 2.5.1 → 2.5.3

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

@@ -1,14 +1,14 @@
-<!-- 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 51 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)
+- **quality** — Design principle violations including contrast, motion, readability, and semantic structure (24 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.
@@ -223,6 +226,14 @@ These are the two categories the `impeccable detect` engine uses:
 **Why it's wrong:** Cramped elements are hard to read, harder to click, and communicate low quality. 8px is the absolute minimum; 16px is the default.  
 **Fix:** Minimum 12px padding inside cards. Minimum 10px vertical + 16px horizontal on buttons. Minimum 44×44px touch targets.
 
+### `dark-scheme-contrast-blindspot` — Dark-scheme contrast blindspot
+
+**Detect** (advisory): The page ships dark styling (a `@media (prefers-color-scheme: dark)` block or a `.dark` / `[data-theme=dark]` scope), but for some selector the dark override changes the background without changing the paired text color — or the reverse — while the light scheme defined both.
+
+**Why it's wrong**: A half-updated color pair often collapses to unreadable contrast in dark mode (dark text left on a newly-dark background). It's the most common dark-mode regression and easy to miss because the light scheme looks fine.
+
+**Fix**: Override text and background together for the same selector, or verify the inherited half still contrasts against the changed half. Prefer semantic tokens (`--fg` / `--bg`) that flip as a pair.
+
 ### `design-system-color` — Color outside DESIGN.md
 
 **Detect**: A literal color value used in CSS that is not declared in the project's `DESIGN.md` palette or its tonal ramps.
@@ -239,6 +250,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.
@@ -252,6 +271,22 @@ These are the two categories the `impeccable detect` engine uses:
 **Why it's wrong:** Gray text on colored backgrounds almost always fails WCAG contrast requirements and looks muddy.  
 **Fix:** Use white or the appropriate neutral from the color ramp. Never use a generic gray on a tinted background.
 
+### `hover-only-affordance` — Functionality gated behind hover only
+
+**Detect**: An element is hidden by default (`display: none`, `visibility: hidden`, or `opacity: 0`) and revealed only via a `:hover` rule on an ancestor, with no matching `:focus`, `:focus-within`, or `:active` rule.
+
+**Why it's wrong**: Hover doesn't exist on touch devices and can't be reached by keyboard. Anything gated behind hover alone is invisible and unusable for a large share of users.
+
+**Fix**: Mirror every hover reveal with a `:focus-within` (or `:active`) rule targeting the same element, so the affordance is reachable without a pointer.
+
+### `image-missing-dimensions` — Image without reserved dimensions
+
+**Detect**: An `<img>` ships without both `width` and `height` attributes and without a CSS `aspect-ratio` or explicit height.
+
+**Why it's wrong**: The browser can't reserve space before the image loads, so surrounding content jumps when it arrives — cumulative layout shift (CLS), a Core Web Vitals failure and a jarring experience.
+
+**Fix**: Set `width` and `height` attributes (the browser derives the aspect ratio), or give the image a CSS `aspect-ratio`. Either reserves the box before load.
+
 ### `justified-text` — Justified text
 **Detect:** `text-align: justify` on paragraph elements.  
 **Why it's wrong:** CSS text justification creates uneven word spacing (rivers of white) because browsers don't hyphenate automatically. It reads as broken on web.  
@@ -270,18 +305,29 @@ 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.
+**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.
 
-### `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.
+### `missing-focus-visible` — Suppressed focus outline with no replacement
+
+**Detect**: An interactive element (link, button, input, `[role=button]`) removes its focus outline (`outline: none` / `0`), but the stylesheet never provides a `:focus-visible` or `:focus` replacement.
+
+**Why it's wrong**: Removing the outline with no substitute strands keyboard users — there's no visible indication of where focus is. It's one of the most common and most damaging accessibility regressions.
+
+**Fix**: Remove the suppression, or pair it with a visible `:focus-visible` ring — an `outline`, `box-shadow`, or `border` that clearly marks the focused control.
 
 ### `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`.  
 **Why it's wrong:** Skipped headings break screen reader navigation and document outline semantics.  
 **Fix:** Maintain sequential heading hierarchy. If you need the visual size of `h3` without the `h2` parent, use a `h2` with class-based styling.
 
+### `small-touch-target` — Touch target below 44px
+
+**Detect**: A clickable control (`button`, link, clickable `input`, `[role=button]`) renders smaller than 44×44px on one or both axes. Inline text links inside prose are exempt.
+
+**Why it's wrong**: Fingers are imprecise. Targets below ~44×44px (the WCAG 2.5.5 / platform HIG minimum) are missed and mis-tapped, especially on mobile and for users with motor impairments.
+
+**Fix**: Give standalone controls at least 44×44px of hit area via `padding` or `min-width` / `min-height`. Spacing between adjacent targets helps too.
+
 ### `text-overflow` — Content overflowing its container
 
 **Detect**: Content renders wider than its container — `scrollWidth > clientWidth` on any non-scroll element, or a horizontal scrollbar appears on the page.
@@ -317,8 +363,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 |
@@ -343,16 +389,21 @@ These are the two categories the `impeccable detect` engine uses:
 | `broken-image` | quality | Real image or remove tag |
 | `clipped-overflow-container` | quality | Portal or visible overflow |
 | `cramped-padding` | quality | 16px minimum |
+| `dark-scheme-contrast-blindspot` | quality | Flip text + background as a pair |
 | `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 |
+| `hover-only-affordance` | quality | Mirror hover with :focus-within |
+| `image-missing-dimensions` | quality | width/height attrs or aspect-ratio |
 | `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) |
+| `missing-focus-visible` | quality | Add a :focus-visible ring |
 | `skipped-heading` | quality | Sequential h1→h2→h3 |
+| `small-touch-target` | quality | 44×44px minimum hit area |
 | `text-overflow` | quality | overflow-wrap + constrained widths |
 | `tight-leading` | quality | line-height: 1.6 |
 | `tiny-text` | quality | 16px minimum body |

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:
 

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

@@ -0,0 +1,139 @@
+Run systematic **technical** quality checks on a native app (`ios` / `android` / `adaptive`) and generate a comprehensive report. Don't fix issues; document them for other commands to address.
+
+This is a code-level audit, not a design critique. Audit from source (SwiftUI / UIKit / Compose / React Native / Flutter); no browser tooling or `detect.mjs` applies. Score against the platform reference(s): [ios.md](ios.md) / [android.md](android.md), both for `adaptive`. Read them before scoring if Setup hasn't already. The report skeleton mirrors [audit.md](audit.md); keep the two in sync when changing it.
+
+## Diagnostic Scan
+
+Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.
+
+### 1. Accessibility (VoiceOver / TalkBack)
+
+**Check for**:
+- **Missing labels**: interactive elements without accessibility labels, traits/roles, or state announcements
+- **Reading and focus order**: illogical traversal, unreachable controls, focus lost on navigation
+- **Text scaling**: fixed point sizes defeating Dynamic Type (iOS) or px instead of sp (Android); layouts that clip or overlap at large sizes
+- **Touch targets**: below 44 pt (iOS) / 48 dp (Android), or crammed without spacing
+- **Reduce Motion ignored**: parallax and large slides with no crossfade alternative
+- **Contrast**: text failing contrast in either appearance, light or dark
+
+**Score 0-4**: 0=Screen reader unusable, 1=Major gaps (unlabeled controls, no scaling), 2=Partial (labels exist, order or scaling breaks), 3=Good (minor gaps), 4=Excellent (labeled, ordered, scales cleanly, Reduce Motion honored)
+
+### 2. Performance
+
+**Check for**:
+- **Slow startup**: heavy work on launch before first frame
+- **Unvirtualized lists**: long content without FlatList / LazyColumn / List recycling
+- **Main-thread jank**: synchronous work in scroll or gesture paths, dropped frames on 60/120 Hz
+- **Wasted rendering**: unnecessary re-renders (React Native) or recompositions (Compose); missing memoization/keys
+- **Image handling**: full-size images decoded for thumbnails, no caching
+- **App weight**: bloated JS bundle or binary, unused dependencies
+
+**Score 0-4**: 0=Janky everywhere, 1=Major problems (unvirtualized lists, slow launch), 2=Partial, 3=Good (minor improvements possible), 4=Excellent (fast launch, smooth scroll, lean)
+
+### 3. Appearance & Theming
+
+**Check for**:
+- **Hard-coded colors**: raw hex instead of semantic system colors (iOS) / Material color roles (Android) / design tokens
+- **Broken dark appearance**: missing dark variants, poor contrast in dark, quick inverts
+- **Dynamic Color** (Android 12+): no static fallback scheme, or ignored where it fits
+- **Off-platform materials**: hand-rolled blur/glassmorphism instead of system materials or tonal elevation
+
+**Score 0-4**: 0=Hard-coded everything, 1=Minimal tokens, 2=Partial (tokens exist, inconsistently used), 3=Good (minor hard-coded values), 4=Excellent (semantic throughout, both appearances first-class)
+
+### 4. Platform Conformance (CRITICAL)
+
+Score against the loaded platform reference(s), including their slop tests. **Check for**:
+- **Broken system gestures**: edge-swipe back disabled (iOS), predictive Back hijacked (Android)
+- **Inset violations**: content under the notch, Dynamic Island, home indicator, status bar, or keyboard
+- **Off-platform navigation**: custom global nav, overloaded tab bars, iOS patterns on Android or vice versa
+- **Web-shaped controls**: HTML-style buttons, custom toggles, hover-dependent affordances
+- **Icon drift**: mixed icon sets instead of SF Symbols / Material Symbols
+- **AI tells**: the shared absolute bans still apply (AI palette, gradient text, hero metrics)
+
+**Score 0-4**: 0=Web port (nothing native), 1=Heavy violations (3-4 kinds), 2=Some (1-2 noticeable), 3=Mostly conformant (subtle issues), 4=Fully native (a fluent user trusts every screen)
+
+### 5. Adaptivity
+
+**Check for**:
+- **Stretched phone layouts**: tablet/iPad rendering a scaled-up phone UI instead of using size classes / window size classes
+- **Orientation breakage**: landscape clipping, ignored, or locked without reason
+- **Keyboard/IME handling**: inputs hidden behind the keyboard, no inset adjustment
+- **Multitasking**: iPad Split View / Android multi-window breaking layout
+- **Foldables**: hinge-unaware layouts on posture change (Android)
+
+**Score 0-4**: 0=One screen size only, 1=Major breakage (landscape or tablet broken), 2=Partial, 3=Good (minor edge cases), 4=Excellent (adapts across sizes, orientations, and windowing)
+
+## Generate Report
+
+### Audit Health Score
+
+| # | Dimension | Score | Key Finding |
+|---|-----------|-------|-------------|
+| 1 | Accessibility | ? | [most critical issue or "--"] |
+| 2 | Performance | ? | |
+| 3 | Appearance & Theming | ? | |
+| 4 | Platform Conformance | ? | |
+| 5 | Adaptivity | ? | |
+| **Total** | | **??/20** | **[Rating band]** |
+
+**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues)
+
+### Platform Conformance Verdict
+**Start here.** Pass/fail: does this read as a native app or a ported website? List specific violations. Be brutally honest.
+
+### Executive Summary
+- Audit Health Score: **??/20** ([rating band])
+- Total issues found (count by severity: P0/P1/P2/P3)
+- Top 3-5 critical issues
+- Recommended next steps
+
+### Detailed Findings by Severity
+
+Tag every issue with **P0-P3 severity**:
+- **P0 Blocking**: Prevents task completion. Fix immediately
+- **P1 Major**: Significant difficulty or platform-guideline violation. Fix before release
+- **P2 Minor**: Annoyance, workaround exists. Fix in next pass
+- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits
+
+For each issue, document:
+- **[P?] Issue name**
+- **Location**: Screen, file, line
+- **Category**: Accessibility / Performance / Theming / Conformance / Adaptivity
+- **Impact**: How it affects users
+- **Guideline**: The HIG / Material rule it violates (if applicable)
+- **Recommendation**: How to fix it
+- **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
+
+Identify recurring problems that indicate systemic gaps rather than one-off mistakes:
+- "Hard-coded colors appear in 15+ screens, should use semantic colors"
+- "Touch targets consistently below 44 pt throughout the tab bar and list rows"
+
+### Positive Findings
+
+Note what's working well: good practices to maintain and replicate.
+
+## Recommended Actions
+
+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: /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:
+
+> You can ask me to run these one at a time, all at once, or in any order you prefer.
+>
+> Re-run `/monodesign audit` after fixes to see your score improve.
+
+**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.
+
+**NEVER**:
+- Report issues without explaining impact (why does this matter?)
+- Provide generic recommendations (be specific and actionable)
+- Skip positive findings (celebrate what works)
+- Forget to prioritize (everything can't be P0)
+- Report false positives without verification

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

@@ -1,12 +1,12 @@
-When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact and personality through stronger hierarchy, committed scale, and decisive type.
+When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact by making the existing design language more decisive, specific, and committed.
 
 ---
 
 ## Register
 
-Brand: "bolder" means distinctive. Extreme scale, unexpected color, typographic risk, committed POV.
+Brand: "bolder" means distinctive. Express a stronger point of view through hierarchy, pacing, proportion, copy, evidence, and one committed visual idea.
 
-Product: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density. The amplification is in clarity, not drama.
+Product: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, sharper information density, and more decisive prioritization. The amplification is in clarity, not drama.
 
 ---
 
@@ -15,98 +15,105 @@ Product: "bolder" rarely means theatrics; those undermine trust. It means strong
 Analyze what makes the design feel too safe or boring:
 
 1. **Identify weakness sources**:
-   - **Generic choices**: System fonts, basic colors, standard layouts
-   - **Timid scale**: Everything is medium-sized with no drama
-   - **Low contrast**: Everything has similar visual weight
-   - **Static**: No motion, no energy, no life
-   - **Predictable**: Standard patterns with no surprises
-   - **Flat hierarchy**: Nothing stands out or commands attention
+   - **Generic choices**: The page could belong to any product in the category.
+   - **Timid scale**: Everything is medium-sized with no clear lead.
+   - **Low contrast**: Important and supporting elements have similar visual weight.
+   - **Static**: The surface has no meaningful moment of emphasis.
+   - **Predictable**: The composition follows a default pattern without a point of view.
+   - **Flat hierarchy**: Nothing stands out or commands attention.
 
 2. **Understand the context**:
-   - What's the brand personality? (How far can we push?)
-   - What's the purpose? (Marketing can be bolder than financial dashboards)
-   - Who's the audience? (What will resonate?)
-   - What are the constraints? (Brand guidelines, accessibility, performance)
+   - What is the brand personality?
+   - What is the purpose of this surface?
+   - Who is the audience?
+   - What design system, tokens, components, and visual conventions already exist?
 
-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**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
+**CRITICAL**: "Bolder" does not mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random noise.
 
-**WARNING - AI SLOP TRAP**: Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects."
+**WARNING - AI SLOP TRAP**: Review ALL the DON'T guidelines from the parent monodesign skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects."
+
+## Design-System Lock
+
+If the project has `DESIGN.md`, tokens, theme variables, or established component styles, treat that system as the boundary. Make the existing language stronger before adding new language.
+
+Do not invent new colors, gradients, radii, shadows, fonts, decorative backgrounds, or effects just because the request says "bolder." A bolder pass should usually change emphasis, proportion, rhythm, density, contrast, copy, artifact specificity, and layout relationships while staying inside the documented system.
+
+If the existing system is genuinely too limited to express the bolder direction, stop and ask the user before expanding it. Name the exact additions, the role each would play, and why the current system cannot do the job. If the user approves expansion, update the design system or tokens alongside the implementation.
 
 ## Plan Amplification
 
 Create a strategy to increase impact while maintaining coherence:
 
-- **Focal point**: What should be the hero moment? (Pick ONE, make it amazing)
-- **Personality direction**: Maximalist chaos? Elegant drama? Playful energy? Dark moody? Choose a lane.
-- **Risk budget**: How experimental can we be? Push boundaries within constraints.
-- **Hierarchy amplification**: Make big things BIGGER, small things smaller (increase contrast)
+- **Focal point**: Pick one thing the viewer should remember, then make the rest support it.
+- **System levers**: Identify which existing tokens, components, layout patterns, and copy structures can carry more weight.
+- **Risk budget**: Decide how far the surface can push while still feeling like the same product or brand.
+- **Hierarchy amplification**: Increase contrast between primary, secondary, and tertiary content instead of making every element louder.
 
 **IMPORTANT**: Bold design must still be usable. Impact without function is just decoration.
 
 ## Amplify the Design
 
-Systematically increase impact across these dimensions:
+Systematically increase impact through intention, not a menu of effects:
 
 ### Typography Amplification
-- **Replace generic fonts**: Swap system fonts for distinctive choices (see the parent skill's typography guidelines and [typography.md](typography.md) for inspiration)
-- **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x)
-- **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400
-- **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default)
-
-### Color Intensification
-- **Increase saturation**: Shift to more vibrant, energetic colors (but not neon)
-- **Bold palette**: Introduce unexpected color combinations. Avoid the purple-blue gradient AI slop
-- **Dominant color strategy**: Let one bold color own 60% of the design
-- **Sharp accents**: High-contrast accent colors that pop
-- **Tinted neutrals**: Replace pure grays with tinted grays that harmonize with your palette
-- **Rich gradients**: Intentional multi-stop gradients (not generic purple-to-blue)
-
-### Spatial Drama
-- **Extreme scale jumps**: Make important elements 3-5x larger than surroundings
-- **Break the grid**: Let hero elements escape containers and cross boundaries
-- **Asymmetric layouts**: Replace centered, balanced layouts with tension-filled asymmetry
-- **Generous space**: Use white space dramatically (100-200px gaps, not 20-40px)
-- **Overlap**: Layer elements intentionally for depth
-
-### Visual Effects
-- **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles)
-- **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue)
-- **Texture & depth**: Grain, halftone, duotone, layered elements. NOT glassmorphism (it's overused AI slop)
-- **Borders & frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side)
-- **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand
+- Strengthen the existing type hierarchy before changing typefaces.
+- Make important text meaningfully more dominant, and make supporting text quieter.
+- Use weight, measure, spacing, and line breaks to sharpen the point of view.
+- Add or replace fonts only after user-approved design-system expansion.
+
+### Color Amplification
+- Use the existing palette more decisively before adding colors.
+- Shift the proportion, placement, and contrast of documented colors to clarify meaning.
+- Treat any new color, gradient, or tint ramp as a design-system expansion that requires user approval.
+- Keep color tied to hierarchy, state, or brand meaning; do not use it as surface decoration.
+
+### Spatial Amplification
+- Change proportion, density, alignment, and sequencing so the composition has a stronger point of view.
+- Create clearer contrast between dense evidence and open breathing room.
+- Let layout express priority and narrative order before adding ornament.
+- Preserve responsive behavior and avoid text overflow at every breakpoint.
+
+### Surface Amplification
+- Use existing surface, border, radius, and shadow rules more deliberately.
+- Remove timid half-measures: either give an element a clear role or simplify it.
+- Add texture, depth, illustration, or decorative treatments only when already established by the system or explicitly approved.
+- Make real product artifacts, imagery, data, or copy carry attention before reaching for effects.
 
 ### Motion & Animation
-- **Entrance choreography**: Staggered, dramatic page load animations with 50-100ms delays
-- **Scroll effects**: Parallax, reveal animations, scroll-triggered sequences
-- **Micro-interactions**: Satisfying hover effects, click feedback, state changes
-- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic, which cheapen the effect)
+- Design one meaningful moment of emphasis when motion genuinely supports the point.
+- Make interaction feedback feel more decisive without becoming distracting.
+- Keep transitions smooth and intentional.
+- **Bolder != scroll-fade-rise on every section.** That's the saturated AI default, the opposite of bold.
 
 ### Composition Boldness
-- **Hero moments**: Create clear focal points with dramatic treatment
-- **Diagonal flows**: Escape horizontal/vertical rigidity with diagonal arrangements
-- **Full-bleed elements**: Use full viewport width/height for impact
-- **Unexpected proportions**: Golden ratio? Throw it out. Try 70/30, 80/20 splits
+- Make the dominant idea unmistakable.
+- Use layout tension, sequencing, contrast, and restraint to create a stronger read.
+- Let the page's structure communicate priority before adding decorative layers.
+- If every element is louder, the composition is not bolder; it is flatter.
 
 **NEVER**:
-- Add effects randomly without purpose (chaos ≠ bold)
-- Sacrifice readability for aesthetics (body text must be readable)
-- Make everything bold (then nothing is bold; you need contrast)
-- Ignore accessibility (bold design must still meet WCAG standards)
-- Overwhelm with motion (animation fatigue is real)
-- Copy trendy aesthetics blindly (bold means distinctive, not derivative)
+- Add undocumented design-system primitives without user approval
+- Add effects randomly without purpose
+- Hide weak hierarchy behind decoration
+- Sacrifice readability for aesthetics
+- Make everything bold; contrast is the point
+- Ignore accessibility
+- Overwhelm with motion
+- Copy trendy aesthetics blindly
 
 ## Verify Quality
 
 Ensure amplification maintains usability and coherence:
 
+- **System-faithful**: Did the pass make the existing design language stronger before adding anything new?
+- **No undocumented drift**: Are new colors, gradients, shadows, radii, fonts, and effects either absent or explicitly approved and documented?
 - **NOT AI slop**: Does this look like every other AI-generated "bold" design? If yes, start over.
 - **Still functional**: Can users accomplish tasks without distraction?
 - **Coherent**: Does everything feel intentional and unified?
-- **Memorable**: Will users remember this experience?
-- **Performant**: Do all these effects run smoothly?
-- **Accessible**: Does it still meet accessibility standards?
+- **Memorable**: Will users remember this experience for the intended reason?
+- **Performant and accessible**: Does the result stay fast, readable, responsive, and WCAG-conscious?
 
 **The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects."