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:

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?