monomind 2.7.11 → 2.7.12

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

@@ -0,0 +1,65 @@
+---
+name: monodesign-animate
+description: Add intentional, purposeful motion to interfaces — scroll-driven reveals, state transitions, micro-interactions, page transitions, and advanced motion effects using CSS and JS libraries.
+type: design-sub-command
+argument-hint: "[target component or page]"
+user-invocable: true
+---
+
+# Monodesign: Animate
+
+Add intentional motion to interfaces. Every animation must earn its place. Read `reference/animate.md` and `reference/motion-design.md` from the monodesign skill directory for the full protocol.
+
+## Motion Rules (non-negotiable)
+
+- **Do not animate CSS layout properties** (width, height, padding, margin, top, left) unless truly needed — causes layout thrashing
+- **Ease out with exponential curves**: ease-out-quart / quint / expo. No bounce, no elastic
+- **`prefers-reduced-motion` is not optional** — every animation needs a fallback (typically crossfade or instant transition)
+- **Reveal animations must enhance an already-visible default** — don't gate content visibility on a class-triggered transition; content ships blank if the transition doesn't fire
+- Use libraries for advanced motion (motion.dev, GSAP, anime.js, Lenis for smooth scroll)
+- Staggering items in one list is legitimate — uniform section fades on every section are not
+
+## Motion Premium Materials
+
+Not just transform/opacity. When they materially improve the effect and stay smooth:
+- Blur, backdrop-filter
+- clip-path, mask
+- shadow/glow transitions
+- View Transitions API for page/component morphing
+
+## Animation Categories
+
+**Entrance/reveal** — elements entering the viewport or DOM. Use IntersectionObserver + CSS transitions. Keep under 400ms. Stagger lists (50–80ms per item).
+
+**State transitions** — loading, success, error, empty. Should feel instantaneous for actions the user triggered. Confirmation animations: 200–400ms.
+
+**Micro-interactions** — button press feedback, toggle switches, checkbox check marks. Sub-200ms. Should feel physical.
+
+**Page/route transitions** — View Transitions API when available. Morphing elements from one state to another feels cinematic without heavy libraries.
+
+**Ambient/background** — scroll-driven effects, parallax, cursor-tracking. Use `animation-timeline: scroll()` for pure CSS scroll-driven. Performance-test before shipping.
+
+## Implementation Pattern
+
+```css
+/* Always start with the safe version */
+@media (prefers-reduced-motion: no-preference) {
+  .element {
+    animation: slide-in 400ms ease-out-quart both;
+  }
+}
+
+/* Explicit reduced-motion fallback */
+@media (prefers-reduced-motion: reduce) {
+  .element {
+    animation: fade-in 200ms ease both;
+  }
+}
+```
+
+## Verify in Browser
+
+Use browser automation to watch the animation play. Check:
+- Does it look smooth at 60fps?
+- Does the timing feel right (not too fast, not too slow)?
+- Does the reduced-motion version make sense?

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

