docs/design.md

# Interface design notes

InferScale is a research workbench, not a SaaS product. The UI is intentionally quiet so the experiment is the visual focus.

## Design rules

- **One job per screen.** Controls define an experiment; results explain that experiment. Secondary actions stay visually subordinate.
- **One accent color.** Blue marks the selected tab, primary action, and key chart series. Status colors are reserved for pass/fail/warning semantics.
- **Flat hierarchy.** Panels and charts use thin borders and square geometry. Avoid nested rounded cards, glass effects, gradients, glowing shadows, and decorative badges.
- **Editorial type.** System sans-serif for prose and controls; monospace only for evidence/provenance snippets. No decorative display font is required.
- **Spacing over decoration.** Use consistent 8/12/16/24 px rhythms before adding borders or backgrounds.
- **Labels are literal.** Prefer `Scheduler comparison`, `Cache budget`, and `Held-out calibration` over promotional names such as “arena”, “command center”, or “insights”.
- **Status is text, not chip soup.** Runtime/pass/fail state should be legible without turning every fact into a badge.
- **Progressive disclosure.** Prefix, trace, P/D, predictive, and calibration controls appear only when relevant.
- **No company chrome.** No promotional footer, testimonials, pricing-style cards, or fake product navigation.
- **Motion has a job.** Only the runtime header retracts after initialization; charts do not animate. Reduced-motion preferences are honored.

## Tokens

The public CSS defines a small neutral palette:

```text
background       #080c11
surface          #0c1219
inset surface    #090e14
border           #27313d
text             #e3e8ee
muted text       #929dab
accent           #6f96cf
success          #68c394
error            #df7d89
warning          #d2b36a
```

Corners are 0–2 px for most surfaces and controls. The interface does not use gradients or pill-shaped containers.

## Maintenance checklist

Before shipping a UI change:

1. Does the element help configure, inspect, compare, or export an experiment?
2. Can an existing treatment be reused instead of introducing another card/button/badge style?
3. Is the copy literal and specific?
4. Is information duplicated between a heading, kicker, chip, and paragraph?
5. Does the layout still work at 720 px and 1100 px breakpoints?
6. Is the control keyboard-focusable and does focus remain visible?
7. Does `scripts/release_check.py` still pass the public-design guardrails?