# Design framework

A philosophy, not a codebase. The behaviour is the spec; any stack can implement it.

## North star
- Intuitive for the person using the interface, not for the developer building it.
- Reference: Apple. The user never feels the machine underneath.
- Through-line: the user never carries anxiety. No "did it save?", no "how much more?", no "did I break something?"
- Every component answers one question: how do these laws apply here?

## Law 1: No surprises
Nothing happens that the user didn't cause.
- Nothing moves, resets or disappears on its own.
- State is predictable: a component is where you left it.
- One action does one thing. No hidden side effects.
- Layout stays stable while content loads and errors appear or clear.

## Law 2: Optimism
Assume success, trust the user, guide instead of block.
- The code is stable and tested, so act instantly and reconcile later.
- No "are you sure?". Prefer undo over confirmation.
- When something is wrong, lead the user to the fix. Never just stop them.
- Assume the user doesn't know what went wrong, and be graceful about it.

## Law 3: Reveal the whole, work in small pieces
The full map is always visible. You walk it one short stretch at a time.
- Show the whole shape up front: every step, what it covers, roughly how long it takes.
- Work with about five things at a time, never more.
- No open-ended "Next" into the unknown.

## Law 4: Saving is shown, not announced
The interface itself proves the work is safe.
- Persist continuously and reflect it structurally: a count, a dot, an item appearing in a list.
- Fastmail: open a new draft and the Drafts count goes up immediately.
- Sublime Text: the tab dot tells the truth quietly.
- No spinners, no "Saving..." toasts.

## Law 5: Nothing is ever lost
A total, invisible safety net. Carelessness is free.
- Every keystroke is kept as it happens, not on an explicit save.
- A crash, a closed tab or a dead battery costs nothing.
- Reopen and you're exactly where you left off, like Sublime Text restoring unsaved files.

## Law 6: Control
The user is never trapped by the interface, least of all on mobile.
- The primary action is always reachable: sticky, never hidden behind the keyboard.
- The keyboard closes by tapping outside the field, or with a visible close-keyboard control.
- Next and previous between fields work every time.
- The user can always see what they entered.
- Menus and overlays close by tapping outside.

## Law 7: Form signals function
Appearance is a vocabulary. You read what something does before reading a word.
- Small pill with an icon: a quick, light action.
- Large solid button: the primary, committing action.
- Text-only button: a secondary path.
- Destructive actions look destructive.
- The same meaning always looks the same, and the same look always means the same.

## Law 8: Summonable structure
Don't bake in structure the user can summon.
- Keep the default view neutral and dense.
- Sorting, filtering, highlighting, freezing and grouping are tools, not decoration.
- The user lights up what matters to them now, and dismisses it after.
- Reference: Excel.

## Across components (first pass)
| Law | Form | Button | List item | Menu |
|---|---|---|---|---|
| 1 No surprises | Layout never shifts on errors | Never moves or resizes as you reach for it | Doesn't jump as items load | Order never changes by itself |
| 2 Optimism | Submit always enabled; errors guide | Acts instantly, reconciles later | Delete instantly, offer undo | No confirmation for reversible choices |
| 3 Small pieces | All steps visible, about five fields each | Label says exactly what happens | Count and groups visible | Groups visible; no blind scrolling |
| 4 Saving shown | Draft appears in a list or count | A toggle's state is its confirmation | New item appears in place | Checked state updates immediately |
| 5 Nothing lost | Input survives errors, reloads, crashes | Every action reversible | Deleted items recoverable | An accidental choice can be undone |
| 6 Control | Sticky submit, dismissible keyboard | Large target, never covered | User decides order and selection | Closes on outside tap or Escape |
| 7 Form signals function | One primary action per step | Style matches the weight of the action | Same kind of item, same layout | Destructive items look destructive |
| 8 Summonable | Rare fields on demand | Secondary actions off the surface | Sort, filter, highlight on demand | Search inside long menus |

## Reference component: the form
Submitting
- The submit button is always clickable. Pressing it always gets a response.
- On a failed submit: scroll to the first problem, focus it, name it. Show how many things need fixing, with links to each.
- Show success immediately. If the server disagrees, restore gently and point to the fix.

Validating
- Validation is a conversation, not a gate.
- Never check a field the user is still typing in.
- First check when the user leaves a field. Once a field is in error, re-check live so they see it clear.
- Errors are instructions: "Add your area code", not "Invalid input".
- Error messages reserve their space. Nothing shifts.

Large forms
- Show every step and what it covers up front, so the user knows scope and time.
- About five fields per step.
- Every step is saved, so Next is never a gamble.

Mobile
- Submit stays reachable above the keyboard.
- The keyboard closes on an outside tap or a visible control.
- Return moves to the next field, every time.

## Context, not instruction
Intuition governs how to operate; explanation is only for where you are and what's happening.
- Explain the map, not the mechanics.
- Explanation is ambient, not instructional. A draft count explains "saved" without a sentence.
- Explain only at the moment of need. No tutorials, no tips.
- If a control needs explaining, the design is wrong.

Fields that need context
- Sharpen the label first: "Gross monthly income (before tax)" instead of "Income".
- At most one line of always-visible help.
- Edge cases go behind a small disclosure, such as "What counts as income?".
- An example often explains more than a definition: "e.g. EUR 3,200".
- If a field needs paragraphs, it is several fields. Split it.

## Grouping and density (direction set)
Padding is the lazy default. It separates things but doesn't group them.
- Every grouping cue costs ink: dividers, fills, borders. Stack them and the screen gets crowded.
- Treat it as a budget: the least ink that keeps the structure unambiguous.
- Structure before decoration. A repeated internal layout says "this is an item" for free.
- One cue, not three.
- Density decides the tool. Sparse: space alone. Dense: one quiet cue.

What Excel gets right
- Gridlines so faint they never add up to noise.
- Persistent coordinates: row numbers, column letters, frozen headers.
- Perfect regularity, so every cell is obviously a unit.
- Alignment carries meaning: numbers right, text left.
- Structure is a tool: sort, filter, highlight on demand.
- Rule: more regularity, less separation.

## Typography and rhythm
Roles, not sizes
- Four roles at most: display, section heading, body, meta.
- Each size has to earn its place with a job nothing else does.
- Rarely more than two heading levels visible at once.

Two linked ratios
- Size: body x one ratio gives the whole type scale.
- Space: one base unit tied to the line height, used in multiples.
- Consistency beats precision. Every equivalent gap is the same gap.
- Spacing on a rhythm is honest grouping; arbitrary padding is not.

Legibility first
- Generous line height, short lines, strong contrast, clearly distinct letterforms, not too much text at once.
- What helps dyslexic readers helps everyone.