VotingMedium

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

Proposed by Jonathan Miller 2 hours ago
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

  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.
Discussion · 0

No comments yet.