first commit

.agent/skills/interface-design/references/critique.md

@@ -0,0 +1,67 @@
+# Critique
+
+Your first build shipped the structure. Now look at it the way a design lead reviews a junior's work — not asking "does this work?" but "would I put my name on this?"
+
+---
+
+## The Gap
+
+There's a distance between correct and crafted. Correct means the layout holds, the grid aligns, the colors don't clash. Crafted means someone cared about every decision down to the last pixel. You can feel the difference immediately — the way you tell a hand-thrown mug from an injection-molded one. Both hold coffee. One has presence.
+
+Your first output lives in correct. This command pulls it toward crafted.
+
+---
+
+## See the Composition
+
+Step back. Look at the whole thing.
+
+Does the layout have rhythm? Great interfaces breathe unevenly — dense tooling areas give way to open content, heavy elements balance against light ones, the eye travels through the page with purpose. Default layouts are monotone: same card size, same gaps, same density everywhere. Flatness is the sound of no one deciding.
+
+Are proportions doing work? A 280px sidebar next to full-width content says "navigation serves content." A 360px sidebar says "these are peers." The specific number declares what matters. If you can't articulate what your proportions are saying, they're not saying anything.
+
+Is there a clear focal point? Every screen has one thing the user came here to do. That thing should dominate — through size, position, contrast, or the space around it. When everything competes equally, nothing wins and the interface feels like a parking lot.
+
+---
+
+## See the Craft
+
+Move close. Pixel-close.
+
+The spacing grid is non-negotiable — every value a multiple of 4, no exceptions — but correctness alone isn't craft. Craft is knowing that a tool panel at 16px padding feels workbench-tight while the same card at 24px feels like a brochure. The same number can be right in one context and lazy in another. Density is a design decision, not a constant.
+
+Typography should be legible even squinted. If size is the only thing separating your headline from your body from your label, the hierarchy is too weak. Weight, tracking, and opacity create layers that size alone can't.
+
+Surfaces should whisper hierarchy. Not thick borders, not dramatic shadows — quiet tonal shifts where you feel the depth without seeing it. Remove every border from your CSS mentally. Can you still perceive the structure through surface color alone? If not, your surfaces aren't working hard enough.
+
+Interactive elements need life. Every button, link, and clickable region should respond to hover and press. Not dramatically — a subtle shift in background, a gentle darkening. Missing states make an interface feel like a photograph of software instead of software.
+
+---
+
+## See the Content
+
+Read every visible string as a user would. Not checking for typos — checking for truth.
+
+Does this screen tell one coherent story? Could a real person at a real company be looking at exactly this data right now? Or does the page title belong to one product, the article body to another, and the sidebar metrics to a third?
+
+Content incoherence breaks the illusion faster than any visual flaw. A beautifully designed interface with nonsensical content is a movie set with no script.
+
+---
+
+## See the Structure
+
+Open the CSS and find the lies — the places that look right but are held together with tape.
+
+Negative margins undoing a parent's padding. Calc() values that exist only as workarounds. Absolute positioning to escape layout flow. Each is a shortcut where a clean solution exists. Cards with full-width dividers use flex column and section-level padding. Centered content uses max-width with auto margins. The correct answer is always simpler than the hack.
+
+---
+
+## Again
+
+Look at your output one final time.
+
+Ask: "If they said this lacks craft, what would they point to?"
+
+That thing you just thought of — fix it. Then ask again.
+
+The first build was the draft. The critique is the design.

.agent/skills/interface-design/references/example.md