@@ -0,0 +1,89 @@
+---
+name: monodesign-audit
+description: Run systematic technical quality checks across accessibility, performance, theming, motion, and interaction — generate a scored report with specific findings. Documents issues; does not fix them.
+type: design-sub-command
+argument-hint: "[target file, route, or component]"
+user-invocable: true
+---
+
+# Monodesign: Audit
+
+Run systematic **technical** quality checks and generate a comprehensive scored report. This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. **Does not fix issues** — documents them for other commands to address.
+
+Read `reference/audit.md` from the monodesign skill directory for the full scoring rubric. For a native app (`ios` / `android` / `adaptive`), read `reference/audit.native.md` instead — it audits from SwiftUI/UIKit/Compose/React Native/Flutter source against `reference/ios.md` / `reference/android.md`, with no browser tooling or detector. For web targets, also run the bundled detector (`monomind design detect`) and fold its findings into the report.
+
+## Diagnostic Scan — 5 Dimensions (score 0–4 each)
+
+### 1. Accessibility (A11y)
+- Contrast ratios (≥4.5:1 body, ≥3:1 large text)
+- ARIA: interactive elements with proper roles, labels, states
+- Keyboard navigation: focus indicators, logical tab order
+- Semantic HTML: heading hierarchy, landmarks, divs vs. buttons
+- Alt text quality; form labels; error messaging
+
+### 2. Performance
+- Layout thrashing (read/write layout properties in loops)
+- Expensive animations (layout-property animation, unbounded blur/filter)
+- Missing optimization (lazy loading, unoptimized assets, missing will-change)
+- Bundle size: unnecessary imports, unused dependencies
+- Unnecessary re-renders, missing memoization
+
+### 3. Theming
+- Hard-coded colors not using design tokens
+- Broken dark mode: missing variants, poor contrast
+- Inconsistent token usage; values that don't update on theme change
+
+### 4. Motion
+- Violations of `prefers-reduced-motion`
+- Inappropriate motion: layout-property animation, bounce/elastic
+- Reveal animations that gate content visibility (content ships blank if transition fails)
+- Motion that adds no information (hover-scale on non-interactive elements)
+
+### 5. Interaction
+- Dropdown clipping (inside overflow:hidden — use popover API or position:fixed)
+- Missing hover/focus/active/disabled states
+- Form UX: validation feedback, error recovery, submission state
+
+## Scoring
+
+| Score | Meaning |
+|---|---|
+| 0 | Broken / inaccessible |
+| 1 | Major gaps |
+| 2 | Partial — effort exists, significant gaps remain |
+| 3 | Good — mostly correct, minor improvements |
+| 4 | Excellent |
+
+## Output Format
+
+```markdown
+# Design Audit Report
+
+**Target**: [file or route]
+**Date**: [date]
+
+## Scores
+| Dimension | Score | Status |
+|---|---|---|
+| Accessibility | X/4 | [PASS/WARN/FAIL] |
+| Performance | X/4 | ... |
+| Theming | X/4 | ... |
+| Motion | X/4 | ... |
+| Interaction | X/4 | ... |
+| **Total** | X/20 | |
+
+## Findings by Priority
+
+### Critical (fix before ship)
+- [finding with file:line reference]
+
+### High
+- ...
+
+### Medium
+- ...
+
+## Recommended next commands
+- `/monodesign harden` — accessibility issues
+- `/monodesign polish` — theming drift and interaction gaps
+```

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

@@ -0,0 +1,50 @@
+---
+name: monodesign-bolder
+description: Make a timid, generic, or bland design more confident, distinctive, and visually committed — without crossing into gratuitous loudness.
+type: design-sub-command
+argument-hint: "[target page, component, or design]"
+user-invocable: true
+---
+
+# Monodesign: Bolder
+
+Make a timid, generic, or bland design more confident and distinctive. Read `reference/bolder.md` from the monodesign skill directory for the full protocol.
+
+## Assess What's Timid
+
+Identify what's making the design feel safe and generic:
+
+1. **Color timidity**: everything is neutral, muted, or generic. The accent color appears on <5% of the surface
+2. **Scale timidity**: headings are a safe 2rem when they could be 5rem. White space is the same everywhere
+3. **Typography timidity**: Inter at 400 weight, barely distinguished hierarchy, no personality
+4. **Composition timidity**: centered cards, symmetric grids, equal padding everywhere
+5. **Commitment timidity**: design feels like it's avoiding choices — trying to work for everyone
+
+## Bold Interventions (choose by diagnosis)
+
+**Color commitment**
+- Move from Restrained to Committed strategy: push one color to 30–60% of the surface
+- Use the brand color as a background, not just an accent
+- Commit to dark or light — don't hedge with a light-gray-on-white page
+
+**Scale expansion**
+- Increase heading scale: hero headlines at 4–6rem with tight tracking (-0.02 to -0.03em)
+- Introduce asymmetric spacing — some sections breathe, others are tight
+- Use a large number, quote, or visual element as an anchor on the page
+
+**Typographic commitment**
+- Switch from invisible system fonts to a distinctive typeface
+- Introduce strong weight contrast (900 + 400, not 600 + 400)
+- Use a display typeface for headings that doesn't appear in the body
+
+**Composition**
+- Break the centered-container pattern: allow some elements to bleed to the edge
+- Use a grid that isn't 12-equal-columns
+- Introduce intentional asymmetry in feature layouts
+
+## Rules
+
+- Bolder ≠ noisier. Every bold choice must serve the hierarchy and brand
+- Don't ban everything from the absolute-bans list just because the design is now bolder — those bans apply at any boldness level
+- If the project has a DESIGN.md, bold moves must be consistent with it, not contrary to it
+- Verify that the bolder version still passes accessibility contrast requirements

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

