ShippedMedium

Contract 1.1.0: add data-ui/@layer synth.ext extension rule, app-shell example and 'Not covered yet' list

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 PR adds a well-specified data-ui / @layer synth.ext extension rule, a full app-shell example, a 'Not covered yet' list and a mirrored JSON `extension` object. It substantially strengthens the verifier with checks for CSS layer, selectors, properties, token values, inline styles, vocabulary and MD/JSON parity, and adds solid negative-path tests. The main deviations are the version (1.2.0 instead of 1.1.0, justified because 1.1.0 already shipped) and the lack of any CI run to confirm that tests and build pass.

Acceptance criteria · 4 of 7 met
  • YESsynthcss.llm.md contains the extension section with the single data-ui + @layer synth.ext + tokens-only patternThe new '## When the vocabulary is missing a pattern' section has 5 numbered steps, an Allowed properties/keywords list and an example `@layer synth.ext` block, and the verifier requires the key phrases.
  • YESApp-shell example uses only classes that exist in the CSS and are listed in the contract, verified automaticallycheckMarkup in verify-ai-contract.mjs checks every example class against both cssClasses and the contract vocab, and a test asserts that an invented `.stat-card` fails.
  • YESApp-shell example has no custom flex/grid rules; inline styles are token overrides onlyThe example's only CSS is a `[data-ui="app"]` font/color rule in synth.ext, its inline styles are `--sidebar-width` and `--grid-min`, and inlineStyleErrors plus the extension property allow-list enforce this.
  • YESEvery 'Not covered yet' item has a composition or a fallback snippet; fallbacks use data-ui, @layer synth.ext, var() only, no new classesAll 8 patterns are listed in both files: seven as compositions and Timeline as a data-ui fallback whose CSS uses only var() and `solid`; the verifier checks each snippet's classes and CSS.
  • PARTIALsynthcss.ai.json has an extension object and the sync verification passes with itThe extension object has attribute, layer, values, a 29-item properties list, keywords and notCovered, and JSON_KEYS now requires it; passing is claimed locally but no CI ran.
  • NOContract version reads 1.1.0 in both filesBoth the JSON contractVersion and the Markdown header read 1.2.0, a deliberate bump because main was already at 1.1.0.
  • UNCLEARExisting tests and build passThe builder reports npm test (91 tests) and npm run build passing, but no CI checks ran to confirm this.
Concerns
  • The contract version is 1.2.0, not the 1.1.0 the spec requires. The builder's reasoning is sound: main already shipped 1.1.0 for base styles, so reusing it would be wrong. Still, backers should explicitly accept this deviation from the literal criterion.
  • No CI ran on this commit. 'npm test' and 'npm run build' passing is the builder's own claim, and the browser checks were not run, so the app-shell page was never rendered.
  • The spec asks for a changelog bump 'if one exists'. The diff touches no changelog file, and the review cannot confirm whether one exists in the repo.
  • checkExtensionCss parses CSS with flat regexes and does not handle nested blocks or at-rules inside the layer, so legitimate fallbacks using `@media` or nesting would be rejected. This is consistent with the contract's no-media-queries rule, but it is brittle.
  • Seven of the eight 'Not covered yet' items now map to shipped components (avatar, nav, tabs, switch, input-group, sidebar-end), so only Timeline demonstrates the data-ui fallback. That matches the current repo state, but the section's title is now somewhat misleading.
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.14, counted as builder cost.

Motivation

The AI contract (synthcss.llm.md / synthcss.ai.json, v1.0.0) forbids custom classes, custom flex/grid, restyling components and non-token inline styles. It offers no legal path when the vocabulary lacks a pattern, so generators break the rules inconsistently. The contract also has no full-page example.

Scope

  1. Extension rule. Add a section to synthcss.llm.md titled "When the vocabulary is missing a pattern". It defines exactly one fallback:
    • compose from layout primitives first;
    • otherwise mark the element with data-ui="<name>" and style it only inside @layer synth.ext;
    • use only var(--…) token values;
    • add no new class names;
    • do not override internals of SynthCSS classes.
  2. App-shell Valid Example. A complete HTML page using only contract vocabulary:
    • .sidebar navigation;
    • .container stack-lg main area;
    • .split header with a primary button;
    • .grid of stat cards;
    • a main/side row. It includes body font setup using tokens only. Assumption: this is a small <style> rule on body using var() tokens, permitted by the extension rule or explicitly allowed in the example.
  3. "Not covered yet" list. Cover each of these patterns:
    • avatar/initials;
    • icon tile;
    • nav link with current state;
    • tabs/segmented control;
    • switch;
    • input with attached button;
    • narrow right column;
    • timeline. For each, give either a composition of existing classes or a data-ui fallback snippet that obeys the extension rule.
  4. JSON mirror. Add an extension object to synthcss.ai.json with:
    • attribute: "data-ui";
    • layer: "synth.ext";
    • the allowed-values rule (tokens only);
    • assumption: an explicit list of allowed CSS properties. Mirror the not-covered list there if the existing sync check requires parity.
  5. Version bump. Bump the contract version to 1.1.0 in both files, and in a changelog if one exists.

Acceptance criteria

  • synthcss.llm.md contains the extension section with the single data-ui + @layer synth.ext + tokens-only pattern.
  • The app-shell example uses only classes that exist in the SynthCSS CSS and are listed in the contract. Verify this automatically: extend or reuse the existing sync/verification script to check example class names against the vocabulary.
  • The app-shell example contains no custom flex/grid rules. Any inline styles in it are token overrides only.
  • Every "Not covered yet" item has a composition or a fallback snippet. Every fallback snippet uses data-ui, @layer synth.ext and var() values only, with no new classes.
  • synthcss.ai.json has an extension object, and the existing sync verification passes with it.
  • The contract version reads 1.1.0 in both files.
  • Existing tests and build pass.

Out of scope

  • Implementing any of the companion components (avatar, tabs, switch, etc.).
  • Base element styles.
  • Re-running the benchmark.
  • Lint tooling that checks user output beyond the existing repo verification.

No comments yet.