ShippedLarge

Add core semantic components (button, field, card, badge, alert, panel, table, empty-state) with docs, showcase and tests

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 is a thorough, well-scoped implementation of all eight components, built purely on tokens with state taken from native attributes. It comes with detailed per-component docs, a 14-row AI reference table, a showcase article for each component and a composed settings screen. The static checks cover every verification item in the spec, with negative tests. The main gap is that no CI ran, so the passing test suite and build are claimed rather than demonstrated; a few minor design choices (`.card` overflow clipping, showcase CSS specificity changes) deserve a glance.

Acceptance criteria · 9 of 10 met
  • YESAll classes listed above exist in the built CSS output.`src/components.css` defines every class in the `COMPONENTS` map, `synthcss.css` imports it after `layout.css`, and `checkComponents` verifies each class against the inlined bundle and rejects extra classes.
  • YESComponent color declarations use only SynthCSS tokens (verified by test).`checkComponentsCss` rejects hex/rgb/hsl/named literals and custom properties, requires color props to be a `var()` or a `color-mix()` of two tokens, and checks that each `var()` is defined; tests cover hex, rgb, hsl, named and custom-property cases.
  • YESButtons and form controls have :focus-visible and disabled styles (verified by test).`.button:focus-visible`, `.field :where(input, textarea, select):focus-visible`, `.button:disabled`/`[aria-disabled="true"]` and `.field … :disabled` exist, are asserted in `focusTargets` and the disabled checks, and have negative tests.
  • YESField error state does not rely on color alone.The `[aria-invalid="true"]` rule doubles the border width with a 5× start edge, `.field-error::before` adds a "!" marker, and the test fails if the border-width change or the marker is removed.
  • YESTables scroll horizontally inside .table-wrap on narrow viewports.`.table-wrap` sets `overflow-x: auto; max-inline-size: 100%`, the static test asserts it, and the optional Playwright script checks scrolling at 375px.
  • YESDocs cover every component and include the compact AI reference table.`docs/components.md` has a section per component with Purpose, Example, Variants, Composition, Accessibility, Recommended use and Misuse, plus a 14-row AI Component Reference; alerts use `role="alert"`/`role="status"`.
  • YESDoc and showcase class usage validated against the CSS (test).`checkClassUsage` validates html blocks in README and `docs/*.md`, showcase snippets and live showcase markup, with negative tests for `.btn`, `.badge-ok` and `.pill`.
  • YESShowcase demonstrates all eight components plus at least one composed interface.`showcase/index.html` adds a `#components` article per component demoing every class and a `#composed` settings screen using all eight components, enforced by new `check-showcase.mjs` checks.
  • UNCLEARThe existing test suite and build pass.`package.json` test script is extended and the builder reports passing, but no CI ran to confirm this.
  • YESNo third-party CSS framework is added.No dependencies are added; Playwright is only an optional, uninstalled dependency of the browser check script, and the existing `THIRD_PARTY` guard remains.
