Page building system

The reusable parts every EcomOptix page is assembled from, rendered with the same stylesheet the real pages load. Open this before building a page, copy the pattern you need, and change the words — not the design. For logo, voice and identity rules, see the brand guidelines doc.

01 · Start here

Build it the boring way

Hand-rolling a page from scratch is how the design drifts and how honest numbers turn into claims nobody can defend. Three rules cover almost every build.

✓Edit the source, run the builder. Change home.src.html, a file in services/<slug>.json, or shared.css, then run python3 build.py. The builder refuses to write a page with an unfilled token, so half-finished pages can’t ship.
✓Take components from this page. Everything below is live markup with the real classes. Copy it, swap the words.
✓Change design in one place. A new colour or spacing value goes in shared.css as a token, never inline on a section.
✕Don’t invent a new section type because the content doesn’t fit. Either the content is wrong for the page, or the new pattern belongs in here first so every page gets it.
One source of truth: this page links shared.css directly. If a component here looks wrong, the stylesheet is wrong — fix it there and every page follows.
02 · Tokens

Colour

Every swatch below is drawn with var(--token) straight from shared.css. If you change a token, this page changes with it — it cannot drift.

Locked 22 Nov 2026. An audit of /ecommerce-seo/ found 16 greens, 7 light surfaces, 3 inks and 2 golds rendering on one page. The list below is now the whole palette. A colour that is not a token here does not ship.

Green — two, not sixteen

On light--g-core · #2a8019Headline highlights, labels, links. The ONLY green on a light surface.
On dark--g · #7fff6bDark-section accents, chips, button fills and the hard shadow.

Why #2a8019 and not #2f8f1c. #2f8f1c reaches only 4.14:1 on white — fine for a 70px headline (needs 3:1), a fail for a 13px label (needs 4.5:1). #2a8019 is the same hue (110°) and saturation, darkened until it clears AA everywhere: 5.00:1 on white, 4.72:1 on warm, 4.53:1 on mist. At display size the two are indistinguishable. --g-deep is retired and now aliases --g-core.

Proof accent — stars only

Rating gold--gold · #e9a000Review stars and nothing else. Never a heading, button, border or icon.

Light surfaces — three

Warm (default)--warm · #faf8f5The default section background.
Mist (alternate)--mist · #f2f4f6The light section that follows another light section.
White--white · #fffCards and panels sitting on warm or mist.
Pale green--pale · #eaf7e4A tint for chips and quote blocks. Never a section background.

