ganbatte-os 0.2.1

package/skills/interface-design/references/extract.md

@@ -0,0 +1,92 @@
+# Extract Patterns
+
+Extract design patterns from existing code to create a `.interface-design/system.md` file.
+
+---
+
+## Usage
+
+Extract from common UI paths or a specific directory.
+
+---
+
+## What to Extract
+
+Scan UI files (tsx, jsx, vue, svelte, css, scss) for:
+
+### 1. Repeated spacing values
+```
+Found: 4px (12x), 8px (23x), 12px (18x), 16px (31x), 24px (8x)
+Suggests: Base 4px, Scale: 4, 8, 12, 16, 24
+```
+
+### 2. Repeated radius values
+```
+Found: 6px (28x), 8px (5x)
+Suggests: Radius scale: 6px, 8px
+```
+
+### 3. Button patterns
+```
+Found 8 buttons:
+- Height: 36px (7/8), 40px (1/8)
+- Padding: 12px 16px (6/8), 16px (2/8)
+Suggests: Button pattern: 36px h, 12px 16px padding
+```
+
+### 4. Card patterns
+```
+Found 12 cards:
+- Border: 1px solid (10/12), none (2/12)
+- Padding: 16px (9/12), 20px (3/12)
+Suggests: Card pattern: 1px border, 16px padding
+```
+
+### 5. Depth strategy
+```
+box-shadow found: 2x
+border found: 34x
+Suggests: Borders-only depth
+```
+
+### 6. Color palette
+```
+Colors found:
+- Gray family: slate-100 through slate-900 (dominant)
+- Accent: blue-600 (12x), blue-500 (3x)
+- Semantic: red-500 (4x), green-500 (3x), amber-500 (2x)
+Suggests: Slate foundation, blue accent
+```
+
+---
+
+## Output Prompt
+
+```
+Extracted patterns:
+
+Spacing:
+  Base: 4px
+  Scale: 4, 8, 12, 16, 24, 32
+
+Depth: Borders-only (34 borders, 2 shadows)
+
+Radius: 6px, 8px
+
+Patterns:
+  Button: 36px h, 12px 16px pad, 6px radius
+  Card: 1px border, 16px pad
+
+Create .interface-design/system.md with these? (y/n/customize)
+```
+
+---
+
+## Implementation Steps
+
+1. Glob for UI files in target path
+2. Parse for repeated spacing, radius, shadow, border, and color values
+3. Identify dominant patterns by frequency
+4. Suggest system based on most common values
+5. Present to user for confirmation
+6. Offer customization before saving to `.interface-design/system.md`

package/skills/interface-design/references/principles.md

