Agent Guide — Outlex Design System v3 Gravity

Section 01

Canonical links

The only valid URL forms for this design system. Repo paths and redirected aliases are NOT canonical — always fetch the live root-absolute URL.

URL	What it is	For
https://design.outlex.ai/agents	This page — v3 agent guide	v3 · New
https://design.outlex.ai/GRAMMAR-v3.md	The six laws + implementation appendix (exact CSS recipes) Primary fetch target for any marketing/hero surface	v3 · New
https://design.outlex.ai/tokens-v3-gravity.css	v3 cinematography tokens — load AFTER `tokens-v2.css`	v3 · New
https://design.outlex.ai/brand-v3.md	Single-file v3 LLM reference	v3 · New
https://design.outlex.ai/brand.md	Foundation brand reference (colour primitives, spacing, typography)	Foundation
https://design.outlex.ai/GRAMMAR.md	Foundation component grammar — exact CSS recipes	Foundation
https://design.outlex.ai/tokens-v2.css	Foundation CSS custom properties (`--ox-*` prefix) — v3's dependency	Foundation
https://design.outlex.ai/components	Component Playground	Agent · Human
https://design.outlex.ai/motion	Motion Lab — budget + demos	Agent · Human
https://design.outlex.ai/voice.md	Core voice and claim-routing rules	Agent · Copywriter
https://design.outlex.ai/voice-marketing.md	Marketing copy patterns for landing pages, email, social, blog, sales, and press	Agent · Copywriter
https://design.outlex.ai/marketing	Browse and download the approved marketing image library	Agent · Human
https://design.outlex.ai/marketing/guide#design	Human guide for visual systems, image choice, and crop rules	Human · Designer
https://design.outlex.ai/marketing/guide#copy	Human guide for simple, clear marketing copy	Human · Copywriter
https://design.outlex.ai/marketing.md	Marketing templates, visual routing, image rules, and approval contract	Agent · Designer
https://design.outlex.ai/marketing/image-library.json	Approved human and non-human photography catalog with light/dark variants and channel derivatives	Agent · Asset
https://design.outlex.ai/v2/	Archived visual brand book — the prior edition, kept live at this path for reference	Archive
https://design.outlex.ai/v1/	v1/V7 legacy archive — reference only Use when editing unmigrated product surfaces that still implement V7	Legacy

Not canonical: /tokens/tokens-v3-gravity.css · /tokens/GRAMMAR-v3.md · /brand/brand-v3.md · tokens/tokens-v2.css · brand/brand.md (repo paths — not URLs)
These 302-redirect to the canonical root-absolute form. Always fetch the live URL, never the repo path.

Section 02

Fetch routing

Which file to fetch depends on what you're touching, not on what version number feels newest. v3 is additive — it never replaces the foundation.

You're touching…	Fetch this	Why
Marketing / hero surface — website, landing page, any dark-theater or light-gallery marketing screen	`marketing.md` + `GRAMMAR-v3.md` + both token files add `image-library.json` when photography applies	Marketing rules select approved photography for people, work, and place; v3 defines Gravity product theater for UI, diagrams, and system states.
Foundation tokens — colour primitives, spacing, typography, motion, any base `--ox-*` value	`brand.md` + `tokens-v2.css`	The foundation (--ox-* tokens) is what every surface stands on. v3 is additive and doesn't redefine primitives.
Product in-app surface — app.outlex.ai, any migrated OR unmigrated surface	`GRAMMAR.md` + `tokens-v2.css` until P3 lands	V7 legacy and the foundation grammar (--ox-* tokens) are what's live in-product — V7 on surfaces not yet migrated, the foundation grammar on migrated ones. The v3 colour law already applies to any NEW in-app surface — no amber-as-AI, no second sage CTA — even ahead of full v3 rollout.
New Linear issue touching UI	Section 08 below — paste the issue block verbatim	Ensures the assigned agent reads the right layer before writing any code.
Unsure which layer a file belongs to	`DESIGN_DIRECTION.md` in mvp2 root	Source of truth for migration state per surface.

Section 03

Migration state

v3 is additive over the foundation. Nothing in v1 or the foundation layer breaks. Read this before touching any product file.

v3 "Gravity" is the cinematography layer — active since 2026-07-15. It ships on top of the foundation layer (tokens-v2.css must load first) and adds scene staging, machined controls, the colour law, life signals, and product theater.

The foundation layer (formerly Precision + Atmosphere) is absorbed into v3 — it defines the colour primitives, spacing, typography, and motion tokens every surface stands on. Nothing in it is redefined; earlier editions are archived at /v2/.

The product (app.outlex.ai) still implements V7 legacy on unmigrated surfaces and the foundation grammar (--ox-* tokens) on migrated ones (Lawyer Portal, PRO-3318). v3's scene/machined/theater grammar is NOT yet applied product-side — that's P3.

