# QERYX design — the machine-readable spec

This file is the public design contract for qeryx.com, served at
`https://qeryx.com/design.md`. It exists so any reader — human or machine —
can verify that what the site does is what the site says it does. The values
here are the values in production; when the site changes, this file changes
with it.

Canvas is pure black. One green commands. Everything you read is white.

---

## 1. Color tokens

| Token | Value | Law |
|---|---|---|
| `--qx-bg` | `#000` | The page. Pure black, never near-black. |
| `--qx-raised` | `oklch(0.17 0.004 150)` | The only lifted surface (cards, menus, panels) — a whisper of green cast. |
| `--qx-raised-2` | `oklch(0.195 0.004 150)` | Hover / nested step of the lifted surface. |
| `--qx-line-1/2/3` | `rgba(255,255,255,0.05 / 0.08 / 0.12)` | Hairlines. Depth is drawn with these, not with gray ladders or shadows. |
| `--qx-fill-1/2/3` | `rgba(255,255,255,0.02 / 0.03 / 0.05)` | Interactive fills; white-alpha so they composite over anything. |
| `--serpent-a1…a8` | `rgba(0,255,65, 0.02→0.45)` | Serpent alpha scale: a1–2 backgrounds, a3–6 component states, a7–8 borders. |
| `--serpent-9` | `#00AA00` | THE solid green. The only green fill that exists. Buttons, one per viewport. |
| `--serpent-10` | `#00C433` | Solid hover. |
| `--serpent-11` | `#00FF41` | Accent text: links, focus, live signal. Never a fill. Never prose. |
| `--serpent-12` | `#B8FFCB` | Text on green fills, desaturated toward white. |
| `--primary` / `--primary-fg` | `var(--serpent-9)` / `#000` | Labels on green are BLACK: 6.75:1 AA. White on this green fails (3.1:1). |
| `--destructive` | `#FF3B30` | Destructive actions only. |
| `--qx-text` | `#EDEDED` | Body text — ~18:1 on black, softer halation than pure white. |
| `--qx-text-2` | `rgba(255,255,255,0.55)` | Secondary text — 6.1:1 AA. |
| `--qx-text-muted-floor` | `#9A9A9A` | The gray floor. Nothing readable ships below it; `#666`-class grays fail AA and are linted out. |
| `--qx-ok-*` | `hsl(145,100%,6%)` bg · `12%` border · `#00FF41` text | Status well, OK. |
| `--qx-warn-*` | `hsl(46,100%,6%)` bg · `9%` border · `hsl(46,87%,65%)` text | Status well, warning. |
| `--qx-err-*` | `hsl(358,76%,10%)` bg · `hsl(357,89%,16%)` border · `hsl(358,100%,81%)` text | Status well, error. |
| `--r-1…5` | `4 / 6 / 8 / 12 / 16px` | Radius law: chips / controls / buttons / cards+menus / hero frames. Pill for capsules. No per-page drift. |

### Color laws
- Green is never prose. There is no green-prose token — the violation is
  unrepresentable in the token system.
- `#00FF41` is never a button fill. It is reserved for focus rings, links, and
  at most four peak-salience moments per page.
- One solid-green fill (`--serpent-9`) per viewport.
- Exactly two surfaces: the black page and the raised step. Everything deeper
  is a hairline.
- Status is never color alone: every status pairs a dot with a text label.

### Contrast (computed, not aspirational)
`#EDEDED` on `#000` = 17.9:1 AAA · `#00FF41` on `#000` = 15.4:1 AAA ·
`#00AA00` on `#000` = 6.75:1 AA · black on `#00AA00` = 6.75:1 AA ·
white on `#00AA00` = 3.1:1 FAIL (which is why labels on green are black).

## 2. Elevation

