# ihumane · UI design module · v0.1

You are an agent about to design or build a user interface. This module is
written for you, not for a human reader. It turns what experienced designers
know by instinct into rules you can follow and checks you can run.

Read this file fully. Read the other files when the step below tells you to.

---

## Why this exists

You go by words. You don't see your work the way a person does, you don't
remember the last project, and when nothing stops you, you produce the most
average answer. That gives two failures humans keep correcting you for:

1. **It looks fine, but it's a mess inside.** Colours typed by hand, spacing
   that changes from screen to screen, the same button built three ways. The
   human sees a nice screen; the next person to touch the code sees chaos.
2. **It isn't made for people.** It ignores how humans read, decide, get
   confused and give up, because you only know those things from descriptions.

Every re-prompt is a human fixing one of these after the fact. Your goal is
work that needs no correction on these two points.

---

## The workflow

Do these in order. Don't skip a step because the task looks small.

| Step | What you do | File |
|------|-------------|------|
| 0. Remember | Look for `DESIGN.md` in the project. If it exists, read it and follow it. | `6-memory.md` |
| 1. Brief | Work out who this is for, what it must do and what "done" means. Ask only what you can't infer. Write the brief back in 5 lines. | `1-brief.md` |
| 2. Translate | If the request uses taste words ("clean", "modern", "premium"), turn them into concrete decisions and say which ones you chose. | `4-taste.md` |
| 3. System first | Find or define tokens and components **before** building any screen. | `2-system.md` |
| 4. Build for humans | Apply the human rules while building. | `3-humans.md` |
| 5. Avoid the defaults | Check your work against the list of things that make UI look machine-made. | `7-avoid.md` |
| 6. Review | Look at what you made, then review it through six lenses. Fix before reporting. | `5-review.md` |
| 7. Remember | Create or update `DESIGN.md` so the next agent stays consistent. | `6-memory.md` |

---

## The format of every rule

Rules in this module use the same fields:

- **Rule:** what to do, as specifically as possible.
- **Why:** what happens to a real person if you don't. This lets you handle
  cases no rule covers.
- **Agent trap:** the specific way agents like you get this wrong.
- **Check:** how to verify it, ideally something you can run or count.

Runnable checks live in `checks/`. Run them on the rendered page; don't
trust your reading of the code.

| Check | Finds |
|---|---|
| `checks/spacing.js` | Text touching dividers or edges; uneven space above and below |
| `checks/affordance.js` | Things that look like links but aren't; expanders with no arrow; back controls on the wrong side or in the global header; link underlines (standalone: hover only; in a sentence: always) |
| `checks/stability.js` | Controls that move or resize when you use them (loading, messages) |

---

## Five rules that matter most

If you remember nothing else:

1. **No raw values in components.** Every colour, spacing, size, radius and
   shadow comes from a token. (`2-system.md`)
2. **One primary action per view.** If everything is emphasised, nothing is.
   (`3-humans.md`)
3. **Design every state.** Empty, loading, error, long content, no permission.
   The happy path is the smallest part of the work. (`2-system.md`)
4. **Look before you say done.** Render it and look at a phone and a desktop
   width. Text descriptions of your own output are not evidence. (`5-review.md`)
5. **Say what you assumed.** Every guess you made goes in your report, so the
   human can correct it in one message instead of five. (`1-brief.md`)

---

## Precedence

The human's instructions and an existing project design system come before
this module. If a rule here conflicts with them, follow them, and mention the
conflict once in your report.