Rule for agents: editing an EXISTING product surface → match the code that's there. Building a NEW marketing/hero surface → use v3. Building any NEW surface at all → the colour law (Law 00) already binds, regardless of rollout phase.

Rollout order — GRAMMAR-v3 §Rollout

P1 · Done This design site (design.outlex.ai)

P2 · Next outlex-corporate-website homepage

P3 mvp2 product, light-first

P4 Marketing kit

Section 04

The six laws

Locked from mockup 6A, July 2026. The foundation layer defined the tokens; v3 defines the cinematography. Condensed here — full recipes in GRAMMAR-v3.md.

Law 00 Color Law (Schindler rule)

The scene is monochrome. Per viewport: 1 sage CTA + 1 sage phrase (7s ox-shine sweep) + life signals, stateful only. Gradient homes: mark, confidence ring, avatar placeholders — nowhere else.

Law 01 Scene staging

--ox-scene-bg deep slate radial — never #000. One --ox-scene-keylight top-center. ≤2 ambient tints (110px blur, 11s breathe, felt not seen). Grain 4%/3.5%. Sections divide by the horizon (1px + glow, 10s breathe).

Law 02 Machined controls

Primary = sage gradient + dark seat border + inset light/shade + letterpress. Hover: translateY(-2px) brightness(1.07). Press: translateY(1px) brightness(0.94), spring cubic-bezier(0.34,1.56,0.64,1) 180ms. Secondary = glass (dark) / white machined (light). Radius 11px in-flow, pills elsewhere.

Law 03 Pill nav

Floating glass bar — 4–5px padding, blur 14px. Active item = inner pill (--ox-nav-active-bg). Brand cluster: mark + capitalized Outlex wordmark, weight 600.

Law 04 Life signals

Teal pulse (AI working), typed verdict + caret, gradient confidence ring (r42/c264 dashoffset). A dead artifact is a brand violation.

AI working

Analyzing clause 4.2_

82% confidence

Law 05 Product theater

Screenshots never flat. Frame tilts 8° → 3° on hover (700ms), floor shadow, 12s specular sheen, alive on an 18s loop, rises through a horizon. A static screenshot is a brand violation.

Law 06 Both worlds

Dark = theater (marketing hero/bookends). Light = gallery (product default, warm cream, white machined, ink horizon). Sage CTA + life signals identical in both. Every pattern ships in both themes or it doesn't ship.

Don'ts — GRAMMAR-v3 §8

No colour-blob auroras, no gradient headlines, no gradient buttons.
No flat black backgrounds; no cold rgba(0,0,0) shadows on light.
No static product screenshots; no empty demo loops (panel blank >3s).
No second colour dose in one element (dot-chip label stays neutral).
No transition: all. No motion on ≥100×/day interactions.
aurora-field.js is a rejected device — do not port it into any repo.

Section 05

Color budget checklist

Run this before shipping any v3 surface. It's Law 00 operationalized — a viewport-scoped count, not a vibe check.

Sage CTAs in this viewport: exactly 1. The one machined primary button. Never two primary CTAs in view — a secondary action is glass or white-machined, not a second sage.

Sage phrases in this viewport: exactly 1. The italic display phrase with the 7s ox-shine sweep. One per page section, serif italic only.

Every gradient use is on the mark, the confidence ring, or an avatar placeholder — nowhere else. Not a headline, not a button, not a background.

Every coloured dot or pulse represents real state — AI working, status, confidence. Never decoration.

If the screen "feels dead" — fix light and motion, never add a colour.

Section 06

Hard rules

These predate v3 and still bind — none of them were superseded by the six laws above.

Hard Stop Mark / SVG container

SVG symbol container: width="0" height="0" style="position:absolute". NEVER display:none — it breaks gradient rendering in Safari/Firefox on #outlex-mark.

Hard Stop Lexi = the mark

Lexi's identity is the Outlex mark (#ic-lexi mono, #outlex-mark gradient for avatars). Sparkle icons are banned on every AI affordance — this holds unchanged in v3.

Hard Stop Teal is the only AI accent

Teal #54D6A4 (--ox-ai-accent / --ox-life-teal) is the ONLY AI accent colour. Amber is never AI background, label, or identity — amber is warning dots and deadline meta text only.

Hard Stop One accent per element

A coloured icon and a coloured label on the same element is a violation. Colour lives in the dot chip only — icon containers stay monochrome.

Hard Stop Typography weight

Newsreader (display, stand-in for Tiempos Headline): max weight 400. Inter: max weight 600. V7/legacy Fraunces: max 500. NEVER font-weight: 700 or font-bold on any heading, in the foundation grammar or v3.