@@ -0,0 +1,64 @@
+---
+name: monodesign-clarify
+description: Fix confusing, ambiguous, or hard-to-understand UI — improve information architecture, navigation labels, empty states, error messages, and cognitive load without a full redesign.
+type: design-sub-command
+argument-hint: "[target page, flow, or interaction]"
+user-invocable: true
+---
+
+# Monodesign: Clarify
+
+Fix confusing or ambiguous UI. Read `reference/clarify.md` and `reference/cognitive-load.md` from the monodesign skill directory for the full protocol.
+
+## Diagnosis: What's Confusing?
+
+**Navigation and labeling**
+- Labels that describe what something IS instead of what it DOES ("Analytics" vs. "See how your campaigns are performing")
+- Navigation items with scope too broad (everything is "Settings")
+- Tabs and menus that require trying each option to understand them
+
+**Information architecture**
+- Related things that aren't grouped together
+- Same concept appearing in multiple places with slightly different names
+- Forms that ask for information before explaining why it's needed
+
+**Feedback and state**
+- Actions without confirmation that they worked
+- Loading states that don't indicate progress or expected duration
+- Errors that describe what happened technically, not what the user should do next
+- Empty states that are blank (not "nothing here yet", just nothing)
+
+**Cognitive load**
+- Too many choices presented simultaneously without hierarchy
+- Options that require domain knowledge to distinguish
+- Visual complexity that masks the primary action
+
+## Clarification Techniques
+
+**Labels**
+- Action-oriented labels on buttons ("Save changes" not "OK")
+- Descriptive labels on navigation ("Payment history" not "Payments")
+- Contextual tooltips on technical terms (hover, not always-visible)
+
+**Progressive disclosure**
+- Show the most common case first; reveal complexity on demand
+- Advanced settings behind a clear "Show advanced" toggle
+- Multi-step flows that reveal the next step only after the current one
+
+**Feedback patterns**
+- Inline validation as the user types, not only on submit
+- Clear success/error states with next-step guidance
+- Progress indicators for multi-step processes
+
+**Copy**
+- Error messages: [what happened] + [why] + [what to do]
+- Empty states: [what will appear here] + [how to add it]
+- Confirm dialogs: [what will happen] + primary action + escape
+
+## Output
+
+Specific code changes that reduce confusion:
+- Updated labels with rationale
+- Added/improved empty states
+- Better error messages
+- Simplified information architecture

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

@@ -0,0 +1,68 @@
+---
+name: monodesign-colorize
+description: Apply or rework the color system — brand color extraction, OKLCH palette construction, token architecture, dark/light mode, and contrast verification.
+type: design-sub-command
+argument-hint: "[target or brand description]"
+user-invocable: true
+---
+
+# Monodesign: Colorize
+
+Apply or rebuild the color system. Read `reference/colorize.md` and `reference/color-and-contrast.md` from the monodesign skill directory for the full protocol.
+
+## Color Strategy (choose one before picking colors)
+
+| Strategy | Surface area | When to use |
+|---|---|---|
+| **Restrained** | Tinted neutrals + one accent ≤10% | Product default; brand minimalism |
+| **Committed** | One saturated color at 30–60% of surface | Brand default for identity-driven pages |
+| **Full palette** | 3–4 named roles, used deliberately | Brand campaigns; data visualization |
+| **Drenched** | Surface IS the color | Brand heroes, campaign pages |
+
+## OKLCH Rules
+
+- Use OKLCH everywhere. Never `#000` or `#fff` — tint every neutral toward the brand hue (chroma 0.005–0.01)
+- Reduce chroma as lightness approaches 0 or 100 (high chroma at extremes looks garish)
+- Tinted neutrals: add 0.005–0.015 chroma toward the brand's hue, not toward generic warmth
+- Gray text on colored background looks washed out — use a darker shade of the bg hue or transparency
+
+## Theme Decision
+
+Dark vs. light is never a default. Write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force dark or light, it's not concrete enough. Add detail until it does.
+
+## Contrast Verification (required)
+
+- Body text: ≥4.5:1 against its background
+- Large text (≥18px or bold ≥14px): ≥3:1
+- Placeholder text: same 4.5:1 (not the muted-gray default)
+
+The most common failure: muted gray body text on a tinted near-white. If contrast is close, bump body color toward the ink end.
+
+## Anti-Cream Rule
+
+The warm-neutral band (OKLCH L 0.84–0.97, C < 0.06, hue 40–100) reads as cream/sand/paper regardless of what you call it. If the brief is "warm, editorial, refined" — that is NOT a license to use a near-white warm-tinted background. Warmth is carried by accent + typography + imagery. Pick: (a) a saturated brand color as body, (b) a true off-white at chroma 0, or (c) a darker mid-tone tinted neutral.
+
+## Token Architecture
+
+```css
+:root {
+  /* Brand */
+  --color-brand: oklch(/* primary */);
+  --color-brand-muted: oklch(/* lower chroma */);
+  
+  /* Surfaces */
+  --color-bg: oklch(/* page ground */);
+  --color-surface: oklch(/* panels */);
+  --color-surface-raised: oklch(/* cards */);
+  
+  /* Text */
+  --color-ink: oklch(/* headings */);
+  --color-body: oklch(/* body */);
+  --color-muted: oklch(/* captions */);
+  --color-faint: oklch(/* disabled */);
+  
+  /* Interactive */
+  --color-accent: oklch(/* CTA, links */);
+  --color-accent-hover: oklch(/* hover state */);
+}
+```

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

