agy-superpowers 5.1.2 → 5.1.4

package/template/agent/skills/frontend-design/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: frontend-design
+description: Use when building web components, pages, artifacts, or applications — especially when high design quality is needed. Generates creative, polished code that avoids generic AI aesthetics (purple gradients, Inter font, card-in-card layouts).
+---
+
+# Frontend Design
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+## Context Gathering Protocol
+
+Design skills produce generic output without project context. Before doing any design work, confirm:
+
+- **Target audience**: Who uses this product and in what context?
+- **Use cases**: What jobs are they trying to get done?
+- **Brand personality/tone**: How should the interface feel?
+
+**Gathering order:**
+1. **Check current instructions**: If your loaded instructions contain a Design Context section, proceed immediately.
+2. **Check `.impeccable.md`**: If it exists in the project root and has context, use it.
+3. **Ask the user**: If neither source has context, ask these 3 questions before proceeding.
+
+---
+
+## Design Direction
+
+Commit to a **BOLD** aesthetic direction before writing any code:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme — brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing users remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute with precision. Bold maximalism and refined minimalism both work — the key is **intentionality**, not intensity.
+
+Implement working code that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+---
+
+## Frontend Aesthetics Guidelines
+
+### Typography
+→ *See [typography reference](reference/typography.md) for scales, pairing, and loading strategies.*
+
+Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font.
+
+**DO**: Use a modular type scale with fluid sizing (`clamp()`)
+**DO**: Vary font weights and sizes to create clear visual hierarchy
+**DON'T**: Use overused fonts — Inter, Roboto, Arial, Open Sans, system defaults
+**DON'T**: Use monospace typography as lazy shorthand for "technical/developer" vibes
+**DON'T**: Put large icons with rounded corners above every heading
+
+### Color & Theme
+→ *See [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.*
+
+**DO**: Use modern CSS color functions (`oklch`, `color-mix`, `light-dark()`) for perceptually uniform palettes
+**DO**: Tint your neutrals toward your brand hue
+**DON'T**: Use gray text on colored backgrounds — looks washed out; use a shade of the bg color instead
+**DON'T**: Use pure black (`#000`) or pure white (`#fff`) — always tint
+**DON'T**: Use the AI color palette: cyan-on-dark, purple-to-blue gradients, neon on dark
+**DON'T**: Use gradient text for "impact" on metrics or headings
+**DON'T**: Default to dark mode with glowing accents without real design decisions
+
+### Layout & Space
+→ *See [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.*
+
+**DO**: Create visual rhythm through varied spacing — tight groupings, generous separations
+**DO**: Use fluid spacing with `clamp()` that breathes on larger screens
+**DO**: Use asymmetry and unexpected compositions; break the grid intentionally
+**DON'T**: Wrap everything in cards — not everything needs a container
+**DON'T**: Nest cards inside cards — visual noise
+**DON'T**: Use identical card grids (same-sized card with icon + heading + text, repeated)
+**DON'T**: Center everything — left-aligned text with asymmetric layouts feels more designed
+**DON'T**: Use the same spacing everywhere
+
+### Visual Details
+**DO**: Use intentional, purposeful decorative elements that reinforce brand
+**DON'T**: Use glassmorphism everywhere — blur/glass/glow as decoration rather than purpose
+**DON'T**: Use rounded rectangles with generic drop shadows — forgettable
+**DON'T**: Use sparklines as decoration
+**DON'T**: Use modals unless there's truly no better alternative
+
+### Motion
+→ *See [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.*
+
+**DO**: Use motion to convey state changes — entrances, exits, feedback
+**DO**: Use exponential easing (`ease-out-quart/quint/expo`) for natural deceleration
+**DO**: For height animations, use `grid-template-rows` transitions instead of animating `height`
+**DON'T**: Animate layout properties (width, height, padding, margin) — use `transform` and `opacity` only
+**DON'T**: Use bounce or elastic easing — dated and tacky
+
+### Interaction
+→ *See [interaction reference](reference/interaction-design.md) for forms, focus, loading patterns.*
+
+**DO**: Use progressive disclosure — start simple, reveal sophistication through interaction
+**DO**: Design empty states that teach the interface, not just say "nothing here"
+**DON'T**: Make every button primary — use ghost buttons, text links, secondary styles
+**DON'T**: Repeat the same information redundantly
+
+### Responsive
+→ *See [responsive reference](reference/responsive-design.md) for mobile-first, fluid design.*
+
+**DO**: Use container queries (`@container`) for component-level responsiveness
+**DO**: Adapt the interface for different contexts — don't just shrink it
+**DON'T**: Hide critical functionality on mobile
+
+### UX Writing
+→ *See [UX writing reference](reference/ux-writing.md) for labels, errors, and empty states.*
+
+**DO**: Make every word earn its place
+**DON'T**: Repeat information users can already see
+
+---
+
+## The AI Slop Test
+
+**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
+
+A distinctive interface should make someone ask "how was this made?" not "which AI made this?"
+
+Review the DON'T guidelines above — they are the fingerprints of AI-generated work from 2024-2025.
+
+---
+
+## Implementation Principles
+
+Match implementation complexity to the aesthetic vision:
+- **Maximalist designs** → elaborate code, extensive animations, rich effects
+- **Minimalist designs** → restraint, precision, careful spacing, subtle details
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. **No design should be the same.** Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations.
+
+---
+
+## Quick Reference: What to Avoid
+
+| Category | DON'T |
+|----------|-------|
+| **Fonts** | Inter, Roboto, Arial, Open Sans |
+| **Colors** | Pure black/white, purple gradients, gray on color |
+| **Layout** | Cards in cards, centered everything, identical grids |
+| **Motion** | Bounce/elastic easing, animating height/width |
+| **Visual** | Glassmorphism everywhere, gradient text, generic shadows |
+| **Writing** | "OK", "Submit", redundant copy, vague errors |

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.