ShippedMedium

Add .avatar component (initials/image/icon, sizes, tone variants), --color-accent token, and .alert-icon part

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-tested implementation: the `--color-accent` token, an `.avatar` component with sizes, round shape and six tones, an `.alert-icon` part that only affects alerts containing it, and synchronized AI contract files. Contrast is checked by script and documented per tone, and the one failing tone (success) is fixed in a documented way. It cannot be a clean pass: no CI ran to confirm the claimed test and build results, the showcase was edited even though the spec puts that out of scope unless confirmed, and the proposal's HTML examples were replaced with the builder's own.

Acceptance criteria · 6 of 8 met
  • YES`--color-accent` is defined in the default theme and documented in the token reference.`src/tokens.css` adds `--color-accent: #6847b0`, and `docs/tokens.md` adds a table row and agent guidance; `check-tokens` now requires the token and checks it is at least 4.5:1 on the background.
  • YES`.avatar` renders initials, an image and an svg icon centred at a fixed square size, with `.avatar-sm`, default and `.avatar-lg` sizes all derived from `--control-height`.`src/components.css` `.avatar` uses inline-flex, centres both ways, sets inline/block-size `var(--control-height)`, gives img `object-fit: cover` and svg 55%, and `-sm`/`-lg` use `calc(var(--control-height) * 0.75/1.5)`; static checks and browser assertions were added.
  • YES`.avatar-round` produces a circle, and the default uses `--radius-md`.`.avatar` sets `border-radius: var(--radius-md)` and `.avatar-round` sets `var(--radius-full)`, and both are enforced in `check-components.mjs`.
  • YESAll six tone variants exist and derive their tint via `color-mix(... 12%, var(--color-background))`, so token overrides propagate.Each `.avatar-<tone>` sets `--tone: var(--color-<tone>)`, and a shared rule applies `background: color-mix(in srgb, var(--tone) 12%, var(--color-background)); color: var(--tone)`; the checker verifies each tone.
  • YESEach tone's foreground on its tint meets WCAG AA 4.5:1 with default tokens, verified by a test or script or documented with ratios, and any adjustment explained.`COLOR_VARIANTS` gains the avatar tones resolved through `withLocals`; the ratios are documented (success adjusted from 4.46 to 5.02:1 via color-mix), and tests assert that failure cases are caught.
  • YES`.alert` containing `.alert-icon` shows the icon beside the content, and `.alert` without an icon is unchanged.`.alert:has(> .alert-icon)` switches to a two-column grid with the icon in column 1 row 1 and other children in column 2, while the base `.alert` rule is untouched; a check asserts `.alert` stays flex.
  • PARTIAL`synthcss.llm.md` and `synthcss.ai.json` list all new classes and the token plus the two Intent Mapping entries, and contract sync verification passes.Both files add the token, the avatar component with nine variants, the `alert-icon` part and the rows "Person initials or photo" and "Icon on a tinted tile"; the sync pass is claimed but not shown by CI, and the proposal's HTML examples were replaced with the builder's own.
  • UNCLEARExisting tests and build pass, and new CSS follows existing naming and file conventions.The CSS follows `.component-variant/-part` naming in `components.css`, but no CI ran, so passing tests and build cannot be confirmed.
Concerns
  • No CI checks ran on this commit. The claims that `npm test` passes (80/80) and the build succeeds rest only on the builder's word, and the optional Playwright check (`check-components-browser.mjs`) that exercises real layout was probably not run.
  • The spec puts showcase site changes out of scope unless the maintainer confirms. This PR edits `showcase/index.html`: an avatar demo card, alert icons, an accent swatch and a token-count badge. It looks needed because the existing class checks and the new browser assertions read the showcase, but the maintainer should sign off.
  • The spec asks to "include the HTML examples from the proposal". The builder did not have them and wrote its own. It extended the existing Dashboard example, citing a 4-example cap, and added one invalid example. Backers should check these match what the proposal intended.
  • The version was not bumped. The builder cites `docs/releasing.md` saying PRs must not change the version, which seems consistent with the spec's "follow the existing convention", but that doc is not in the diff to confirm.
  • `.avatar-success` draws its foreground as a 90/10 mix with `--color-text`, not pure `var(--tone)`. The spec allows this adjustment and the PR documents it. With `.alert-icon`, loose text nodes in an alert land in auto-placed grid cells; this is documented ("wrap loose text in a <p>") rather than handled.
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.