@@ -0,0 +1,51 @@
+---
+name: monodesign-craft
+description: Build a feature with exceptional UX and UI quality — shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar.
+type: design-sub-command
+argument-hint: "[feature description]"
+user-invocable: true
+---
+
+# Monodesign: Craft
+
+Build a feature with exceptional UX and UI quality. Real working code, committed design choices, exceptional craft.
+
+**Gates — do not compress.** Craft requires all setup gates to pass before writing code:
+1. PRODUCT.md and DESIGN.md loaded
+2. Register identified (brand or product) and matching reference loaded
+3. Shape brief confirmed by user
+
+Read `reference/craft.md` from the monodesign skill directory for the full flow.
+
+## Step 0: Project Foundation
+
+Before shape, before code: determine what kind of project you're working in.
+
+Check for:
+- An existing framework (`astro.config.mjs`, `next.config.js`, `vite.config.js`, etc.) — **if found, use it**
+- Existing component library or design system — read what's there before adding to it
+- Existing icon set — use what's already in the project; don't introduce a second set
+
+If greenfield with no framework, ask the user:
+- Astro (for content-led brand sites, landing pages)
+- SvelteKit / Next.js / Nuxt (app surfaces, significant interactivity)
+- Single index.html (one-shot demo, prototype)
+
+## Step 1: Shape the Design
+
+Run `/monodesign shape` if no confirmed brief exists. Stop and wait for explicit brief confirmation before writing code. Shape confirmation is NOT a green light to code; it's the green light to confirm direction.
+
+## Step 2: Implement
+
+With a confirmed brief:
+1. Load `reference/craft.md` for the full implementation protocol
+2. Follow the register-specific implementation guide (brand.md or product.md)
+3. Apply all shared design laws from the monodesign SKILL.md
+4. Verify visually using browser automation — don't assume it looks right
+5. Iterate until it meets the approved direction
+
+## Quality bar
+
+Produce ready-to-ship, production-grade code. Not a prototype. Not a starting point. Beautiful, responsive, fast, precise, bug-free, on-brand. Take attention to detail seriously.
+
+**The AI slop test**: if someone could look at this and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans in the design laws.

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

