ShippedLarge

Add versioned AI contract (synthcss.llm.md + synthcss.ai.json) with sync verification and showcase section

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 delivers a thorough AI contract: a canonical JSON file and a hand-written Markdown twin covering every token, layout, component part and variant, plus schema docs. A dependency-free verifier with targeted tests covers each required failure mode, and the showcase section and Pages deploy publish both files. The content and tests match the spec closely, and no CSS was changed. No CI ran, so a passing final tree is unconfirmed, and the verifier also checks README prose and showcase markup in ways that may prove brittle.

Acceptance criteria · 8 of 9 met
  • YESsynthcss.ai.json and synthcss.llm.md exist at the repo root and state the SynthCSS versionBoth files are added at the root; the JSON has `"synthcssVersion": "0.1.0"` and the Markdown header reads `Version: SynthCSS 0.1.0 · contract 1.0.0`.
  • YESEvery current token, layout primitive, component class and variant appears in both filesThe JSON lists 57 tokens, 19 layout classes and 8 components with their parts and variants, mirrored line for line in the Markdown. verifyContract cross-checks both against the built CSS `:root` and its selectors, though no CI run confirms the result.
  • YESMarkdown contains every listed section including the intent table and the 10 generation rulessynthcss.llm.md has a version header, Design Tokens, Layout and Component Vocabulary, an 18-row Intent Mapping table, Composition Rules with Recommended/Avoid, 10 numbered AI Generation Rules, 3 valid examples and 5 invalid ones, including flex-row-gap-large-center and inline display:flex/gap.
  • UNCLEARThe verification script passes on the final treeThe test 'the repository contract passes' asserts no errors and the builder reports a pass, but no CI checks ran to confirm it.
  • YESFake class, deleted class, renamed token, and real class in an invalid example each make the script fail (tests/fixtures)verify-ai-contract.test.mjs has a dedicated test for each case ('fake class is added', 'class is deleted', 'token is renamed', 'invalid example uses a real class'), covering both the JSON and the Markdown.
  • YESScript prints the size estimate; Markdown is under the thresholdThe main block logs chars and ~tokens (chars ÷ 4) and warns without failing above the threshold (`--max-tokens` or an env var, default 8000). The file is about 2,829 tokens.
  • YESScript runs in the existing test/CI commandpackage.json `test` now runs `node scripts/verify-ai-contract.mjs` and its test file. The Pages and Release workflows already run `npm test`.
  • YESShowcase has an AI Contract section with view link, download link, size and example; deploy publishes both filesshowcase/index.html adds #ai-contract with a ../synthcss.llm.md link, a download link for ../synthcss.ai.json, '≈ 2,830 tokens', and a prompt next to rendered HTML. pages.yml copies both files to _site/ and adds them to the push paths.
  • YESREADME mentions the contract and that public API changes must update it in the same PRThe new README section 'AI contract' says, in bold, that public API changes must update both contract files in the same pull request.
Concerns
  • No CI ran on this commit, so nothing independently confirms that `npm test`, including the new verifier and its 11 tests, passes on the final tree. The builder summary claiming 54 passing tests is also cut off.
  • The verifier goes beyond the spec: it also checks the README wording (a 'same pull request' regex), the pages.yml `cp` line format and a hard-coded '≈ 2,830 tokens' badge in the showcase, which must stay within 10%. These ties to prose and markup make the check brittle under routine doc and showcase edits.
  • The test file builds the repo path with `new URL('..', import.meta.url).pathname`. That breaks on Windows and on paths containing spaces or percent-encoded characters; `fileURLToPath` would be the safer choice.
  • The showcase AI Contract snippet is 15 lines and adds new classes such as `sc-label` and `sc-button-secondary`. The diff does not show whether the existing check-showcase.mjs 'snippets are short' and sc-class checks accept them, and without CI this is unconfirmed.
  • The showcase hard-codes a GitHub URL (`nabledhq/synthcss`) that the verifier does not check. Markdown invalid examples are matched to the JSON only by their html, so a note can drift between the two files without failing.
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.21, counted as builder cost.

