Skip to main content
jax
home install tokens components htmx guide case study grounding changelog roadmap
Getting Started
Home Installation Design Tokens HTMX Guide case study grounding changelog roadmap
Components
Button Card Media Card Badge Form Alert Dialog Table Navbar Tabs Accordion Toast Dropdown Spinner Skeleton Toggle Tooltip File Input Tag Segmented Drawer Stat Card Gauge Sparkline Radio Group Data Table Feed & Hero Prose
Layout
Container Grid Stack

changelog

Brief, actionable updates assembled from docs/changelog/*.jsonl.

in development

2026-08-27 - Five widget families: media, prose, data table, feed, navigation macros

The kit now covers every recurring pattern that previously needed a per-project implementation: picture-led cards, long-form reading, filterable sortable tables, chronological feeds with a profile hero, and Jinja APIs over the existing navigation CSS.

  • Added components/media.css: .media-card (plus horizontal and overlay variants), .media-cover with five ratio classes, .media-placeholder, and .media-grid at four densities. Ratio is a class because the template guard forbids inline style, so the shipped ratios are the whole set.
  • Added components/prose.css: .article-header, a .prose container measured at var(--measure), .prose-figure, .prose-row, .prose-sheet, .pullquote, .compare, and .prose-bleed.
  • Added components/datatable.css and the <jax-table> web component: search, per-column filters, sortable headers, and an aria-live count over a real <table>. Sort buttons are injected rather than authored, so with JS off the header stays plain text instead of a dead control.
  • Added components/feed.css: .feed as hairline-separated records (.feed-boxed opts into boxes), .feed-entry-media for media objects, and .profile-hero whose classifier sits under the title rather than as an eyebrow above it.
  • Added .stat-row/.stat-item to data.css: the flat sibling of stat-card, for measured facts that live inside another component.
  • Extended nav.css with .pagination-bar, .pagination-gap, .per-page, and .prevnext, and added the breadcrumb, pagination, pagination_bar, and prev_next macros over them.
  • New tokens: --font-size-display, --line-height-display, --letter-spacing-tight, --measure, --measure-tight.
  • Raised the CSS budget to 20KB gzipped and the JS budget to 10KB. Current build: 12.5KB CSS, 5.7KB JS.
  • Workbench gained media, prose, datatable, and feed benches, each with specimens and a design contract; the registry order now follows the bundle order.
  • A disabled pagination arrow now renders as a <span> rather than a dimmed <a> — an anchor with an href stays keyboard-activatable however it is styled.

rationale: These five families were the whole gap list, derived from real duplicated markup in a private site project. Filling them in the kit, on the kit's existing contract, is the alternative to a sixth per-project design system.

2026-08-27 - Colour schemes: the palette becomes a swappable module

Colour moves out of tokens.css into one file per scheme. jax.core.css is every rule with no colour values; a scheme supplies the palette and is chosen at import. Six ship: ember, moss, cobalt, viola, teal, mono.

  • Split tokens.css: it now holds every non-colour token plus the formulas (focus rings, scrims, dropdown shadow) that read colour, and documents the colour contract — the exact 26 tokens a scheme must define. It names no colour itself
  • Added css/schemes/<name>.css, one per scheme, each defining the whole contract. ember keeps its hand-tuned values verbatim; moss, cobalt, viola, teal and mono were generated in OKLCH by solving each role's lightness against the contrast targets rather than picked by eye
  • Both modes now live in one declaration per token: light-dark(light, dark), with tokens.css setting color-scheme from [data-theme] or the OS. This deletes the duplicated light palette — the old file carried the light values twice, once under prefers-color-scheme and once under [data-theme=light], which is exactly the pair that would have become 12 hand-synced blocks at six schemes
  • Dropped every --*-rgb token. Tints are color-mix(in srgb, var(--token) N%, transparent), which is what makes light-dark() usable for the whole contract: light-dark() takes colours, not the bare rgb triples the old rgba(var(--x-rgb), a) pattern needed. 25 call sites converted; the three hardcoded rgba(0,0,0,x) overlay scrims became var(--shadow), so they warm up in light like the rest of the palette
  • jax-contrast-check now runs every scheme x both modes and fails on a missing contract token, so a new palette cannot ship until it is both complete and accessible. jax-build --scheme <name> picks the default baked into jax.css, and emits jax.core.css plus every scheme standalone, each under a new 1KB gzip budget
  • Added jax.scheme (js/scheme.js, ~700B): swaps the scheme stylesheet and persists the choice. Only needed when a page ships more than one scheme — the normal case stays a single <link> and no JS. The docs and the workbench both grew a scheme picker; workbench frames take theirs from the URL, the same way they already took the theme

rationale: The palette was the one part of the language that could not be swapped without editing the language. Isolating it was cheap — no component held a raw hex, so nothing outside tokens.css had to change structurally — but the byte budget ruled out shipping all six at once and switching at runtime: the bundle was already at 9.9KB of 10KB. Selection therefore happens at import, one scheme per page, and each scheme costs 0.4KB gzip. Collapsing the duplicated light palette and deleting the --*-rgb tokens paid for the split outright: the default bundle came down to 9.6KB.

2026-08-26 - Light theme repalette: warm paper, deeper status lines

The light theme moves off pure white and neutral grey onto a warm paper scale, with status hues deepened at source so borders and status edges clear the 3:1 non-text threshold.

  • Replaced the light surface and text scale with warm neutrals (bg #ffffff -> #fbfaf7, #f4f4f4 -> #f2efe8, #eaeaea -> #e8e5dd; borders #d0d0d0 -> #d9d4c9, #e0e0e0 -> #eae6de; text #111111 -> #1f1c17 through to #777777 -> #77705f), so the neutrals share a hue family with the amber instead of fighting it
  • Deepened the light status colours at source (ok #27ae60 -> #2f8757, warn #f39c12 -> #b0790e, error #c0392b -> #b84a3c, info #3498db -> #35719e) with matching text tokens; because badge fills are a 15% tint, a deeper source keeps the fill pastel while making the 1px border and 3px card edge legible
  • Retoned the light accent instead of re-hueing it: --accent and --color-accent-solid are both #d1731f, which is dark mode's #e67e22 at the same hue (28) and saturation (85%) with its value dialled down for paper. --text-on-accent flips to the darkest neutral in the theme (#1f1c17), matching what dark mode already does, and that is what keeps the fill a true amber: a light label forces the fill down to about #b34b00 to clear AA, which is where the rust came from
  • Warmed --shadow-rgb and --highlight-rgb in light from 0, 0, 0 to 61, 52, 40 so dropdown shadows and tag washes sit on the same warm axis as the surfaces
  • Added component_checks to jax-contrast-check enforcing 3.0:1 for --accent and the four status colours against --bg-primary in both themes; --border-color is exempt as a structural hairline
  • Light's fill brightens on hover (#dd8129) where dark's deepens (#d35400). With dark ink the fill sits inside a narrow luminance band (0.228-0.285); deepening it would drop the label below 4.5:1

rationale: Light mode read muddy because two things were fighting: dead-neutral greys under a warm amber accent, and status hues picked for a dark background. The new non-text check is what makes this enforceable rather than a matter of taste -- the previous light palette failed it on --color-ok (2.87:1) and --color-warn (2.19:1), so status edges there were decoration rather than state. The accent itself stays ember in both themes -- the light problem was tone, not hue: a light label on the fill forced a dark rust that read nothing like the amber it is in dark mode.

2026-08-26 - Button redesign: corner marks replace brackets, lg becomes a density step

Buttons are now framed by four corner marks revealed on hover and focus rather than by literal [ label ] brackets, the primary is the kit's one filled control, and .btn-lg drops its type step.

  • Replaced bracketed labels with four corner marks drawn as eight background-image hairlines on .btn; the marks size to 0 at rest and grow in on :hover/:focus-visible, use currentColor so they track the label, and consume no pseudo-elements, so .btn-text/.btn-loading stay free and the htmx loading swap is unaffected
  • Made .btn-primary the one filled control (solid accent, no marks -- the fill is already the affordance) and .btn-secondary frameless at rest, with the marks as its whole affordance
  • Added --color-accent-solid, --color-accent-solid-hover, and --text-on-accent to tokens.css: --accent is tuned to read as a line on --bg-primary, and white on light's #d35400 is only 4.17:1, so a label sitting ON the fill needs its own pair rather than a [data-theme] override in button.css
  • Extended jax-contrast-check to enforce that pair (4.5:1 for the label on the fill and on its hover, 3.0:1 for the block against the page) in both themes
  • Retargeted .btn-lg as a density step, not a volume step: 44px and --space-3/--space-4, with no font-size change. It previously declared min-height 44px but rendered 49px, because 18px x --line-height-tight plus padding overflowed the min-height; that made it +13px against a 36px md and +10px against the field beside it
  • Fixed lg getting NARROWER on mobile than on desktop: the mobile branch's .btn padding rule is later in the file at equal specificity (0,1,0) and silently overrode .btn-lg's, cutting it from 115px to 99px. lg now declares the same metrics, so the two rules agree
  • Added an always-on mark for .btn-secondary under (max-width: 768px), since coarse pointers never fire :hover and a frameless secondary would otherwise have no affordance at all
  • Suppressed marks inside .btn-group, where neighbouring corner sets sit 1px apart and merge into a single shape
  • Dropped the bracketed= parameter from the btn() macro, stripped 101 literal [ label ] pairs across 16 docs templates, and removed the bracket-writing label logic from actions.js, clipboard.js, and workbench.js
  • Updated the button design contract in workbench.py, the LLM grounding button_contract fact, the components page copy, and design rule 6 in CLAUDE.md

rationale: Brackets were padding you could see: at 14px mono they added ~17px of optical inset per side on top of the CSS padding, giving a 3.23:1 horizontal-to-vertical inset ratio against a 1.5-2.0 target, which is what made the button read squat and over-wide. Corner marks sit ON the box edge and cost nothing, so the same label fits a 1.84:1 box. The lg change is separate: it was the only control in the kit that stepped its type, which made it read as a different component rather than a bigger one, and the repo backs that up -- btn-lg appeared three times and all three were demos of itself, while btn-sm was used ~25 times in real UI.

2026-08-25 - Form validation states tokenized and specificity-corrected

Validation rings now resolve through tokens, and error/ok state colours survive focus instead of being overridden by base input styles.

  • Added `--shadow-focus-error` and `--shadow-focus-ok` to `tokens.css`, matching the `--shadow-focus` geometry; a single `:root` definition is enough because custom properties resolve their inner `var()` per theme at use time
  • Replaced all five hand-rolled `0 0 0 2px rgba(...)` rings in `form.css` with the new tokens, clearing the file's remaining cohesion drift
  • Paired `.is-error`/`.is-ok` with `.form-input.is-error`/`.form-input.is-ok` so the state border outranks the `input[type=...]` base rule in `base.css`, which previously left `.is-ok` rendering the default border with no colour at all
  • Made all five validation `:focus` rules re-assert their own `border-color`, including the two inside `@supports selector(input:user-invalid)`, so `input:focus { border-color: var(--accent) }` no longer repaints an error field's border accent while its ring stays red

rationale: The server-rendered `.is-error`/`.is-ok` fallback was visually inert and every state lost its colour on focus. Routing the rings through tokens keeps the shadow rule enforceable by the cohesion check.

2026-08-25 - Component workbench and cohesion drift check

Added a dev-only per-component workbench at `/workbench` plus `jax-cohesion`, a mechanical token-drift check wired advisory-only into the build.

  • Added `jax_ui.scripts.cohesion` (`uv run jax-cohesion`, `--component <id>`) enforcing that colour, radius, shadow, spacing, type-scale, and motion values resolve through a token, with `tokens.css` exempt as the one file allowed to hold literals
  • Wired cohesion into `jax-build` as an advisory report that prints drift counts per file but never fails the build, so an existing backlog cannot block a release
  • Added `docs/workbench.py` with a component registry as the single source of truth for each component's CSS, Jinja macros, JS, and design contract
  • Added `/workbench` index and `/workbench/{id}` bench routes rendering specimens in sandboxed dark and light iframes at selectable viewport widths (360/768/1024/full), isolating components from docs chrome
  • Added a handoff panel that copies the file map, full design contract, and live drift list into an LLM-ready prompt
  • Added `.wb-*` docs-only styles, a `workbench_enabled`-gated navbar link, and a `just bench` recipe; the workbench is excluded from the published static site

rationale: Design-rule violations were previously caught only by review. A mechanical check plus per-component isolation makes drift visible where the work happens, without gating releases on a pre-existing backlog.

2026-02-17 - UI coherence pass and core-only JS bundle

Applied a full docs/component coherence pass, normalized control proportions, and restricted the shipped JS bundle to reusable UI-kit runtime only.

  • Introduced shared control sizing tokens (`--control-height-sm|md|lg`, `--touch-target-min`) and applied them across buttons, nav controls, form controls, sidebar links, and dialog/drawer close controls
  • Normalized spacing rhythm in badges/tags/tooltips/sparkline via tokenized spacing values
  • Added HTMX guide into top and sidebar navigation and corrected grounding/case-study copy defects
  • Updated JS build composition to include only core UI-kit runtime modules (theme, actions, toast, dropdown, tabs), excluding docs/demo helpers (`clipboard.js`, `flash.js`) from `jax.js`/`jax.min.js` and default Jinja layout
  • Extracted docs-only interaction handlers (summary-safe controls, segmented demos, pagination mock state, drag-drop file demo labels) into `docs-actions.js` loaded only by docs templates

rationale: Keeps published assets productized and predictable for downstream integrators, while preserving rich docs behavior as optional page-level scripts.

2026-02-17 - Wrapping, state semantics, and focus accessibility hardening

Implemented upgrades across the UI kit for robust text handling, accessible current-page semantics, interaction-state validation, and keyboard-first hidden content reveal.

  • Added wrapping utilities (`.text-wrap`, `.text-wrap-anywhere`, `.text-break-spaces`) plus balanced/pretty text fallback behavior
  • Hardened long-string rendering for alerts, toasts, file labels, tables, tags, and badges to prevent overflow regressions
  • Added dense data helpers (`.table-wrap`, `.table-data`) and documented `break-spaces` behavior for key/value and terminal-like content
  • Extended current-state styling to semantic `aria-current` usage in navbar, sidebar, breadcrumb, pagination, and segmented controls
  • Implemented browser-state form validation with `:user-invalid`/`:user-valid` (with fallback) and label feedback via `:has(...)`
  • Upgraded visually hidden patterns with focus-reveal helpers and introduced skip-link behavior in docs base layout

rationale: These changes improve resilience and accessibility without adding runtime dependencies.

2026-02-16 - Mobile navbar pattern standardized

`navbar-collapsible` is now the default mobile navigation pattern in docs, with compatibility-first behavior and CSS-first transitions.

  • Standardized markup pattern: `.navbar-collapsible` + `[data-action="nav-toggle"]` + `.navbar-nav-wrap`
  • Added robust mobile interactions: outside-click close, link-click close, Escape close, single-open behavior, and synced `aria-expanded`/`aria-hidden` state
  • Kept navigation transitions CSS-first (`@view-transition`) and removed JS fallback transition hooks to keep runtime JS lean
  • Scoped navbar view-transition naming to `.site-navbar` to avoid demo-page conflicts and improve cross-page transition reliability
  • Introduced JS-gated menu animation via `.jax-js` so no-JS mobile still keeps navigation accessible

rationale: Replaces horizontal-scrolling header links with a predictable mobile menu while preserving accessibility semantics and reducing JS overhead.

2026-02-16 - Unified checkbox/toggle/radio macro contract

Checkbox, toggle, and radio macros now follow one attribute contract for predictable usage.

  • Supports hx_*, data_*, aria_*, and id passthrough
  • Added optional disabled/required support across controls
  • Checkbox and toggle now support optional value; checkbox and toggle names are optional for JS-driven selection flows

2026-02-16 - Summary-safe controls in accordions

Interactive controls inside <summary> no longer close parent <details> when clicked.

  • Added automatic stopPropagation bindings for summary a/button/select and label.checkbox|toggle|radio
  • Rebinds after HTMX swaps so dynamic content keeps the same behavior

rationale: Prevents accidental accordion toggles while preserving expected checkbox and label interactions.