Website Design System

Composition — surfaces, seams and spines

Which sections exist, what surface each paints, and what each owes its neighbours. This is the section that would have caught the use-case overlap: the trust card declared a straddle, the band below it declared it could receive one, and nothing checked that the numbers agreed. Everything here is rendered from src/util/section-contract.ts and page-spines.ts, and the edge verdicts are probed against the shipped stylesheet on mount — so a wrong declaration shows up as a MISMATCH rather than as a wrong page.

The seams, rendered

Real components, real class names, real CSS, at real viewport width, in the adjacent PAIRS the contract governs. A seam is a relationship between two sections, so a specimen of one section on its own cannot show whether the seam works — which is exactly how the use-case overlap shipped past a design-system page that already had specimens on it. Media queries read the window, not these stages: to QA the mobile straddle use responsive mode at 375px and at 1024px.

R1 · straddles → bandclients → firstEvidence

The join that broke. The trust card is displaced past its own bottom edge and the band underneath has to clear it. On desktop the displacement is half the card's own height, applied as a transform, which layout cannot see. Below 1024px the straddle is dropped entirely, because the card measures 217–285px across the four pages and no single clearance serves a 68px spread. Check the heading below the card is never touched.

Trusted by teams measuring immersive work at scale

Specimen copy. This line is one of the three things the original overhang estimate forgot, and it is worth about 67px on a phone.

Adding Cognitive3D to an existing build

Engines and devices

Specimen fact with a figure: 40+

Specimen fact, second row

Specimen fact, third row

Getting data out

Specimen fact, first row

Specimen fact, second row

Specimen fact, third row

Governance

Specimen fact, first row

Specimen fact, second row

Specimen fact, third row

Specimen primaryGet a Demo

R1 · straddles → bandtestimonial → workedExample

The same rule, the other straddle. This one displaces by a fixed -240px section margin below 1024px rather than a transform, which is why it is height-independent and has held: clearance is 330 − 240 = 90px whatever the quote length. It is the mechanic to copy. Note the card must float ON TOP of the band (z-index 16 against 2) while the section beneath stays under it — that has broken twice.

Specimen quote. Length matters here, because on desktop the overhang is half of whatever height this card ends up being.

Specimen Name

SPECIMEN TITLE

One session, end to end

Specimen intro line. The four steps are the pillar names in order, and the rail runs their colours.

1. 1

   Tracked. Specimen step copy.

2. 2

   Explored. Specimen step copy.

3. 3

   Analyzed. Specimen step copy.

4. 4

   Reported. Specimen step copy.

The contract, and its audit

Use-case spine — all four pages run this order

Drawn from USE_CASE_SPINE in page-spines.ts, so it cannot disagree with what tsc checks. Reorder the spine and this diagram moves with it.

1. 1useCaseHerohero
   plain join
2. 2outcomeswhite
   plain join
3. 3mapExperiencedarkflat
   featureSection tucks under mapExperience — R2
4. 4featureSectionwash
   plain join
5. 5clientswash
   straddles into firstEvidence — R1
6. 6firstEvidenceband
   featureSection tucks under firstEvidence — R2
7. 7featureSectionwash
   plain join
8. 8testimonialwash
   straddles into workedExample — R1
9. 9workedExampleband
   featureSection tucks under workedExample — R2
10. 10featureSectionwash
    plain join
11. 11testimonialwash
    straddles into ctaBandClosing — R1
12. 12ctaBandClosingband

Every seam in that spine

About spine — /about/

Drawn from ABOUT_SPINE in page-spines.ts, so it cannot disagree with what tsc checks. Reorder the spine and this diagram moves with it.

1. 1aboutHerohero
   aboutOrigin tucks under aboutHero — R2
2. 2aboutOriginwash
   plain join
3. 3aboutTodaywash
   plain join
4. 4aboutBrandswash
   plain join
5. 5aboutHowWeWorkwash
   plain join
6. 6aboutFounderwash
   plain join
7. 7aboutTeamwash
   plain join
8. 8aboutUseCaseswash
   plain join
9. 9testimonialwash
   straddles into aboutTrustData — R1
10. 10aboutTrustDataband
    aboutBacked tucks under aboutTrustData — R2
11. 11aboutBackedwash
    aboutClose covers its own clipped top — no rule
12. 12aboutCloseband

Every seam in that spine

Attaching a page to this system

Pages join one at a time, each on its own branch. This is the order that works — steps 1 and 2 are where every past mistake happened.

1. Inherit, never copy. Give the wrapper both classes: bodyWrapperClass="frontpage <pagename>". Every rule in _front-page.scss is a descendant selector, so the page picks up the whole system for free. Hand-copying those rules into a page partial produced ~860 lines that had to be deleted again.
2. Delete the page's old hero and section CSS before writing new. Leftover rules out-specify the inherited ones and you'll spend a day chasing why a wash won't apply.
3. Write the new partial against tokens, not literals — var(--c3d-purple-wash), not #ede6f8. A page joining the system gets this for free; there is no separate migration step.
4. Wire the reveal hook — usePageReveal with the page's selectors and bodyClass: 'fp-enhanced', plus the fp-scrolled toggle. Copy from track.tsx.
5. Pick the pillar and use it everywhere — hero spotlight, CTA glows, section washes, card accents. A mismatched CTA glow is the most common drift.
6. Mark the last CTA home-cta-section--straight-bottom so it runs flat into whatever follows.
7. Check desktop and mobile before calling it done. The curve values differ across the ≤1024px boundary and the two mechanisms are independent — see Curves.

