Zaudit — homepage

The Zaudit marketing homepage, built from the Claude Design handoff in ../project (Homepage Veltrex.dc.html). Next.js App Router + React + TypeScript.

npm install
cp .env.example .env.local   # see "Keys" below — the audit degrades without them
npm run dev                  # http://localhost:3000

Layout

src/
  design/tokens.ts        colour, type ramp, spacing, radius, shadow, motion — typed
  app/
    layout.tsx            fonts + metadata
    globals.css           the design's token set (light + dark), keyframes, hover rules
    page.tsx              renders <Homepage />
    design/page.tsx       /design — every token and component on one page
    api/audit/route.ts    POST /api/audit — NDJSON stream of stage/result/error events
  components/
    Homepage.tsx          section composition + shared audit state
    sections/             one file per section, in page order
    site/                 announcement bar, nav, footer
    ui/                   the design system — see below
  content/homepage.ts     every string on the page
  hooks/useAudit.ts       drives the hero's idle/goal/running/error/done states
  lib/audit/              the engine: framework + criteria catalog, browser
                          probes, checks → criteria → pillars → score

The design system

src/design/tokens.ts holds the values; src/components/ui holds the components built from them. Both are extracted from what the page already did — before this existed, the twelve sections between them declared 57 distinct font shorthands, 16 hand-written section borders and 15 hand-written card surfaces.

import { Section, Container, Stack, Card, Heading, Text } from '@/components/ui';
import { color, radius, t } from '@/design/tokens';

file	what's in it
ui/layout.tsx	Section, Container, Stack, Row, Grid, Spacer, Divider, Card
ui/typography.tsx	Text, Heading, Eyebrow, GradientText, SectionHeader
ui/elements.tsx	ArrowLink, IconTile, Dot, CountPill, Meter, MetaRow, FieldLabel
ui/SeverityTag.tsx	the Critical/High/Medium/Low scale, shared by the hero and the results
ui/Button Badge Input Icon ImageSlot	ported straight from the design system

Three things worth knowing before you add to it:

Spacing is pixels, not step indices. gap={20} means twenty pixels. Values on the design's scale autocomplete; an off-scale number still compiles, because the design has a few.

The type ramp is named by job, not size — lead, sectionTitle, metric. The design carries near-duplicate steps (13/18, 13/19, 13/20 and 13/21 all appear), so those are transcribed as they are rather than snapped onto a tidier scale that would change the rendering. A step the ramp doesn't name composes through t(weight, size, lineHeight, family) instead of a raw string.

Colour is a role, resolved through a CSS custom property. Nothing hard-codes a hex except staticColor, which is the ink the design fixes regardless of theme. This is why the footer can redefine --fg/--border on itself and every component inside it inverts without knowing it is on a dark field — and why /design's theme toggle works at all.

/design renders the whole thing from the same components as the homepage, so if something drifts there it has drifted here too.

Design fidelity

Tokens, type ramps, spacing, radii, shadows and the 1152px container are transcribed verbatim from the design file — globals.css and src/design/tokens.ts are the design, not an approximation of it. src/components/ui/icon-data.ts is generated from the design system's own icon data, so the glyphs are byte-identical.

Moving the sections onto the components above was checked rather than assumed: the computed styles of all 784 elements were captured before the change and diffed against the rendering after it. What survived was 43 differences across 763 matched elements, every one deliberate — whiteSpace: nowrap and a centred label on the two buttons that had been hand-written instead of using Button, a 1px rule that is now a Divider rather than a bare borderTop, the browser's default 6px padding on a full-width centred button, and start → flex-start, which is the same value. No rendered pixel moved.

Both themes are defined. The design has no theme toggle (it was a design-tool prop), so the page renders light; add data-theme="dark" to <html> to switch, or wire a toggle to that attribute. /design has one, which is the quickest way to see the dark palette.

The audit engine

The engine implements the Audit Benchmark Framework v1.0: pillars → criteria → evidence → score. The framework's types are in src/lib/audit/framework.ts, the criteria library is src/lib/audit/catalog/pillars.ts, and the measurements behind the criteria are the checks in src/lib/audit/catalog/*.ts with their code in src/lib/audit/rules/.

Two layers, deliberately separate. A criterion is what the report quotes: a checkable statement carrying the standard it comes from, the platforms it applies to, whether it can be measured, and what counts as a pass. A check is the engine's unit of measurement, with the evidence it must produce and the fix to print. A criterion names the checks that decide it; a check can serve more than one criterion. Nothing in the report says ACC-012 — it says AC-11, WCAG 2.2 AA 2.5.8, measured 20×22px, required 24×24px.

This is the beginning of the README. Read the rest at the original. Read the full README ↗