---
version: 1.0
name: ZKAuth Warm Obsidian
description: ZKAuth's design system. A warm-paper editorial system with a single
  electric-cobalt accent. Dark theme is the default for the landing, pricing,
  blog, and dashboard. Warm paper is reserved for docs and legal-style reading
  surfaces where used.
colors-light:
  paper: "#fbfaf6"
  paper-alt: "#f4f1e9"
  surface: "#ffffff"
  ink: "#191917"
  ink-soft: "#56544c"
  ink-muted: "#8b887f"
  line: "#e4e1d8"
  line-strong: "#d8d3c6"
  brand: "#004dff"
  brand-hover: "#0042db"
  brand-wash: "#e9efff"
  brand-ink: "#ffffff"
  code-bg: "#171714"
  code-line: "#2b2a25"
colors-dark:
  paper: "#131310"
  paper-alt: "#1a1a16"
  surface: "#1a1a16"
  ink: "#f5f2ea"
  ink-soft: "#c9c5ba"
  ink-muted: "#a8a49a"
  line: "#2a2925"
  line-strong: "#38362f"
  brand: "#5b8cff"
  brand-hover: "#739dff"
  brand-wash: "#18233f"
  code-line: "#26251f"
typography:
  display: "Manrope"
  body: "Inter"
  mono: "JetBrains Mono"
  eyebrow: "JetBrains Mono, uppercase, 10.5-11px, letter-spacing 0.16-0.2em"
radius:
  control: "6-8px (rounded-md / rounded-lg)"
  panel: "12px (rounded-xl)"
  card-large: "16px (rounded-2xl)"
---

# ZKAuth Design System

ZKAuth's visual language is a warm editorial system: warm paper (light) or
warm obsidian (dark) surfaces, near-black warm ink, hairline structure, and a
single electric-cobalt accent. It is designed to read like a well-set
technical document, not a marketing site.

## Principles

- **One accent.** Cobalt (`brand`) is the only strong color. It marks the
  active state, the primary action, and nothing else. Success, warning, and
  danger use muted emerald, amber, and rose sparingly and only for state.
- **Numbers are the hero.** Metrics render in the display face with
  `tabular-nums`, large, over a quiet mono uppercase label. No decorative
  icons compete with the number.
- **Hairline structure.** Sections are separated by 1px `line` rules, not
  boxes inside boxes. Panels are a single border; content inside divides
  with hairlines (`divide-y`), never nested bordered cards.
- **Mono eyebrows.** Section labels are JetBrains Mono, uppercase, ~11px,
  letter-spacing 0.16em, in `ink-muted`. Often preceded by a short cobalt
  tick (a 24px 1px line).
- **Icons are quiet.** Lucide icons at 1.5-1.6 stroke width, sized 14-16px,
  in `ink-muted`, turning `brand` only when active. Never place an icon in a
  bordered chip as decoration.
- **Dark code everywhere.** Code blocks sit on the warm obsidian `code-bg`
  surface even in the light theme, with a header row (filename left,
  language right) and a copy button.
- **Restrained motion.** Opacity-first transitions (route fade), small
  fade+rise reveals (`dash-in`), and one orchestrated moment per page at
  most. `prefers-reduced-motion` disables all of it.

## Typography

- **Display (Manrope, 600-800):** page titles, metric values, card titles.
  Tight tracking (-0.02em) at large sizes.
- **Body (Inter):** 13.5-16px UI text; 16px/1.85 for long-form reading.
- **Mono (JetBrains Mono):** code, eyebrow labels, dates, keys, protocol
  fragments. Mono is a voice in this system, not just a code font: technical
  truth renders in mono.
- Copy is sentence case. Buttons say exactly what they do ("Save changes",
  not "Submit"). Errors explain what happened and what to do next.

## Color usage

- Backgrounds layer as `paper` (page) -> `paper-alt` (alternating sections,
  inputs) -> `surface` (cards/panels).
- Text layers as `ink` (primary) -> `ink-soft` (secondary) -> `ink-muted`
  (labels, metadata).
- `brand-wash` is the tinted fill for selected/active states; pair it with a
  `brand`-tinted border at 25-30% opacity.
- In the dark theme, filled primary controls use a deepened cobalt
  (hsl 224 100% 58%) while text accents use the lighter `#5b8cff`.

## Signature elements

- **Cobalt underline rail:** primary navigation is text on a hairline, the
  active item marked by a 2px cobalt underline sitting on the rule.
- **Protocol-line art:** covers and cards use oversized, deliberately
  cropped JetBrains Mono fragments of the real API (for example
  `login(proof, publicSignals)`) with a single cobalt token, over obsidian
  with a faint drafting grid and a low cobalt glow. No stock imagery.
- **The vault glow:** a radial cobalt light source used sparingly as the
  one luminous moment on dark pages.

## Honesty rules for copy

Every public sentence must be backed by the implementation. Claims are
tracked in a machine-checked inventory and the build fails on overclaims.
Do not write "passwordless" (it is zero-knowledge password auth), do not
claim compliance certifications, and mark previews as previews.