monomind 1.16.6 → 1.16.8

package/packages/@monomind/cli/.claude/skills/monodesign/reference/component-specs.md

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

package/packages/@monomind/cli/.claude/skills/monodesign/reference/component-states.md

@@ -0,0 +1,274 @@
+# Component States
+
+Interactive state system for all UI components: state definitions, priority, focus rings, disabled/loading/error patterns, and ARIA semantics.
+
+---
+
+## State Definitions
+
+| State | Trigger | Visual change |
+|-------|---------|---------------|
+| `default` | None | Base appearance |
+| `hover` | Mouse over | Slight color/background shift |
+| `focus` | Tab or click | Focus ring (see below) |
+| `active` | Mouse/touch down | Darkest color state |
+| `disabled` | `disabled` attribute | Reduced opacity, no interaction |
+| `loading` | Async in progress | Spinner + reduced opacity, no interaction |
+| `error` | Validation failure | Error color on border + ring |
+
+### State Priority
+
+When multiple states apply simultaneously, highest priority wins:
+
+```
+1. disabled  ← always wins
+2. loading
+3. active
+4. focus
+5. hover
+6. default
+```
+
+---
+
+## Standard Transition
+
+Apply to all interactive elements:
+
+```css
+.interactive {
+  transition-property: color, background-color, border-color, box-shadow, opacity;
+  transition-duration: var(--duration-fast);   /* 150ms */
+  transition-timing-function: var(--ease-out); /* cubic-bezier(0.16, 1, 0.3, 1) */
+}
+```
+
+| Property | Duration | Easing |
+|----------|----------|--------|
+| Color changes | 150ms | `var(--ease-out)` |
+| Background | 150ms | `var(--ease-out)` |
+| Transform | 200ms | `var(--ease-out)` |
+| Opacity | 150ms | `var(--ease-out)` |
+| Shadow | 200ms | `var(--ease-out)` |
+
+**Never** use `transition: all` — it catches layout properties and causes jank.
+
+---
+
+## Focus Ring
+
+Use `focus-visible` (not `focus`) to avoid showing rings on mouse click.
+
+```css
+.focusable:focus-visible {
+  outline: none;
+  box-shadow:
+    0 0 0 2px var(--color-bg),          /* offset — matches page background */
+    0 0 0 4px var(--color-accent-veil); /* ring — Magenta Veil */
+}
+```
+
+| Property | Value |
+|----------|-------|
+| Ring width | 2px |
+| Ring offset | 2px (matches page background) |
+| Ring color | `var(--color-accent-veil)` — `oklch(60% 0.25 350 / 0.25)` |
+
+For inputs, the container gets the focus ring on `:focus-within`:
+
+```css
+.input-wrapper:focus-within {
+  border-color: var(--color-accent);
+  box-shadow: 0 0 0 3px var(--color-accent-dim);
+}
+```
+
+**Never use `outline: none` without a visible replacement.** This breaks keyboard navigation and fails accessibility requirements.
+
+---
+
+## Disabled State
+
+```css
+.disabled,
+[disabled],
+[aria-disabled="true"] {
+  opacity: 0.5;
+  pointer-events: none;
+  cursor: not-allowed;
+}
+```
+
+| Property | Value |
+|----------|-------|
+| Opacity | 0.5 (0.38 minimum for WCAG 3:1) |
+| Pointer events | none |
+| Cursor | not-allowed |
+
+**ARIA:**
+```html
+<!-- Form controls: use disabled attribute -->
+<button disabled>Submit</button>
+<input disabled type="text">
+
+<!-- Non-form interactive elements: use aria-disabled -->
+<div role="button" aria-disabled="true" tabindex="-1">Action</div>
+```
+
+---
+
+## Loading State
+
+```css
+.loading {
+  position: relative;
+  pointer-events: none;
+  opacity: 0.7;
+}
+```
+
+### Spinner placement by component
+
+| Component | Spinner position |
+|-----------|-----------------|
+| Button | Replaces leading icon, or center of icon-only button |
+| Input | Trailing position |
+| Card | Center overlay with translucent scrim |
+| Page section | Center of section |
+| Full page | Center of viewport |
+
+**ARIA:**
+```html
+<button aria-busy="true" aria-describedby="loading-msg" disabled>
+  <span aria-hidden="true"><!-- spinner SVG --></span>
+  <span id="loading-msg" class="sr-only">Saving...</span>
+</button>
+```
+
+**Rule:** Always disable the trigger element during loading. Never allow double-submit.
+
+---
+
+## Error State
+
+```css
+.field-error .input {
+  border-color: var(--color-error);           /* oklch(55% 0.22 27) */
+}
+
+.field-error .input:focus-visible {
+  box-shadow:
+    0 0 0 2px var(--color-bg),
+    0 0 0 4px oklch(55% 0.22 27 / 0.25);
+}
+
+.error-message {
+  color: var(--color-error);
+  font-size: var(--font-size-sm);
+  margin-top: 4px;
+}
+```
+
+| Element | Treatment |
+|---------|-----------|
+| Input border | `var(--color-error)` |
+| Input focus ring | `oklch(55% 0.22 27 / 0.25)` |
+| Error message text | `var(--color-error)` |
+| Error icon | `var(--color-error)` |
+
+**Rules:**
+- Position error message directly below the field (not at page top)
+- Clear error on valid input (validate on blur, not on keystroke)
+- Auto-focus the first invalid field after a failed submit
+- Use `role="alert"` or `aria-live="polite"` on the error message
+
+**ARIA:**
+```html
+<div class="field" role="group">
+  <label for="email">Email</label>
+  <input
+    id="email"
+    type="email"
+    aria-invalid="true"
+    aria-describedby="email-error"
+  >
+  <span id="email-error" role="alert" class="error-message">
+    Enter a valid email address.
+  </span>
+</div>
+```
+
+---
+
+## Color Variants — CSS Pattern
+
+Use CSS custom properties scoped to the component for variant colors. Never hard-code variant colors directly on the element:
+
+```css
+/* Pattern */
+.btn {
+  --btn-bg: var(--color-ink);
+  --btn-fg: var(--color-surface);
+  background: var(--btn-bg);
+  color: var(--btn-fg);
+}
+
+.btn.secondary {
+  --btn-bg: var(--color-mist);
+  --btn-fg: var(--color-ink);
+}
+
+.btn.destructive {
+  --btn-bg: var(--color-error);
+  --btn-fg: white;
+}
+```
+
+This pattern means dark mode only needs to override semantic tokens — component variant CSS stays unchanged.
+
+---
+
+## Size Variants — CSS Pattern
+
+```css
+/* Pattern */
+.btn {
+  --btn-height: 40px;
+  --btn-px: var(--space-2);   /* 16px */
+  --btn-font: var(--font-size-sm);
+  height: var(--btn-height);
+  padding-inline: var(--btn-px);
+  font-size: var(--btn-font);
+}
+
+.btn.sm {
+  --btn-height: 32px;
+  --btn-px: 12px;
+  --btn-font: var(--font-size-xs);
+}
+
+.btn.lg {
+  --btn-height: 48px;
+  --btn-px: var(--space-3);   /* 24px */
+  --btn-font: var(--font-size-base);
+}
+```
+
+---
+
+## ARIA State Reference
+
+Quick reference for the most commonly missed ARIA attributes:
+
+| Situation | Attribute | Example |
+|-----------|-----------|---------|
+| Currently selected (tabs, nav) | `aria-selected="true"` | `<button role="tab" aria-selected="true">` |
+| Expanded/collapsed | `aria-expanded="true/false"` | `<button aria-expanded="false" aria-controls="menu">` |
+| Loading | `aria-busy="true"` | `<button aria-busy="true">` |
+| Disabled (non-form) | `aria-disabled="true"` | `<div role="button" aria-disabled="true">` |
+| Invalid input | `aria-invalid="true"` | `<input aria-invalid="true">` |
+| Error description | `aria-describedby` | `<input aria-describedby="field-error">` |
+| Live region | `aria-live="polite"` | `<div aria-live="polite">` (for toasts, status) |
+| Alert / urgent | `role="alert"` | `<span role="alert">Error message</span>` |
+| Sorted column | `aria-sort` | `<th aria-sort="ascending">Name</th>` |
+| Controls another element | `aria-controls` | `<button aria-controls="dropdown-menu">` |