@@ -0,0 +1,86 @@
+# Craft in Action
+
+This shows how the subtle layering principle translates to real decisions. Learn the thinking, not the code. Your values will differ — the approach won't.
+
+---
+
+## The Subtle Layering Mindset
+
+Before looking at any example, internalize this: **you should barely notice the system working.**
+
+When you look at Vercel's dashboard, you don't think "nice borders." You just understand the structure. When you look at Supabase, you don't think "good surface elevation." You just know what's above what. The craft is invisible — that's how you know it's working.
+
+---
+
+## Example: Dashboard with Sidebar and Dropdown
+
+### The Surface Decisions
+
+**Why so subtle?** Each elevation jump should be only a few percentage points of lightness. You can barely see the difference in isolation. But when surfaces stack, the hierarchy emerges. This is the Vercel/Supabase way — whisper-quiet shifts that you feel rather than see.
+
+**What NOT to do:** Don't make dramatic jumps between elevations. That's jarring. Don't use different hues for different levels. Keep the same hue, shift only lightness.
+
+### The Border Decisions
+
+**Why rgba, not solid colors?** Low opacity borders blend with their background. A low-opacity white border on a dark surface is barely there — it defines the edge without demanding attention. Solid hex borders look harsh in comparison.
+
+**The test:** Look at your interface from arm's length. If borders are the first thing you notice, reduce opacity. If you can't find where regions end, increase slightly.
+
+### The Sidebar Decision
+
+**Why same background as canvas, not different?**
+
+Many dashboards make the sidebar a different color. This fragments the visual space — now you have "sidebar world" and "content world."
+
+Better: Same background, subtle border separation. The sidebar is part of the app, not a separate region. Vercel does this. Supabase does this. The border is enough.
+
+### The Dropdown Decision
+
+**Why surface-200, not surface-100?**
+
+The dropdown floats above the card it emerged from. If both were surface-100, the dropdown would blend into the card — you'd lose the sense of layering. Surface-200 is just light enough to feel "above" without being dramatically different.
+
+**Why border-overlay instead of border-default?**
+
+Overlays (dropdowns, popovers) often need slightly more definition because they're floating in space. A touch more border opacity helps them feel contained without being harsh.
+
+---
+
+## Example: Form Controls
+
+### Input Background Decision
+
+**Why darker, not lighter?**
+
+Inputs are "inset" — they receive content, they don't project it. A slightly darker background signals "type here" without needing heavy borders. This is the alternative-background principle.
+
+### Focus State Decision
+
+**Why subtle focus states?**
+
+Focus needs to be visible, but you don't need a glowing ring or dramatic color. A noticeable increase in border opacity is enough for a clear state change. Subtle-but-noticeable — the same principle as surfaces.
+
+---
+
+## Adapt to Context
+
+Your product might need:
+- Warmer hues (slight yellow/orange tint)
+- Cooler hues (blue-gray base)
+- Different lightness progression
+- Light mode (principles invert — higher elevation = shadow, not lightness)
+
+**The principle is constant:** barely different, still distinguishable. The values adapt to context.
+
+---
+
+## The Craft Check
+
+Apply the squint test to your work:
+
+1. Blur your eyes or step back
+2. Can you still perceive hierarchy?
+3. Is anything jumping out at you?
+4. Can you tell where regions begin and end?
+
+If hierarchy is visible and nothing is harsh — the subtle layering is working.

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

