DESIGN.md

How I build interfaces

These are the design principles I hand to my AI coding agents — Claude Code, Codex, whatever’s writing the UI. One short file that decides how everything should look and feel: fast, simple, and made with intent. Steal it.

Drop it in your repo, or point your agent at it. It beats framework defaults.

  1. Fast by default

    Optimistic UI, instant feedback, prefetch. Never make the user wait for no reason. Spinners are a bug — use skeletons if you absolutely must load. Noticeable loading is a design bug.

    e.g. A sent message appears instantly and syncs in the background — it doesn't spin while it waits for the server.

  2. Keep it simple, give it air

    Way simpler than you think — cut it, then cut more. Fewer elements, more space: always more padding and margin than feels right.

    e.g. Four grouped rows with room to breathe beat a dense grid of twenty toggles.

  3. Every element is a decision

    No defaults. If you can't say why this, redo it.

    e.g. That divider — is it separating two real groups, or just there? If you can't say, cut it.

  4. One decision per screen

    One call-to-action, one thing to do. Ask one question, let them move on — never a wall of choices. Everything else quiet and secondary — emphasize everything and you emphasize nothing.

    e.g. Onboarding asks name → goal → plan, one per screen. Not a 12-field form.

  5. Type carries the personality

    Deliberate faces, real scale, sentence case. Fix the type before adding anything.

    e.g. A distinct display face for headlines + a clean body face — not everything 16px semibold.

  6. Copy is design

    Plain, specific, active voice. Say what the button does.

    e.g. "Save changes," not "Submit." "Delete 3 files," not "Confirm."

  7. Motion is subtle and necessary

    ~150ms, ease-out, only where it clarifies. One bold hero moment is fine — used sparingly. Respect reduced-motion.

    e.g. A sheet slides up from the button that opened it. The logo animates once on first load, never again.

  8. Empty & error states are direction, not filler

    Point empty screens at the first action; on errors say what happened and what to do next. Never blank, never vague, never grovel.

    e.g. "No projects yet — create your first one" (with the button). "Couldn't save — you're offline. We'll retry when you reconnect." Not "Oops! Something went wrong 😞".

  9. Match execution to ambition

    Commit to one idea and finish it. Don't land halfway.

    e.g. Going minimal? Get spacing and alignment pixel-right. Don't ship a bold idea at 60%.

  10. Kill the generic-AI look

    No purple→blue gradient hero, reflexive 3-card grid, or emoji bullets standing in for design.

    e.g. If a screen drifts toward cream-bg + serif + terracotta, you reached for a default instead of thinking.

  11. The best UI is no UI

    The ideal is it just works, without the user having to think. Decide for them: smart defaults, their previous choices already filled in, steps removed. Use AI magic wherever you can, even subtly. One magic button beats ten controls.

    e.g. The form opens pre-filled with their last answers and the likely option selected — better yet, do it for them and let them undo.

The floor (always)

Feels instant · responsive · visible focus · AA contrast · reduced-motion. A project’s own tokens and components win over this. It’s the floor, not a cage.

Practical patterns

Concrete rules, not vibes.

The raw file

# DESIGN.md

How I want things built. Read before writing UI. These beat framework defaults.

1. **Fast by default.** Optimistic UI, instant feedback, prefetch. Never make the user wait for no reason. Spinners are a bug — use skeletons if you absolutely must load. Noticeable loading is a design bug.
   *e.g.* A sent message appears instantly and syncs in the background — it doesn't spin while it waits for the server.

2. **Keep it simple, give it air.** Way simpler than you think — cut it, then cut more. Fewer elements, more space: always more padding and margin than feels right.
   *e.g.* Four grouped rows with room to breathe beat a dense grid of twenty toggles.

3. **Every element is a decision.** No defaults. If you can't say why *this*, redo it.
   *e.g.* That divider — is it separating two real groups, or just there? If you can't say, cut it.

4. **One decision per screen.** One call-to-action, one thing to do. Ask one question, let them move on — never a wall of choices. Everything else quiet and secondary — emphasize everything and you emphasize nothing.
   *e.g.* Onboarding asks name → goal → plan, one per screen. Not a 12-field form.

5. **Type carries the personality.** Deliberate faces, real scale, sentence case. Fix the type before adding anything.
   *e.g.* A distinct display face for headlines + a clean body face — not everything 16px semibold.

6. **Copy is design.** Plain, specific, active voice. Say what the button does.
   *e.g.* "Save changes," not "Submit." "Delete 3 files," not "Confirm."

7. **Motion is subtle and necessary.** ~150ms, ease-out, only where it clarifies. One bold hero moment is fine — used sparingly. Respect reduced-motion.
   *e.g.* A sheet slides up from the button that opened it. The logo animates once on first load, never again.

8. **Empty & error states are direction, not filler.** Point empty screens at the first action; on errors say what happened and what to do next. Never blank, never vague, never grovel.
   *e.g.* "No projects yet — create your first one" (with the button). "Couldn't save — you're offline. We'll retry when you reconnect." Not "Oops! Something went wrong 😞".

9. **Match execution to ambition.** Commit to one idea and finish it. Don't land halfway.
   *e.g.* Going minimal? Get spacing and alignment pixel-right. Don't ship a bold idea at 60%.

10. **Kill the generic-AI look.** No purple→blue gradient hero, reflexive 3-card grid, or emoji bullets standing in for design.
   *e.g.* If a screen drifts toward cream-bg + serif + terracotta, you reached for a default instead of thinking.

11. **The best UI is no UI.** The ideal is it just works, without the user having to think. Decide for them: smart defaults, their previous choices already filled in, steps removed. Use AI magic wherever you can, even subtly. One magic button beats ten controls.
   *e.g.* The form opens pre-filled with their last answers and the likely option selected — better yet, do it for them and let them undo.

**Floor (always):** feels instant · responsive · visible focus · AA contrast · reduced-motion.

## Practical patterns
Concrete rules, not vibes.
- **Uploads have a drop zone.** Anywhere a file can be uploaded, support drag-and-drop with a visible zone and an obvious drag-over state (border + tint + "Drop to upload") so it's discoverable. Keep click-to-browse as a fallback.

A project's own tokens and components win over this. It's the floor, not a cage.

— Emory Fierlinger · https://emoryf.com/design.md