Release retrospective

@ponchia/ui — the road to 0.5.0

Every release from the first standalone 0.1.0 to the analytical-and-report milestone 0.5.0, and what each one added to the design system.

Print copy: generated for archive review.

Executive summary

@ponchia/ui is a CSS-first design system for interfaces that explain themselves — it works in plain HTML, in every framework, and in PDF, with no component runtime. Over 14 releases it grew from a re-skinned "Nothing"-inspired CSS bundle into a governed system with a typed class contract, optional framework bindings, a five-tier color constitution, CSS-native motion, and an opt-in analytical & report layer.

The throughline: keep plain CSS as the universal substrate and add thin, opt-in layers on top — never a component framework. Breaking changes are rationed to the minor; everything else lands as additive, drift-checked surface.

Releases 14 0.1.0 → 0.5.0
Current 0.5.0 2026-06-02
Runtime deps 0 by design
CI gates 24 +22 since 0.2

Release timeline

All 14 releases shipped between 2026-05-15 and 2026-06-02 — a tight, review-driven cadence. The headline release of each line is marked live.

  1. 0.1.0 — first standalone release; Nothing-inspired re-skin.
  2. 0.2.0–0.2.2 — cascade layers, tokens-as-data, typed classes, behaviors, hardening.
  3. 0.3.0 — multi-POV review; legacy vocabulary removed, all surface under .ui-*.
  4. 0.3.1–0.3.6 — six adoption/discoverability patches; glyphs land.
  5. 0.4.0 — the color-system release (ADR-0001 steps 1–8).
  6. 0.4.1 — CSS-native motion + static report kit (ADR-0002).
  7. 0.5.0 — the analytical & generated-report layer.

How the surface grew

The default bundle is gated by a raw-size budget on every release. Growth is deliberate and recalibrated in the open — the analytical primitives that headline 0.5.0 are opt-in leaves and stay out of the default bundle.

Fig 1 — Default bundle raw size (kB) across selected releases
  • dist/bronto.css — raw kB
Default bundle raw size by release Measured dist/bronto.css raw size climbs from about 62 kB at 0.2.2 to 78.1 kB at 0.5.0, staying under the 80 kB budget ceiling marked by the threshold rule. 62 54 64 73 77 78.1 0.2.2 0.3.0 0.3.2 0.3.5 0.4.1 0.5.0 80 kB cap budget ceiling
Default bundle raw size by release (approximate)
Release Raw kB Gzip kB
0.2.2 ~62 ~11
0.3.0 ~54 ~10
0.3.2 ~64 ~11
0.3.5 ~73 ~12.7
0.4.1 ~77 ~13.1
0.5.0 78.1 13.6
0.5.0 cap 80 14.5

Bars are the measured dist/bronto.css raw size (0.5.0 = 78.1 kB, taken from the working tree); the threshold rule is the 80 kB gate ceiling, not a data point. Earlier figures are the documented per-release CHANGELOG sizes. Opt-in leaves (colorways, data-viz, analytical primitives, report kit) are excluded from the default bundle by design.

0.1.x — the standalone package

0.1.0 · 2026-05-15 · First release

The library was extracted into its own standalone package and re-skinned to a Nothing-inspired design language: a monochrome dual light/dark palette, a single red accent, the Doto dot-matrix display type, flat hairline surfaces, sharp radii, and no soft shadows.

  • motion.css — keyframes plus reveal / stagger / skeleton / spinner / caret utilities with full reduced-motion handling.
  • dots.css — dot-grid surfaces, dotted rules, the live-pulse status dot, dot loaders and progress, matrix-reveal.
  • forms.css — input, select, textarea, search, switch, checkbox.
  • table.css — ui-table with dense / comfortable / lined variants and numeric helpers.
  • An expanded admin shell (app.css): rail with dot nav, blurred sticky topbar, toolbar, panel, metric tiles, empty state, mobile collapse.

0.2.x — the optional layers

0.2.0 · 2026-05-15 · Architecture

The architectural turn: keep plain CSS as the universal substrate, add thin optional layers on top. The whole framework now ships inside @layer bronto, so un-layered consumer CSS overrides it without specificity fights.

  • @ponchia/ui/tokens — design tokens as data (canonical JS, generated JSON, typed themeColor()).
  • @ponchia/ui/classes — a typed class-name contract: the cls registry, ui.* recipe builders, cx().
  • @ponchia/ui/behaviors — vanilla, SSR-safe, dependency-free helpers (theme, dismissible, disclosure).
  • Published to npm as @ponchia/ui with provenance; drift gates check-tokens / check-classes added.

