monomind 2.7.11 → 2.7.12

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">` |

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

@@ -0,0 +1,358 @@
+# Component System
+
+Build production-quality component libraries with consistent visual language, design tokens, developer-ready CSS, and proper accessibility.
+
+## Token-First Approach
+
+Every component is built on semantic tokens. Never hard-code values — always reference the token system. Use the OKLCH token system from `tokens.css` as the foundation; extend it with semantic aliases per project.
+
+```css
+:root {
+  /* Semantic aliases (project-specific — map to OKLCH tokens) */
+  --bg-primary: var(--color-cream);
+  --bg-elevated: var(--color-paper);
+  --text-primary: var(--color-ink);
+  --text-secondary: var(--color-charcoal);
+  --text-muted: var(--color-ash);
+  --border-subtle: var(--color-mist);
+  --interactive: var(--color-accent);
+  --interactive-hover: var(--color-accent-hover);
+}
+
+[data-theme="dark"] {
+  --bg-primary: oklch(10% 0.002 350);
+  --bg-elevated: oklch(15% 0.003 350);
+  --text-primary: oklch(94% 0 0);
+  --text-secondary: oklch(75% 0 0);
+  --text-muted: oklch(55% 0 0);
+  --border-subtle: oklch(22% 0 0);
+}
+```
+
+## Theme System
+
+Every new project gets light/dark/system toggle. Never default to one without a scene sentence that forces the answer (see shared design laws).
+
+```html
+<!-- Theme toggle — place in header navigation -->
+<div class="theme-toggle" role="radiogroup" aria-label="Color theme">
+  <button class="theme-toggle-option" data-theme="light" aria-checked="false">Light</button>
+  <button class="theme-toggle-option" data-theme="dark" aria-checked="false">Dark</button>
+  <button class="theme-toggle-option" data-theme="system" aria-checked="true">System</button>
+</div>
+```
+
+```javascript
+class ThemeManager {
+  constructor() {
+    this.current = localStorage.getItem('theme') || 'system';
+    this.apply(this.current);
+    document.querySelector('.theme-toggle')?.addEventListener('click', (e) => {
+      const btn = e.target.closest('.theme-toggle-option');
+      if (btn) this.apply(btn.dataset.theme);
+    });
+  }
+
+  apply(theme) {
+    if (theme === 'system') {
+      document.documentElement.removeAttribute('data-theme');
+      localStorage.removeItem('theme');
+    } else {
+      document.documentElement.setAttribute('data-theme', theme);
+      localStorage.setItem('theme', theme);
+    }
+    this.current = theme;
+    document.querySelectorAll('.theme-toggle-option').forEach(btn =>
+      btn.setAttribute('aria-checked', String(btn.dataset.theme === theme))
+    );
+  }
+}
+document.addEventListener('DOMContentLoaded', () => new ThemeManager());
+```
+
+## Core Components
+
+### Button
+
+```css
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-family: var(--font-body);
+  font-weight: 500;
+  text-decoration: none;
+  border: none;
+  cursor: pointer;
+  transition: background-color var(--duration-fast) var(--ease-out),
+              transform var(--duration-fast) var(--ease-out),
+              box-shadow var(--duration-fast) var(--ease-out);
+  user-select: none;
+
+  &:focus-visible {
+    outline: 2px solid var(--color-accent);
+    outline-offset: 2px;
+  }
+
+  &:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+}
+
+/* Sizes */
+.btn--sm  { padding: var(--space-2) var(--space-4); font-size: var(--font-size-sm); }
+.btn--md  { padding: var(--space-3) var(--space-6); font-size: var(--font-size-base); }
+.btn--lg  { padding: var(--space-4) var(--space-8); font-size: var(--font-size-lg); }
+
+/* Primary — solid accent fill */
+.btn--primary {
+  background-color: var(--color-accent);
+  color: var(--color-paper);
+  border-radius: var(--radius-none); /* editorial: no rounding */
+
+  &:hover:not(:disabled) {
+    background-color: var(--color-accent-hover);
+    transform: translateY(-1px);
+    box-shadow: var(--shadow-md);
+  }
+}
+
+/* Secondary — outlined */
+.btn--secondary {
+  background-color: transparent;
+  color: var(--color-accent);
+  border: 1.5px solid var(--color-accent);
+  border-radius: var(--radius-none);
+
+  &:hover:not(:disabled) {
+    background-color: var(--color-accent-dim);
+  }
+}
+
+/* Ghost — no border */
+.btn--ghost {
+  background-color: transparent;
+  color: var(--text-secondary);
+
+  &:hover:not(:disabled) {
+    background-color: var(--color-mist);
+    color: var(--text-primary);
+  }
+}
+```
+
+### Form Input
+
+```css
+.form-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.form-label {
+  font-size: var(--font-size-sm);
+  font-weight: 500;
+  color: var(--text-secondary);
+  letter-spacing: 0.01em;
+}
+
+.form-input {
+  padding: var(--space-3) var(--space-4);
+  border: 1.5px solid var(--border-subtle);
+  background-color: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: var(--font-size-base);
+  font-family: var(--font-body);
+  border-radius: var(--radius-sm);
+  transition: border-color var(--duration-fast) var(--ease-out),
+              box-shadow var(--duration-fast) var(--ease-out);
+
+  &::placeholder { color: var(--text-muted); }
+
+  &:focus {
+    outline: none;
+    border-color: var(--color-accent);
+    box-shadow: 0 0 0 3px var(--color-accent-dim);
+  }
+
+  &[aria-invalid="true"] {
+    border-color: oklch(50% 0.2 25);
+  }
+}
+
+.form-error {
+  font-size: var(--font-size-sm);
+  color: oklch(50% 0.2 25);
+}
+```
+
+### Card
+
+Cards are not the default layout answer — use them only when content requires clear grouping. Never nest cards.
+
+```css
+.card {
+  background-color: var(--bg-elevated);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  overflow: hidden;
+  transition: box-shadow var(--duration-base) var(--ease-out),
+              transform var(--duration-base) var(--ease-out);
+
+  &:where([href], [tabindex], [role="button"]):hover {
+    box-shadow: var(--shadow-md);
+    transform: translateY(-2px);
+  }
+}
+
+.card__media {
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+
+  img { width: 100%; height: 100%; object-fit: cover; }
+}
+
+.card__body {
+  padding: var(--space-6);
+}
+
+.card__title {
+  font-size: var(--font-size-xl);
+  font-weight: 600;
+  color: var(--text-primary);
+  margin-bottom: var(--space-2);
+}
+```
+
+### Navigation
+
+```css
+.nav {
+  display: flex;
+  align-items: center;
+  gap: var(--space-8);
+  padding: var(--space-4) var(--space-8);
+}
+
+.nav__link {
+  font-size: var(--font-size-sm);
+  font-weight: 500;
+  color: var(--text-secondary);
+  text-decoration: none;
+  letter-spacing: 0.02em;
+  position: relative;
+  transition: color var(--duration-fast) var(--ease-out);
+
+  &::after {
+    content: '';
+    position: absolute;
+    left: 0; bottom: -2px;
+    width: 100%; height: 1px;
+    background-color: var(--color-accent);
+    transform: scaleX(0);
+    transform-origin: right;
+    transition: transform var(--duration-base) var(--ease-out);
+  }
+
+  &:hover, &[aria-current="page"] {
+    color: var(--text-primary);
+  }
+
+  &:hover::after, &[aria-current="page"]::after {
+    transform: scaleX(1);
+    transform-origin: left;
+  }
+}
+```
+
+## Responsive Layout System
+
+Mobile-first. Grid collapses from desktop to tablet to mobile. Use CSS Grid for 2D layouts, Flexbox for 1D.
+
+```css
+.container {
+  width: 100%;
+  margin-inline: auto;
+  padding-inline: var(--space-4);
+}
+
+@media (min-width: 640px)  { .container { max-width: 640px;  padding-inline: var(--space-6); } }
+@media (min-width: 768px)  { .container { max-width: 768px;  } }
+@media (min-width: 1024px) { .container { max-width: 1024px; padding-inline: var(--space-8); } }
+@media (min-width: 1280px) { .container { max-width: 1280px; } }
+@media (min-width: 1536px) { .container { max-width: 1400px; } }
+
+/* Auto-responsive grid — no breakpoint classes needed */
+.grid-auto {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(300px, 100%), 1fr));
+  gap: var(--space-6);
+}
+
+/* Explicit column grid */
+.grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: var(--space-8); }
+.grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--space-6); }
+
+@media (max-width: 768px) {
+  .grid-2, .grid-3 { grid-template-columns: 1fr; }
+}
+
+/* Sidebar layout */
+.layout-sidebar {
+  display: grid;
+  grid-template-columns: 1fr 320px;
+  gap: var(--space-12);
+  align-items: start;
+}
+
+@media (max-width: 1024px) {
+  .layout-sidebar { grid-template-columns: 1fr; }
+}
+```
+
+## Accessibility Baseline
+
+Required on every component:
+- 4.5:1 contrast for body text; 3:1 for large text (≥24px or 18.5px bold)
+- 44×44px minimum touch target
+- Focus-visible on all interactive elements — never `outline: none` without replacement
+- Keyboard navigation: tab order matches visual order
+- All images have `alt` text; decorative images have `alt=""`
+- Form inputs have associated `<label>` elements (not just placeholder text)
+- Error messages use `aria-describedby`, not just color
+
+## Component States Required
+
+For every interactive component, define all states before shipping:
+
+| State | Required behavior |
+|---|---|
+| Default | Base appearance |
+| Hover | Visible feedback (not just cursor change) |
+| Focus-visible | Distinct ring; keyboard users need this |
+| Active | Pressed indication |
+| Disabled | Reduced opacity + `cursor: not-allowed` |
+| Loading | Spinner or skeleton; disable interaction |
+| Error | Red border/icon + error message |
+| Success | Confirmation feedback |
+| Empty | Helpful empty state with action |
+
+## File Structure
+
+```
+styles/
+├── tokens.css          # Design tokens (OKLCH palette, spacing, motion)
+├── reset.css           # Opinionated reset
+├── typography.css      # Type hierarchy classes
+├── layout.css          # Container, grid, section patterns
+├── components.css      # All component styles
+├── utilities.css       # Helper classes (.sr-only, .visually-hidden)
+└── main.css            # Import orchestration
+
+scripts/
+├── theme-manager.js    # Light/dark/system toggle
+└── main.js             # App init
+```