all-the-vibes/atv-phoenix/phoenix-design

phoenix-design — taste is the differentiator, polished with evidence

Encodes Emil Kowalski's design-engineering philosophy: in a world where

everyone's software is good enough, taste is the differentiator, and unseen details compound into

interfaces people love without knowing why. Phoenix adds the verify-heal discipline so polish ships

without regressing build/lint/behavior.

Core philosophy

• Taste is trained, not innate. Reverse-engineer great interfaces; understand why they feel right.
• Unseen details compound. Users rarely notice them consciously — that's the point. The aggregate of

invisible correctness is what makes software feel stunning.

• Beauty is leverage. People pick tools on the whole experience. Good defaults + good motion stand out.

The Animation Decision Framework (answer in order, before writing any animation)

1. Should this animate at all?

Never animate keyboard-initiated actions — they repeat hundreds of times a day; animation makes them feel slow. (Raycast has no open/close animation. That's optimal for something used constantly.)

2. What is the purpose?

Every animation needs a clear answer to "why does this animate?" Valid: spatial consistency, state indication, explanation, feedback. No purpose → no animation.

3. What curve & properties?

• Animate specific properties (transform, opacity) — never all (janky, animates the unexpected).
• `ease-out` for things entering / responding to user action (instant feedback). ease-in feels

sluggish for UI. Custom curves for personality.

• Nothing appears from nothing: enter with scale(0.95) + opacity, not scale(0).
• Respond to press: interactive elements get an :active state (transform: scale(0.97)).
• Scale from origin: popovers/dropdowns scale from their trigger (transform-origin), modals stay centered.
• Honor prefers-reduced-motion.

Review Format (REQUIRED)

When reviewing UI code you MUST output a single markdown table — never a "Before:/After:" list:

Verify the polish (the Phoenix part — taste, but gated)

Craft is not an excuse to skip evidence. Where a check exists, gate on it:

• Build/lint stay green: phoenix_sense {"kind":"command_exit","target":["npm","run","lint"],"expect":0}

and the build — beautiful code that doesn't compile isn't shipped.

• Behavior unbroken: if the component has tests, sense them; a motion tweak must not break logic.
• Reduced-motion path exists: check (regex or test) that prefers-reduced-motion is honored.
• Visual/interaction check when possible: screenshot or interaction test for the changed state.
• Snapshot before a risky restyle so phoenix_heal can roll back a regression.

Common Rationalizations

Red Flags

• Animation on a keyboard-repeated action. → Remove it; speed beats motion there.
• transition: all or scale(0) entrances. → Name properties; enter from 0.95+opacity.
• No :active / no prefers-reduced-motion. → Add both; responsiveness and accessibility are table stakes.
• A UI review written as a prose list. → Use the Before/After table.
• Shipping a restyle without a green build/lint sense. → Gate it; beauty that breaks the build isn't shipped.

Next

Pair with phoenix-build (implement under the heal loop), phoenix-typescript (typed components), and phoenix-review/phoenix-ship (gate the polish on green evidence). Deeper craft: Emil's course at animations.dev.