The design system, locked.

This page is the single source of truth for the design and brand system of citelight.ai as shipped in this version. It is written for whoever touches the site next: designer, engineer, or Andy in six months. Everything here was extracted from the live build, not reconstructed from memory. The :root token block in this page’s own stylesheet is copied verbatim from index.html at build time, and every swatch and specimen below renders from those variables. If this page looks wrong, the system has drifted; fix the drift, then rebuild this page.

“Locked” means: these decisions were made deliberately, tested at both breakpoints, and survived review. Changing a locked value is allowed, but it is a design decision with site-wide consequences, not a tweak. Section 13 defines what is open.

Premise. Citelight measures whether AI platforms (ChatGPT, Perplexity, Gemini, AI Overview: always these four, always this order) cite a real estate agent when buyers and sellers ask who to work with. The product’s emotional engine is exclusion and its resolution: the agent discovers they are absent from answers their competitors live in, then watches the light move to them.

The metaphor is citation-light. Gold is not decoration; it is the light of being cited. This single rule governs every use of aurum on the site: a gold element must represent citation, presence, or the action that earns them. A gold divider for taste is a violation.

Two registers, one world. The paper world (bone grounds, ink text) is where the agent reads, decides, buys. The vessel (the dark gradient) is inside the machine: streamed answers, audits, the takeover. Paper is calm and editorial; the vessel is where things happen to you. Crossing between them is an event, never a casual background change.

Lexicon. Speak the system’s language in code and conversation: bone (paper grounds), ink (text on paper), aurum (citation gold), void (vessel palette), vessel (the dark surface itself), pmark (platform mark), absence salmon (the not-cited tone), the ledger and the search (the mobile audit mechanics).

Copy is part of the design system and carries hard rules. These apply to UI text, marketing copy, study pages, emails, and code comments alike.

Casing. Spaced-caps registers (eyebrows, marquee, mono labels) use text-transform:uppercase, except where a brand’s casing is its identity: eXp is exempted via .brokq__item--case. Never re-case a brand name.

One family speaks for the brand: Söhne (Klim Type Foundry), with Söhne Mono as the machine’s voice. Sans carries reading and display; Mono is reserved for genuine data registers: labels, timestamps, counts, queries, machine output. Mono used decoratively is a violation.

Four families and one rule of scarcity: the page is bone and ink; aurum appears only as citation-light; the vessel is its own world with its own foreground ramp. Platform tints exist solely to identify the four platforms in data marks.

Absence has a color: salmon, used only for the not-cited state. Text rgba(222,138,107,.95), borders rgba(222,138,107,.3). It exists in the vessel only.

Bands. Sections are .band blocks with vertical rhythm --band-y: clamp(88px,12vh,164px). Grounds change by band class; content is centered by .band__in (max-width --max, inline padding --gut).

Paper surfaces. Cards use the fill-delta recipe: interior panels are one bone step away from their parent, hairline --line, and at most two shadow layers (a 1px contact shadow plus one long soft drop). No third material inside a card.

The vessel. linear-gradient(rgb(28,23,16), rgb(20,16,9)). Inside it, hairlines are --void-line (aurum at 13%), never grey; text uses the void-fg ramp; raised elements use --void-2.

Two curves, one duration scale, and a doctrine: motion is diegetic. Every animation depicts something the interface is actually doing (extracting a name, searching text, filling a segment of elapsed time). Motion that only decorates is removed.

Arrival grammar. Entrances use .rv: opacity 0 and 12px rise, .6s on the house curve, staggered by --beat via .rv-2 etc. Arrival is a one-time event with memory; scroll does not scrub it backwards. High-frequency interactions animate at --d-micro/--d-state or not at all.

Counters roll only when something is decided. A count changes at the moment a conclusion lands (a platform finishes, a chip arrives), rendered as a masked digit swap. Ambient counting is banned.

Platform marks. Official monochrome marks (OpenAI, Perplexity, Gemini, Google) inlined as .pmark SVGs on currentColor. On paper they run ink-toned and muted; in data contexts they take their platform tint via color:rgb(var(--t-*)). Full-color logo walls are banned: muted marks read as confidence, color reads as a sponsor wall and implies endorsement.

The brokerage wall. Nine official monochrome marks, one ink. The standing ruling holds and is unchanged: official assets or deliberate typographic voice, never in-between, and never a redrawn wordmark. The ruling never banned logos - it gated them on completeness, and the gate is now met, so the wall converted. Every mark is knocked out of its official file and tinted to a single baked ink (#57514A, measured 6.04:1 in situ against the band). Ink is baked rather than applied as CSS opacity, because opacity over the mark lightens the effective colour and invalidates the measurement. Corcoran is the one name held back: the supplied file is a crop with the outer letterforms amputated at the canvas edge, and a shaved wordmark is not an official asset. It returns to the wall when a clean file exists. wall-scan in the decay gate now enforces the ruling: a wall that mixes marks with typographic brand names closes the gate, as does a mark whose file is missing from the deploy. The italic closer is exempt - it is a phrase, not a brand.

Every named component, its purpose, and its laws. File references are the component’s home; shared pieces live in index.html unless noted.

Until the real audit engine ships, every surface draws from one fictional market so a visitor who reads everything finds a single consistent world. All of it is marked ILLUSTRATION.

Locked: tokens, type system and license scope, the two registers, motion doctrine and RM contracts, language laws, the data canon, component laws above.

Open: new sections and surfaces, the desktop switchboard build, copy refinement inside the laws, roster curation, real-API data replacing the canon.

The extension bar. A new surface earns its place with one structural idea that only it uses. If a proposed section could be described as two-column copy/image, centered hero, or a rounded rectangle grid sharing one rhythm, it does not ship; it gets a concept. “Feels generic” from Andy triggers a full concept rebuild, never a patch.

Ship gates: check-studies.mjs exits 0; em-dash grep is clean; both breakpoints captured and reviewed; overflow 0; zero console errors; processor-scan passes, meaning every external host in shipped code is named in the privacy policy; deploy via vercel --prod from ~/citelight-deploy/ with hash verification.