design

Files (3)

• SKILL.md
• effect-catalog.md · references/
• stack-engineering.md · references/

SKILL.md (first lines)

# Design

> **Routing:** visual/aesthetic quality only — not code-correctness review, backend/API/"system" design, or logo/brand-identity work. Deep animation/motion craft → `emil-design-eng`.

Build interfaces that look like a person with taste made deliberate choices — not like a model
emitted a safe default. The enemy is "AI slop": the centered hero, the three equal cards, the
purple-blue gradient, Inter everywhere, everything in a rounded box. This skill encodes the
principles and concrete rules that avoid that and produce work that feels intentional and
expensive.

## Modes

Pick based on the task (the user may name one, or infer it):

- **`craft`** — greenfield. Build a new component/page/app from scratch. → start at *Direction*.
- **`redesign`** — existing code. Audit what's there and fix it without breaking it. → jump to
  *Redesign mode* near the end.
- **`teach`** — capture design context before building. → see *Direction → context*.

## The one rule behind all the others

**Commit to a point of view.** Generic output comes from refusing to choose — hedging toward
the safe middle on every axis. Good design picks a direction (editorial? brutalist? soft and
expensive? technical and dense?) and pushes it consistently through type, color, space, and
motion. Before writing any CSS, decide what this should *feel* like, and let that decision
cascade. When in doubt, be more opinionated, not less.

A quick gut check before shipping — the **AI Slop Test**: *would someone look at this and
immediately assume an AI made it?* If yes, find the tells and kill them (see *Absolute bans*).

---

## Direction (do this first in `craft`/`teach`)

You cannot design well for a context you don't understand. Don't infer the audience or brand
from the code — ask. Get three things before committing to an aesthetic:

1. **Who/what** — the product, the audience, the one feeling it should evoke.
2. **Three brand words** — adjectives the user picks (e.g. "calm, precise, trustworthy"). These
   drive type and color far better than a generic "make it modern."
3. **Viewing context** — where it's used (dev tool at night → dark; wedding site → light/airy).
   *Derive* the theme from this rather than defaulting to dark mode reflexively.

In `teach` mode, write these into a `.design-context.md` at the project root so future sessions
inherit the decisions. If the user is impatient ("just make it look good"), pick a bold,
defensible direction yourself and state the call you made in one line.

---

## Typography

Type is the highest-leverage design decision and the most common AI tell.

- **Font choice = brand expression, not a default.** Translate the three brand words into a
  pairing. Don't reflexively reach for the current monoculture — **Inter, Geist, Space Grotesk,
  DM Sans, Roboto, Open Sans, Arial, Helvetica** and the like are not *wrong*, but they're so
  overused they read as "default." If you use one, do it deliberately and vary across projects.
  Prefer a pairing with a distinct display face for headings + a clean text face for body.
- **Scale with contrast.** Timid type (everything 14–18px) is slop. Use a real type scale with a
  decisive jump between body and headings (display can be 2–4× body). Set `line-height` tighter
  on headings (~1.05–1.2), looser on body (~1.5–1.6).
- **Body measure 65–75ch.** Wider is unreadable; full-width text is a tell.
- **Tighten tracking on large text**, leave body alone. Use real typographic characters
  (curly quotes, en/em dashes, × not x).

---

## Color & theme

- **Use OKLCH, not HSL.** It keeps perceived lightness consistent across hues. Reduce chroma at
  the extremes (very light/very dark) or colors turn neon or muddy.
- **Never pure `#000` or `#fff`.** Use a near-black tinted toward the brand hue and an off-white;
  pure black/white on screen is harsh and flat.
- **One accent, used sparingly.** A single saturated accent (desaturate it below ~80% so it
  isn't garish) carries more weight than a rainbow. **60-30-10** by *visual weight*: dominant
  neutral, secondary tone, 10% accent.
- **Tint your neutrals** toward the brand hue (a warm gray under a warm brand, etc.) — pure gray
  scales feel sterile.
- **Tint shadows** toward the background hue rather than using black-with-opacity.
- **Avoid the AI palette:** the purple→blue gradient ("Lila"), teal-on-dark, and the generic
  SaaS-violet. If you reach for purple-blue, stop and choose something the brand words justify.

---

## Layout & space

- **4pt spacing system with semantic tokens.** Define `--space-xs/sm/md/lg/...` on a 4px base and
  reference *those*, not magic numbers. Prefer `gap` on flex/grid over per-element margins.
- **Generous, intentional whitespace.** Cramped UIs feel cheap; let things breathe, but vary
  density so it's not uniform mush.
- **Break the grid.** Symmetry and dead-center everything is the slop default. Use asymmetry,
  off-center focal points, and deliberate alignment. A 12-col grid you actually break beats a
  3-equal-card row.
- **Don't box everything.** Cards are for when elevation communicates real hierarchy — not a
  reflex wrapper around every element. Use whitespace, dividers, and type to group instead.
- **Modern CSS for real layout:** `grid-template-columns: repeat(auto-fit, minmax(...))` for
  responsive grids, container queries so components adapt to their container (not just the
  viewport), `min-h-[100dvh]` not `100vh` (mobile browser chrome), `clamp()` for fluid type/space.

For named layout archetypes (Bento, editorial split, Z-axis cascade, etc.), see
`references/effect-catalog.md`.

---

## Surface & materiality

This is where "expensive" lives — the details most output skips.

- **Real glassmorphism** = `backdrop-blur` + a 1px inner border (subtle top-light) + a soft inner
  shadow. Just blur with no border looks cheap. Apply blur only on `fixed`/`sticky` elements,
  never on scrolling content (it thrashes performance).
- **Nested enclosures (the "double-bezel"):** an outer shell + an inner core with concentric
  radii — inner radius = outer radius − padding (`rounded-[calc(1.5rem-0.375rem)]`). This reads as
  crafted hardware. Pairs with "button-in-button" (a trailing icon chip inside a button).
- **Grain/noise**, if used, goes on one `fixed`, `pointer-events-none` overlay at low opacity —
  not per-component.
- **Depth through layering** (shadow + border + subtle background shift), not heavy drop shadows.

---

From gesmith0606/claude-config-public, MIT.

More from gesmith0606/claude-config-public