STD-X — The Design Standard

Subordinate to Codex 1 and the Codices named in §1. See 00-index.md for authority, normative vocabulary, citation format, and waiver rules, which this Standard does not restate.

1. Purpose

This Standard turns Codex 6's experience doctrine and the Codex 6 Rubric into obligations a reviewer who did not build the surface can check without asking the author. It governs the visual and interaction language of every surface: tokens, typography, spacing, componentry, states, motion, accessibility, responsiveness, performance, metadata, and writing register. It states what makes a surface eligible for built status and what a surface must never do.

Codex 6 doctrine  ────────────►  states what "good" means
Codex 6 Rubric    ────────────►  scores a specific surface against it
STD-X (this file) ────────────►  states what a reviewer checks, clause by clause
Registry entry    ────────────►  records the score, the review form, the status

2. Scope and non-scope

In scope. Every route rendered to a human (institutional, division, member, operator, verification classes per Codex 0 §11.2); the components and tokens that render them; the review procedure that gates built status.

Not in scope. Machine-class surfaces with no renderer (Codex 0 §11.2, §13); the substance of the Codex 6 Rubric's scoring dimensions, which this Standard does not restate — see §12; server-side authorisation logic (STD-S); data modelling behind a surface (STD-D); the copy of the Codex 6 doctrine itself, which this Standard cites rather than repeats.

3. Normative clauses

3.1 Semantic tokens and the prohibition on hardcoded colour