@@ -0,0 +1,348 @@
+# Design Principles — Technical Reference
+
+Deep reference for token architecture, CSS patterns, spacing systems, and implementation details.
+
+---
+
+## Token Architecture
+
+Every color in your interface should trace back to a small set of primitives:
+
+- **Foreground** — text colors (primary, secondary, tertiary, muted)
+- **Background** — surface colors (base, elevated, overlay)
+- **Border** — edge colors (default, subtle, strong, stronger)
+- **Brand** — your primary accent
+- **Semantic** — functional colors (destructive, warning, success, info)
+
+No random hex values. Everything maps to primitives.
+
+### The Primitive Foundation
+
+```css
+/* Dark mode example — slate family */
+:root {
+  /* Foreground (text hierarchy) */
+  --fg-primary: hsl(210 11% 93%);      /* ~#e8eaed */
+  --fg-secondary: hsl(215 8% 62%);     /* ~#959ba5 */
+  --fg-tertiary: hsl(215 8% 46%);      /* ~#6b7280 */
+  --fg-muted: hsl(215 8% 34%);         /* ~#4e545e */
+
+  /* Background (surface elevation) */
+  --bg-base: hsl(220 13% 9%);          /* ~#141518 */
+  --bg-surface-1: hsl(220 13% 11%);    /* ~#191b1f */
+  --bg-surface-2: hsl(220 13% 13%);    /* ~#1e2025 */
+  --bg-surface-3: hsl(220 13% 16%);    /* ~#262830 */
+  --bg-inset: hsl(220 13% 7%);         /* ~#101114 */
+
+  /* Border (separation hierarchy) */
+  --border-default: rgba(255, 255, 255, 0.08);
+  --border-subtle: rgba(255, 255, 255, 0.05);
+  --border-strong: rgba(255, 255, 255, 0.12);
+  --border-stronger: rgba(255, 255, 255, 0.20);
+
+  /* Brand */
+  --accent: hsl(217 91% 60%);          /* blue-500 */
+  --accent-hover: hsl(217 91% 55%);
+
+  /* Semantic */
+  --destructive: hsl(0 72% 51%);
+  --warning: hsl(38 92% 50%);
+  --success: hsl(142 71% 45%);
+}
+```
+
+### Light Mode Equivalent
+
+```css
+:root[data-theme="light"] {
+  --fg-primary: hsl(220 13% 13%);
+  --fg-secondary: hsl(215 16% 47%);
+  --fg-tertiary: hsl(215 14% 62%);
+  --fg-muted: hsl(215 12% 77%);
+
+  --bg-base: hsl(0 0% 100%);
+  --bg-surface-1: hsl(210 20% 98%);
+  --bg-surface-2: hsl(210 17% 95%);
+  --bg-surface-3: hsl(210 14% 92%);
+  --bg-inset: hsl(210 20% 96%);
+
+  --border-default: rgba(0, 0, 0, 0.08);
+  --border-subtle: rgba(0, 0, 0, 0.05);
+  --border-strong: rgba(0, 0, 0, 0.12);
+  --border-stronger: rgba(0, 0, 0, 0.20);
+}
+```
+
+---
+
+## Text Hierarchy
+
+Four levels, each with a distinct role:
+
+| Level | Role | Example |
+|-------|------|---------|
+| **Primary** | Default text, highest contrast | Page titles, body text, labels |
+| **Secondary** | Supporting text, slightly muted | Descriptions, helper text |
+| **Tertiary** | Metadata, timestamps | "Updated 2 hours ago", table headers |
+| **Muted** | Disabled, placeholder | Input placeholders, disabled labels |
+
+Use all four consistently. Two-level hierarchy (text + gray text) is too flat.
+
+---
+
+## Border Progression
+
+Four levels matching intensity to importance:
+
+| Level | Opacity (dark) | Use |
+|-------|---------------|-----|
+| **Subtle** | 0.05 | Softest separation, visual grouping |
+| **Default** | 0.08 | Standard card/panel borders |
+| **Strong** | 0.12 | Emphasis, hover states, section dividers |
+| **Stronger** | 0.20 | Focus rings, maximum emphasis |
+
+Use `rgba()` not solid hex. Low-opacity borders blend with backgrounds — they define edges without demanding attention.
+
+---
+
+## Control Tokens
+
+Form controls need dedicated tokens, not reused surface tokens:
+
+```css
+--control-bg: hsl(220 13% 7%);         /* Slightly darker than surface (inset) */
+--control-border: rgba(255, 255, 255, 0.10);
+--control-border-hover: rgba(255, 255, 255, 0.15);
+--control-border-focus: var(--accent);
+--control-ring: 0 0 0 2px rgba(59, 130, 246, 0.3);
+```
+
+This separation lets you tune interactive elements independently from layout surfaces.
+
+---
+
+## Spacing System
+
+Pick a base unit (4px is standard) and use only multiples:
+
+| Context | Values | Use |
+|---------|--------|-----|
+| **Micro** | 2px, 4px | Icon gaps, tight element pairs |
+| **Component** | 6px, 8px, 12px | Within buttons, inputs, badges |
+| **Section** | 16px, 20px, 24px | Card padding, group spacing |
+| **Major** | 32px, 48px, 64px | Page sections, layout gaps |
+
+```css
+--space-1: 4px;
+--space-2: 8px;
+--space-3: 12px;
+--space-4: 16px;
+--space-6: 24px;
+--space-8: 32px;
+--space-12: 48px;
+```
+
+Random values (14px, 17px, 22px) signal no system.
+
+### Padding Symmetry
+
+Keep it symmetrical. TLBR must match unless content naturally requires asymmetry.
+
+```css
+/* Good */
+padding: 16px;
+padding: 12px 16px; /* Only when horizontal needs more room */
+
+/* Bad — no system */
+padding: 24px 16px 12px 16px;
+```
+
+---
+
+## Depth & Elevation Strategy
+
+Choose ONE approach and commit:
+
+### Borders-only (flat)
+Clean, technical, dense. For utility-focused tools where information density matters.
+
+```css
+--border: rgba(0, 0, 0, 0.08);
+--border-subtle: rgba(0, 0, 0, 0.05);
+border: 0.5px solid var(--border);
+```
+
+Linear, Raycast, and developer tools use this approach.
+
+### Subtle single shadows
+Soft lift without complexity. For approachable products that want gentle depth.
+
+```css
+--shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+```
+
+### Layered shadows
+Rich, premium, dimensional. For cards that need to feel like physical objects.
+
+```css
+--shadow-layered:
+  0 0 0 0.5px rgba(0, 0, 0, 0.05),
+  0 1px 2px rgba(0, 0, 0, 0.04),
+  0 2px 4px rgba(0, 0, 0, 0.03),
+  0 4px 8px rgba(0, 0, 0, 0.02);
+```
+
+Stripe and Mercury use layered shadows.
+
+### Surface color shifts
+Background tints establish hierarchy without any shadows.
+
+```css
+/* Card on page */
+background: #fff; /* card */
+/* sits on */
+background: #f8fafc; /* page - already feels elevated */
+```
+
+**Never mix approaches.** Shadows + dramatic borders = visual confusion.
+
+---
+
+## Border Radius
+
+Build a scale matching product personality:
+
+| Product feel | Small | Medium | Large |
+|-------------|-------|--------|-------|
+| **Technical** | 2px | 4px | 6px |
+| **Balanced** | 4px | 6px | 8px |
+| **Friendly** | 6px | 8px | 12px |
+| **Soft** | 8px | 12px | 16px |
+
+Small for inputs/buttons, medium for cards, large for modals. Don't mix sharp and soft randomly.
+
+---
+
+## Typography Hierarchy
+
+Distinct levels distinguishable at a glance:
+
+| Level | Size | Weight | Tracking | Use |
+|-------|------|--------|----------|-----|
+| **Display** | 24-32px | 600-700 | -0.02em | Page hero, main title |
+| **Heading** | 18-20px | 600 | -0.01em | Section headers |
+| **Body** | 14-16px | 400 | normal | Content, descriptions |
+| **Label** | 12-13px | 500 | 0.01em | UI labels, badges |
+| **Data** | 13-14px mono | 400 | 0 | Numbers, IDs, timestamps |
+
+Don't rely on size alone — combine size, weight, and letter-spacing.
+
+### Monospace for Data
+
+Numbers, IDs, codes, timestamps belong in monospace. Use `font-variant-numeric: tabular-nums` for columnar alignment.
+
+---
+
+## Card Layouts
+
+Design each card's internal structure for its specific content — but keep the surface treatment consistent:
+
+- Same border weight across all cards
+- Same shadow depth (or none)
+- Same corner radius
+- Same padding scale
+
+A metric card doesn't have to look like a settings card. Internal structure varies; surface treatment stays consistent.
+
+---
+
+## Controls
+
+Never use native form elements for styled UI:
+- `<select>` renders OS-native dropdown — build custom trigger + positioned dropdown
+- `<input type="date">` renders OS-native calendar — build custom input + calendar popover
+- Custom checkbox/radio: styled div with state management
+
+Custom select triggers must use `display: inline-flex` with `white-space: nowrap`.
+
+---
+
+## Iconography
+
+Icons clarify, not decorate. If removing an icon loses no meaning, remove it.
+
+- Choose one icon set (e.g., Lucide) and use it consistently
+- Standalone icons: give presence with subtle background containers
+- Icons next to text: align optically, not mathematically
+- Icon-only buttons: always include `aria-label`
+
+---
+
+## Animation
+
+| Context | Duration | Easing |
+|---------|----------|--------|
+| Hover, focus | ~150ms | ease-out |
+| Dropdowns, panels | 200-250ms | ease-out |
+| Page transitions | 250-350ms | ease-in-out |
+
+Avoid spring/bounce effects in professional interfaces. They feel playful, not serious.
+
+---
+
+## Interactive States
+
+Every interactive element needs all states:
+
+| State | Visual treatment |
+|-------|-----------------|
+| **Default** | Base appearance |
+| **Hover** | Subtle bg shift or border emphasis |
+| **Active/Pressed** | Slightly darker than hover |
+| **Focus** | Focus ring (border-stronger or accent ring) |
+| **Disabled** | Reduced opacity (0.5), no pointer events |
+
+Data elements need additional states: **loading** (skeleton/spinner), **empty** (illustration + action), **error** (message + retry).
+
+Missing states make an interface feel like a photograph of software.
+
+---
+
+## Navigation Context
+
+Screens need grounding — a data table floating in space feels like a component demo.
+
+Include:
+- **Navigation** — sidebar or top nav showing position in the app
+- **Location indicator** — breadcrumbs, page title, or active nav state
+- **User context** — who's logged in, what workspace/org
+
+**Sidebar approach:** Same background as main content with border separation. Different colors fragment the visual space.
+
+---
+
+## Dark Mode
+
+Dark interfaces have different needs:
+
+- **Borders over shadows** — shadows are less visible on dark backgrounds; lean on borders for definition
+- **Desaturate semantics** — success/warning/error colors often need slight desaturation for dark surfaces
+- **Same hierarchy, inverted values** — higher elevation = slightly lighter (opposite of light mode)
+- **Surface shifts stay subtle** — a few percentage points of lightness between levels, not dramatic jumps
+
+---
+
+## Avoid
+
+- **Harsh borders** — if borders are the first thing you see, they're too strong
+- **Dramatic surface jumps** — elevation changes should be whisper-quiet
+- **Inconsistent spacing** — the clearest sign of no system
+- **Mixed depth strategies** — pick one approach and commit
+- **Missing interaction states** — hover, focus, disabled, loading, error
+- **Dramatic drop shadows** — shadows should be subtle, not attention-grabbing
+- **Large radius on small elements**
+- **Pure white cards on colored backgrounds**
+- **Thick decorative borders**
+- **Gradients and color for decoration** — color should mean something
+- **Multiple accent colors** — dilutes focus
+- **Different hues for different surfaces** — keep the same hue, shift only lightness