--cream (#f5f2ec) is retired and now aliases --warm. It was the fifth off-white on the page and nobody could tell it from the other four.

Dark surfaces

Ink--ink · #080b0fDark sections, primary button fill, and all text on light.
Slate--slate · #0d1117The second dark tone, for a panel inside an ink section.
Dark card--card-d · #111820Cards on an ink background.
Dark border--bd-d · #1a2a3aHairlines on dark.

Text

Heading & body on light--t · #080b0fOne ink. Was split across #0c1116, #080b0f and #101318.
Long copy on light--t-body · #3d4852
Muted on light--t-mute · #5a6672Captions and sources.
Body on dark--t-d · #b8c8d4Never go darker than this on ink.
Muted on dark--t-mute-d · #8595a3Captions and sources only.

The two-tone headline

Ink carries the setup, green lands the payoff. It is the one piece of brand expression in the type system, so it has rules.

Great products that the
right shoppers never find.

Rule Why
Green goes on the shorter half — at most ~40% of the headline Colour is emphasis. When two-thirds of the words are green, the ink line reads as a leftover.
Green lands on the payoff, never the setup The eye finishes on the coloured phrase. Put the thing you want remembered there.
Exactly one colour break per headline Two breaks turn a headline into a list.
Use <span class="g"> — never an inline colour It binds to --g-core, so it follows the token.
Label above and highlight below are the same green Two near-identical greens 20px apart read as a bug, not a system.

What the hero does today./ecommerce-seo/ puts 34 of 49 characters in green across two of three lines, and the kicker above it is a different green (#2f6f1b against #2f8f1c). Both are fixed by the rules above.

Shape

Two radii and one shadow. The audit found 14 radius values and 7 shadow recipes on a single page — including two different greens for the same hard shadow at two different offsets.

Token Value Use it for
--r 18px Cards, panels, media, dark CTA blocks
--r-s 14px Number chips, tags, inputs, images inside a card
--r-pill 999px Buttons and badges — the only other radius
--sh 7px 7px 0 var(–g) The signature hard shadow. One offset, one green.
--sh-soft 0 8px 24px rgba(24,40,18,.06) The only soft elevation on a light surface

A circle (50%) is allowed for avatars, play buttons and icon dots. Nothing else may invent a radius. On hover the primary button lifts 2px and the shadow grows to calc(var(--off) + 2px) — that is the token, not a new value.

Type

Two faces only. Barlow Condensed 900 all-caps for display, 800 for labels and buttons; Barlow 400 for everything you read. Body never drops below 17px and never uses weight 300.

Loaded weights: Barlow 400 / 500 / 600 / 700, Barlow Condensed 600 / 700 / 800 / 900. Do not write a weight outside that list — the browser will synthesise it and the headline goes soft.

Role Class 390px 1440px Weight Tracking Case
Hero kicker .hero h1 .kick 13–14px 15.8px 600 +1.3 to 2px Upper
Hero headline .hv-a / .hv-b 42px 70.6px 900 −1.2px Upper
Section heading .h2 32px 48px 900 −0.5px Upper
Card / sub heading .h3 19px 21.6px 900 +0.8px Upper
Section label .eyebrow / .lbl 13px 13.5px 800 ← open +2.4px Upper
Lede .lede 17px 18px 400 +0.1px Sentence
Body — 17px 17px 400 +0.1px Sentence
Button .btn-p / .btn-g 16px 19px 900 +0.8px Upper

These are measured, not intended. Every row above was read off the rendered /ecommerce-seo/ page at 390px and 1440px on 22 Nov 2026. Earlier versions of this table listed the sizes that were written — those rules lose the cascade and never reach the screen.

Only the headline is allowed maximum weight. The hero kicker ran at 900 — the same weight as the 70px headline below it — so it read as a small second headline competing with the real one rather than as a label. It is now 600 on the homepage and in shared.css (22 Nov 2026). On phones it also tightens to 13px / +1.3px tracking so the line does not wrap; that narrowing is deliberate, not drift.

Measure at an explicit width. Every size here is labelled 390px or 1440px because a computed value carries no hint of which media query produced it. Reading styles at whatever width a panel happens to be is how the kicker was first mis-recorded as 12px when it is 15.8px on desktop.

Why the scale drifts. The live service page carries 26 <style> blocks in the body on top of 15 in the head, because each past fix appended another block instead of editing the first. The hero headline now has ten competing font-size rules, six of them with no media query; the section heading has seven. The last one written wins, so the scale changes whenever anyone adds a block. Fix type by editing shared.css, never by appending a new style block.

Spacing & layout

Token Value Used for
--wrap 1240px Max content width on every section
--gut clamp(16px, 5vw, 48px) Side padding. Never let content touch the edge.
--sec clamp(72px, 9vw, 128px) Vertical padding on .sec
--r 18px Card radius. Buttons are full pills (999px).
--off 7px Hard offset shadow on bordered cards
Breakpoints: under 600px single column · 600–960px two columns · 960px+ full layout. Check every page at 390px and 1440px before it ships.
03 · Rhythm

Alternate light and dark on purpose

Roughly 40% of a page is dark. Light sections carry copy and proof; dark sections carry impact and the asks. Two darks never touch — put slate between them, or a light section. The pale-green band appears once, for the single biggest idea.

Header
ink
Hero
cream
Proof
white
Problem
cream
Levers
slate
Stories
mist
Statement
pale
Fit
warm
Final CTA
ink
✓Surface classes:.sec alone is white. Add .paper (cream + dot grid), .warm, .mist, .slate, .dark, or .band.
✕Don’t put two of the same surface in a row. If the content needs it, the two sections are really one section.
04 · Section library

The parts

Each block below is rendered with the live stylesheet. Copy the markup, replace the words, keep the classes.

Section shell

The wrapper every section starts from. .sec + surface + .wrap.

Section label

A heading that makes the point, with one phrase highlighted.

One or two sentences of context. Keep the line length short enough to read without effort.

<section class="sec paper"> <div class="wrap"> <span class="lbl">Section label</span> <h2 class="h2">A heading that makes the point, with <span class="g">one phrase highlighted.</span></h2> <p class="lede">One or two sentences of context.</p> </div> </section>

Buttons

Pills, always. .btn-p is the one real action on the screen; .btn-g is the quiet alternative.

<a class="btn btn-p" href="#offer">Get my free growth analysis</a> <a class="btn btn-g" href="#results">See client results</a>
Height Size / weight Radius Fill Shadow
.btn-p 60px 19px / 900 upper --r-pill --ink, white text --sh
.btn-g 60px 19px / 900 upper --r-pill transparent, 2px --ink none

One button, one size. The audit found 8 CTAs on /ecommerce-seo/ wearing 5 different looks — four heights (54 / 56 / 57 / 58px), three font sizes (14 / 17 / 19px), two shadow offsets (5px and 7px) and two radii. Two of them carried the class .btn-p and looked nothing alike: one was a black pill with a green hard shadow, the other a green 10px-radius block with no shadow. Never restyle a button inline or in a page-level block — if it needs to look different, it is a different component and belongs in shared.css.

Proof figure

A client number with its dashboard, dates and source. Never a number on its own.

Glass Railing Store · Canada + US · Shopify

$362,763
Total store sales, 19 May – 18 Jun 2026

When we started, the site had no SEO and almost no search traffic.

Source: the store’s own Shopify Analytics

<article class="card"> <span class="lbl">Client · market · platform</span> <div class="pw-big">$362,763</div> <div class="pw-lab">Total store sales, 19 May – 18 Jun 2026</div> <p>What the situation was and what we changed.</p> <p class="small pw-src">Source: the store's own Shopify Analytics</p> </article>

Problem list

Short, concrete, in the buyer’s words. Lead each line with the bold claim.

  • You pay more for the same customer every quarter. You raised spend just to stand still.
  • The ads dashboard says it’s working. Your margin and your bank balance don’t agree.
  • You rank for your own brand name and almost nothing a new customer would type.

<ul class="pains"> <li><span><b>The bold claim.</b> The sentence that lands it.</span></li> </ul>

Statement band

One big idea, once per page, on pale green. No button, no list.

AI does the analysis and the volume. People own the strategy and the judgement calls.It’s how a focused team moves faster than a traditional agency, without handing your store to a bot.

<section class="sec band" aria-label="How we use AI"> <div class="wrap"><p>The one big idea.<small>The line that explains it.</small></p></div> </section>

FAQ

Real objections only — cost, timeline, who does the work, where the team is. First one open.

How much does it cost?

The teardown comes first, so you can weigh the spend against the opportunity we actually found in your store, not against a guess.

How long until I see results?

Technical and conversion fixes can move numbers early because they work on traffic you already have. Commercial change usually shows between months three and six.

<div class="faq"> <details open><summary>The question in their words?</summary> <p>A straight answer.</p></details> <details><summary>Next question?</summary><p>…</p></details> </div>

Final CTA

Dark. One action, with the reassurance lines directly beneath it.

Free growth analysis

Your next sales channel probably already exists. Let’s find it.

We look at your real store and your real competitors, then tell you what we’d fix first.

Get my free growth analysis

Free, no card · Reviewed by a person · Yours to keep

<section class="sec dark paper" id="cta"> <div class="wrap center"> <span class="lbl">Free growth analysis</span> <h2 class="h2">The promise. <span class="g">The payoff.</span></h2> <p class="lede">What actually happens next.</p> <a class="btn btn-p" href="#offer">Get my free growth analysis</a> <p class="small">Free, no card · Reviewed by a person · Yours to keep</p> </div> </section>
05 · Page recipes

Approved section orders

These orders are settled. Build to them unless there’s a reason to change, and change the recipe here first so the next page inherits it.

Homepage

Proof sits directly under the hero — most visitors never scroll far.

  1. Hero — two-tone headline, proof wallcream
  2. Proof — three client monthswhite
  3. If your ads stopped + calculatorcream
  4. Five leversslate
  5. First 90 dayswhite
  6. Clients on cameramist
  7. Reviewswhite
  8. No-guarantees ledgerwhite
  9. AI statementband
  10. Free analysis + formcream
  11. Fit / not a fitwhite
  12. FAQwarm
  13. SEO paragraphwhite
  14. Final CTAink

Service page

Built from services/<slug>.json. Optional blocks drop out when the data isn’t there, so a page without a real case study can’t invent one.

  1. Hero + breadcrumbcream
  2. What’s actually wrongwhite
  3. What we dowhite
  4. Case studyoptional
  5. Us vs themoptional
  6. Clients on cameraoptional
  7. FAQwarm
  8. Related servicesoptional
  9. Final CTAink

Paid-ads funnel

One action only. No menu, no footer links, noindex. Booking sits high, not at the bottom.

  1. Hero — offer + proofink
  2. Proof barslate
  3. What’s in the reportcream
  4. Book — calendar full widthink
  5. Case studieswhite
  6. Clients on cameraink
  7. Why uscream
  8. Fit / not a fitcream
  9. FAQwhite
  10. Final CTAink
Calendar sections: the GHL booking widget only uses its compact two-pane layout at 1000px or wider. Give it the full content width, never a narrow column, or it stacks and towers over everything beside it.
06 · Non-negotiables

Before a page ships

✓Every number names its metric, its store and its dates. “$206,546 — total store sales, March 2026, Shopify Analytics.” A number without those three is not ready.
✓One action per screen. A second button next to the main one costs more than it adds.
✓Reassurance under the button, not in a paragraph above it.
✓Every heading carries the claim on its own. Assume the visitor reads only the headings. “What clients say” fails; “What clients wrote where we can’t edit it” passes.
✓Check 390px and 1440px. No sideways scroll, nothing cropped, the main button reachable without hunting.
✓Only the headline gets weight 900. Kickers, labels, buttons and card headings sit below it. When a 12px label and a 70px headline are both 900, the label stops reading as a label. Hero kicker is 600; section labels (.lbl, .eyebrow) are still 800 and should follow.
✓Every value comes from a token. No hand-written hex, radius, shadow or section padding. If what you need is not in section 02, it does not exist yet — add it to shared.css first, so every page gets it.
✓Every section uses .sec for its padding. The audit found the native sections at a clean 72/72 and the imported proof blocks at 65/70, 58/64 and 0/0 — the vertical beat stumbles exactly where the proof sits.
✓One heading size per level, page-wide. H2 was 48px everywhere except the reviews block (50px) and the reel block (32px). An imported block does not get its own scale.
✓One pattern per job.#included numbered its steps with 56px black rounded-squares reading “01, 02, 03”; #offer used black circles reading “1, 2, 3”. Same page, same job, two designs — pick one and reuse it.
✕Never append a <style> block to fix a page./ecommerce-seo/ carries 26 of them in the body on top of 15 in the head, which is why its hero headline has ten competing font-size rules. Edit shared.css and rebuild.
✕No speed claims. No “in 30 days”, no “from a standing start”. Results took months to years, on stores that were already selling.
✕No self-reported counts or scores. No review tallies we control, no PageSpeed numbers, no “X stores built”. Third-party-verifiable proof only.
✕Never say “no sales call” about a call that is one. Say what the visitor actually gets.
✕Don’t ship a placeholder. If a video, review or figure isn’t ready, the block comes out until it is.

Files:EMS/ecomoptix/v7/ — shared.css (the system), home.src.html, service-template.html, services/*.json, build.py. Identity, logo and voice live in skills/proposal-os/brand/brand-guidelines.html.

This page is noindex. Internal reference, not a public page.