# DESIGN.md

Visual direction for the PASITA Space. Language: flat, neutral, React/Next-like
(Vercel Geist grammar: semantic grays, 6/12 radii, hairline strokes, no gradients).
Explicitly excluded: gradients, glows, blue/purple accents, glassmorphism, decoration.

## Design read

A document tool for Hugging Face users, in a flat instrument-panel language,
with dials ENERGY 2 / RHYTHM 1 / MOTION 1.

- ENERGY 2: clear header and one high-contrast primary action, no hero, no landing decoration.
- RHYTHM 1: a single two-panel composition, because the task is one input and one output.
- MOTION 1: hover and focus states only, plus the pulsing status dot while loading.

## Tokens

- Page `#0a0a0b`, panels `#101013`, raised surfaces `#16161a`, code `#0d0d10`. Flat fills only.
- Text `#f4f4f5`, secondary `#a1a1aa`, tertiary `#8e8e96` (both AA on the page background).
- Signature gold `#e8b34c`: the product mark and the selected-state text (tabs, candidate pills).
- Primary action is white (`#fafafa` on `#0a0a0b`), secondary is a ghost with a hairline border.
- Status is semantic and always paired with text: green `#4cc38a` ready, gold busy, red `#f87171` error.
- Type: Inter for reading, JetBrains Mono for labels, counters, metrics and code.
  Metrics use tabular numerals.

## Why each decision

- Flat near-black: reading documents needs contrast, not decoration; gradients are banned here.
- White primary action: the highest-contrast element on the page, marking the one key action.
- Gold only on the product mark and the active selection: one identity color, one meaning.
- Mono plus tabular numerals for machine text: counts and metrics stay scannable and stable.
- Two panels: conversion is input to output; they stack on mobile.
- Details tab with run metrics in plain words: route, numbers kept (with the missing list),
  coverage, time and candidate count.
- Download button writes the current Markdown to a `pasita-*.md` file; old files are pruned.
- Print stylesheet renders the output black on white and hides the input chrome.
- Status line with real metrics: it proves the faithfulness promise (numbers kept, coverage,
  route used) instead of claiming it.
- Green/red/yellow status with text labels: color never carries meaning alone.
- Real controls: Convert, Clear, candidates 1 to 3, deterministic converter. No decorative
  element without a function.

## Contrast (WCAG AA)

Computed with the relative-luminance formula:

- `#a1a1aa` on `#0a0a0b`: 8.3:1 (normal text, pass).
- `#8e8e96` on `#0a0a0b`: 6.5:1 (normal text, pass).
- `#e8b34c` on `#0a0a0b`: 9.9:1 (normal text, pass).
- Text `#0a0a0b` on button `#fafafa`: 19.5:1 (pass).
- Focus ring `#e8b34c` on `#0a0a0b`: 9.9:1 (non-text, above 3:1).

## States

- Empty: the output panel shows a marker and the status says READY.
- Loading: the js pre-call flips the status to CONVERTING; Gradio shows minimal progress.
- Error: the status switches to ERROR with the exception type and the output shows the message.
- Keyboard: every control is reachable, `:focus-visible` ring in gold.

## What we do not do

- No gradients, no glows, no blue or purple anywhere.
- No emoji in the UI chrome.
- No fake screenshots, testimonials or invented figures.
- No looping animations (the busy dot is the only exception, with a reduced-motion kill switch).
- No decorative grids or background patterns.