Contract 1.1.0: add data-ui/@layer synth.ext extension rule, app-shell example and 'Not covered yet' list
Specification
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
- Extension rule. Add a section to
synthcss.llm.mdtitled "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.
- App-shell Valid Example. A complete HTML page using only contract vocabulary:
.sidebarnavigation;.container stack-lgmain area;.splitheader with a primary button;.gridof stat cards;- a main/side row.
It includes body font setup using tokens only. Assumption: this is a small
<style>rule onbodyusingvar()tokens, permitted by the extension rule or explicitly allowed in the example.
- "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-uifallback snippet that obeys the extension rule.
- JSON mirror. Add an
extensionobject tosynthcss.ai.jsonwith: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.
- Version bump. Bump the contract version to 1.1.0 in both files, and in a changelog if one exists.
Acceptance criteria
synthcss.llm.mdcontains the extension section with the singledata-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.extandvar()values only, with no new classes. synthcss.ai.jsonhas anextensionobject, 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.
Discussion · 0
No comments yet.