Skip to content

Source: design-system/affiliate-review-site/pages/README.md. Edit it there; this page is generated at build time.

Per-page design overrides ​

../MASTER.md is the design system for the whole public site. This folder is the escape hatch: a file here overrides the Master file for one page type only.

The mechanism is real, but it is deliberately empty right now — every public page follows MASTER.md unmodified. This README exists so the folder survives a clone (Git does not store empty directories) and so the next person can see the convention without guessing at it.

The convention ​

One file per page type, named after the page, lowercase and hyphenated:

design-system/affiliate-review-site/pages/
├── README.md          ← this file, not an override
├── review.md
├── comparison.md
├── listicle.md
├── article.md
└── home.md

Rules:

  • Override, don't restate. A page file lists only the rules that differ. Anything it is silent about still comes from MASTER.md — so copying the whole Master file and editing two lines is the wrong shape, because the other 250 lines then drift silently.
  • Say why. An override is a documented exception to the design system. Without the reason it reads as an inconsistency and someone eventually "fixes" it back.
  • Tokens stay tokens. An override may change which token a page uses. It may not introduce a raw hex value or a dark: variant in Blade — that constraint is in the Master file's pre-delivery checklist and is not overridable, because it is what keeps dark mode working.

Worked example ​

pages/listicle.md, if the "best of" pages ever needed to diverge:

markdown
# Listicle — page overrides

Overrides `../MASTER.md` for listicle (“best X”) pages only. Everything not listed here
still comes from the Master file.

## CTA Placement

**Master:** Hero (sticky) + Bottom
**Here:** one CTA cluster per entry, none sticky.

Why: a listicle has one buy button per entry, and FTC 16 CFR §465.1(c)(4) requires the
disclosure to be visible in the same viewport as the link it covers. A sticky CTA can
scroll away from its disclosure, which a per-entry cluster cannot. See
`docs/adr/0005-per-cluster-affiliate-disclosure.md`.

## Section Order

**Master:** Hero with headline/image > Value prop > Key features (3-5) > CTA section > Footer
**Here:** Hero > How we picked > Ranked entries > Buying advice > Footer.

Why: `how_we_picked` is one of Google's 14 review-quality criteria and belongs above the
ranking it explains. Monetised clusters stop at the “Buying advice” heading — the
educational back half of the page carries no buy buttons.

Note that both overrides above cite the reason and the record that establishes it, and neither repeats a colour, a type scale or a component spec.