Pages that predate the tokens — homepage, the three pillars, pricing, the demo funnel — still carry literals. That is deliberate. They get migrated when next touched for another reason, never as a bulk sweep; there is no upside to editing an approved page just to move where its numbers come from.

What's global vs what's opt-in

The single most confusing thing about this system: some of the July-2026 tightening was pushed into the shared base and applies to EVERY page including ones nobody has touched. The rest only arrives when a page opts in. Knowing which is which saves an afternoon.

So an untouched page has the new type and chrome but the old spacing and structure. That mismatch is expected mid-rollout — it is not a bug to chase. When you bring a page onto the system, the spacing arrives with the frontpage class; you do not hand-set margins to imitate it.

Pillar colour map

Every hero spotlight, CTA glow and section wash must match its page's pillar. Mixing them is the most common drift.

Core colours

The dark-mode ladder from nav to footer. The footer tone doubles as the seam target — a CTA fading to anything else shows a visible line.

Type scale

Onest throughout. The two numbers are a fluid floor and ceiling via the fluid-type mixin, not breakpoint steps.

Layout & breakpoints

The curve system

Read this before changing any curve. Heroes and CTA bands use different mechanisms, so changing one does nothing to the other — and they must be matched in pixels of sag, not percentages.

Desktop hero and band are deliberately not matched — the deep dome is the approved look there. On mobile they are matched to ~11px, which is why the mobile control point is 93 and not 98. The mobile menu keeps its own 320% and is not part of this group.

Constellation field

The spatial data-field canvas behind every hero and CTA band. Four tints, live below — the tint must match its section's pillar or the band reads as the wrong colour.

Z-index ladder

Measured from the live homepage. This is invisible until it breaks, and it broke twice — the testimonial card must float on top of the band it straddles, and the tucked section must stay beneath.

Vertical rhythm & overlaps

Measured on the live homepage at 1535px. The negative margins are load-bearing — they pull a section under the masked arc above it so the transparent part of that arc reveals a pillar wash instead of white.

The testimonial straddle is expressed as 50% of the card's own height, never a pixel value — the card's height changes with quote length, and a fixed offset stops landing on the band's flat top.

Texture & effects

The small things that make the dark surfaces read as lit volumes rather than flat fills.

Demo funnel — a separate system

/demo, /demo/calendar and /demo/confirm use .demo-dark, not .frontpage. Values measured live. The legacy .demo-hero block must stay: seven call/* pages depend on it.

The card background is plain white — no gradient. A faint wash on the card was tried and rejected; only the fields carry any tint.

Buttons

Shine sweep plus a 2px lift. No hover glows anywhere — that was removed deliberately. Hover each specimen to check the sweep direction and that nothing flips to a dark fill.

Content components

Section headers and statistics, live, in all three pillar themes. Kicker icons are hidden under .frontpage on purpose.

Surfaces & cards

The card family. Note that the recommended pricing card's rim and glow are two separate elements — a single masked element cannot do both without a visible wash.

CTA bands

The real component, all three pillars plus the straight-bottom variant. These are tall, so they are collapsed by default. Each carries the band mask on three layers and the constellation canvas at 0.55 opacity.

Forms

Live FormRow in every input type. The demo form is placeholder-only by design — labels plus placeholders made it too tall and cluttered. Field order on the live form must not change.

Motion

All motion is subtle and slow. Every effect below is wrapped in prefers-reduced-motion on the live site — if you have reduced motion enabled, these will be still, which is correct.

Anti-patterns

Each of these was shipped once and had to be undone. They are settled — don't reintroduce them.

• No hover glows on CTA buttons. Shine sweep and a 2px lift only. Removed with !important; re-adding a box-shadow reverses a deliberate decision.
• Constellation opacity is 0.55. Not 0.42 — that was an early iteration.
• Never hand-copy .frontpage rules into a page partial. Add the frontpage class to the wrapper and inherit. Hand-copying produced ~860 lines that had to be deleted again.
• No inline style backgrounds on testimonials or heroes — they beat every stylesheet rule and break the wash.
• Avoid z-index: -1 for glows. It paints above the parent's background when the parent is a stacking context, and below in-flow ancestor backgrounds otherwise. Use box-shadow.
• mask-composite: exclude only cancels at alpha 0 or 1. Two partial alphas leave a visible wash. Split into two elements.
• Match arcs in pixels, not percentages. Equal percentages leave the shorter element visibly flatter, because sag scales with element height.
• Invalid CSS values fail silently. justify-content: justify-between did nothing for a while — check computed styles, not the source.