@@ -0,0 +1,66 @@
+---
+name: monodesign-critique
+description: Provide an expert design critique — honest, specific, prioritized feedback on what's working, what's failing, and exactly how to fix it. The design director review.
+type: design-sub-command
+argument-hint: "[target URL, screenshot, or codebase path]"
+user-invocable: true
+---
+
+# Monodesign: Critique
+
+Provide an expert design critique. Honest, specific, and prioritized. Read `reference/critique.md` from the monodesign skill directory for the full protocol. Critiques are persisted via the bundled `critique-storage.mjs` helper (resolve a slug for the target, write the critique body, and query the trend across the last runs) so repeat critiques of the same target track progress over time — follow the reference's storage steps rather than emitting a one-off report.
+
+## Voice
+
+Critique speaks with the voice of an experienced design director — not a checklist tool. It identifies what's actually wrong, explains why it's wrong in terms of user experience or brand damage, and says specifically what to do instead. Not: "The typography could be improved." Yes: "The heading is using Inter 500 at 2rem — this reads as a system default. Set it to your display typeface at 3.5rem 700 with -0.025em tracking."
+
+## Critique Dimensions
+
+**Visual hierarchy**
+- Can a first-time user identify the primary action without thinking?
+- Is the most important information visually loudest?
+- Is there a clear reading path (F-pattern, Z-pattern, or single column)?
+
+**Brand coherence**
+- Does this look like it belongs to the product's brand family?
+- Could it be any company's product, or does it have a specific identity?
+- Does it pass the AI slop test? (If someone could say "AI made that" without doubt, it's failed)
+
+**Information architecture**
+- Is related information grouped? Is unrelated information separated?
+- Is the navigation structure consistent with user mental models?
+- Are labels accurate and specific?
+
+**Interaction design**
+- Are interactive elements visually distinct from non-interactive ones?
+- Are states visible? (hover, active, loading, error, disabled)
+- Is the user always clear on what will happen before they act?
+
+**Technical implementation**
+- Are there obvious anti-patterns present? (Gradient text, side-stripe borders, glassmorphism as default, identical card grids)
+- Contrast failures
+- Broken responsive behavior
+
+## Critique Format
+
+```markdown
+# Design Critique: [Feature/Page]
+
+## What's working
+[2–3 specific things that are genuinely good]
+
+## Critical issues (fix before ship)
+### [Issue title]
+**What**: [specific description with element reference]
+**Why it matters**: [user impact or brand damage]
+**Fix**: [exact prescription — not "improve typography", but "set h1 to Geist 800 at 4rem"]
+
+## High priority
+...
+
+## Medium priority
+...
+
+## The single most important fix
+[If they fix only one thing, it should be this]
+```

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

@@ -0,0 +1,47 @@
+---
+name: monodesign-delight
+description: Add moments of delight, whimsy, and personality to interfaces — micro-interactions, easter eggs, playful copy, unexpected moments that make users smile without sacrificing usability.
+type: design-sub-command
+argument-hint: "[target component, empty state, interaction, or whole product]"
+user-invocable: true
+---
+
+# Monodesign: Delight
+
+Add moments of delight, whimsy, and personality. Read `reference/delight.md` from the monodesign skill directory for the full protocol.
+
+## Philosophy
+
+Delight is not decoration. It's the feeling a user gets when the product treats them as a human, not a task-completer. The best delight is:
+- **Discovered, not announced** — it rewards exploration, it doesn't interrupt
+- **Appropriate to context** — a playful empty state is right; a playful error message on a failed payment is wrong
+- **Consistent with brand personality** — delight that contradicts the brand voice creates whiplash
+
+## Where Delight Lives
+
+**Empty states**
+The most underdesigned surface in almost every product. When a user has no data, they're often new and uncertain. An empty state that's warm, encouraging, and occasionally charming turns uncertainty into curiosity.
+
+**Micro-interactions**
+The moments that feel physical: a button that compresses on press, a toggle that snaps, a checkbox that checks with a tiny satisfying arc, a completion animation that celebrates without being overwrought.
+
+**Copy**
+Delight isn't always visual. An error message that says "Hmm, that didn't work — here's what we know:" treats the user as a collaborator. Copy that has a voice (specific to this product, not generic SaaS) is delightful in itself.
+
+**Easter eggs**
+Hidden interactions that reward the curious. The konami code that does something silly. A hover state that's unexpectedly specific. A tooltip that breaks the fourth wall once.
+
+**Loading states**
+Instead of a spinning circle, something that's interesting to watch. A progress animation that tells you something about what the product is doing.
+
+## Delight Hierarchy
+
+Rate each idea against:
+1. **Does it interrupt the user's task?** If yes, cut it. Delight never gets in the way.
+2. **Is it consistent with the brand personality?** A product that's "expert, decisive, editorial" shouldn't have cartoon characters.
+3. **Does it degrade gracefully?** The primary function must work even if the delightful layer fails.
+4. **Will it get old?** Animations that play every time something happens become annoying. Use sparingly.
+
+## Implementation
+
+Read `reference/delight.md` for specific delight patterns by component type (empty states, interactions, copy formulas, animation recipes).

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

@@ -0,0 +1,56 @@
+---
+name: monodesign-distill
+description: Simplify an over-designed, cluttered, or complexity-burdened interface — remove what doesn't earn its place, reveal the essential structure underneath.
+type: design-sub-command
+argument-hint: "[target page, flow, or component]"
+user-invocable: true
+---
+
+# Monodesign: Distill
+
+Simplify an over-designed or cluttered interface. Read `reference/distill.md` from the monodesign skill directory for the full protocol.
+
+## Philosophy
+
+Every element on a page is a claim on the user's attention. When too many claims compete equally, the user's attention costs rise and comprehension falls. Distill removes the claims that can't justify their cost.
+
+## Assess the Clutter
+
+Walk through the interface and identify:
+
+**Structural complexity**
+- How many distinct visual layers exist? (More than 3 is usually too many)
+- How many columns? (Sometimes 1 column is the right answer)
+- Are there containers-within-containers? (Nested cards are always wrong)
+- Is the Z-axis used purposefully or as a decoration?
+
+**Information redundancy**
+- Is the same information shown twice? (Heading + tooltip + label that all say the same thing)
+- Are there labels that label things that are already obvious from context?
+- Are there intros that restate the page title?
+
+**Visual noise**
+- Decorative dividers between every section when whitespace would suffice
+- Icon + text where one alone would communicate equally well
+- Background patterns, textures, or gradients that add nothing
+
+**Navigation complexity**
+- Are there paths that lead nowhere useful?
+- Are there settings no one changes?
+- Are there features that serve < 5% of users in the primary navigation?
+
+## Distillation Protocol
+
+1. **List every element** on the target surface (visual inventory)
+2. **For each element, ask**: if this were removed, would a first-time user notice something missing? If no: remove it
+3. **Consolidate redundant information** into one canonical location
+4. **Increase whitespace** where elements were removed — don't fill the vacuum with something else
+5. **Verify the essential path** still works and is faster than before
+
+## Output
+
+A version of the interface that is measurably simpler:
+- Fewer distinct visual elements on screen at once
+- Clearer visual hierarchy (the important thing is visually louder than the less-important thing)
+- Faster to scan for a first-time user
+- No functionality removed from the primary user path

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

@@ -0,0 +1,83 @@
+---
+name: monodesign-document
+description: Create or update DESIGN.md — extract and codify the design system from the codebase into a portable, AI-readable design reference that anchors all future monodesign work.
+type: design-sub-command
+argument-hint: "[project path]"
+user-invocable: true
+---
+
+# Monodesign: Document
+
+Create or update `DESIGN.md` — the design system reference for this project. Every `/monodesign` sub-command uses DESIGN.md to make on-brand decisions without asking the same questions repeatedly.
+
+DESIGN.md is the portable export of the project's design system: colors, typography, spacing, components, and conventions — extracted from what's actually in the code, not invented.
+
+Read `reference/document.md` from the monodesign skill directory for the full protocol.
+
+## Discovery
+
+**Extract from codebase (monograph-first):**
+```
+# Preferred: monograph for design token discovery
+monograph_query({ query: "CSS custom properties variables tokens" })
+monograph_query({ query: "font-family font-face typography" })
+monograph_query({ query: "color theme palette" })
+```
+
+**Fallback (if monograph returns 0 results or DB not built):**
+```bash
+grep -r "^--" src/ --include="*.css" --include="*.scss" -h | sort -u
+grep -r "font-family\|@font-face\|@import.*font" src/ -h | sort -u
+grep -rE "#[0-9a-fA-F]{3,8}|oklch\(|rgb\(|hsl\(" src/ -h | sort -u | head -50
+```
+
+**Also read:**
+- `tailwind.config.js/ts` — theme configuration
+- `tokens.css`, `theme.css`, `variables.css`, or equivalent
+- A representative component to understand CSS conventions
+
+## DESIGN.md Structure
+
+```markdown
+# Design System
+
+## Brand Identity
+**Name**: [product name]
+**System**: [design system name, e.g. "Neo kinpaku system"]
+**Strategy**: [Restrained | Committed | Full palette | Drenched]
+**Theme**: [dark | light | both]
+
+## Colors (OKLCH)
+
+### Brand
+| Token | Value | Use |
+|---|---|---|
+| --color-brand | oklch(…) | Primary accent |
+| --color-brand-muted | oklch(…) | Secondary accent |
+
+### Surfaces
+[table]
+
+### Text
+[table]
+
+## Typography
+
+| Role | Font | Size | Weight | Line Height |
+|---|---|---|---|---|
+| Display | [family] | clamp(3rem, 5vw, 5rem) | 800 | 1.1 |
+| Heading 1 | … | … | … | … |
+| Body | … | 1rem | 400 | 1.6 |
+| Caption | … | 0.875rem | 400 | 1.4 |
+
+## Spacing Scale
+[4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 / 128]
+
+## Components
+[Brief description of key shared components and their variants]
+
+## Conventions
+- File naming: [convention]
+- Token naming: [convention]  
+- Component import style: [named/default/barrel]
+```