0.2.1 · 2026-05-15 · Hygiene

Removed private project names and personal paths from shipped CSS comments and docs (no selector or token changes). Supersedes 0.2.0, which still carried those references.

0.2.2 · 2026-05-15 · Framework hardening

Component and mobile expansion followed by a framework-grade hardening pass driven by multi-agent review.

  • RTL / logical properties across every file, lint-enforced.
  • A11y: initTabs WAI-ARIA pattern, forced-colors support, WCAG contrast fixes, an axe gate.
  • Theming contract: --accent as one knob; density and high-contrast presets.
  • content.css: .ui-prose styles raw Markdown HTML with zero per-element classes.
  • Prebuilt bundles (dist/bronto.css), Playwright visual snapshots, DTCG token export, and a print stylesheet.

0.3.x — adoption & hardening

Seven releases of review-driven, mostly-additive adoption work. The 0.3.0 cleanup was the one breaking gate; everything after it landed as patches under the 0.x "only the minor may break" policy.

0.3.0 · 2026-05-16 · Multi-POV review · BREAKING

A six-perspective review drove the big cleanup: the entire non-ui-* legacy vocabulary was removed or migrated, so everything shipped now lives under the .ui-* contract and the check-classes drift gate.

  • New --accent-text token so a pale re-brand can't silently fail text contrast; --focus-ring wired live.
  • Generated literal .d.ts types — mistyped class/token keys are now compile errors.
  • Per-leaf imports are now layer-safe; the raw escape hatch moved to css/unlayered/*.
  • First-class site.css content shell and ui-quote; an optional Shiki theme.

0.3.1 · 2026-05-16 · 12-POV adoption

ui-combobox, ui-popover, initFormValidation, initTableSort, busy buttons; form/layout primitives; semantic --bronto-color-* and ramp tokens; a generated reference, framework guides, and example apps.

0.3.2 · 2026-05-16 · Re-skin-proven adoption

Promotes genuinely generic, token-only primitives upstream: ui-stat/ui-statgrid, ui-link--cta, ui-badge--dot/--muted, ui-num, ui-dotmatrix, ui-container--wide — all non-breaking, with permanent aliases for the old shell-locked names.

0.3.3 · 2026-05-16 · Consumer evidence + discoverability

tokens/resolved.json (every color resolved to hex per theme, for canvas/WebGL/SVG); button size scale; a shell-agnostic ui-empty-state; a controlled ui-modal is-open path; llms.txt and shipped docs in the tarball for offline agents.

0.3.4 · 2026-05-17 · A11y + adoption pass

A CI-gated WCAG 2.1 contrast matrix (docs/contrast.md, check:contrast); a docs/usage.md decision guide; the info status tone wired through the full status family; a full re-skin recipe proving "Nothing" is a token skin, not the architecture.

0.3.5 · 2026-05-29 · Six requested primitives

Primitives adopters were hand-rolling: ui-pagehead, ui-steps, ui-timeline, ui-meter, ui-kbd, ui-input-icon, plus a scroll-snap ui-carousel + initCarousel and a <dialog>-based lightbox.

0.3.6 · 2026-05-31 · Display glyphs

@ponchia/ui/glyphs — a frozen 43-glyph 16×16 dot-matrix display-icon set rendered on the existing .ui-dotmatrix primitive (no SVG, no icon font), with a solid mode legible as an inline icon down to ~16px and an initDotGlyph() behavior. The GlyphName union is generated and drift-checked.

0.4.x — color & motion

0.4.0 · 2026-05-31 · The color system · BREAKING

A governed evolution beyond pure monochrome — ADR-0001 steps 1–8. The tier model is written down and enforced (check:color-policy), and the "Nothing" look is proven to be a skin, not the architecture.

  • Colorways (skins.css): amber CRT · phosphor green · e-ink, each a contrast-gated one-hue re-point, opt-in only.
  • Data-viz palette (dataviz.css, charts.json): accent-led + Okabe-Ito, colourblind-gated, with pattern fills so colour is never the sole signal.
  • OKLCH authoring + a perceptually-even accent ramp; an APCA advisory contrast track.
  • Optional React + Solid bindings; a one-node glyph mask render path + .ui-icon.
  • The only break: the orphan --orange token was removed.

0.4.1 · 2026-06-01 · Motion + the report kit

Patch hardening plus the first step of the modern-platform motion direction (ADR-0002) — and the static report kit this very document is built on.

  • Static report kit (css/report.css, docs/reporting.md): covers, sections, summaries, findings, evidence, chart wrappers, and print utilities — PDF-first, opt-in, runtime-free.
  • Zero-JS enter and exit motion for dialog, drawer, popover, toast, and accordion via @starting-style + allow-discrete.
  • Scroll-driven motion and View Transitions as progressive enhancement; browser floor raised (Chrome 125 / Safari 18 / Firefox 129).
  • Optional Qwik bindings; OLED data-surface="oled"; a re-tuned, more readable dark theme.

0.5.0 — the analytical & report layer

The release that builds out the "analytical & generated-report UI" identity: a full suite of opt-in communication primitives, each owning its own visual grammar and pure geometry while refusing to own scales, state, or hit-testing — so none of them is a chart engine.

0.5.0 · 2026-06-02 · Added — the analytical suite

  • SVG annotations (annotations.css) — the d3-annotation grammar: subject · connector · note, with many variants, six tones, and reduced-motion-safe draw/reveal motion.
  • Legends / data keys (legend.css) — a standalone data-key layer reading the --chart-* palette; WCAG 1.4.1 by construction; optional series-toggling.
  • Text marks / evidence (marks.css) — sober, report-grade emphasis for running prose (the inline counterpart to SVG annotations).
  • Connectors / leader lines (connectors.css) — a line between two DOM elements; the geometry kernel now single-sources both connectors and annotations.
  • Spotlight, crosshair / readout, and selection states — guided focus, a plot ruler that reports position (not data), and an on/off/maybe emphasis vocabulary.
  • Sources, citations & provenance (sources.css) — a CSS-only trust layer: "where did this come from?", with verified/reviewed/generated/unverified/stale/conflict states.
  • Label declutter + direct labels — deterministic 1-D de-overlap and direct-labeling helpers (pure, no DOM/scales).
  • Plus a command palette, workbench tool-UI core, lifecycle/system state, generated-content trust surfaces, the .ui-shortcut hint, and an analytical.css roll-up.

0.5.0 · Changed — three rationed breaks

Per the versioning policy, the minor carries the breaking changes — here, three small ones, all mechanical:

  1. The chart data key moved out of the report kit into the standalone .ui-legend layer.
  2. Annotation arrowheads now render via the shared connectors geometry kernel — a small path-shape change.
  3. The opt-in marks' rationed-accent tone was renamed evidence → accent to match the rest of the analytical vocabulary.

The default dist/bronto.css is otherwise unchanged. The Doto webfont also moved to woff2-only, cutting the six-weight payload from ~823 kB to ~35 kB.

Pinning Pre-1.0, breaking changes ship in the minor — pin to the minor (~0.5.0). A bare ^0 / * wildcard does not protect you.
New CSS layers 13 all opt-in
Breaking changes 3 mechanical
Font payload 35 kB −96%

Release matrix

Every @ponchia/ui release and its headline contribution
Version Date Kind Headline
0.1.0 2026-05-15 Initial Standalone package, Nothing-inspired re-skin
0.2.0 2026-05-15 Minor Cascade layers, tokens-as-data, typed classes, behaviors
0.2.1 2026-05-15 Patch Scrub private references from shipped CSS
0.2.2 2026-05-15 Patch RTL, a11y, theming contract, prebuilt bundles
0.3.0 2026-05-16 Minor (breaking) Legacy vocabulary removed; all surface under .ui-*
0.3.1 2026-05-16 Patch Combobox, popover, form validation, table sort
0.3.2 2026-05-16 Patch Stat, num, dotmatrix and friends promoted upstream
0.3.3 2026-05-16 Patch Resolved-color JSON, llms.txt, offline docs
0.3.4 2026-05-17 Patch Gated WCAG contrast matrix, usage guide, info tone
0.3.5 2026-05-29 Patch Six requested primitives + carousel/lightbox
0.3.6 2026-05-31 Patch 43-glyph dot-matrix icon set
0.4.0 2026-05-31 Minor (breaking) Color system: colorways, data-viz, OKLCH, bindings
0.4.1 2026-06-01 Patch CSS-native motion + the static report kit
0.5.0 2026-06-02 Minor (breaking) The analytical & generated-report layer

Sources

  • CHANGELOG.md — the curated, per-release narrative (and the GitHub Release body since 0.4.0).
  • docs/adr/0001-color-system.md — the five-tier color constitution behind 0.4.0.
  • docs/adr/0002-scope-and-2026-baseline.md — the modern-platform motion direction and browser floor behind 0.4.1.
  • docs/reporting.md — the report grammar this document is composed in.
  • package.json — current version 0.5.0, zero runtime dependencies.

Generated as a dogfooding test of the @ponchia/ui report layer — static HTML, no behavior JS, Chromium PDF-ready.