how to build from this

Compose from the parts. Never restyle one.

If a surface disagrees with the design system, the surface is the defect. That is the whole contract, and everything below is what it means in practice.

← the full reference

01 · what to reach for

The situation, and the part that answers it.

nine situations that cover most of a pageWhen none of these fits, the answer is almost never a new component. Check the roster in section 13 of the reference, then check shadcn, then ask whether the thing is a row.
when	use	never
A call to action, anywhere, on any ground	Button, with ground="dark" over ink. size="nav" only in the header.	An anchor styled to look like a button. The fill, the height and the radius are all tokens and they will drift within a week.
A list of things a reader gets, or a list of pains they have	CheckList. Default mark for what they get, mark="cross" for what they suffer.	A bulleted <ul>. The mark, its colour and its baseline offset are the system speaking.
A section opening	SectionHeader. It carries the eyebrow, the heading, the side note and the one gap between them.	A hand-built h2 with a span above it. The 20px eyebrow gap is invariant and this is where it lives.
The email ask, at the end of any page	GraderField. Every page ends with this and there is no second conversion device.	A bespoke input and button pair. The 56px shell with the 8px inner button is the only nested radius in the system.
Somewhere a photograph will eventually go	ImageSlot with a placeholder string that names the shot.	A grey div, and never a stock image as a stand-in. A stand-in that looks finished ships.
Eight services, five steps, twelve locations, or anything else that repeats	Hairline rows. The moment a pattern repeats, the box comes off.	A grid of identical cards. Identical items in identical boxes is agency-template grammar and it is the single most visible tell.
One thing standing alone: a featured case, the terms card, the best-value tier	A container. This is the case a card is for.	A container around each of a set. See the row above.
A question and its answer	FAQItem. Native details, which is deliberate and documented.	A shadcn accordion here. This is the one place the platform primitive wins, and it is written down so nobody reverses it.
Anything stateful or interactive not already listed	shadcn, themed with the v2 tokens (D-24).	A new hand-rolled control. Ever. That is the rule that closed the "broken components all over the site" defect.

02 · section order

Order is a conversion decision, never an SEO one.

knowledge/rules-library/marketing-page-section-order.md. BINDING, signed jointly by Ratatoskr and Sindri, 2026-07-30.

the six rules

Order by importance to the reader, never by internal company logic

Anything load-bearing sits in the first 40 to 50 percent, and repeats once lower

Split proof across the page, next to the claim it backs. Never cluster it into one Results section

Show a price signal rather than hiding it

Length comes from real topical coverage, never from section count

Question-shaped headings distributed mid-page are a logged bet, not an established practice. Cite them as one

why it is worth reading the file

Only one of those six is backed by a controlled test: splitting proof around a decision point rather than bunching it, which produced a 64.5 percent lift in the Aagaard test reported by CXL. The rest are directional. The rule file is explicit about which is which, and it bans the percentage statistics that circulate alongside this topic, because every one of them is extrapolated from studies of different page types. If you find yourself about to write “put proof in section 3 for SEO”, that sentence is unsupported.

One hard consequence for layout: one dark CTA moment maximum between the hero and the close, and every page ends with the grader ask.

03 · the eyebrow pattern

Two elements. Only two. Never three.

knowledge/rules-library/eyebrow-heading-pattern.md v2.0. BINDING org-wide. It shipped backwards once, which is why the correct and backwards forms are both printed below.

correct

<h2 class="eyebrow">BEST SEO COMPANY LAS VEGAS</h2>
<p class="section-statement">Reviews</p>

The eyebrow carries the keyword string itself, verbatim, and it is for Google. The statement is the literal section name, it is the big visual line, and it is for the human. One heading element per section, eyebrow first in the DOM, and the statement is never a heading element.

backwards · what shipped once

<h2 class="eyebrow">Reviews</h2>
<p class="section-statement">What clients say.</p>

<!-- ...with the keyword sitting in an Airtable field
     that renders nowhere on the page. -->

A keyword in a database field that never renders is not an optimisation, it is a record of an intention. On /services/seo/, five of seven H2s carried an assigned keyword that was absent from the heading string.

Statements say what the section is: Reviews, Results, Pricing, How It Works, Common Questions. The brand line is retired. Where a possessive applies it is first person singular, My Results and My Work, never Our, because this is one person and the copy says so (D-07).

One honest exception, named rather than hidden. The eyebrows on the reference page itself carry section names, not keywords, because that surface has no keyword target and is noindex. The rule governs marketing pages. Do not read the doc surface as a licence to drop the keyword on a page that has one.

04 · band rhythm

Grounds and air, never a rule across the page.

the rhythm

Sections meet as a change of ground, #F5F5F5 to #FFFFFF to dark, or as 150px of air. There are no full-width rules at section edges and no tinted divider bands. Hairlines live inside sections: on rows, on tables, on terms strips. Display moments run 160px, and both step down under 760px through the tokens rather than through a component breakpoint.

the dark ground is a moment

Dark is reserved. One dark CTA moment between the hero and the close, and that is the budget. Grain sits over an ink ground and never over paper. Two shadows exist in the whole system, the lifted grader field and the featured price card, and a third is a defect rather than a variation.

Before you start: read the recipe for your page type in section 14 of the reference. Thirteen archetypes cover all 190 routesWhile you build: no invented statistics. A figure with no source is a TK marker, not a numberBefore you claim done: npm run build green, which runs preflight, the Next build and the rendered redline check. An em dash in body copy fails the build

← the full reference