agy-superpowers 5.1.1 → 5.1.3

package/template/agent/skills/frontend-design/reference/color-and-contrast.md

@@ -0,0 +1,117 @@
+# Color & Contrast
+
+## Color Spaces: Use OKLCH
+
+**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform — equal steps in lightness *look* equal, unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.
+
+```css
+/* OKLCH: lightness (0-100%), chroma (0-0.4+), hue (0-360) */
+--color-primary: oklch(60% 0.15 250);       /* Blue */
+--color-primary-light: oklch(85% 0.08 250); /* Same hue, lighter */
+--color-primary-dark: oklch(35% 0.12 250);  /* Same hue, darker */
+```
+
+**Key insight**: As you move toward white or black, reduce chroma. High chroma at extreme lightness looks garish. A light blue at 85% lightness needs ~0.08 chroma, not the 0.15 of your base color.
+
+---
+
+## Building Functional Palettes
+
+### The Tinted Neutral Trick
+**Pure gray is dead.** Add a subtle hint of your brand hue to all neutrals:
+
+```css
+/* Dead grays */
+--gray-100: oklch(95% 0 0);   /* No personality */
+--gray-900: oklch(15% 0 0);
+
+/* Warm-tinted grays */
+--gray-100: oklch(95% 0.01 60);  /* Hint of warmth */
+--gray-900: oklch(15% 0.01 60);
+
+/* Cool-tinted grays (tech, professional) */
+--gray-100: oklch(95% 0.01 250); /* Hint of blue */
+--gray-900: oklch(15% 0.01 250);
+```
+
+The chroma is tiny (0.01) but perceptible. It creates subconscious cohesion between your brand color and UI.
+
+### Palette Structure
+| Role | Purpose | Example |
+|------|---------|---------|
+| **Primary** | Brand, CTAs, key actions | 1 color, 3–5 shades |
+| **Neutral** | Text, backgrounds, borders | 9–11 shade scale |
+| **Semantic** | Success, error, warning, info | 4 colors, 2–3 shades each |
+| **Surface** | Cards, modals, overlays | 2–3 elevation levels |
+
+Skip secondary/tertiary unless you need them. Most apps work fine with one accent color.
+
+### The 60-30-10 Rule (Applied Correctly)
+This rule is about **visual weight**, not pixel count:
+- **60%**: Neutral backgrounds, white space, base surfaces
+- **30%**: Secondary — text, borders, inactive states
+- **10%**: Accent — CTAs, highlights, focus states
+
+The common mistake: using accent everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power.
+
+---
+
+## Contrast & Accessibility
+
+### WCAG Requirements
+| Content Type | AA Minimum | AAA Target |
+|--------------|------------|------------|
+| Body text | 4.5:1 | 7:1 |
+| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 |
+| UI components, icons | 3:1 | 4.5:1 |
+| Decorative elements | None | None |
+
+**The gotcha**: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere? Usually fails WCAG.
+
+### Dangerous Color Combinations
+- Light gray text on white (the #1 accessibility fail)
+- **Gray text on any colored background** — looks washed out; use a darker shade of the background color
+- Red on green (or vice versa) — 8% of men can't distinguish
+- Blue on red background (vibrates visually)
+- Yellow text on white (almost always fails)
+
+### Never Use Pure Gray or Pure Black
+Pure gray and `#000` don't exist in nature — real shadows always have a color cast. Even chroma of 0.005–0.01 feels natural without being obviously tinted.
+
+---
+
+## Theming: Light & Dark Mode
+
+### Dark Mode Is Not Inverted Light Mode
+You can't just swap colors. Dark mode requires different design decisions:
+
+| Light Mode | Dark Mode |
+|------------|-----------|
+| Shadows for depth | Lighter surfaces for depth (no shadows) |
+| Dark text on light | Light text on dark (reduce font weight slightly) |
+| Vibrant accents | Desaturate accents slightly |
+| White backgrounds | Never pure black — use dark gray (oklch 12–18%) |
+
+```css
+/* Dark mode depth via surface color, not shadow */
+[data-theme="dark"] {
+  --surface-1: oklch(15% 0.01 250);
+  --surface-2: oklch(20% 0.01 250);  /* "Higher" = lighter */
+  --surface-3: oklch(25% 0.01 250);
+
+  --body-weight: 350;  /* Reduce from 400, perceived weight is lighter */
+}
+```
+
+### Token Hierarchy
+Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer.
+
+---
+
+## Alpha Is A Design Smell
+
+Heavy use of transparency usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency. Define explicit overlay colors for each context. Exception: focus rings and interactive states where see-through is needed.
+
+---
+
+**Avoid**: Relying on color alone to convey information. Using pure black (#000) for large areas. Skipping color blindness testing (8% of men affected).

package/template/agent/skills/frontend-design/reference/interaction-design.md

@@ -0,0 +1,159 @@
+# Interaction Design
+
+## Make Interactions Feel Fast
+
+Use **optimistic UI** — update immediately, sync later. This is the single biggest perceived-performance improvement you can make.
+
+```javascript
+// BAD: Wait for server
+async function likePost(id) {
+  const result = await api.like(id);
+  setLiked(result.liked);
+}
+
+// GOOD: Optimistic update
+function likePost(id) {
+  setLiked(true);  // Instant feedback
+  api.like(id).catch(() => {
+    setLiked(false);  // Revert on failure
+    showError('Could not save like');
+  });
+}
+```
+
+Use optimistic UI for low-stakes actions. Avoid for payments, destructive operations, or anything requiring server validation first.
+
+---
+
+## Progressive Disclosure
+
+Start simple, reveal sophistication through interaction:
+
+- Basic options visible immediately
+- Advanced options behind expandable sections
+- Hover/focus states reveal secondary actions
+- "Show more" patterns for secondary content
+
+This prevents overwhelming users while keeping power-user features accessible.
+
+---
+
+## Form Design
+
+### Fields
+- Show format with placeholders, not fixed instruction text (instructions disappear on focus)
+- For non-obvious fields, explain **why** you're asking, not just what to enter
+- Group related fields visually with spacing, not just labels
+- Use `autocomplete` attributes — they're free UX
+
+```html
+<input 
+  type="email" 
+  autocomplete="email"
+  placeholder="you@company.com"
+  aria-describedby="email-hint"
+>
+<span id="email-hint">We'll send your receipt here</span>
+```
+
+### Validation
+**Validate on blur, not on keystroke** — keystroke validation creates stress (errors appear before you've finished typing). Clear errors immediately when the user corrects them.
+
+```css
+/* Visual validation state */
+input:invalid:not(:focus):not(:placeholder-shown) {
+  border-color: oklch(55% 0.2 25);
+  background: oklch(98% 0.01 25);
+}
+```
+
+---
+
+## Loading States
+
+Three types — use the right one:
+
+| State | When | Pattern |
+|-------|------|---------|
+| **Skeleton** | Content structure is known | Placeholder shapes in layout position |
+| **Spinner** | Action feedback (button click) | Small inline spinner, disable button |
+| **Progress** | Long operations | Bar with estimated time if >10s |
+
+**Specific loading messages beat generic ones:**
+- `"Saving your draft..."` not `"Loading..."`
+- `"Analyzing 40 files..."` not `"Processing..."`
+- `"This usually takes 30 seconds"` for long waits
+
+---
+
+## Error States
+
+Every error needs: (1) What happened, (2) Why, (3) How to fix it.
+
+- `"Email address isn't valid. Please include an @ symbol."` ✅
+- `"Invalid input"` ❌
+
+For field errors, place them directly below the field, not in a banner far away.
+
+---
+
+## Empty States
+
+Empty states are **onboarding moments**:
+1. Acknowledge briefly ("No projects yet")
+2. Explain the value of filling it
+3. Provide a clear action ("Create your first project →")
+
+Empty states that just say "No items found" are missed opportunities.
+
+---
+
+## Focus Management
+
+Always visible focus indicators — don't set `outline: none` without providing an alternative.
+
+```css
+:focus-visible {
+  outline: 2px solid oklch(60% 0.15 250);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+
+/* Hide focus ring for mouse users */
+:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+Move focus intentionally after actions — after closing a modal, return focus to the trigger. After deleting an item, move focus to the next item.
+
+---
+
+## Button Hierarchy
+
+Not every action deserves a primary button. Create clear hierarchy:
+
+| Style | Use For | Frequency |
+|-------|---------|-----------|
+| **Primary** (filled) | The one main action | 1 per view |
+| **Secondary** (outlined) | Important but not primary | 2–3 max |
+| **Ghost/text** | Low-priority actions | Multiple OK |
+| **Destructive** (red) | Delete, remove | When needed |
+
+Never put two primary buttons side by side — the user can't tell which is "more primary."
+
+---
+
+## Modals: Use Sparingly
+
+Modals are lazy default design. Ask: does this need to interrupt the user? Alternatives:
+- **Inline editing**: Edit in place
+- **Slide-over panel**: For complex forms
+- **Undo**: For destructive actions instead of confirmation
+- **Toast**: For confirmations that don't need user input
+
+When you must use a modal: trap focus inside, close on Escape and backdrop click, return focus to trigger on close.
+
+---
+
+**Avoid**: Confirming every action with a modal. Showing errors only in banners. Disabled buttons without explanation. Making hover the only way to access functionality (touch users can't hover).

package/template/agent/skills/frontend-design/reference/motion-design.md

@@ -0,0 +1,150 @@
+# Motion Design
+
+## Duration: The 100/300/500 Rule
+
+Timing matters more than easing. These durations feel right for most UI:
+
+| Duration | Use Case | Examples |
+|----------|----------|----------|
+| **100–150ms** | Instant feedback | Button press, toggle, color change |
+| **200–300ms** | State changes | Menu open, tooltip, hover states |
+| **300–500ms** | Layout changes | Accordion, modal, drawer |
+| **500–800ms** | Entrance animations | Page load, hero reveals |
+
+**Exit animations are faster than entrances** — use ~75% of enter duration.
+
+---
+
+## Easing: Pick the Right Curve
+
+**Don't use `ease`.** It's a compromise that's rarely optimal. Instead:
+
+| Curve | Use For | CSS |
+|-------|---------|-----|
+| **ease-out** | Elements entering | `cubic-bezier(0.16, 1, 0.3, 1)` |
+| **ease-in** | Elements leaving | `cubic-bezier(0.7, 0, 0.84, 0)` |
+| **ease-in-out** | State toggles (there → back) | `cubic-bezier(0.65, 0, 0.35, 1)` |
+
+**For micro-interactions, use exponential curves — they mimic real physics:**
+
+```css
+--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);   /* Smooth, refined (recommended) */
+--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);   /* Slightly more dramatic */
+--ease-out-expo:  cubic-bezier(0.16, 1, 0.3, 1);    /* Snappy, confident */
+```
+
+**Avoid bounce and elastic curves.** They were trendy in 2015 but now feel tacky and amateurish. Real objects decelerate smoothly — they don't bounce when they stop.
+
+---
+
+## The Only Two Properties You Should Animate
+
+**`transform` and `opacity` only** — everything else causes layout recalculation.
+
+For height animations (accordions, expandables), use `grid-template-rows: 0fr → 1fr` instead of animating `height` directly:
+
+```css
+.expandable {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 300ms var(--ease-out-quart);
+}
+
+.expandable.open {
+  grid-template-rows: 1fr;
+}
+
+.expandable > div {
+  overflow: hidden;
+}
+```
+
+---
+
+## Staggered Animations
+
+Use CSS custom properties for cleaner stagger:
+
+```css
+.item {
+  animation: slide-up 500ms var(--ease-out-expo) both;
+  animation-delay: calc(var(--i, 0) * 50ms);
+}
+```
+
+```html
+<div class="item" style="--i: 0">...</div>
+<div class="item" style="--i: 1">...</div>
+<div class="item" style="--i: 2">...</div>
+```
+
+**Cap total stagger time** — 10 items at 50ms = 500ms total. For many items, reduce per-item delay or cap staggered count.
+
+---
+
+## Reduced Motion
+
+This is not optional. Vestibular disorders affect ~35% of adults over 40.
+
+```css
+/* Define animations normally */
+.card {
+  animation: slide-up 500ms ease-out;
+}
+
+/* Provide crossfade alternative */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    animation: fade-in 200ms ease-out;
+  }
+}
+
+/* Or disable all motion */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+**What to preserve**: Progress bars, loading spinners (slowed), and focus indicators should still work — just without spatial movement.
+
+---
+
+## Perceived Performance
+
+Nobody cares how fast your site is — just how fast it **feels**.
+
+**The 80ms threshold**: Anything under 80ms feels instant. This is your target for micro-interactions.
+
+**Strategies:**
+- **Optimistic UI**: Update immediately, sync later. Instagram likes work offline — the UI updates instantly. Use for low-stakes actions; avoid for payments or destructive operations.
+- **Skeleton screens**: Show structure before content. Beats blank loading states.
+- **Progressive loading**: Show content as it arrives — don't wait for everything.
+
+**Caution**: Too-fast responses can decrease perceived value. Users may distrust instant results for complex operations (search, analysis). Sometimes a brief delay signals "real work" is happening.
+
+---
+
+## Performance
+
+Don't use `will-change` preemptively — only when animation is imminent (`:hover`, `.animating`). For scroll-triggered animations, use Intersection Observer instead of scroll events; unobserve after animating once.
+
+Create motion tokens for consistency:
+
+```css
+:root {
+  --duration-instant: 100ms;
+  --duration-fast: 200ms;
+  --duration-normal: 300ms;
+  --duration-slow: 500ms;
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in: cubic-bezier(0.7, 0, 0.84, 0);
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+}
+```
+
+---
+
+**Avoid**: Animating everything (animation fatigue is real). Using >500ms for UI feedback. Ignoring `prefers-reduced-motion`. Using animation to hide slow loading.