Motivation

Dashboards need small square or round chips for initials, photos and icons on a tinted background. SynthCSS has no component for these, and no non-status decorative hue. In a benchmark, agents hand-wrote 21–70 lines of custom CSS per page, invented --color-accent, and in one run added unsanctioned classes. Alerts with an icon also render the icon above the text, because .alert is a column flexbox.

Scope

1. Token

Add --color-accent to the default theme alongside the status colours.

  • It is a violet hue.
  • It must meet WCAG AA (4.5:1) as text on its own tint: color-mix(in srgb, var(--color-accent) 12%, var(--color-background)).
  • Add it to any other theme that already exists in the repo.
  • Add it to the token reference docs.

2. .avatar component

The component goes in the existing components stylesheet, following the conventions from #4.

Base class .avatar:

  • Works on <span>, <div> or <img>.
  • Uses inline-flex and centres its content both ways.
  • Uses a fixed equal width and height.
  • Default size equals --control-height.
  • Corners are --radius-md.
  • Sets overflow: hidden and flex-shrink: 0.
  • Initials use a font-weight and font-size scaled to the avatar and do not wrap.
  • A child <img>, or .avatar on an <img> itself, fills the box with object-fit: cover.
  • A child <svg> is sized proportionally (about 50–60%) and uses currentColor.

Variants:

  • .avatar-round uses --radius-full.
  • .avatar-sm and .avatar-lg give smaller and larger size steps derived from --control-height with calc(). Assumption: roughly 0.75× and 1.5×.
  • Tone variants are .avatar-primary, .avatar-success, .avatar-warning, .avatar-danger, .avatar-info and .avatar-accent.
    • Each sets a local --tone custom property.
    • Background is color-mix(in srgb, var(--tone) 12%, var(--color-background)).
    • Foreground colour is the tone.
  • Assumption: an untoned avatar uses a neutral surface or muted background with the normal text colour.

3. .alert-icon

Add an .alert-icon part so that an icon inside .alert sits to the left of the content, aligned to the top. The content keeps its existing stacking.

  • Assumption: implement with .alert:has(> .alert-icon) switching to a two-column grid or row flex, with a fixed icon size.
  • Alerts without an icon must render exactly as before.

4. AI contract

Update both synthcss.llm.md and synthcss.ai.json with:

  • the new token;
  • the avatar classes and variants;
  • .alert-icon.

Add these Intent Mapping entries:

  • "Person initials or photo" maps to .avatar / .avatar-round.
  • "Icon on a tinted tile" maps to .avatar with a tone variant.

Include the HTML examples from the proposal. Bump version metadata following the project's existing convention.

Acceptance criteria

  • --color-accent is defined in the default theme and documented in the token reference.
  • .avatar renders initials, an image and an svg icon centred at a fixed square size. It has .avatar-sm, default and .avatar-lg sizes, all derived from --control-height.
  • .avatar-round produces a circle, and the default uses --radius-md.
  • All six tone variants exist and derive their tint via color-mix(... 12%, var(--color-background)), so token overrides propagate.
  • Each tone's foreground on its tint meets WCAG AA 4.5:1 with default tokens. This is verified by a test or script, or documented with computed ratios in the PR. If a tone fails, its foreground is adjusted and the PR explains how.
  • .alert containing .alert-icon shows the icon beside the content. .alert without an icon is unchanged.
  • synthcss.llm.md and synthcss.ai.json list all new classes and the token, plus the two Intent Mapping entries. The existing contract sync verification passes.
  • Existing tests and build pass. New CSS follows existing naming and file conventions.

Out of scope

  • Avatar groups or stacks, status dots, badges on avatars, and image fallback logic.
  • Additional decorative hues beyond --color-accent.
  • Showcase site changes, unless the maintainer confirms otherwise.

No comments yet.