| Token | Value | Use |
|---|---|---|
| `--qx-shadow-border` | `0 0 0 1px rgba(255,255,255,0.14), 0 1px 2px rgba(0,0,0,0.16), 0 0 0 1px #000` | Border-as-shadow on cards and controls; the outer black ring guarantees separation when raised surfaces overlap. |
| `--qx-focus` | `0 0 0 1px rgba(0,255,65,0.5), 0 0 0 4px rgba(0,255,65,0.18)` | The global focus ring. |
| `--qx-menu-shadow` | `rgba(8,9,10,0.6) 0 4px 32px` | The only black blur allowed on chrome. |
| `--qx-glow-ambient` / `--qx-glow-edge` | stacked low-alpha green falloff | Glow is stacked shadows, never filter blur. Budget: two glowing objects per viewport, never on text. |

Grain overlays at 4% sit on every green-glow gradient surface — green on black
bands without it. Art layers mask-fade into black; no hard edges.

## 3. Typography

| Surface | Stack | Rules |
|---|---|---|
| Body, headings | `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif` | Zero bytes, zero layout shift. 16–18px body, line-height 1.6, measure ≤70ch. H1 `clamp(3rem, 8vw, 5.5rem)`, weight 600, letter-spacing −0.035em. |
| Crypto surfaces only | `"JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace` (self-hosted, subset) | Ciphertext, fingerprints, safety numbers, primitive chips, telemetry, status labels, keycaps, code, table ID columns. 12–14px. Two-tone: values in white or `#00FF41`, labels and punctuation in `--qx-text-2` — never whole green blocks. |

`font-variant-numeric: tabular-nums` on every numeric surface. No shipped font
file exceeds 40 KB; the total font budget is 120 KB.

## 4. Space and layout

4px base unit. 8px within groups, 16px between groups, 32–40px between
sections. Max content width 1280px; prose measure ≤70ch regardless. Wide
content (tables, code, diagrams) scrolls inside its own `overflow-x: auto`
container — the page body never scrolls horizontally.

Breakpoints: base 0–479px (phone portrait — the design target) · 480px large
phones · 900px nav switch (below: drawer + sticky bottom CTA; above: full
header) · 1200px multi-column. Mobile is the primary experience; desktop is
the phone experience scaled up.

## 5. Motion

| Token | Value |
|---|---|
| `--t-instant` | `120ms` — hover, press, focus, palette open |
| `--t-fast` | `180ms` — menus, tooltips, small reveals |
| `--t-base` | `240ms` — cards, panels, section reveals |
| `--t-modal` | `500ms` — drawers and sheets only |
| `--ease-out` | `cubic-bezier(0.16, 1, 0.3, 1)` — default entrance |
| `--ease-ios` | `cubic-bezier(0.32, 0.72, 0, 1)` — drawers/sheets |
| `--ease-exit` | `cubic-bezier(0.4, 0, 1, 1)` |
| `--ease-scrub` | `cubic-bezier(0.33, 0, 0.2, 1)` — scrubbed camera moves only |
| `--spring-snap` | spring via `linear()` where supported, ~4% overshoot — timing only, never color |

### Motion value sheet

| Interaction | Duration / ease | Property |
|---|---|---|
| Header state change | 100–120ms ease-out | border-color, background |
| Label hover white → `#00FF41` | 120ms | color |
| Press | 120ms | `scale(0.97)` |
| Mega-panel open | 240ms `--ease-out` | opacity + rotateX(−12°→0) |
| Panel morph between sections | 300ms `--ease-out` | translate/scale on the background layer only — never width/height |
| Panel content swap | 200ms ease-out | opacity + translateX ±16px |
| Command palette open | 120ms | opacity + scale 0.98→1 |
| Drawer / drill-in | 500ms `--ease-ios` / 250ms | translateY / translateX |
| Odometer digits | ~300ms | translateY column roll |
| Scroll reveals | scroll-driven `view()` timeline | opacity + 12–24px rise |

### Motion laws
- Interactions ≤200ms; nothing exceeds 300ms except sheets.
- Animate `transform` and `opacity` only — compositor or nothing.
- High-frequency UI (menus, nav, list operations) gets no entrance animation.
- Every animation is interruptible. Loops pause off-screen and on hidden tabs;
  any loop over 5s shows a visible pause control.