@@ -0,0 +1,235 @@
+# Core Craft Principles
+
+These apply regardless of design direction. This is the quality floor.
+
+---
+
+## Surface & Token Architecture
+
+Professional interfaces don't pick colors randomly — they build systems. Understanding this architecture is the difference between "looks okay" and "feels like a real product."
+
+### The Primitive Foundation
+
+Every color in your interface should trace back to a small set of primitives:
+
+- **Foreground** — text colors (primary, secondary, muted)
+- **Background** — surface colors (base, elevated, overlay)
+- **Border** — edge colors (default, subtle, strong)
+- **Brand** — your primary accent
+- **Semantic** — functional colors (destructive, warning, success)
+
+Don't invent new colors. Map everything to these primitives.
+
+### Surface Elevation Hierarchy
+
+Surfaces stack. A dropdown sits above a card which sits above the page. Build a numbered system:
+
+```
+Level 0: Base background (the app canvas)
+Level 1: Cards, panels (same visual plane as base)
+Level 2: Dropdowns, popovers (floating above)
+Level 3: Nested dropdowns, stacked overlays
+Level 4: Highest elevation (rare)
+```
+
+In dark mode, higher elevation = slightly lighter. In light mode, higher elevation = slightly lighter or uses shadow. The principle: **elevated surfaces need visual distinction from what's beneath them.**
+
+### The Subtlety Principle
+
+This is where most interfaces fail. Study Vercel, Supabase, Linear — their surfaces are **barely different** but still distinguishable. Their borders are **light but not invisible**.
+
+**For surfaces:** The difference between elevation levels should be subtle — a few percentage points of lightness, not dramatic jumps. In dark mode, surface-100 might be 7% lighter than base, surface-200 might be 9%, surface-300 might be 12%. You can barely see it, but you feel it.
+
+**For borders:** Borders should define regions without demanding attention. Use low opacity (0.05-0.12 alpha for dark mode, slightly higher for light). The border should disappear when you're not looking for it, but be findable when you need to understand the structure.
+
+**The test:** Squint at your interface. You should still perceive the hierarchy — what's above what, where regions begin and end. But no single border or surface should jump out at you. If borders are the first thing you notice, they're too strong. If you can't find where one region ends and another begins, they're too subtle.
+
+**Common AI mistakes to avoid:**
+- Borders that are too visible (1px solid gray instead of subtle rgba)
+- Surface jumps that are too dramatic (going from dark to light instead of dark to slightly-less-dark)
+- Using different hues for different surfaces (gray card on blue background)
+- Harsh dividers where subtle borders would do
+
+### Text Hierarchy via Tokens
+
+Don't just have "text" and "gray text." Build four levels:
+
+- **Primary** — default text, highest contrast
+- **Secondary** — supporting text, slightly muted
+- **Tertiary** — metadata, timestamps, less important
+- **Muted** — disabled, placeholder, lowest contrast
+
+Use all four consistently. If you're only using two, your hierarchy is too flat.
+
+### Border Progression
+
+Borders aren't binary. Build a scale:
+
+- **Default** — standard borders
+- **Subtle/Muted** — softer separation
+- **Strong** — emphasis, hover states
+- **Stronger** — maximum emphasis, focus rings
+
+Match border intensity to the importance of the boundary.
+
+### Dedicated Control Tokens
+
+Form controls (inputs, checkboxes, selects) have specific needs. Don't just reuse surface tokens — create dedicated ones:
+
+- **Control background** — often different from surface backgrounds
+- **Control border** — needs to feel interactive
+- **Control focus** — clear focus indication
+
+This separation lets you tune controls independently from layout surfaces.
+
+### Context-Aware Bases
+
+Different areas of your app might need different base surfaces:
+
+- **Marketing pages** — might use darker/richer backgrounds
+- **Dashboard/app** — might use neutral working backgrounds
+- **Sidebar** — might differ from main canvas
+
+The surface hierarchy works the same way — it just starts from a different base.
+
+### Alternative Backgrounds for Depth
+
+Beyond shadows, use contrasting backgrounds to create depth. An "alternative" or "inset" background makes content feel recessed. Useful for:
+
+- Empty states in data grids
+- Code blocks
+- Inset panels
+- Visual grouping without borders
+
+---
+
+## Spacing System
+
+Pick a base unit (4px and 8px are common) and use multiples throughout. The specific number matters less than consistency — every spacing value should be explainable as "X times the base unit."
+
+Build a scale for different contexts:
+- Micro spacing (icon gaps, tight element pairs)
+- Component spacing (within buttons, inputs, cards)
+- Section spacing (between related groups)
+- Major separation (between distinct sections)
+
+## Symmetrical Padding
+
+TLBR must match. If top padding is 16px, left/bottom/right must also be 16px. Exception: when content naturally creates visual balance.
+
+```css
+/* Good */
+padding: 16px;
+padding: 12px 16px; /* Only when horizontal needs more room */
+
+/* Bad */
+padding: 24px 16px 12px 16px;
+```
+
+## Border Radius Consistency
+
+Sharper corners feel technical, rounder corners feel friendly. Pick a scale that fits your product's personality and use it consistently.
+
+The key is having a system: small radius for inputs and buttons, medium for cards, large for modals or containers. Don't mix sharp and soft randomly — inconsistent radius is as jarring as inconsistent spacing.
+
+## Depth & Elevation Strategy
+
+Match your depth approach to your design direction. Choose ONE and commit:
+
+**Borders-only (flat)** — Clean, technical, dense. Works for utility-focused tools where information density matters more than visual lift. Linear, Raycast, and many developer tools use almost no shadows — just subtle borders to define regions.
+
+**Subtle single shadows** — Soft lift without complexity. A simple `0 1px 3px rgba(0,0,0,0.08)` can be enough. Works for approachable products that want gentle depth.
+
+**Layered shadows** — Rich, premium, dimensional. Multiple shadow layers create realistic depth. Stripe and Mercury use this approach. Best for cards that need to feel like physical objects.
+
+**Surface color shifts** — Background tints establish hierarchy without any shadows. A card at `#fff` on a `#f8fafc` background already feels elevated.
+
+```css
+/* Borders-only approach */
+--border: rgba(0, 0, 0, 0.08);
+--border-subtle: rgba(0, 0, 0, 0.05);
+border: 0.5px solid var(--border);
+
+/* Single shadow approach */
+--shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+
+/* Layered shadow approach */
+--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);
+```
+
+## Card Layouts
+
+Monotonous card layouts are lazy design. A metric card doesn't have to look like a plan card doesn't have to look like a settings card.
+
+Design each card's internal structure for its specific content — but keep the surface treatment consistent: same border weight, shadow depth, corner radius, padding scale, typography.
+
+## Isolated Controls
+
+UI controls deserve container treatment. Date pickers, filters, dropdowns — these should feel like crafted objects.
+
+**Never use native form elements for styled UI.** Native `<select>`, `<input type="date">`, and similar elements render OS-native dropdowns that cannot be styled. Build custom components instead:
+
+- Custom select: trigger button + positioned dropdown menu
+- Custom date picker: input + calendar popover
+- Custom checkbox/radio: styled div with state management
+
+Custom select triggers must use `display: inline-flex` with `white-space: nowrap` to keep text and chevron icons on the same row.
+
+## Typography Hierarchy
+
+Build distinct levels that are visually distinguishable at a glance:
+
+- **Headlines** — heavier weight, tighter letter-spacing for presence
+- **Body** — comfortable weight for readability
+- **Labels/UI** — medium weight, works at smaller sizes
+- **Data** — often monospace, needs `tabular-nums` for alignment
+
+Don't rely on size alone. Combine size, weight, and letter-spacing to create clear hierarchy. If you squint and can't tell headline from body, the hierarchy is too weak.
+
+## Monospace for Data
+
+Numbers, IDs, codes, timestamps belong in monospace. Use `tabular-nums` for columnar alignment. Mono signals "this is data."
+
+## Iconography
+
+Icons clarify, not decorate — if removing an icon loses no meaning, remove it. Choose a consistent icon set and stick with it throughout the product.
+
+Give standalone icons presence with subtle background containers. Icons next to text should align optically, not mathematically.
+
+## Animation
+
+Keep it fast and functional. Micro-interactions (hover, focus) should feel instant — around 150ms. Larger transitions (modals, panels) can be slightly longer — 200-250ms.
+
+Use smooth deceleration easing (ease-out variants). Avoid spring/bounce effects in professional interfaces — they feel playful, not serious.
+
+## Contrast Hierarchy
+
+Build a four-level system: foreground (primary) → secondary → muted → faint. Use all four consistently.
+
+## Color Carries Meaning
+
+Gray builds structure. Color communicates — status, action, emphasis, identity. Unmotivated color is noise. Color that reinforces the product's world is character.
+
+## Navigation Context
+
+Screens need grounding. A data table floating in space feels like a component demo, not a product. Consider including:
+
+- **Navigation** — sidebar or top nav showing where you are in the app
+- **Location indicator** — breadcrumbs, page title, or active nav state
+- **User context** — who's logged in, what workspace/org
+
+When building sidebars, consider using the same background as the main content area. Rely on a subtle border for separation rather than different background colors.
+
+## Dark Mode
+
+Dark interfaces have different needs:
+
+**Borders over shadows** — Shadows are less visible on dark backgrounds. Lean more on borders for definition.
+
+**Adjust semantic colors** — Status colors (success, warning, error) often need to be slightly desaturated for dark backgrounds.
+
+**Same structure, different values** — The hierarchy system still applies, just with inverted values.

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

@@ -0,0 +1,48 @@
+# Memory Management
+
+When and how to update `.interface-design/system.md`.
+
+## When to Add Patterns
+
+Add to system.md when:
+- Component used 2+ times
+- Pattern is reusable across the project
+- Has specific measurements worth remembering
+
+## Pattern Format
+
+```markdown
+### Button Primary
+- Height: 36px
+- Padding: 12px 16px
+- Radius: 6px
+- Font: 14px, 500 weight
+```
+
+## Don't Document
+
+- One-off components
+- Temporary experiments
+- Variations better handled with props
+
+## Pattern Reuse
+
+Before creating a component, check system.md:
+- Pattern exists? Use it.
+- Need variation? Extend, don't create new.
+
+Memory compounds: each pattern saved makes future work faster and more consistent.
+
+---
+
+# Validation Checks
+
+If system.md defines specific values, check consistency:
+
+**Spacing** — All values multiples of the defined base?
+
+**Depth** — Using the declared strategy throughout? (borders-only means no shadows)
+
+**Colors** — Using defined palette, not random hex codes?
+
+**Patterns** — Reusing documented patterns instead of creating new?