monomind 1.16.6 → 1.16.8

package/packages/@monomind/cli/.claude/skills/monodesign/reference/ux-research.md

@@ -0,0 +1,143 @@
+# UX Research
+
+Validate design decisions with evidence. Research before redesigning; test before shipping.
+
+## When to Research
+
+| Signal | Method |
+|---|---|
+| "We don't know if users want this" | User interviews (5–8 participants) |
+| "We don't know if users can do this" | Usability testing (5 tasks, think-aloud) |
+| "We don't know which version is better" | A/B testing (statistical significance required) |
+| "We don't know who our users are" | Survey + analytics segmentation |
+| "We're redesigning a live product" | Contextual inquiry + session recording analysis |
+
+## Study Plan
+
+Before any research session:
+
+```markdown
+## Research Plan: [Feature/Product Name]
+
+**Research question**: [One clear question this study answers]
+**Method**: [Interview / Usability test / Survey / A/B test]
+**Participants**: [N=X; criteria: role, experience, age range; how recruited]
+**Timeline**: [Dates for recruiting, sessions, synthesis, readout]
+**Success**: [What finding would change a product decision]
+
+### Session protocol
+- [Task 1]: [Goal — what we want to observe, not prescribe]
+- [Task 2]: ...
+- Post-task questions: "How difficult was that? Why?"
+- Closing: "What surprised you? What would you change?"
+```
+
+## User Persona Template
+
+Personas are empirical — built from interview synthesis, not imagination. A persona without a source citation is a fiction.
+
+```markdown
+## [Persona Name] — [One-line description]
+
+**Source**: [N interviews + X survey responses, Month Year]
+
+### Context
+- Role: [job title, team size, seniority]
+- Environment: [device, OS, when/where they use the product]
+- Technical fluency: [1–5 scale with evidence]
+
+### Goals
+Primary: [What they're actually trying to accomplish]
+Secondary: [Nice-to-have outcomes]
+
+### Frustrations (direct quotes where possible)
+- "[Their words]" — quote from interview participant
+- [Observed behavior that contradicts stated preference]
+
+### Mental model
+[How they currently think about the problem domain — diagram if useful]
+
+### Decision triggers
+[What causes them to start using, stop using, recommend, or abandon]
+```
+
+## Usability Test Protocol
+
+5 participants reveals 85% of usability issues (Nielsen's rule). Run moderated think-aloud tests before major launches.
+
+```markdown
+## Usability Test: [Feature Name]
+
+**Prototype/build**: [URL or Figma link]
+**Tasks** (state goal, not steps):
+1. "Find a plan that fits your budget" ← correct
+   "Click Pricing, then select Pro" ← wrong (leads the user)
+2. ...
+
+**Observation sheet** (one per participant):
+| Task | Completed? | Time | Errors | Quotes / Observations |
+|------|-----------|------|--------|----------------------|
+| T1   |           |      |        |                      |
+
+**Severity scale**:
+- P0: Blocks task completion — fix before launch
+- P1: Causes errors or frustration — fix this sprint
+- P2: Causes hesitation — fix next sprint
+- P3: Polish issue — backlog
+```
+
+## Synthesis
+
+After 5+ sessions, synthesize before drawing conclusions. Affinity mapping is the default method.
+
+Steps:
+1. Transcribe or note-take immediately after each session
+2. Write observations on individual cards ("User tried X before Y")
+3. Group cards by theme across participants
+4. Count frequency: "4/5 users misread the CTA as navigation"
+5. Map to product decisions: what changes, what validates current design
+
+**Red flags that invalidate a finding:**
+- Only one participant showed this behavior
+- Observation conflicts with analytics data — investigate before concluding
+- "Users said they would do X" (stated preference ≠ behavior)
+
+## A/B Testing Standards
+
+Don't A/B test unless:
+- You have enough traffic for statistical significance (use a calculator — typically n=1,000+ per variant)
+- The test runs ≥2 weeks to account for weekly cycles
+- You have a pre-registered hypothesis ("Changing CTA copy will increase conversion by 10%")
+- You have a single primary metric per test
+
+**What to test**: CTAs, headlines, onboarding steps, form field count, pricing page layout.  
+**What not to test**: Navigation structure, brand identity, accessibility requirements.
+
+## Research Repository
+
+After each study, file a one-page summary:
+
+```markdown
+## Research Summary: [Study Name] — [Date]
+
+**Question**: [What we set out to learn]
+**Method + participants**: [Brief]
+**Top 3 findings**:
+1. [Finding with evidence — quote or count]
+2. ...
+3. ...
+**Recommended changes** (linked to findings):
+- Design: [What to change]
+- Product: [What to consider]
+**Follow-up questions this surfaced**: [What to research next]
+```
+
+Store in `docs/research/` or equivalent. Link from design decisions so future teammates understand why choices were made.
+
+## Inclusive Research
+
+- Recruit participants with disabilities in every study (not just accessibility-specific studies)
+- Test on real devices users own — not just latest iPhone/MacBook
+- Account for non-native language users if the product has international reach
+- Analyze session recordings for accessibility errors: keyboard traps, screen reader failures, zoom breakage
+- Don't use "average user" — disaggregate findings by user segment

package/packages/@monomind/cli/.claude/skills/monodesign/reference/ux-rules.md

@@ -0,0 +1,211 @@
+# UX Rules — Implementation-Level Guidance
+
+170+ rules across 10 categories, ordered by priority. Use during `audit`, `critique`, and `review` workflows to catch implementation-level issues that antipattern detection misses.
+
+---
+
+## Priority 1: Accessibility (CRITICAL)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `color-contrast` | Minimum 4.5:1 for normal text; 3:1 for large text (18px+ or 14px+ bold) | WCAG AA |
+| `focus-states` | Visible focus rings on all interactive elements (2–4px outline) | Never remove outlines |
+| `alt-text` | Descriptive alt text for all meaningful images; `alt=""` for decorative | |
+| `aria-labels` | aria-label for icon-only buttons; all interactive elements labeled | |
+| `keyboard-nav` | Tab order matches visual order; all actions reachable without a mouse | |
+| `form-labels` | `<label for="">` wired to every input; no placeholder-as-label | |
+| `skip-links` | "Skip to main content" link for keyboard users | |
+| `heading-hierarchy` | Sequential h1→h2→h3, no level skips | |
+| `color-not-only` | Never convey information by color alone — add icon or text | |
+| `dynamic-type` | Support system text scaling; no truncation as text grows | |
+| `reduced-motion` | `@media (prefers-reduced-motion: reduce)` wraps all animations | Non-negotiable |
+| `escape-routes` | Cancel/back affordance in all modals and multi-step flows | |
+| `keyboard-shortcuts` | Preserve system accessibility shortcuts | |
+
+---
+
+## Priority 2: Touch & Interaction (CRITICAL)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `touch-target-size` | Min 44×44pt interactive area; expand hit area beyond visual bounds if needed | |
+| `touch-spacing` | Minimum 8px gap between adjacent touch targets | |
+| `hover-vs-tap` | Primary interactions are click/tap; hover is enhancement only | |
+| `loading-buttons` | Disable button during async operations; show spinner or progress | |
+| `error-feedback` | Clear error messages near the problem element | |
+| `cursor-pointer` | `cursor: pointer` on all clickable elements | Web |
+| `tap-delay` | `touch-action: manipulation` to remove 300ms delay | Web |
+| `press-feedback` | Visual feedback on press (opacity, scale, ripple) within 80–150ms | |
+| `drag-threshold` | Movement threshold before starting drag to avoid accidental drags | |
+
+---
+
+## Priority 3: Performance (HIGH)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `image-optimization` | WebP/AVIF, responsive `srcset`/`sizes`, lazy load non-critical | |
+| `image-dimension` | Declare `width`/`height` or `aspect-ratio` to prevent CLS | Core Web Vitals |
+| `font-loading` | `font-display: swap` or `optional`; preload critical fonts only | |
+| `critical-css` | Above-the-fold CSS loads first (inline critical or early stylesheet) | |
+| `bundle-splitting` | Split code by route/feature (React Suspense, dynamic import) | |
+| `reduce-reflows` | Batch DOM reads then writes; no layout thrashing | |
+| `content-jumping` | Reserve space for async content (skeleton screens, aspect-ratio boxes) | |
+| `virtualize-lists` | Virtualize lists of 50+ items | |
+| `debounce-throttle` | Debounce/throttle for scroll, resize, and input events | |
+| `progressive-loading` | Skeleton/shimmer for operations >1s; never a blocking spinner | |
+
+---
+
+## Priority 4: Style Selection (HIGH)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `consistency` | One visual style across all pages; no mid-product style drift | |
+| `no-emoji-icons` | SVG icons only (Heroicons, Lucide, Phosphor); never emojis as icons | |
+| `effects-match-style` | Shadows, blur, radius aligned with chosen style | |
+| `state-clarity` | Hover/pressed/disabled states are visually distinct | |
+| `elevation-consistent` | Consistent shadow scale for cards, sheets, modals | |
+| `icon-style-consistent` | One icon set; consistent stroke weight and corner radius | |
+| `primary-action` | One primary CTA per screen; secondary actions visually subordinate | |
+| `blur-purpose` | Blur indicates background dismissal (modals, sheets); never decorative | |
+
+---
+
+## Priority 5: Layout & Responsive (HIGH)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `viewport-meta` | `width=device-width, initial-scale=1`; never disable zoom | |
+| `mobile-first` | Design mobile-first; scale up to tablet and desktop | |
+| `breakpoint-consistency` | Systematic breakpoints: 375 / 768 / 1024 / 1440 | |
+| `readable-font-size` | Min 16px body on mobile (avoids iOS auto-zoom) | |
+| `line-length-control` | Mobile 35–60 chars; desktop 60–75 chars | |
+| `horizontal-scroll` | No horizontal scroll on mobile | |
+| `spacing-scale` | 4pt/8dp incremental spacing system | |
+| `container-width` | Consistent max-width on desktop (max-w-6xl / 7xl) | |
+| `z-index-management` | Defined layered z-index scale (0 / 10 / 20 / 40 / 100 / 1000) | |
+| `fixed-element-offset` | Fixed navbar/bottom bar reserves safe padding for underlying content | |
+| `viewport-units` | Prefer `min-h-dvh` over `100vh` | |
+| `visual-hierarchy` | Hierarchy via size, spacing, contrast — not color alone | |
+
+---
+
+## Priority 6: Typography & Color (MEDIUM)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `line-height` | `1.5`–`1.75` for body text (`1.6` is the Editorial Sanctuary target) | |
+| `line-length` | `max-width: 65ch` on paragraph containers | |
+| `font-pairing` | Heading and body fonts have distinct personalities | |
+| `font-scale` | Consistent type scale (12 / 14 / 16 / 18 / 24 / 32) | |
+| `weight-hierarchy` | Bold headings (600–700), regular body (400), medium labels (500) | |
+| `color-semantic` | Semantic color tokens (primary, secondary, error, surface); no raw hex in components | |
+| `color-dark-mode` | Dark mode uses desaturated/lighter tonal variants; test contrast independently | |
+| `color-accessible-pairs` | All foreground/background pairs meet 4.5:1 (AA) or 7:1 (AAA) | |
+| `color-not-decorative-only` | Functional colors (error, success) also use icon or text — no color-only meaning | |
+| `letter-spacing` | Avoid tight tracking on body text; track only micro-labels, buttons, uppercase | |
+| `number-tabular` | Tabular/monospaced figures for data columns, prices, timers | |
+
+---
+
+## Priority 7: Animation (MEDIUM)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `duration-timing` | 150–300ms for micro-interactions; complex transitions ≤400ms | |
+| `transform-performance` | Animate `transform` and `opacity` only; never width/height/top/left | |
+| `easing` | `ease-out` for entering; `ease-in` for exiting; never linear for UI | |
+| `motion-meaning` | Every animation expresses cause-effect; no purely decorative motion | |
+| `spring-physics` | Prefer spring/physics curves over cubic-bezier for natural feel | |
+| `exit-faster` | Exit animations 60–70% of enter duration — feels responsive | |
+| `stagger-sequence` | Stagger list/grid entrances 30–50ms per item | |
+| `interruptible` | Animations are interruptible; user action cancels in-progress animation | |
+| `no-blocking-animation` | UI stays interactive during animations; never block input | |
+| `scale-feedback` | Subtle scale (0.95–1.05) on press for tappable cards/buttons | |
+| `layout-shift-avoid` | Animations must not trigger reflow or CLS | |
+| `loading-states` | Skeleton or progress indicator when loading exceeds 300ms | |
+| `excessive-motion` | Animate 1–2 key elements per view max | |
+
+---
+
+## Priority 8: Forms & Feedback (MEDIUM)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `input-labels` | Visible label per input — no placeholder-as-label | |
+| `error-placement` | Error message below the related field | |
+| `submit-feedback` | Loading → then success/error state on submit | |
+| `required-indicators` | Required fields marked (asterisk + sr-only explanation) | |
+| `empty-states` | Helpful message and action when no content | |
+| `toast-dismiss` | Auto-dismiss toasts in 3–5s | |
+| `confirmation-dialogs` | Confirm before all destructive actions | |
+| `disabled-states` | Disabled: reduced opacity (0.38–0.5) + cursor change + semantic attribute | |
+| `progressive-disclosure` | Reveal complex options progressively; don't overwhelm upfront | |
+| `inline-validation` | Validate on blur, not on keystroke; show error only after user finishes | |
+| `password-toggle` | Show/hide toggle for password fields | |
+| `error-clarity` | Error messages state cause + how to fix (not just "Invalid input") | |
+| `focus-management` | After submit error, auto-focus the first invalid field | |
+| `error-summary` | Multiple errors get a summary at top with anchor links to each field | |
+| `toast-accessibility` | Toasts use `aria-live="polite"` — never steal focus | |
+| `undo-support` | Allow undo for destructive or bulk actions | |
+| `multi-step-progress` | Multi-step flows show step indicator; allow back navigation | |
+| `timeout-feedback` | Request timeout shows clear feedback with retry option | |
+
+---
+
+## Priority 9: Navigation Patterns (HIGH)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `back-behavior` | Back navigation is predictable and consistent; preserves scroll/state | |
+| `deep-linking` | All key screens reachable via URL for sharing | |
+| `nav-label-icon` | Navigation items have both icon and text label | |
+| `nav-state-active` | Current location visually highlighted (color, weight, or indicator) | |
+| `nav-hierarchy` | Primary nav vs secondary nav are clearly separated | |
+| `modal-escape` | Modals/dialogs have a clear close affordance | |
+| `search-accessible` | Search easily reachable from top bar or primary nav | |
+| `breadcrumb-web` | Breadcrumbs for 3+ level deep hierarchies | Web |
+| `state-preservation` | Back restores previous scroll position, filter state, and input | |
+| `overflow-menu` | When actions exceed space, use overflow/more menu instead of cramming | |
+| `navigation-consistency` | Navigation placement same across all pages | |
+| `modal-vs-navigation` | Modals are not used for primary navigation flows | |
+| `focus-on-route-change` | After page transition, move focus to main content for screen readers | |
+| `destructive-nav-separation` | Dangerous actions (delete, logout) spatially separated from normal nav | |
+
+---
+
+## Priority 10: Charts & Data (LOW)
+
+| ID | Rule | Check |
+|----|------|-------|
+| `chart-type` | Match chart to data: trend → line, comparison → bar, proportion → pie/donut | |
+| `color-guidance` | Accessible color palettes; no red/green-only pairs (colorblind) | |
+| `data-table` | Table alternative for screen readers; charts alone are not accessible | |
+| `legend-visible` | Always show legend; position near the chart | |
+| `tooltip-on-interact` | Tooltips on hover/focus showing exact values | |
+| `axis-labels` | Label axes with units; avoid truncated labels | |
+| `responsive-chart` | Charts reflow or simplify on small screens | |
+| `empty-data-state` | Meaningful empty state when no data | |
+| `no-pie-overuse` | No pie/donut for >5 categories; use bar chart | |
+| `gridline-subtle` | Grid lines are low-contrast (e.g. gray-200); don't compete with data | |
+| `focusable-elements` | Interactive chart elements are keyboard-navigable | |
+| `screen-reader-summary` | Text summary or aria-label describing chart's key insight | |
+| `tooltip-keyboard` | Tooltip content keyboard-reachable; not hover-only | |
+| `sortable-table` | Data tables support sorting with `aria-sort` | |
+| `animation-optional` | Chart entrance animations respect `prefers-reduced-motion` | |
+
+---
+
+## Quick Decision: When to use this reference
+
+| You're doing | Jump to |
+|---|---|
+| Accessibility review | Priority 1 |
+| Mobile/touch audit | Priority 2 |
+| Performance audit | Priority 3 |
+| Animation review | Priority 7 |
+| Form UX | Priority 8 |
+| Navigation review | Priority 9 |
+| Data visualization | Priority 10 |
+| Full pre-ship review | Use `pre-delivery-checklist.md` |

package/packages/@monomind/cli/.claude/skills/monodesign/reference/ux-writing.md

@@ -0,0 +1,107 @@
+# UX Writing
+
+## The Button Label Problem
+
+**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
+
+| Bad | Good | Why |
+|-----|------|-----|
+| OK | Save changes | Says what will happen |
+| Submit | Create account | Outcome-focused |
+| Yes | Delete message | Confirms the action |
+| Cancel | Keep editing | Clarifies what "cancel" means |
+| Click here | Download PDF | Describes the destination |
+
+**For destructive actions**, name the destruction:
+- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
+- "Delete 5 items" not "Delete selected" (show the count)
+
+## Error Messages: The Formula
+
+Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".
+
+### Error Message Templates
+
+| Situation | Template |
+|-----------|----------|
+| **Format error** | "[Field] needs to be [format]. Example: [example]" |
+| **Missing required** | "Please enter [what's missing]" |
+| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
+| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
+| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
+
+### Don't Blame the User
+
+Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".
+
+## Empty States Are Opportunities
+
+Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".
+
+## Voice vs Tone
+
+**Voice** is your brand's personality, consistent everywhere.
+**Tone** adapts to the moment.
+
+| Moment | Tone Shift |
+|--------|------------|
+| Success | Celebratory, brief: "Done! Your changes are live." |
+| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
+| Loading | Reassuring: "Saving your work..." |
+| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
+
+**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
+
+## Writing for Accessibility
+
+**Link text** must have standalone meaning: "View pricing plans" not "Click here". **Alt text** describes information, not the image: "Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
+
+## Writing for Translation
+
+### Plan for Expansion
+
+German text is ~30% longer than English. Allocate space:
+
+| Language | Expansion |
+|----------|-----------|
+| German | +30% |
+| French | +20% |
+| Finnish | +30-40% |
+| Chinese | -30% (fewer chars, but same width) |
+
+### Translation-Friendly Patterns
+
+Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.
+
+## Consistency: The Terminology Problem
+
+Pick one term and stick with it:
+
+| Inconsistent | Consistent |
+|--------------|------------|
+| Delete / Remove / Trash | Delete |
+| Settings / Preferences / Options | Settings |
+| Sign in / Log in / Enter | Sign in |
+| Create / Add / New | Create |
+
+Build a terminology glossary and enforce it. Variety creates confusion.
+
+## Avoid Redundant Copy
+
+If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
+
+## Loading States
+
+Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
+
+## Confirmation Dialogs: Use Sparingly
+
+Most confirmation dialogs are design failures; consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
+
+## Form Instructions
+
+Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.
+
+---
+
+**Avoid**: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.

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

@@ -0,0 +1,71 @@
+---
+name: monodesign-shape
+description: Shape the UX and UI for a feature before any code is written — produces a structured design brief through discovery, not guesswork. Design planning only; no code written. Output is a brief for monodesign:craft.
+type: design-sub-command
+argument-hint: "[feature description]"
+user-invocable: true
+---
+
+# Monodesign: Shape
+
+Shape the UX and UI for a feature before any code is written. This command produces a **design brief**: a structured artifact that guides implementation through discovery.
+
+**Scope**: Design planning only. No code written. Output: a design brief for `/monodesign craft`.
+
+## Setup
+Read `PRODUCT.md` and (if present) `DESIGN.md` from the project root before starting. These are required anchors.
+
+Read `reference/shape.md` from the monodesign skill directory for the full command flow.
+
+## Phase 1: Discovery Interview
+
+Do NOT write any code or make design decisions during this phase. Ask 2–3 questions per round, then wait for answers. Have a natural dialogue; don't dump all questions at once.
+
+**Purpose & Context**
+- What is this feature for? What problem does it solve?
+- Who specifically will use it? (Role, context, frequency — not "users")
+- What's the user's state of mind when they reach this? (Rushed? Exploring? Anxious?)
+
+**Content & Data**
+- What content or data does this display or collect?
+- What are the realistic ranges? (0 items, typical, max, edge cases)
+- What are the empty state, error state, first-time use, power-user scenarios?
+
+**Design Direction** — force a visual decision on three fronts:
+- **Color strategy**: Restrained / Committed / Full palette / Drenched
+- **Theme via scene sentence**: one sentence of physical context that forces dark vs. light
+- **Two or three named anchor references** — specific products, brands, objects (not adjectives)
+
+**Scope** — always ask explicitly:
+- Fidelity: Sketch / mid-fi / high-fi / production-ready?
+- Breadth: One screen / a flow / a whole surface?
+- Time intent: Quick exploration or polish until it ships?
+
+## Phase 2: Brief Synthesis
+
+After the discovery round, synthesize and present a structured **Design Brief**:
+
+```
+## Design Brief: [Feature Name]
+
+**User**: [concrete description]
+**Problem**: [one sentence]
+**Success**: [measurable outcome]
+**User state**: [emotional/contextual state]
+
+**Content**: [what's displayed/collected + realistic ranges]
+**Edge cases**: [empty, error, overload, first-use]
+
+**Visual direction**:
+- Color strategy: [Restrained|Committed|Full palette|Drenched]
+- Theme: [dark|light] — [scene sentence]
+- References: [3 named references]
+
+**Scope**: [fidelity] / [breadth] / [time intent]
+```
+
+Stop and wait for explicit user confirmation before advancing to `/monodesign craft`. Do not start coding until the brief is approved.
+
+## Assert-then-confirm
+
+When PRODUCT.md and the prompt make one option obvious, name it and ask the user to confirm or override. Don't present four-option menus when the answer is already clear.

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

@@ -0,0 +1,69 @@
+---
+name: monodesign-teach
+description: Create or update PRODUCT.md — extract product context, users, brand voice, and design principles from the codebase, existing files, and conversation to anchor all future monodesign work.
+type: design-sub-command
+argument-hint: "[project path or description]"
+user-invocable: true
+---
+
+# Monodesign: Teach
+
+Create or update `PRODUCT.md` — the required context anchor for all `/monodesign` sub-commands.
+
+`PRODUCT.md` is not a design document — it's the product context document. It answers: who uses this, what is it for, what is the brand personality, and what design anti-references should be avoided.
+
+## When to Run
+
+Run `/monodesign teach` when:
+- Starting work on a new project with no `PRODUCT.md`
+- The existing `PRODUCT.md` is empty, placeholder (<200 chars), or has `[TODO]` markers
+- The product has significantly evolved and the `PRODUCT.md` is stale
+
+## Discovery Protocol
+
+**Step 1: Gather existing signals**
+
+Read the following files if they exist:
+- `README.md` — what is this product?
+- `package.json` — name, description, keywords
+- Any landing page copy (`index.html`, `src/pages/index.astro`, etc.)
+- Existing `PRODUCT.md` (to assess completeness)
+
+If a description or tagline exists, extract: target user, core value proposition, brand personality signals.
+
+**Step 2: Ask for what's missing**
+
+Ask the user 3–5 targeted questions based on what couldn't be inferred:
+- Who specifically uses this? (Role, context, skill level)
+- What's the one thing this does better than alternatives?
+- Three words that describe the brand personality
+- What design style do you want to AVOID? (anti-references)
+- Is this a marketing surface, product UI, or both?
+
+**Step 3: Write PRODUCT.md**
+
+```markdown
+# Product
+
+## Register
+[brand | product | both]
+
+## Users
+[Specific description of who uses this — not "developers", but "senior engineers at mid-size SaaS companies who need to..."]
+
+## Product Purpose
+[What this does and why it matters to those users. One paragraph.]
+
+## Brand Personality
+[3 words + a description of the tone. Direct, specific, no hedging.]
+
+## Anti-references
+[Specific things this product should NOT look like. Brand names, aesthetics, clichés to avoid.]
+
+## Design Principles
+[3–5 opinionated principles that guide all design decisions.]
+```
+
+## After Writing
+
+Confirm with the user that the PRODUCT.md is accurate before continuing to any design work. The PRODUCT.md is the foundation — if it's wrong, everything built on it is built on the wrong foundation.

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

@@ -0,0 +1,59 @@
+---
+name: monodesign-typeset
+description: Replace generic type defaults with fonts that reflect the brand and scale with intentional contrast — font selection, hierarchy, scale, and responsive type systems.
+type: design-sub-command
+argument-hint: "[target page, component, or whole site]"
+user-invocable: true
+---
+
+# Monodesign: Typeset
+
+Typography carries most of the information on the page. Replace generic defaults (Inter, Roboto, system fallback at flat scale) with type that reflects the brand and scales with intentional contrast.
+
+Read `reference/typeset.md` and `reference/typography.md` from the monodesign skill directory for the full protocol.
+
+## Register
+
+**Brand**: font selection procedure in `reference/brand.md`. Fluid `clamp()` scale, ≥1.25 ratio between steps.
+
+**Product**: system fonts and familiar sans stacks are legitimate. One well-tuned family typically carries the whole UI. Fixed `rem` scale, 1.125–1.2 ratio.
+
+## Assess Current Typography
+
+**Font choices**
+- Are we using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
+- Does the font match the brand personality?
+- Are there too many families? (More than 2–3 is almost always a mess)
+
+**Hierarchy**
+- Can you tell headings from body from captions at a glance?
+- Are sizes too close together? (14px, 15px, 16px = muddy hierarchy)
+- Are weight contrasts strong enough? (Medium vs Regular is barely visible)
+
+**Sizing & scale**
+- Is there a consistent type scale, or are sizes arbitrary?
+- Body text ≥16px?
+- Fixed `rem` scales for app UIs; fluid `clamp()` for marketing/content page headings
+
+## Typographic Rules (non-negotiable)
+
+- Cap body line length at **65–75ch**
+- Hero/display heading ceiling: `clamp()` max ≤ **6rem (~96px)**
+- Display letter-spacing floor: **≥ -0.04em** (anything tighter makes letters touch)
+- Use `text-wrap: balance` on h1–h3; `text-wrap: pretty` on long prose
+- Pair fonts on a contrast axis (serif + sans, geometric + humanist) — NOT similar families
+- Hierarchy through scale + weight contrast (≥1.25 ratio between steps)
+
+## Font Selection Process
+
+1. Load brand context from PRODUCT.md and DESIGN.md
+2. Identify brand personality from 3 words or the product description
+3. Propose 2–3 Google Fonts / variable font pairings with rationale
+4. Load one via `<link>` and demonstrate it on a real page section
+5. Iterate until the type feels native to the brand
+
+## Output
+
+- Updated CSS custom properties or tokens for `--font-heading`, `--font-body`, `--font-mono`
+- Fluid or fixed type scale as CSS custom properties
+- Applied to all heading levels and body copy on the target