Hard Stop 8px grid

NEVER gap-1 (4px). Minimum is gap-2 (8px) = --ox-space-2. No -5 utilities (20px) — use -6 (24px).

Hard Stop No pure black

NEVER text-black, bg-black, literal #000000/#FFFFFF. Always semantic --ox-* tokens. Scene bg is deep slate, never flat black.

Required OKLCH tokens only

Copy exact values from GRAMMAR.md / GRAMMAR-v3.md or the linked token files — never derive from taste or hardcode hex.

Required Motion budget + reduced motion

Foundation: enter 220ms / exit 130ms / press 80ms. v3 machined controls: spring 180ms cubic-bezier(0.34,1.56,0.64,1). Always respect prefers-reduced-motion.

Required Canonical keyframe names are API

ox-shine, ox-sheen, ox-ambient, ox-horizon, ox-teal-pulse, ox-caret, ox-breathe — never rename. Consumers reference these by name.

Section 07

Copy-paste snippets

Executable blocks. Values are copied verbatim from GRAMMAR-v3.md §9 — do not derive or modify.

1 — Token import (foundation first, v3 second)

<!-- v3 references the foundation's [data-theme] mechanism — load order matters -->
<link rel="stylesheet" href="https://design.outlex.ai/tokens-v2.css">
<link rel="stylesheet" href="https://design.outlex.ai/tokens-v3-gravity.css">

2 — Theme setup (shared ox-theme key, site-wide)

<html lang="en" data-theme="dark">

<script>
(function() {
  var saved = localStorage.getItem('ox-theme');
  var preferred = window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
  document.documentElement.setAttribute('data-theme', saved || preferred);
})();
</script>

3 — Machined primary CTA (Law 02 / GRAMMAR-v3 §9d)

