/design-engineering

name: design-engineering
description: "UI craftsmanship: animation rules, easing, micro-interactions, state polish. Triggers: animation, transition, ease-out, motion, micro-interaction, hover, loading state, UI polish."
effort: medium
user-invocable: false
allowed-tools: Read

Design Engineering Skill

Based on Emil Kowalski's design engineering philosophy — UI polish, component craftsmanship, and the compound value of invisible details.

Core Principles

• **Taste is trainable.** Develops through studying exceptional work, reverse-engineering animations, and intentional practice.
• **Invisible details create love.** Most UI refinements users never consciously register — but combined they produce something stunning.
• **Beauty differentiates.** When functionality is table stakes, aesthetic excellence becomes genuine leverage.

Anti-Slop Visual & Structural Checklist

Defaults that signal machine-generated UI ("AI slop"). Each is a falsifiable rule to uphold:

• **Avoid** full-bleed saturated gradient backgrounds (purple-to-pink/blue hero washes) and gradient headlines (`background-clip: text`). Use solid ink or warm neutral tinting.
• **Avoid** emoji as load-bearing decoration (emoji as icons, bullet markers, or section badges). Use a real icon set (Lucide/Phosphor/Heroicons) or typographic hierarchy.
• **Avoid** the 3-equal-column card grid with icon-above-heading tiles, nested cards-in-cards, or cards with thick coloured left-edge side stripes.
• **Avoid** hand-drawn fake imagery in SVG (synthetic "photos", invented logos, faux screenshots). Use a real asset or an honest labeled placeholder.
• **Avoid** fake re-drawn UI chrome (mock browser bars with traffic-light dots, mock IDE title bars, faux phone frames). Let content stand cleanly or use real screenshots in a `<figure>`.
• **Avoid** default-attractor sameness (Hero → 3 features → CTA → footer). Pick intentional macrostructures and vary heading placement, column rhythm, and divider language.
• **Avoid** the overused default font stack (Inter/Roboto on system-ui with no pairing). Apply the **2+1 rule** (display + body + at most 1 outlier face in <=2 slots).
• **Avoid** italic headers: headings and display type are always roman (`font-style: normal`). Never use single-word italic emphasis inside a headline.

Pre-Emit Self-Critique (Six Axes)

Before marking any UI output complete, score it 1–5 on these six axes (score <3 on any axis triggers a revision pass):

| # | Axis | Assessment | |---|---|---| | **P** | **Philosophy** | Clear position and intent ("why"), not just arbitrary decoration | | **H** | **Hierarchy** | Clear primary / secondary / tertiary weight distinguishable in 2 seconds | | **E** | **Execution** | Exact rule weights, contrast ratios, focus rings, zero layout shifts | | **S** | **Specificity** | Tailored specifically to this brief, not a generic interchangeable template | | **R** | **Restraint** | Removed anything unearned (decorative bloat, redundant cards, excess padding) | | **V** | **Variety** | Structurally distinct from previous layouts in the project (not just a color swap) |

The 8 Interactive States Discipline

Every interactive element (button, input, select, card, tab, switch) must explicitly handle all 8 states in code. Styling only default + hover is an immediate defect:

| State | Trigger | Required Treatment | |---|---|---| | **1. Default** | At rest | Clean base styling, defined token bindings | | **2. Hover** | Pointer over (`@media (hover: hover)`) | Subtle background shift (4–6%) or 1px translate, no layout jump | | **3. Focus** | Keyboard navigation | Visible `:focus-visible` ring (2px solid, 1–2px offset), instant appearance | | **4. Active** | Pressed | Pressed-in feel: slight darken, `transform: translateY(1px)` or `scale(0.98)` | | **5. Disabled** | Inactive (`disabled`, `aria-disabled`) | 3 channels: `opacity: 0.55`, `cursor: not-allowed`, muted token color | | **6. Loading** | Async in-flight (`data-state="loading"`) | Inline spinner replacing icon/badge, label preserved, submit disabled | | **7. Error** | Validation failure (`aria-invalid="true"`) | Distinct error token border/message, helper text replaced, error icon | | **8. Success** | Operation completed (`data-state="success"`) | Quiet confirmation: subtle green/accent indicator or checkmark, auto-dismiss |

Input Fields & Zero Layout Shift

Input fields, textareas, and selects are where almost-right UIs break:

• **Constant border width (1px everywhere)**: Never change `border-width` between default, hover, focus, error, or disabled states. State changes go to `background-color`, `outline`, `box-shadow`, or `border-color`.
• **Reserved transparent outline**: Initialize with `outline: 2px solid transparent; outline-offset: 1px;` so activating `:focus-visible` never shifts layout or thrashes paint.
• **Matched component heights**: Input height MUST equal adjacent button height (base floor 44px for touch targets).
• **Reserved helper-text slot**: Allocate `min-height: 1lh` for helper/error text so appearing validation messages do not push downstream page content.

Responsive Non-Negotiables

Verify every layout at **320px, 375px, 414px, and 768px**:

• **No horizontal scroll**: Apply `overflow-x: clip` (never `hidden`) on **both** `html` and `body`.
• **Single-line clickable affordances**: Buttons, primary nav links, footer links, and CTAs must never wrap to two lines. Shorten label or reflow parent container.
• **Image grid tracks**: Always use `minmax(0, 1fr)` instead of bare `1fr` to prevent image intrinsic dimensions from blowing out the grid.
• **Header wrapping**: Display headers must include `overflow-wrap: anywhere; min-width: 0;`.

Locked Tokens Discipline

• All colors and typography must bind to declared tokens (`var(--color-accent)`, `var(--font-display)`).
• Never improvise inline hex / rgb / OKLCH values in components mid-build.
• Keep accent footprint under **~5%** of viewport area (accent i