- Stagger 60ms; a cascade completes within 300ms of its first child.
- One signature animation and at most two ambient loops per page. Trust and
  pricing surfaces run nearly still — stillness is the trust signal.
- `prefers-reduced-motion`: durations collapse to 0.01ms, canvases hold their
  posters, results still announce via `aria-live="polite"`. The reduced state
  is designed, never a blank hole.

### The signature — decrypt-resolve
Per-glyph monospace scramble (`#00AA00` churn, one `#00FF41` flash at the
resolve instant) settling into white plaintext inside a fixed `ch` grid, so
zero reflow. 120ms micro · 350–500ms medium · ~700ms hero. Reduced motion:
instant swap + 150ms opacity.

## 6. Component inventory

| Component | Intended use |
|---|---|
| `Section` | Page section wrapper; owns vertical rhythm and below-fold `content-visibility`. |
| `Hero` | Page-top statement: H1, sub, CTA pair, optional island slot. |
| `FeatureRow` | Alternating 50/50 media + essential-line rows. |
| `CryptoCard` | Raised card for a primitive or protocol; mono chip + one-line guarantee. |
| `SpecTable` | Normative primitive/parameter tables; mono value columns, `tabular-nums`. |
| `PrimitiveStrip` | The mono strip naming the primitives (ML-KEM-1024 · ML-DSA-87 · X25519 · ChaCha20-Poly1305 · HKDF-SHA-512 · Argon2id). |
| `CTASection` | Closing call to action: one solid green button + one ghost. |
| `Button` | Solid (`--serpent-9`, black label), ghost (hairline), and link variants; press scale 0.97. |
| `Badge` | Capsule status/label chip on the serpent alpha scale; black label on any green fill. |
| `Accordion` | Disclosure list, one open at a time, native `<details>/<summary>` with synced `aria-expanded`, 44px rows. |
| `StatusWell` | OK / warn / error wells from the `--qx-ok/warn/err` triplets; dot + text, never color alone. |
| `TabSwitcher` | ≥5-state content switching; mono uppercase rail, 2px `#00FF41` active underline. |
| `HighlightsRail` | Post-hero tile rail; four-word descriptors, anchor TOC. |
| `NumberedSection` | Dossier-style numbered chapters with mono `#00AA00` index numbers. |
| `StatBlock` | Display-size mono numerals; every stat footnotes to published methodology. |
| `VerdictTable` | Category-level comparison tables on real workloads. |

Interactive **islands** (the demo instruments) follow one doctrine: one bounded
canvas per island, poster-first (a static image is the first paint and the
reduced-motion end-state), pause off-viewport, real controls (`<button>`,
`<a>`), and a single-pointer alternative for every drag or scrub. Demo
cryptography is real — real ciphertext, real verification, run on your device
— or it is labeled for exactly what it is. Nothing on this site fakes a
cryptographic operation.

## 7. Voice

- The site speaks to one reader, in second person, present tense.
- Positive assertion. Say what the thing is.
- Short sentences. Verbs early. A headline is one breath.
- Name the primitive, never the adjective: every security sentence carries a
  primitive name, a linked artifact, or a statement of what the system cannot
  do. Statements of incapacity ("the server cannot read messages") are honesty
  instruments and are welcome.
- No superlatives on trust surfaces. No exclamation marks. No fear adjectives.
- Each section leads with one essential line; depth is a tap away, never a
  wall of text.
- Every quantitative claim footnotes to published methodology, or it does not
  ship. Every telemetry value is true or absent.

## 8. Performance and accessibility contract

Enforced in CI, measured on a throttled mobile profile: LCP ≤1.2s · CLS 0.00 ·
INP ≤100ms · initial JS ≤60KB gz · hydrated total ≤200KB/page · fonts ≤120KB.
Zero third-party requests — no CDNs, no font hosts, no analytics, no trackers,
no cookies; every byte comes from QERYX-controlled origins. WCAG 2.2 AA:
touch targets ≥24px (primary controls 44px), visible focus everywhere,
single-pointer alternatives for all drags, no hover-dependent content, and the
full site remains readable with JavaScript disabled.