Concerns
  • No CI checks ran on this commit, so the builder's claim that `npm test` passes (40 tests) and that the build is intact is unverified. Run it before merging.
  • `.card` sets `overflow: hidden` so media and footer bleed to the rounded corners. This also clips anything that overflows the card, such as a wide table placed without `.table-wrap`, or focus outlines on full-bleed children. It may surprise authors composing inside cards.
  • The doc class check in `checkClassUsage` only inspects class attributes inside fenced ```html blocks. Classes mentioned inline in prose or tables are not validated. This is acceptable against the spec, but worth knowing.
  • `showcase/showcase.css` heading and link rules were lowered to `:where(.sc-page)` specificity so component styles win. The change is justified, but it touches existing showcase styling, so the earlier sections should get a quick visual check.
  • `check-showcase.mjs` now ends sections at `<footer class="sc-footer"` instead of any `<footer`. This makes the section parsing depend on that exact attribute string.
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.29, counted as builder cost.

Motivation

Give AI agents a small, semantic, predictable component vocabulary on top of the existing SynthCSS tokens and layout primitives, so they can build a common app UI without composing low-level utility classes.

Scope

Components

All components live in the existing CSS source. Each uses only existing SynthCSS custom properties for color, spacing, radius, typography and shadows; no hard-coded colors. Naming follows .component, .component-variant, .component-part.

  • Button: .button plus .button-primary, .button-secondary and .button-danger.
    • Assumption: .button-danger is canonical, matching the spec's examples; .button-destructive is not added.
    • Sizes: .button-sm and .button-lg.
    • Disabled: styled via :disabled and [aria-disabled="true"].
    • Loading: styled via [aria-busy="true"], which shows reduced interactivity plus a CSS-only indicator.
      • Assumption: no .button-loading class is added.
    • Icon + text: an inline svg or element inside the button is aligned with a gap.
    • Icon-only: .button-icon, a square button; documentation requires aria-label.
  • Form controls: .field wrapper, .field-label, .field-help, .field-error.
    • Native input types text, email, password and number, plus textarea, select, checkbox and radio, are styled when inside .field.
      • Assumption: scoped under .field to avoid global resets; document this.
    • Disabled fields are styled via :disabled.
    • Error state is triggered by [aria-invalid="true"]. It must change more than color, for example a thicker border plus a visible error text or icon marker.
  • Card: .card with optional .card-header, .card-body, .card-footer, .card-media and .card-actions.
  • Badge: .badge plus .badge-success, .badge-warning, .badge-danger and .badge-info.
  • Alert: .alert plus .alert-info, .alert-success, .alert-warning and .alert-danger. Arbitrary headings, paragraphs and buttons inside must render sensibly without a special structure.
  • Panel: .panel (optionally .panel-header and .panel-body), visually lighter than .card.
  • Table: .table applied to native <table>, with an optional .table-wrap wrapper for horizontal scroll on narrow screens.
    • Header and body row styling, borders.
    • Hover rows via .table-hover.
    • .numeric cell class for right-aligned tabular numbers.
  • Empty state: .empty-state, a centered stack for heading, description, an optional icon or illustration, and an optional action.

Shared requirements

  • Visible :focus-visible styles on all interactive components.
  • Consistent disabled treatment that is still distinguishable.
  • No JavaScript.
  • Responsive by default.
  • Native semantics preserved; do not remove native focus or keyboard behavior.

Documentation

  • One doc section or file per component, covering:
    • purpose
    • minimal example
    • variants
    • composition with .stack, .cluster, .split and .grid
    • accessibility notes
    • recommended use
    • misuse examples where useful
  • A compact intent-to-class reference table, of about 15 rows or fewer, as in the proposal.
  • Alert examples use role="alert" or role="status" appropriately.

Showcase

  • Add a section for each component to the existing showcase/ site.
  • Add at least one composed mini-interface, for example a settings form or a project card grid with badges and an alert, built only from SynthCSS classes.

Verification

Extend the existing test or fixture setup. Assumption: static checks only, with no screenshot tooling unless it already exists. Tests must check that:

  • every listed component class exists in the built CSS;
  • component rules reference var(--…) tokens and contain no raw hex, rgb or hsl color literals;
  • interactive components define :focus-visible styles;
  • disabled selectors exist for buttons and fields;
  • every class used in doc examples and the showcase exists in the CSS;
  • the showcase contains each component.

Acceptance Criteria

  • All classes listed above exist in the built CSS output.
  • Component color declarations use only SynthCSS tokens (verified by test).
  • Buttons and form controls have :focus-visible and disabled styles (verified by test).
  • Field error state does not rely on color alone.
  • Tables scroll horizontally inside .table-wrap on narrow viewports.
  • Docs cover every component and include the compact AI reference table.
  • Doc and showcase class usage validated against the CSS (test).
  • Showcase demonstrates all eight components plus at least one composed interface.
  • The existing test suite and build pass.
  • No third-party CSS framework is added.

Out of Scope

  • Dark theme implementation (components must merely consume semantic tokens).
  • JavaScript-driven components (modals, dropdowns, tabs).
  • Additional color or size variants beyond those listed.
  • Icon sets.

No comments yet.