package/template/agent/skills/frontend-design/reference/responsive-design.md

@@ -0,0 +1,161 @@
+# Responsive Design
+
+## Mobile-First: Write It Right
+
+Start with base styles for mobile, use `min-width` queries to layer complexity. Desktop-first (`max-width`) means mobile loads unnecessary styles first.
+
+```css
+/* Mobile-first (correct) */
+.container { padding: 1rem; }
+
+@media (min-width: 768px) {
+  .container { padding: 2rem; }
+}
+
+/* Desktop-first (wrong way) */
+.container { padding: 2rem; }
+
+@media (max-width: 768px) {
+  .container { padding: 1rem; }
+}
+```
+
+---
+
+## Breakpoints: Content-Driven
+
+Don't chase device sizes — let content tell you where to break. Start narrow, stretch until design breaks, add breakpoint there. Three breakpoints usually suffice: 640, 768, 1024px. Use `clamp()` for fluid values without breakpoints.
+
+---
+
+## Detect Input Method, Not Just Screen Size
+
+Screen size doesn't tell you input method. A laptop with touchscreen, a tablet with keyboard — use pointer and hover queries:
+
+```css
+/* Fine pointer (mouse, trackpad) */
+@media (pointer: fine) {
+  .button { padding: 8px 16px; }
+}
+
+/* Coarse pointer (touch, stylus) */
+@media (pointer: coarse) {
+  .button { padding: 12px 20px; }
+}
+
+/* Device supports hover */
+@media (hover: hover) {
+  .card:hover { transform: translateY(-2px); }
+}
+
+/* Device doesn't support hover (touch) */
+@media (hover: none) {
+  .card { /* No hover state — use active instead */ }
+}
+```
+
+**Critical**: Don't rely on hover for functionality. Touch users can't hover.
+
+---
+
+## Safe Areas: Handle the Notch
+
+Modern phones have notches, rounded corners, and home indicators:
+
+```css
+body {
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+
+/* With fallback */
+.footer {
+  padding-bottom: max(1rem, env(safe-area-inset-bottom));
+}
+```
+
+Enable viewport-fit in your meta tag:
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+```
+
+---
+
+## Responsive Images
+
+### srcset with Width Descriptors
+
+```html
+<img
+  src="hero-800.jpg"
+  srcset="
+    hero-400.jpg 400w,
+    hero-800.jpg 800w,
+    hero-1200.jpg 1200w
+  "
+  sizes="(max-width: 768px) 100vw, 50vw"
+  alt="Hero image"
+>
+```
+
+- `srcset` lists available images with their actual widths
+- `sizes` tells the browser how wide the image will display
+- Browser picks the best file based on viewport width AND device pixel ratio
+
+### Picture Element for Art Direction
+
+When you need different crops/compositions (not just resolutions):
+
+```html
+<picture>
+  <source media="(min-width: 768px)" srcset="wide.jpg">
+  <source media="(max-width: 767px)" srcset="tall.jpg">
+  <img src="fallback.jpg" alt="...">
+</picture>
+```
+
+---
+
+## Layout Adaptation Patterns
+
+**Navigation** — three stages:
+- Mobile: hamburger + drawer
+- Tablet: horizontal compact
+- Desktop: full with labels
+
+**Tables** — transform to cards on mobile:
+```css
+@media (max-width: 640px) {
+  table, thead, tbody, tr, td {
+    display: block;
+  }
+  
+  td::before {
+    content: attr(data-label) ": ";
+    font-weight: bold;
+  }
+  
+  thead { display: none; }
+}
+```
+
+**Progressive disclosure** — use `<details>/<summary>` for content that can collapse on mobile.
+
+---
+
+## Testing: Don't Trust DevTools Alone
+
+DevTools device emulation is useful for layout but misses:
+- Actual touch interactions
+- Real CPU/memory constraints
+- Network latency patterns
+- Font rendering differences
+- Browser chrome/keyboard appearances
+
+**Test on at least**: One real iPhone, one real Android, a tablet if relevant. Cheap Android phones reveal performance issues you'll never see on simulators.
+
+---
+
+**Avoid**: Desktop-first design. Device detection instead of feature detection. Separate mobile/desktop codebases. Ignoring tablet and landscape. Assuming all mobile devices are powerful.

package/template/agent/skills/frontend-design/reference/spatial-design.md

@@ -0,0 +1,122 @@
+# Spatial Design
+
+## Spacing Systems
+
+### Use 4pt Base, Not 8pt
+8pt systems are too coarse — you'll frequently need 12px (between 8 and 16). Use 4pt for granularity: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
+
+### Name Tokens Semantically
+Name by relationship (`--space-sm`, `--space-lg`), not value (`--spacing-8`). Use `gap` instead of margins for sibling spacing — it eliminates margin collapse and cleanup hacks.
+
+---
+
+## Grid Systems
+
+### The Self-Adjusting Grid
+Use `repeat(auto-fit, minmax(280px, 1fr))` for responsive grids without breakpoints. Columns are at least 280px, as many as fit per row, leftovers stretch.
+
+For complex layouts, use named grid areas (`grid-template-areas`) and redefine them at breakpoints.
+
+---
+
+## Visual Hierarchy
+
+### The Squint Test
+Blur your eyes (or screenshot and blur). Can you still identify:
+- The most important element?
+- The second most important?
+- Clear groupings?
+
+If everything looks the same weight blurred, you have a hierarchy problem.
+
+### Hierarchy Through Multiple Dimensions
+Don't rely on size alone. Combine:
+
+| Tool | Strong Hierarchy | Weak Hierarchy |
+|------|------------------|----------------|
+| **Size** | 3:1 ratio or more | <2:1 ratio |
+| **Weight** | Bold vs Regular | Medium vs Regular |
+| **Color** | High contrast | Similar tones |
+| **Position** | Top/left (primary) | Bottom/right |
+| **Space** | Surrounded by white space | Crowded |
+
+**The best hierarchy uses 2–3 dimensions at once**: A heading that's larger, bolder, AND has more space above it.
+
+### Cards Are Not Required
+Cards are overused. Spacing and alignment create visual grouping naturally. Use cards only when:
+- Content is truly distinct and actionable
+- Items need visual comparison in a grid
+- Content needs clear interaction boundaries
+
+**Never nest cards inside cards** — use spacing, typography, and subtle dividers for hierarchy within a card.
+
+---
+
+## Container Queries
+
+Viewport queries are for page layouts. **Container queries are for components**:
+
+```css
+.card-container {
+  container-type: inline-size;
+}
+
+.card {
+  display: grid;
+  gap: var(--space-md);
+}
+
+/* Card layout changes based on its container, not viewport */
+@container (min-width: 400px) {
+  .card {
+    grid-template-columns: 120px 1fr;
+  }
+}
+```
+
+**Why this matters**: A card in a narrow sidebar stays compact, while the same card in a main content area expands — automatically, without viewport hacks.
+
+---
+
+## Optical Adjustments
+
+- Text at `margin-left: 0` looks indented due to letterform whitespace — use negative margin (`-0.05em`) to optically align
+- Geometrically centered icons often look off-center; play icons need to shift right, arrows shift toward their direction
+
+### Touch Targets vs Visual Size
+Buttons can look small but need large touch targets (44px minimum). Use padding or pseudo-elements:
+
+```css
+.icon-button {
+  width: 24px;
+  height: 24px;
+  position: relative;
+}
+
+.icon-button::before {
+  content: '';
+  position: absolute;
+  inset: -10px;  /* Expand tap target to 44px */
+}
+```
+
+---
+
+## Depth & Elevation
+
+Create semantic z-index scales (dropdown → sticky → modal-backdrop → modal → toast → tooltip) instead of arbitrary numbers.
+
+For shadows, create a consistent elevation scale (sm → md → lg → xl). **Key insight**: Shadows should be subtle — if you can clearly see it, it's probably too strong.
+
+```css
+:root {
+  --shadow-sm: 0 1px 2px oklch(0% 0 0 / 0.05);
+  --shadow-md: 0 4px 6px oklch(0% 0 0 / 0.07);
+  --shadow-lg: 0 10px 15px oklch(0% 0 0 / 0.1);
+  --shadow-xl: 0 20px 25px oklch(0% 0 0 / 0.12);
+}
+```
+
+---
+
+**Avoid**: Arbitrary spacing values outside your scale. Making all spacing equal (variety creates hierarchy). Creating hierarchy through size alone. Nesting cards in cards.