Motivation

AI agents should be able to learn SynthCSS's full public vocabulary from one compact file in a single context window. They should not need to crawl the docs or read the source.

Scope

1. synthcss.ai.json (repo root)

A structured contract and the canonical machine-readable source.

Top-level keys:

  • synthcssVersion: must equal the version in package.json.
  • contractVersion
  • tokens: name → short purpose.
  • layouts: class → intent.
  • components: class → { intent, parts, variants }.
  • intentMap: list of { intent, use }.
  • compositionRules: { recommended[], avoid[] }.
  • generationRules[]
  • examples: { valid[], invalid[] }, each with { html, note }.

The schema must be documented in a short section of the README, or in docs/ai-contract.md if a docs folder exists.

2. synthcss.llm.md (repo root)

A prompt-ready, terse reference with one line per item, e.g. .stack — vertical flow with tokenized spacing. Sections:

  • Version header
  • Design Tokens
  • Layout Vocabulary
  • Component Vocabulary (with variants)
  • Intent Mapping table
  • Composition Rules (Recommended / Avoid)
  • AI Generation Rules: the 10 rules from the proposal
  • Valid Examples: 2–4 short snippets showing composition
  • Invalid / Discouraged Examples: at least an invented class such as flex-row-gap-large-center and an inline-style flex/gap case

The file must cover exactly the tokens, layouts and components that exist in the current CSS. Do not invent any.

Assumption: both files are shipped. The Markdown file is hand-written unless the maintainer answers otherwise.

3. Verification script

Add a script such as scripts/verify-ai-contract.*, using the repo's existing language and test runner, exposed as an npm script or test. Add it to CI if CI exists.

It fails when:

  • A class in the JSON or Markdown contract is not present as a selector in the compiled/source CSS.
  • A public layout or component class in the CSS is missing from the JSON contract. Assumption: public means every class selector in the framework CSS. Internal helpers are excluded via an explicit allowlist in the script.
  • A token name in the contract is not defined as a custom property in :root, or a :root token is missing from the contract.
  • A class used in an invalid example is a real SynthCSS class. Only classes that the example's note marks as the correct alternative are exempt.
  • The set of class and token names in the Markdown file differs from the set in the JSON file.
  • synthcssVersion does not match package.json.

The script also prints the approximate size of synthcss.llm.md in characters and estimated tokens (chars ÷ 4). It emits a warning, not a failure, when the size exceeds a configurable threshold (default 8,000 tokens).

4. Showcase

Add an "AI Contract" section to the existing showcase. It must:

  • Briefly explain the contract.
  • Link to or display synthcss.llm.md.
  • Provide a download link for synthcss.ai.json.
  • Show the approximate token size.
  • Show one static example: a natural-language prompt alongside the HTML generated from the contract, rendered with SynthCSS.

The existing Pages deploy workflow must copy both contract files into the published site.

Acceptance Criteria

  • synthcss.ai.json and synthcss.llm.md exist at the repo root and state the SynthCSS version.
  • Every current token, layout primitive, component class and variant appears in both files.
  • The Markdown file contains every section listed above, including the intent table and the 10 generation rules.
  • The verification script passes on the final tree.
  • Each of these temporary changes makes the script fail (demonstrated by its tests or fixtures):
    • adding a fake class to the contract
    • deleting a class from the contract
    • renaming a token
    • using a real class in an invalid example
  • The script prints the size estimate. The Markdown contract is under the threshold.
  • The script runs in the existing test/CI command.
  • The showcase has an AI Contract section with the view link, download link, size and example. The deploy publishes both files.
  • The README mentions the contract and that public API changes must update it in the same PR.

Out of Scope

  • Changing any CSS classes or tokens.
  • Live LLM calls in the showcase.
  • Publishing to npm or other registries beyond what already exists.
  • A real tokenizer dependency (unless the maintainer requests it).

No comments yet.