ShippedMedium

Add a zero-specificity base layer applying font, colour and type-scale tokens to html and h1–h4 in synthcss.css

Proposed by Jonathan Miller 1 month agoFunding opened 1 month agoFunded 1 month agoShipped 1 month ago
Acceptance · round 1
Shipped
CINo checks
Automated reviewPass with concerns

This branch adds tests only: a bundle-content test built from the real sources, a stricter modular-file check that rejects page-wide and bare-heading selectors, and a plain-markup `--font-sans` fixture in the browser check. The base layer, bundle wiring and contract updates are reported as already merged in #7, so #12 may be a duplicate. The added node tests look correct. However, the computed-style browser check was never run, and its new assertions depend on measurement fields this diff doesn't show. No CI ran, so passing tests can't be confirmed.

Acceptance criteria · 3 of 7 met
  • YESThe built synthcss.css contains the synth.base layer with the specified rules, using only existing tokensThe new `build.test.mjs` test builds from the real `src/` and asserts `@layer synth.base`, `:where(html)`, `font-family: var(--font-sans)` and the h1 `--text-3xl` rule appear after the tokens; the base.css contents themselves are pre-existing and not in the diff.
  • YESTokens, layout and components build and work individually without base; none has a :where(html) or heading-size rule`checkModular` in `check-base.mjs` now rejects html/body/bare h1–h6 selectors, including inside @media, and the build test asserts the modular outputs lack `synth.base` and `:where(html)`.
  • YESEvery base selector has zero specificity, wrapped in :where(), asserted by a test/scriptThe builder says the pre-existing `scripts/check-base.mjs` checks this; it is not changed in this diff.
  • PARTIALFixture page with only the stylesheet link, the --font-sans override and plain markup; html gets --font-sans and h1 gets --text-3xlThe `inter` fixture in `check-base-browser.mjs` now uses `PLAIN_MARKUP` and asserts html/body/p font-family and the h1 size, but the script was never executed.
  • PARTIALAuthor rules like body { font-family: serif } / h1 { font-size: 10px } override the base layerThe `author` fixture and its assertions in `check-base-browser.mjs` already existed, but the browser check was not run on this branch.
  • UNCLEARsynthcss.llm.md contains the sentence, synthcss.ai.json describes the base styles, contract sync passesThe builder says these are on main via #7 and checked by `verify-ai-contract.mjs`; none of it is in this diff.
  • UNCLEARAll existing tests, lint and build steps passNo CI ran, and only the builder's local `npm test` report is available.
Concerns
  • The browser check (`check-base-browser.mjs`) was never run: Chromium failed to download in the sandbox and the builder only ran `node --check`. The new `inter` fixture assertions and the author-override assertions are therefore unexecuted.
  • The new assertions read `inter.html` and `inter.tokens.sizes["--text-3xl"]`, but the diff doesn't show `measure()` returning an `html` entry or a `tokens.sizes` map. If either is missing, the browser script will throw rather than check anything.
  • No CI checks ran on this commit, so the claim of 83 passing tests plus all check scripts rests only on the builder's report.
  • `isPageOrHeadingSelector` only unwraps a selector that is entirely `:where(...)`/`:is(...)`. Descendant forms like `body h1` or `html body` in a modular file would not be flagged, so the new guard is narrower than its error message suggests.
  • Most of the deliverable (`base.css`, bundle wiring, contract updates) is said to already be on main from #7 and isn't in this diff. Backers should confirm that #12 isn't a duplicate before funding it as new work.
CI details
No CI checks ran on this commit.

BackersAccepted
1 accept · 0 rebuild · 0 not voted · quorum 1 of 1
MaintainerMerge

Accepted by the backers and merged by the maintainer.

Ballots · 1
AcceptJonathan Miller

Automated review cost $0.07, counted as builder cost.

Apply the font, colour and type tokens to the page by default

Motivation

SynthCSS defines --font-sans, --color-text, --color-background, --leading-normal and the --text-* scale, but no rule applies them to the document.

  • Pages that follow synthcss.llm.md render in the browser's default serif font.
  • Overriding --font-sans on :root has no visible effect.
  • A page <h1> ignores --text-3xl.

In a benchmark, 5 of 6 agent-built pages rendered in serif for this reason.

Scope

  1. New base stylesheet. Add it alongside the existing modular sources, e.g. base.css next to the tokens, layout and components files, following the repo's naming conventions. It contains a cascade layer synth.base with zero-specificity rules:
    @layer synth.base {
      :where(html) {
        font-family: var(--font-sans);
        font-size: 100%;
        line-height: var(--leading-normal);
        color: var(--color-text);
        background: var(--color-background);
      }
      :where(h1, h2, h3, h4) { line-height: var(--leading-tight); font-weight: var(--weight-semibold); }
      :where(h1) { font-size: var(--text-3xl); }
      :where(h2) { font-size: var(--text-2xl); }
      :where(h3) { font-size: var(--text-xl); }
      :where(h4) { font-size: var(--text-lg); }
      :where(code, kbd, pre, samp) { font-family: var(--font-mono); }
    }
    
    • Assumption: the agent must check that --leading-tight, --weight-semibold and --font-mono exist in the tokens file. If one is missing, use the closest existing token and note the substitution in the PR description. Do not invent new tokens unless none fit.
    • Assumption: if the project already declares a layer order, slot synth.base first, before tokens/layout/components, consistent with existing naming. If the project uses no layers, keep @layer synth.base as specified. Unlayered author and component CSS will then always win.
  2. Bundle. Include the base stylesheet in the main synthcss.css bundle, and in its minified or CDN variant if one is built. The modular tokens, layout and components files must not import or depend on it. They keep working standalone with no base styles.
  3. Contract. Make three updates:
    • In synthcss.llm.md → Design Tokens, add: "Base styles apply --font-sans, --color-text and --color-background to the page and the --text-* scale to h1–h4. Override the tokens to restyle."
    • Add a matching description of the base layer to synthcss.ai.json, in whatever structure the existing schema uses.
    • Keep the existing contract sync verification passing.
  4. Docs/changelog. Update the README or file listing and the changelog if they enumerate bundle contents.

Acceptance criteria

  • The built synthcss.css contains the synth.base layer with the rules above, using only tokens defined in the tokens file.
  • Tokens, layout and components still build and are usable individually without the base file. None of them contains a :where(html) or heading-size rule.
  • Every base selector has zero specificity, wrapped in :where(). A test or script check asserts this.
  • A test fixture page contains only the stylesheet link, :root { --font-sans: "Inter", sans-serif } and plain markup. Under the base layer, html gets font-family: var(--font-sans) and h1 gets font-size: var(--text-3xl).
    • Verify with the repo's existing test tooling. Use computed-style checks if a headless browser is already available; otherwise use CSS parse/assertion tests. Do not add a heavy new browser dependency.
  • An author rule such as body { font-family: serif } or h1 { font-size: 10px } overrides the base layer. Verify with a computed-style test if browser tooling exists; otherwise argue it from layer and specificity in tests and docs.
  • synthcss.llm.md contains the sentence above, synthcss.ai.json describes the base styles, and the contract sync check passes.
  • All existing tests, lint and build steps pass.

Out of scope

  • A full CSS reset or normalize: margins, box-sizing, h5/h6, lists.
  • New design tokens or a changed token scale.
  • Changing the .card-header heading rules or other component styles.
  • Showcase redesign (assumption: the showcase is untouched unless the build breaks).

No comments yet.