package/skills/interface-design/references/templates/system-precision.md

@@ -0,0 +1,73 @@
+# Design System — Precision & Density
+
+Starter template for dashboard, admin, and data-heavy interfaces. Adapt values to your product's world — this is a starting point, not a prescription.
+
+## Direction
+
+**Personality:** Precision & Density
+**Foundation:** Cool (slate)
+**Depth:** Borders-only
+
+## Tokens
+
+### Spacing
+Base: 4px
+Scale: 4, 8, 12, 16, 24, 32
+
+### Colors
+```
+--fg-primary: slate-900
+--fg-secondary: slate-600
+--fg-tertiary: slate-400
+--fg-muted: slate-200
+--border-default: rgba(0, 0, 0, 0.08)
+--border-subtle: rgba(0, 0, 0, 0.05)
+--accent: blue-600
+```
+
+### Radius
+Scale: 4px, 6px, 8px (sharp, technical)
+
+### Typography
+Font: system-ui (fast, native feel)
+Scale: 11, 12, 13, 14 (base), 16, 18
+Weights: 400, 500, 600
+Mono: SF Mono, Consolas (for data)
+
+## Patterns
+
+### Button
+- Height: 32px (compact)
+- Padding: 8px 12px
+- Radius: 4px
+- Font: 13px, 500 weight
+- Border: 1px solid
+- Usage: Actions in dense layouts
+
+### Card
+- Border: 0.5px solid (subtle)
+- Padding: 12px
+- Radius: 6px
+- Shadow: none
+- Usage: Data containers, metric displays
+
+### Table Cell
+- Padding: 8px 12px
+- Font: 13px tabular-nums
+- Border-bottom: 1px solid (subtle)
+
+### Input
+- Height: 32px
+- Padding: 6px 8px
+- Radius: 4px
+- Background: inset (slightly darker)
+- Border: 1px solid (default)
+
+## Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Borders-only | Information density matters more than lift |
+| Compact sizing | Power users, high information density |
+| System fonts | Performance, native feel |
+| Sharp radius | Technical, precise personality |

