ShippedMedium

Add .nav/.nav-link and .tabs/.tabs-item components with ARIA-driven state and AI contract entries

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 delivers token-only, CSS-only `.nav`/`.nav-link` and `.tabs`/`.tabs-item` components with ARIA-driven state, focus rings and wrapping tabs. It also adds AI contract entries naming one state attribute each and explicitly banning `aria-pressed`, docs, showcase demos, and solid static and browser checks. The implementation looks correct and closely follows the spec and repo conventions. However, no CI ran, so passing tests and the contract sync check are unverified, and the showcase's character count is now stale next to the updated token figure.

Acceptance criteria · 4 of 8 met
  • YES`.nav-link[aria-current="page"]` is styled distinctly from default and hover, and no state classes existIn `src/components.css`, `.nav-link[aria-current="page"]` sets a color-mix primary tint background and `--color-primary` text, and comes after `:hover` at equal specificity so it wins. No state classes are added, and the class whitelist test rejects `.tabs-item-selected`.
  • YES`.tabs-item[aria-selected="true"]` is styled distinctly, and `aria-selected="false"` items use the default styleThe selected rule sets `--color-surface-elevated`, `--border-color` and `--shadow-sm`. There is no `[aria-selected="false"]` rule, and the browser check asserts that unselected items all look the same.
  • PARTIAL`.nav` and `.tabs` render correctly inside `.stack` (vertical) and `.cluster` (horizontal)`.nav` sets no display, and `.tabs` uses `fit-content` with `max-inline-size: 100%`. The showcase demos both layouts and the browser script checks row counts, but that script is optional and did not run in CI.
  • YES`:focus-visible` on `.nav-link` and `.tabs-item` uses the `--focus-*` tokensBoth rules set `outline: var(--focus-width) solid var(--focus-color); outline-offset: var(--focus-offset)`, enforced by new `focusTargets` entries and tests.
  • PARTIAL`.tabs` does not cause horizontal overflow at 320px`.tabs` has `flex-wrap: wrap` and `max-inline-size: 100%`, the static check requires `flex-wrap: wrap`, and a 320px browser test with a long-tabs clone exists but was not run.
  • YESAll colors, radii and spacing come from existing tokens, with no hard-coded valuesThe new CSS uses only `var(--…)` tokens, `color-mix` of two tokens, `transparent`, `0` and `1em` icon sizing, and the existing token-only checker covers `components.css`.
  • PARTIALBoth Intent Mapping rows are in `synthcss.llm.md`, the components are in `synthcss.ai.json`, and the sync check passesThe rows and the JSON `nav`/`tabs` entries and `intentMap` entries are added verbatim, with a new `STATE_ATTRIBUTES` check, but the sync check was not run because there was no CI.
  • UNCLEARExisting tests, lint and build pass, and new tests are added in the existing styleNew cases in `check-components.test.mjs` and `verify-ai-contract.test.mjs` follow the existing `withCss`/`assertError` style, but no CI ran to confirm that anything passes.
Concerns
  • No CI checks ran on this commit, so nothing confirms that the existing tests, lint, build and the contract sync check (`verify-ai-contract.mjs`) actually pass; the size-tolerance and row-count checks are especially easy to trip.
  • The showcase badge was changed to '≈ 3,490 tokens', but the adjacent sentence 'about 11,300 characters' was left unchanged. At characters ÷ 4 the new figure implies roughly 14,000 characters, so the page now contradicts itself.
  • An unrelated edit in `docs/components.md`: the existing 'Invalid input' row was merged into the 'Labeled input' row, apparently to stay under `MAX_REFERENCE_ROWS = 15`. It is reasonable, but it changes existing documentation without being called out.
  • The 320px no-overflow check and the stack/cluster layout checks live only in the optional Playwright script (`check-components-browser.mjs`), which is not part of `npm test`. Those criteria are verified only if someone runs it manually.
  • The spec asks for the proposer's markup examples in the docs. The diff cannot show whether the examples used are the proposer's or new ones written by the builder.
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.17, counted as builder cost.

Add navigation links (.nav) and tabs / segmented control (.tabs)

Motivation

In benchmark runs, every agent-generated page with navigation hand-wrote nav-link CSS. Every team-screen run also hand-wrote a segmented control. The selected-state attribute was inconsistent: aria-selected in some runs, aria-pressed in another. SynthCSS should provide both components and name one state attribute for each in the AI contract.

Scope

1. .nav / .nav-link

  • .nav is a list reset: no bullets, margin or padding. Layout comes from combining it with .stack-* (vertical) or .cluster (horizontal).
  • .nav-link:
    • is an inline-flex row with a gap between an optional leading svg and the label;
    • has padding from spacing tokens and a --radius-md border radius;
    • has no underline and inherits the text color.
  • Hover: background --color-surface.
  • Current page: .nav-link[aria-current="page"] gets a --color-primary tint (background and/or text). No state classes are used.
  • :focus-visible shows a focus ring using the existing --focus-* tokens.

2. .tabs / .tabs-item

  • .tabs is an inline-flex group with a --color-surface track background, a small inner padding and a radius.
  • .tabs-item:
    • is a button reset with padding;
    • uses a transparent background by default.
  • Selected: .tabs-item[aria-selected="true"] gets a --color-surface-elevated background with a raised look (shadow or border token).
  • :focus-visible shows a focus ring using the --focus-* tokens.
  • Narrow screens: .tabs must not overflow its container.
    • Assumption: use flex-wrap: wrap.
  • Assumption: the components are CSS-only. Keyboard arrow navigation and panel switching are the author's responsibility, and the contract says so.

3. Contract and docs

  • Update synthcss.llm.md:
    • add component entries;
    • state the single state attribute for each: aria-current="page" for nav, aria-selected="true" with role="tab" for tabs;
    • say explicitly not to use aria-pressed or state classes.
  • Add Intent Mapping rows:
    • "Navigation links → .nav + .nav-link"
    • "Tabs or segmented filter → .tabs + .tabs-item"
  • Update synthcss.ai.json to match, so the existing sync verification passes.
  • Use the proposer's markup examples in the docs.
  • Assumption: add a short demo to the showcase only if the existing component docs/showcase pattern requires it for every component.

4. Placement

  • Follow the file and layer structure used for the components added in #4, including the build entry point.

Acceptance criteria

  • .nav-link[aria-current="page"] is styled distinctly from the default and hover states, and no state classes exist.
  • .tabs-item[aria-selected="true"] is styled distinctly, and aria-selected="false" items use the default style.
  • .nav and .tabs render correctly inside .stack (vertical) and .cluster (horizontal).
  • :focus-visible on .nav-link and .tabs-item uses the --focus-* tokens.
  • .tabs does not cause horizontal overflow at 320px width.
  • All colors, radii and spacing come from existing tokens, with no hard-coded values.
  • Both Intent Mapping rows are present in synthcss.llm.md, the components appear in synthcss.ai.json, and the contract sync check passes.
  • Existing tests, lint and build pass, and new tests or fixtures are added in the same style as the existing component tests.

Out of scope

  • JavaScript for tab switching or keyboard roving focus.
  • Tab panels (role="tabpanel") styling.
  • Dropdown or nested navigation, breadcrumbs, pagination.
  • New design tokens.

No comments yet.