.btn-primary {
  background: linear-gradient(180deg,#84AA8B 0%,#5E8065 55%,#527258 100%);
  border: 1px solid rgba(0,0,0,0.5);
  color: #F0EDE8;
  border-radius: 11px;
  text-shadow: 0 1px 1px rgba(0,0,0,0.32);
  box-shadow:
    inset 0 1px 0 rgba(255,255,255,0.42),
    inset 0 -2px 3px rgba(0,0,0,0.30),
    0 1px 1px rgba(0,0,0,0.5),
    0 12px 28px -8px rgba(95,130,102,0.55),
    0 28px 56px -16px rgba(0,0,0,0.7);
  transition:
    transform 180ms cubic-bezier(0.34,1.56,0.64,1),
    filter 180ms ease,
    box-shadow 180ms ease;
}
.btn-primary:hover { transform: translateY(-2px); filter: brightness(1.07); }
.btn-primary:active { transform: translateY(1px); filter: brightness(0.94); }
/* Never rgba(0,0,0) shadows on a LIGHT surface — swap for the light-theme
   --ox-btn-secondary-shadow token, which is warm-tinted. */

4 — Pill nav (Law 03 / GRAMMAR-v3 §9c)

.nav {
  padding: 4–5px;
  border-radius: var(--ox-nav-radius);       /* 9999px */
  background: var(--ox-nav-bg);
  backdrop-filter: blur(var(--ox-nav-blur)); /* 14px */
  border: 1px solid var(--ox-nav-border);
  box-shadow: inset 0 1px 0 rgba(255,255,255,0.08), 0 4px 14px rgba(0,0,0,0.35);
}
.nav__links a {
  padding: 7px 14–15px;
  border-radius: 9999px;
  font-size: 13px; font-weight: 500;
}
.nav__links a[aria-current="page"] {
  background: var(--ox-nav-active-bg);
  box-shadow: inset 0 1px 0 rgba(255,255,255,0.12);
}
/* Brand cluster left: mark 22–26px + wordmark "Outlex" weight 600. */

5 — Confidence ring (Law 04 / GRAMMAR-v3 §9e)

<svg viewBox="0 0 96 96">
  <!-- track -->
  <circle cx="48" cy="48" r="42" stroke="var(--ox-ring-track)" stroke-width="7" fill="none"/>
  <!-- fill: gradient #306AEF .35 → #54D6A4 1.0 -->
  <circle cx="48" cy="48" r="42"
    stroke="url(#oxg-ring)" stroke-width="7" fill="none"
    stroke-linecap="round" stroke-dasharray="264"
    stroke-dashoffset="{264 * (1 - pct)}"
    transform="rotate(-90 48 48)"/>
</svg>

6 — Grain overlay (Law 01 / GRAMMAR-v3 §9f)

/* feTurbulence type=fractalNoise baseFrequency=0.85 numOctaves=4 */
body::after {
  background-image: url("data:image/svg+xml,...opacity='0.04'...");
  position: fixed; inset: 0; pointer-events: none; z-index: 9999;
  mix-blend-mode: overlay;         /* dark — 4% */
}
[data-theme="light"] body::after {
  opacity: 0.875;                  /* 0.04 × 0.875 ≈ 0.035 */
  mix-blend-mode: multiply;        /* light — 3.5% */
}

Section 08

Issue template

Copy this block into Linear issues that touch UI, marketing surfaces, or product surfaces alike.

Ready-to-paste Linear issue block (Markdown)

## Design system context

**Read first (in order):**
1. `DESIGN_DIRECTION.md` in mvp2 root — migration state for the exact surface you're touching
2. https://design.outlex.ai/brand.md — foundation brand reference
3. Marketing/hero surface → https://design.outlex.ai/GRAMMAR-v3.md + https://design.outlex.ai/tokens-v3-gravity.css
4. Product in-app surface → https://design.outlex.ai/GRAMMAR.md + https://design.outlex.ai/tokens-v2.css
   (v3's colour law still applies to any NEW surface, even here)

**Color budget (Law 00) — run before shipping:**
- [ ] Exactly 1 sage CTA in this viewport
- [ ] Exactly 1 sage phrase in this viewport
- [ ] Gradient only on the mark / confidence ring / avatar placeholder
- [ ] Every coloured dot or pulse represents real state

**Hard-rule reminders (still binding):**
- SVG symbol container: `width="0" height="0" style="position:absolute"` — NEVER `display:none`
- Lexi = the mark (`#ic-lexi`). No sparkles on AI, ever
- Teal `#54D6A4` is the only AI accent — no amber fills on AI
- One accent per element — coloured icon + coloured label = violation
- 8px grid minimum — never `gap-1` (4px)
- No pure black, no cold `rgba(0,0,0)` shadows on a light surface
- Newsreader/display max weight 400, Inter max 600 — never 700/bold on headings
- No `transition: all`

**Acceptance criteria (add to this section):**
- [ ] Screenshots vs blueprint mockup attached to PR
- [ ] Token linter passes (0 hardcoded hex in changed files)
- [ ] Both themes verified (dark theater + light gallery)
- [ ] Reduced-motion tested

Section 09

Common mistakes

Carried-over foundation mistakes that still recur, plus the new ways to violate the six laws.

✗

Gradient on a headline or button

The blue→teal gradient is exclusive to the mark, the confidence ring, and avatar placeholders. A gradient hero headline or a gradient CTA is a Law 00 violation, no matter how good it looks in isolation.

✗

Two sage CTAs in one viewport

A primary + a secondary action both styled sage. Only one sage CTA per viewport — the other is glass (dark) or white-machined (light).

✗

Color-blob aurora as ambient background

aurora-field.js (cursor-reactive canvas) and CSS color-blob auroras were both explored and explicitly rejected. The canonical ambient device is the static blurred-tint pair (--ox-ambient-sage / --ox-ambient-blue) breathing at 11s.

✗

Static product screenshot, no life signal

Any product frame must be alive on an 18s loop — typed text with caret, a pulse, a ring fill, one toast. A flat `<img>` of a UI, or a panel blank >3s, is a brand violation under Law 05.

✗

transition: all anywhere

Always name the specific properties (transform, filter, box-shadow, border-color). transition: all is banned — it silently animates properties you didn't intend to (and tanks perf on layout-affecting props).

✗

Renaming a v3 keyframe

ox-shine, ox-sheen, ox-ambient, ox-horizon, ox-teal-pulse, ox-caret, ox-breathe are the canonical keyframe names — consumers reference them directly. Renaming one silently breaks every surface that uses it.

✗

Cold rgba(0,0,0,N) shadow on a light surface

Light-theme shadows must be warm-tinted (rgba(45,38,28,N) or the --ox-shadow-* / --ox-frame-shadow tokens). A raw black shadow reads as cold and breaks the "paper" feel of the gallery theme.

✗

Applying v3 scene/theater grammar to a product surface before P3

The product is still on V7 legacy or the foundation grammar. Don't wire --ox-scene-bg, machined controls, or product-theater framing into app.outlex.ai ahead of the P3 rollout — the colour law (Law 00) is the one v3 rule that already binds early.

✗

display:none on the SVG symbol container (carried from the foundation)

Any <use href="#outlex-mark"/> renders blank in Safari/Firefox if the container has display:none. Use width="0" height="0" style="position:absolute" exclusively.

✗

Amber as AI identity (carried from the foundation)

Amber styles AI cards, Lexi panels, or AI labels. Amber is exclusively warning dots and deadline meta text. Teal #54D6A4 is the only AI accent, in both the foundation and v3.

Design systemfor agents.