3.1.1 Every colour, gradient, shadow, and border value used in a component must resolve to a semantic token defined in src/styles.css (--color-*, or a named institutional token such as --charcoal, --bronze, --gold) or a Tailwind utility class that itself maps to one of those tokens (bg-card, text-muted-foreground, border-border). A component must not contain a literal colour value: no hex, rgb, hsl, oklch literal, and no arbitrary Tailwind colour utility (bg-[#...], text-[oklch(...)]) outside src/styles.css.

3.1.2 A reviewer verifies 3.1.1 by searching the changed files for hex codes, rgb(, hsl(, oklch( outside src/styles.css, and for Tailwind colour utilities not backed by a theme token (bg-red-500, text-blue-600, and equivalents). Any match is a defect; there is no severity below blocking for this clause.

3.1.3 A new token is added to src/styles.css under @theme inline or :root, never invented ad hoc inside a component file, and is named for its semantic role (--color-warning), never for its appearance (--color-orange).

3.1.4 Radius, motion duration, and font tokens follow the same rule: a component must reference --radius-*, the declared --font-* families, or an existing motion token, never a literal pixel radius or arbitrary duration outside src/styles.css.

3.2 Typographic hierarchy

3.2.1 A surface must use only the five typographic roles named in Codex 6 — eyebrow, numeral, hairline, body, marginalia — realised as the existing utilities and primitives (eyebrow, numeral, .display, Hairline, body text, marginalia styling) in src/styles.css and src/components/editorial/primitives.tsx. A reviewer checks that no heading, label, or caption on the surface uses a typographic treatment absent from this set.

3.2.2 Heading levels (h1–h6) must be assigned by document structure, not by desired visual size. Visual size is controlled by utility classes on the correct heading level, never by skipping a level to get a smaller or larger default. A reviewer checks the rendered DOM's heading sequence contains no skipped level.

3.2.3 Exactly one h1 exists per rendered document. A reviewer checks this by inspecting the rendered page.

3.2.4 The eyebrow role marks category or context, the numeral role marks an ordinal or index, body text carries the argument, and marginalia carries commentary subordinate to body text. A reviewer checks that no role is used for a purpose outside this list (for example, an eyebrow used as a decorative label with no categorical meaning is a defect).

3.2.5 Font family usage is limited to the three declared families (--font-serif, --font-sans, --font-mono); a reviewer greps for any font-family declaration or Tailwind font utility referencing a family outside this set and treats a match as a defect.

3.2.6 A serif display face (.display) is reserved for headings and numerals carrying institutional weight; body copy at reading length must use the sans family. A reviewer checks that no long-form paragraph is set in the display face, which degrades legibility at length.

3.3 Spacing, rhythm, and measure

3.3.1 Body text measure (line length) must fall between 45 and 75 characters at the container's default rendered width, checked at the surface's primary breakpoint by counting characters in a representative rendered line or by the container's max-width relative to its font size.

3.3.2 Vertical rhythm between sections must use a consistent spacing scale drawn from Tailwind's spacing tokens (the default space-y-*, gap-*, py-* scale); a reviewer checks that spacing values within one surface are drawn from a small, consistent set (three or fewer distinct step sizes between major sections) rather than ad hoc arbitrary values (mt-[17px]).

3.3.3 Arbitrary spacing values (p-[13px], gap-[22px]) must not appear in a component; a reviewer greps the changed files for bracketed arbitrary spacing utilities and treats any match as a defect unless the clause is waived per STD-X §4 with a stated geometric reason (e.g. matching an external asset's fixed dimension).

3.4 Component reuse before creation

3.4.1 Before writing a new component, the author must check src/components/editorial/ and the existing src/components/ui/ primitives (shadcn variants) for one that serves the need with a prop or variant addition. A reviewer checks the Registry proposal or PR description states which existing primitives were checked and why none served (Codex 6 Rubric dimension 6 evidence, restated here as a design obligation).

3.4.2 A pattern that appears twice in the codebase in materially the same form must be extracted into a shared component before a third use is added. A reviewer checks by searching for the repeated markup shape across files at the time of the third addition.

3.4.3 A new primitive is justified in writing before it is built: the need it serves, the existing primitives considered and rejected, and why a variant of an existing primitive could not be extended instead. This justification is recorded in the surface's Registry proposal (Codex 6 TEMPLATE-page.md §10) or, for a primitive introduced outside a specific surface, in the component's own file header comment.

3.4.4 A new primitive must expose its visual properties through the existing token set (§3.1) and must not introduce a parallel styling system (inline styles, a separate CSS file, a competing class-naming convention).

3.5 The five required states, plus offline

3.5.1 Every surface that reads or writes data must specify, before implementation, its behaviour and wording for: empty, loading, partial (some data unavailable), error, and unauthorised (Codex 0 §11.3.3.1). A reviewer checks the surface's Registry specification (TEMPLATE-page.md §7) names all five with concrete wording, not a placeholder.

3.5.2 A sixth state — offline or poor connection — must be specified wherever the surface is reasonably reached outside a reliable network (any member or public surface without a stated exception). A reviewer checks for a stated offline behaviour or a documented reason the surface is exempt (for example, an internal operator console used only on institutional wired networks).

3.5.3 An error state must name cause, consequence, and remedy in plain language, checkable by reading the exact copy against these three components. Absence of any one of the three is a defect (Codex 0 §11.3.3.2).

3.5.4 An unauthorised state must name what access is missing and what the person can do about it; it must not render as if the content did not exist. A reviewer checks the rendered unauthorised state against this requirement directly.

3.5.5 A partial state must identify which specific data is unavailable, not merely display a generic warning; a reviewer checks the copy names the missing element.

3.5.6 A loading state must never present a numeral, count, or figure as a placeholder value (a fake "0" or a skeleton digit that could be mistaken for a real figure); a reviewer checks that loading placeholders are visually and textually distinct from real data (skeleton bars, not zeros).

3.6 Motion

3.6.1 Motion must serve orientation (confirming a transition, showing where new content entered) or hierarchy (drawing attention to the one primary action); motion used purely as ornament is prohibited.

3.6.2 Every animation or transition must be wrapped by, or must itself respect, a prefers-reduced-motion check: a reviewer checks the component code for a reduced-motion guard (a CSS @media (prefers-reduced-motion: reduce) rule, a motion-safe:/motion-reduce: Tailwind variant, or an equivalent JS check) wherever a non-trivial animation (duration > 150ms, or any transform/opacity animation on page load) is present.

3.6.3 No animation may be indefinite, looping, or attention-seeking (pulsing badges, bouncing icons, autoplaying carousels) per the Codex 6 prohibition on manufactured attention mechanics. A reviewer checks for any animate- utility or custom keyframe with infinite iteration and treats it as a defect unless it communicates an active, ongoing process (a loading spinner) with a stated maximum duration or cancel affordance.

3.7 The accessibility floor

3.7.1 Keyboard completeness. Every interactive element must be reachable and operable via keyboard alone, in a logical tab order matching visual order. A reviewer checks by tabbing through the rendered surface without a mouse and confirming every action reachable by pointer is reachable by keyboard.

3.7.2 Visible focus. Every focusable element must show a visible focus indicator meeting at least 3:1 contrast against its background, using the --ring token, never outline: none without a replacement. A reviewer checks by tabbing through the surface and confirming a visible indicator at each stop.

3.7.3 Contrast. Body text must meet WCAG 2.1 AA (4.5:1 for text under 18pt/14pt bold, 3:1 above that size); UI component boundaries and icons carrying meaning must meet 3:1. A reviewer checks foreground/background token pairs against these ratios using a contrast-checking tool, not by eye.

3.7.4 Landmark and heading order. Every surface must expose header, main, and nav (where navigation exists) as identifiable landmarks, and headings must nest without skipped levels (§3.2.2). A reviewer checks the accessibility tree (browser devtools or an automated audit) for landmark presence and heading order.

3.7.5 Alternative text. Every image or icon carrying meaning must have alternative text describing that meaning; purely decorative images must be marked so assistive technology skips them (alt="" or aria-hidden). A reviewer checks every img and meaningful SVG in the changed files has one or the other, deliberately chosen, not left blank by omission.

3.7.6 Form labelling. Every form input must have a programmatically associated label (a <label for>, aria-label, or aria-labelledby); placeholder text alone is never a label. A reviewer checks each form field in the changed files for an associated label and confirms no field relies on placeholder text as its sole label.

3.7.7 Accessibility is verified, not asserted (Codex 0 §11.3.5.2). The surface's review form states the specific method used for each of §3.7.1–3.7.6 (manual keyboard pass, automated audit tool and its result, contrast checker reading), not a checkbox with no evidence.

3.8 Responsive obligations

3.8.1 A surface must render without horizontal scroll, overlapping content, or truncated interactive controls at 320px width and at the institution's standard desktop breakpoint at minimum; a reviewer checks both widths in the browser devtools responsive view.

3.8.2 Touch targets on any surface reachable on a touch device must be at least 44×44 CSS pixels; a reviewer checks interactive element dimensions at the mobile breakpoint.

3.8.3 Layouts must use the project's existing breakpoint scale (Tailwind's sm/md/lg/xl); a bespoke breakpoint introduced for one surface is a defect unless justified per §3.4.3.

3.9 Performance obligations

3.9.1 A surface's primary content must be visible and its primary action operable within 3 seconds on a throttled "Slow 3G" network profile in browser devtools; a reviewer checks this directly using devtools network throttling.

3.9.2 A surface must render a loading state (§3.5) within 200ms of navigation, even where the underlying data has not yet arrived, so the person is never looking at a blank screen while waiting.

3.9.3 Images must be sized and, where the framework supports it, lazy-loaded outside the initial viewport; a reviewer checks that below-the-fold images carry a lazy-loading attribute or equivalent and that no unsized image causes layout shift (checked visually or via a Cumulative Layout Shift reading).

3.9.4 A surface must remain usable — not merely present some content, but allow its primary action to complete — when a non-critical request (an analytics call, a secondary data panel) fails or times out; a reviewer checks this by blocking the non-critical request in devtools and confirming the primary action still completes.

3.9.5 A surface must not block its primary action behind the load of an unrelated resource (a marketing script, a chat widget, a font not yet resolved); a reviewer checks the primary action's operability with such resources deliberately delayed in devtools.

3.10 Route metadata obligations

3.10.1 Every content route must declare, via its route's head(): a title unique across every other route in the application and under 60 characters; a description under 160 characters. A reviewer checks character counts directly and greps other routes' head() for a duplicate title or description string.

3.10.2 Every content route must declare og:title, og:description, and, where the surface renders a meaningful cover image, og:image and twitter:image as absolute https:// URLs — never relative paths, and never an image with no representative relationship to the page's content. A reviewer checks the rendered head() output for these fields and, where present, resolves the image URL to confirm it is absolute.

3.10.3 A route with no meaningful cover image must omit og:image/twitter:image rather than supply a generic placeholder asset reused across unrelated routes; a reviewer checks that any shared image is not attached to a route it does not represent.

3.10.4 Metadata fields are written in the surface's own register (§3.11), never in marketing voice, and never assert a status (certified, compliant, audited) unless the surface itself carries the documented evidence for that claim (Codex 1 Art. VI.8).

3.11 Writing register

3.11.1 Copy must use plain, declarative sentences. A reviewer checks for compound marketing sentences, superlatives without evidence ("the best," "revolutionary"), and rhetorical questions used as headings, and treats each as a defect.

3.11.2 A term new to the reader must be defined either in place (a short parenthetical or adjacent sentence) or by a link to the glossary (/glossary), per the Codex 6 Rubric's three-term budget. A reviewer checks each surface introduces no more than three undefined terms and that each is defined by one of these two means.

3.11.3 Copy must not manufacture urgency (countdowns, "act now," artificial deadlines not tied to a real, stated constraint) or imply social proof that cannot be evidenced (unverified counts, vague "trusted by many"). A reviewer checks copy against this list directly.

3.11.4 A claim of certification, compliance, audit outcome, or credential validity appearing in surface copy must be traceable to documented evidence named in the surface's Registry entry; a reviewer checks the claim against that evidence and treats an untraceable claim as a defect requiring removal, not softening.

3.11.5 Sentences must not be assembled by string concatenation across languages or plural forms in a way that breaks under localization (Codex 6, "Localization readiness"); a reviewer checks source strings for concatenated fragments that assume English word order or English pluralisation rules.

3.11.6 Numerals shown in copy or in a figure must state what they count and over what period, matching Codex 0 §12.3.1 even outside a dashboard context; a reviewer checks every standalone figure on the surface carries this adjacent statement.

3.12 The rubric gate

3.12.1 A surface must pass the Codex 6 Rubric (docs/codices/CODEX-6/RUBRIC.md) with no dimension scoring 0, and any dimension scoring 1 must carry a named remediation owner and date, before its Registry entry may move to built (Codex 0 §11.5.1–§11.5.2). This Standard does not restate the rubric's scoring instrument; it is scored exactly as RUBRIC.md and its templates (TEMPLATE-page.md, TEMPLATE-interaction.md, TEMPLATE-review.md) specify.

3.12.2 A completed review form (TEMPLATE-review.md) must be attached to the Registry entry before built status is recorded; a reviewer checks the form exists, is dated, and answers every field, including the final gate paragraph ("did this make the person's life better?").

3.12.3 A surface scoring 16 or below on the rubric is redesigned, not patched, and does not move to built in its patched form (Codex 0 §11.5.3); a reviewer checks the total score before accepting any subsequent partial fix as sufficient.

3.13 Prohibited interaction patterns

3.13.1 The following must not appear on any surface, without exception or waiver (Codex 1 Art. VI.1, Codex 6 "Forbidden," Rubric §7): manufactured urgency; countdowns; artificial scarcity; loss-framed nudges; notification pressure; infinite feeds; vanity counts (raw logins, clicks, time-on-site shown as an achievement); streak guilt; points, levels, or badges of mere participation; rankings of people against each other; consent bundled into an unrelated action; obstructed cancellation or export; any mechanic designed to make leaving feel costly; "AI aesthetic" ornament (glows, neon, generated-looking decoration); startup-cliché visual identity (purple-on-white gradients, default sans stack used as brand identity).

3.13.2 A reviewer checks for each item in §3.13.1 explicitly, by name, in the review form; an unchecked list is an incomplete review, not a passed one.

4. Governing Codex clauses

Codex 6 (Experience Doctrine), in full, and its Rubric and templates. Codex 0 Chapter 11 §11.3 (surface contract), §11.4 (naming), §11.5 (rubric gate). Codex 0 Chapter 12 (dashboard-specific figure and disclosure rules, where the surface is a dashboard). Codex 1 Article V (the member is not the product), Article VI.1 (no dark patterns), VI.8 (documented evidence for public claims), VI.9 (accessibility is a requirement).

5. Conformance checklist

• [ ] No hardcoded colour, gradient, shadow, or arbitrary radius value found in changed component files (§3.1). — yes / no / not-applicable-because
• [ ] Only the five typographic roles are used, correctly, with one h1 and no skipped heading level (§3.2). — yes / no / not-applicable-because
• [ ] Body measure is 45–75 characters and spacing is drawn from a consistent, small step set with no arbitrary bracketed spacing values (§3.3). — yes / no / not-applicable-because
• [ ] Existing primitives were checked before any new component was written, and any new primitive is justified in writing (§3.4). — yes / no / not-applicable-because
• [ ] Empty, loading, partial, error, unauthorised, and (where applicable) offline states are specified with concrete wording (§3.5). — yes / no / not-applicable-because
• [ ] All non-trivial motion respects prefers-reduced-motion and no motion is indefinite or attention-seeking (§3.6). — yes / no / not-applicable-because
• [ ] Keyboard completeness, visible focus, contrast, landmarks/heading order, alt text, and form labelling are each verified with a stated method (§3.7). — yes / no / not-applicable-because
• [ ] The surface renders correctly at 320px and at the standard desktop breakpoint with 44×44px touch targets (§3.8). — yes / no / not-applicable-because
• [ ] Primary content and action are usable within 3 seconds on a throttled connection, and a non-critical failure does not block the primary action (§3.9). — yes / no / not-applicable-because
• [ ] Route metadata (title, description, og/twitter fields) is unique, within length limits, and uses absolute image URLs only where meaningful (§3.10). — yes / no / not-applicable-because
• [ ] Copy is plain, defines new terms within budget, and carries no unmanufactured urgency or untraceable claims (§3.11). — yes / no / not-applicable-because
• [ ] The Codex 6 Rubric self-score and review form are complete, with no dimension at 0 and any dimension at 1 carrying a named owner and date (§3.12). — yes / no / not-applicable-because
• [ ] No item from the prohibited interaction pattern list (§3.13) is present. — yes / no / not-applicable-because

6. Interfaces to other Standards

STD-Q gates final shipment and cites this Standard's checklist rather than restating it. STD-S governs server-side authorisation behind the unauthorised state (§3.5.4); this Standard governs only its presentation. STD-A governs when a new architectural boundary is justified; §3.4 governs only the design-primitive analogue of that question. STD-I governs the explainability of any AI-produced content that appears on a surface (Codex 0 §12.3.6); this Standard governs only how that explanation is presented, not its correctness. STD-R governs metadata and register on research-authored routes where they diverge from general institutional copy; this Standard's §3.10–3.11 are the floor both must meet.

7. Open questions

7.1 Whether an automated tokenisation linter (blocking a commit containing a literal colour value) should be required infrastructure rather than a manual review step is undecided; until built, §3.1.2's grep is manual.

7.2 Whether the 45–75 character measure (§3.3.1) should be enforced by a container max-width token added to src/styles.css, rather than left to per-surface judgement, is open.

7.3 The specific automated accessibility audit tool (§3.7.7) to standardise on, and whether its output becomes a required CI gate, is unresolved.

7.4 Whether performance budgets (§3.9) should be measured in CI against a fixed Lighthouse threshold rather than a manual devtools check is open, pending Codex 0 Chapter 14 tooling decisions.

7.5 Whether a shared max-measure or prose container primitive should be added to src/components/editorial/primitives.tsx to make §3.3.1 self-enforcing, rather than relying on per-surface review, is undecided.

7.6 Whether the prohibited-pattern list (§3.13) should be extended by a linting rule that flags known offending class names or copy patterns automatically is open.