package/skills/interface-design/references/templates/system-warmth.md

@@ -0,0 +1,67 @@
+# Design System — Warmth & Approachability
+
+Starter template for collaborative, creative, and consumer-facing apps. Adapt values to your product's world — this is a starting point, not a prescription.
+
+## Direction
+
+**Personality:** Warmth & Approachability
+**Foundation:** Warm (stone)
+**Depth:** Subtle shadows
+
+## Tokens
+
+### Spacing
+Base: 4px
+Scale: 8, 12, 16, 24, 32, 48 (generous)
+
+### Colors
+```
+--fg-primary: stone-900
+--fg-secondary: stone-600
+--fg-tertiary: stone-400
+--fg-muted: stone-200
+--accent: orange-500
+--shadow: 0 1px 3px rgba(0, 0, 0, 0.08)
+```
+
+### Radius
+Scale: 8px, 12px, 16px (soft, friendly)
+
+### Typography
+Font: Inter (approachable, readable)
+Scale: 13, 14, 15, 16 (base), 18, 20, 24
+Weights: 400, 500, 600
+
+## Patterns
+
+### Button
+- Height: 40px (comfortable)
+- Padding: 12px 20px
+- Radius: 8px
+- Font: 15px, 500 weight
+- Shadow: subtle
+- Usage: Primary actions, comfortable click targets
+
+### Card
+- Border: none
+- Padding: 20px
+- Radius: 12px
+- Shadow: 0 1px 3px rgba(0,0,0,0.08)
+- Background: white on stone-50
+- Usage: Content containers, feature cards
+
+### Input
+- Height: 44px
+- Padding: 12px 16px
+- Radius: 8px
+- Border: 1.5px solid (subtle)
+- Usage: Form fields, generous touch targets
+
+## Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Subtle shadows | Gentle depth, approachable feel |
+| Generous spacing | Focused tasks, not cramming information |
+| Warm foundation | Human, comfortable, inviting |
+| Soft radius | Friendly, organic personality |

