ShippedMedium

Add zero-specificity base layer applying font, colour and heading type tokens to html and h1–h4

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

The implementation matches the spec closely. `src/base.css` is a single `@layer synth.base` of `:where()` rules with exactly the requested declarations, bundled after tokens and before layout and components. Both contract files are updated, and the sync verifier now enforces them against `base.css`. Tests are thorough on paper: static checks run in `npm test`, plus a browser check covering every acceptance criterion. However, no CI ran and the browser check is optional, so the computed-style criteria and the test suite passing are not demonstrated.

Acceptance criteria · 5 of 7 met
  • YESA bundle-only fixture page with `:root { --font-sans: "Inter", sans-serif }` has body and p font-family resolving to --font-sans`src/base.css` sets `:where(html){font-family: var(--font-sans)}`, which body and p inherit; the `inter` fixture in `check-base-browser.mjs` asserts body and p equal `Inter,sans-serif`, but that check is optional and not in `npm test`.
  • YESWith no author CSS, h1–h4 font-size equals --text-3xl/2xl/xl/lg`base.css` sets the four `:where(hN)` font-size rules; `check-base.mjs` checks them statically and the browser fixture compares computed sizes to the resolved tokens.
  • YESAuthor rules `body { font-family: serif }` and `h1 { font-size: 10px }` override the base layerAll base rules are layered `:where()` selectors, so unlayered author rules win; the `author` fixture in `check-base-browser.mjs` asserts both overrides.
  • UNCLEARExisting component heading styles (e.g. card header headings) render unchangedThe browser check compares size, weight, line-height and colour of card, alert, panel and empty-state headings between the bundle and modular-only pages; the design (layered, zero specificity) supports this, but the test is optional and not shown to have run.
  • YESLoading only the modular tokens/layout/components files applies no base styles`checkModular` in `check-base.mjs` forbids `base.css` imports and `@layer` in the modular files; the browser `modular` fixture asserts that neither the font nor the h1 size and weight are applied.
  • YESsynthcss.llm.md and synthcss.ai.json describe the base stylesThe spec sentence is added verbatim to the Design Tokens section of `synthcss.llm.md`; `synthcss.ai.json` gains a `baseStyles` key with that note and rules, and the verifier checks both stay in sync.
  • UNCLEARThe existing contract sync verification and all tests passThe verifier and its tests are updated (including the `--text-*` wildcard fix), but no CI ran, so passing cannot be confirmed.
Concerns
  • No CI ran on this commit, so the claim that `npm test` passes is unverified. The builder summary is also cut off in its 'How it was verified' section.
  • Every computed-style acceptance criterion (Inter font on body/p, h1–h4 sizes, author overrides, unchanged component headings, no base styles from modular files) is only checked by `scripts/check-base-browser.mjs`. That script needs Playwright, which is not a dependency, and it is not part of `npm test`. Nothing shows it was actually run.
  • In `verifyContract`, `contract.baseStyles.rules` and `contract.baseStyles.note` are read without a guard. If `baseStyles` is missing entirely from the JSON, this could throw a TypeError instead of reporting the shape error, unless the function returns early on shape errors (not visible in the diff).
  • Scope goes slightly beyond the spec. `base.css` is published as a standalone `dist/base.css`, and `release.yml` now purges it from the CDN cache. This is reasonable and documented but not requested, and it adds a public artifact to maintain.
  • `contractVersion` goes from 1.0.0 to 1.1.0 and the `TOKEN_MENTION` regex in the contract verifier is loosened. Both are justified and tested, but they change shared contract tooling, which backers may want to note.
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.13, counted as builder cost.

Motivation

SynthCSS defines font, colour and type tokens but never applies them to the document. Pages that follow the contract render in the browser's default serif font, and overriding --font-sans on :root has no visible effect. Benchmark evidence: 5 of 6 agent-built pages rendered in serif.

Scope

  1. Add a base layer @layer synth.base containing zero-specificity (:where) rules:
    • :where(html) sets:
      • 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) sets line-height: var(--leading-tight) and font-weight: var(--weight-semibold).
    • Heading sizes:
      • h1 uses --text-3xl
      • h2 uses --text-2xl
      • h3 uses --text-xl
      • h4 uses --text-lg
    • :where(code,kbd,pre,samp) sets font-family: var(--font-mono).
  2. Include the base layer in the main synthcss.css bundle.
    • The modular files (tokens, layout, components) must still work when loaded without it.
  3. Contract wording:
    • Add to the Design Tokens section of synthcss.llm.md: "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."
    • Reflect the same information in synthcss.ai.json.

Assumptions

  • Missing tokens:
    • Before use, verify that --leading-tight, --weight-semibold and --font-mono exist.
    • If any is missing, add it to the tokens file with a sensible value and document it.
  • Layer order:
    • If the project already uses @layer, declare synth.base first in the layer order.
    • Existing component rules (e.g. .card-header :where(h1…h6)) must keep precedence over base heading rules.
    • If the project does not use layers, wrap only the base rules in synth.base. This is acceptable because unlayered rules always beat layered ones.
  • Bundle placement: the base layer goes in the bundle after tokens and before layout and components, as its own source file (e.g. base.css) if the build concatenates modules.

Acceptance criteria

  • A test or fixture page using only the bundle, :root { --font-sans: "Inter", sans-serif } and plain markup has computed font-family on body and p resolving to the --font-sans value.
  • With no author CSS, a page <h1> has computed font-size equal to --text-3xl. Likewise h2 matches --text-2xl, h3 matches --text-xl and h4 matches --text-lg.
  • Author rules still win over the base layer:
    • An author rule body { font-family: serif } overrides it.
    • An author rule h1 { font-size: 10px } overrides it.
  • Existing component heading styles (e.g. card header headings) render unchanged.
  • Loading only the modular tokens/layout/components files applies no base styles.
  • synthcss.llm.md and synthcss.ai.json describe the base styles.
  • The existing contract sync verification and all tests pass.

Out of scope

  • CSS resets or normalisation (margins, box-sizing, etc.).
  • Styling h5/h6, links or lists.
  • New theme variants.
  • Showcase redesign beyond any regressions caused by this change.

No comments yet.