package/skills/interface-design/references/validation.md

@@ -0,0 +1,137 @@
+# Validation & Memory Management
+
+When and how to update `.interface-design/system.md`. Rules for pattern persistence and consistency verification.
+
+---
+
+## When to Add Patterns
+
+Add to system.md when:
+- Component used **2+ times** in the project
+- Pattern is **reusable** across different contexts
+- Has **specific measurements** worth remembering (height, padding, radius, shadow)
+
+## When NOT to Add
+
+- **One-off components** — unique to a single page/context
+- **Temporary experiments** — still iterating on the design
+- **Variations better handled with props** — a Button with size variants doesn't need separate patterns per size
+
+---
+
+## Pattern Format
+
+Keep patterns concise and scannable:
+
+```markdown
+### Button Primary
+- Height: 36px
+- Padding: 12px 16px
+- Radius: 6px
+- Font: 14px, 500 weight
+- Usage: Primary actions, form submits
+```
+
+Include:
+- Name (component + variant)
+- Key measurements (height, padding, radius)
+- Typography if specific (size, weight)
+- Usage context (when to use this pattern)
+
+---
+
+## Pattern Reuse Rules
+
+Before creating any component, **check system.md first:**
+
+1. **Pattern exists?** Use it exactly. Don't reinvent.
+2. **Need a variation?** Extend the existing pattern, don't create a new one from scratch.
+3. **New pattern type?** Build it, then add to system.md after first use.
+4. **Pattern outdated?** Update the system.md entry, don't just override silently.
+
+Memory compounds: each pattern saved makes future work faster and more consistent.
+
+---
+
+## system.md Structure
+
+```markdown
+# Design System
+
+## Direction
+Personality: [Precision & Density / Warmth / etc]
+Foundation: [Cool slate / Warm stone / etc]
+Depth: [Borders-only / Subtle shadows / Layered]
+
+## Tokens
+### Spacing
+Base: 4px
+Scale: 4, 8, 12, 16, 24, 32
+
+### Colors
+--foreground: [value]
+--secondary: [value]
+--accent: [value]
+
+### Radius
+Scale: [values]
+
+### Typography
+Font: [family]
+Scale: [sizes]
+Weights: [values]
+
+## Patterns
+### [Component Name]
+- [Key properties]
+- Usage: [when to use]
+
+## Decisions
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| [choice] | [why]     | [when] |
+```
+
+---
+
+## Consistency Checks
+
+If system.md defines values, verify against them:
+
+| Check | Rule |
+|-------|------|
+| **Spacing** | All values multiples of defined base unit |
+| **Depth** | Using declared strategy throughout (borders-only = no shadows) |
+| **Colors** | Using defined palette, no random hex codes |
+| **Patterns** | Reusing documented patterns instead of creating new |
+| **Radius** | Using defined scale, not ad-hoc values |
+| **Typography** | Using defined font stack and size scale |
+
+---
+
+## When to Update system.md
+
+| Trigger | Action |
+|---------|--------|
+| New reusable component built | Add pattern after confirmation |
+| Existing pattern modified | Update pattern entry |
+| Direction change | Update Direction section, verify cascading consistency |
+| New token added | Add to Tokens section |
+| Design decision made | Add to Decisions table with rationale |
+
+---
+
+## Offering to Save
+
+After completing any UI building task, always offer:
+
+```
+"Want me to save these patterns for future sessions?"
+```
+
+If yes, write or update `.interface-design/system.md` with:
+- Direction and feel (if new project)
+- Depth strategy
+- Spacing base unit
+- Any new component patterns
+- Key decisions with rationale