brontoui
GitHub
Docs Reference & maintenance

Documentation

The full docs set for @ponchia/ui. The curated subset listed in package.json files also ships inside the npm tarball, so an offline agent or consumer gets it under node_modules/@ponchia/ui/docs/. A navigable static documentation site with individual, shareable pages is published at Bronto UI documentation. The original Markdown remains available for offline agents and direct reading.

New to the repo? Start with architecture.md → Repository layout for what each top-level directory is and which files are generated.

Upgrading? Start with MIGRATIONS.json for machine-readable rename rules, then use migrations/ for version-by-version notes.

Start here

Getting started (frameworks)

Usage & concepts

  • concepts.md — the canonical mental model: CSS-first surface, cascade layer, colour tiers, primitive ownership, token projections, and package shape.
  • usage.md — the decision guide: which primitive to reach for when.
  • frontier-primitives.md — the design line for new analytical/communication primitives.
  • reference.md — the generated catalog of every .ui-* class and token. (generated — do not hand-edit)

Theming & color

  • theming.md — the root-level --accent model, its limits, and a full re-skin recipe.
  • contrast.md — the CI-gated WCAG contrast matrix (+ APCA advisory).

App/service primitives

  • state.md — lifecycle / system-state vocabulary and sync bar.
  • generated.md — trust surfaces for AI / system-generated content.
  • command.md — the command-palette shell + behavior.
  • workbench.md — tool-UI core (inspector, property rows, selection bar).

Reports & analytical primitives

  • reporting.md — the static, PDF-first report grammar and the analytical toolbox available to a report.
  • figure.md — reusable chart/diagram/media figure stage with overlay, key, and fallback-data slots.
  • discussion.md — thread lists, quotations, messages and composers with host-owned state.
  • annotations.md — SVG annotations (subject / connector / note), off-chart use, and the geometry helpers.
  • legends.md — standalone data keys / legends.
  • mermaid.md — theme Mermaid diagrams from bronto tokens, and annotate the rendered SVG.
  • d2.md — theme D2 diagrams from bronto tokens (theme-override slots), and annotate the rendered SVG.
  • vega.md — theme Vega-Lite charts from bronto tokens (resolved config) — the recommended path when a report needs a chart, since bronto ships no chart component.
  • marks.md — text/evidence emphasis for running prose (ui-mark, ui-bracket-note).
  • dots.md — the dot-matrix surface family: backgrounds, loaders, readouts, and data-bound dot primitives.
  • glyphs.md — the display glyph API built on the dot-matrix primitive.
  • sources.md — the citations / provenance trust layer.
  • interval.md — host-normalised low/high uncertainty spans for estimates and evidence windows.
  • clamp.md — bounded excerpts with optional CSS-only show-more / show-less reveal.
  • highlights.md — CSS Custom Highlight API paint for evidence, search, and current ranges.
  • diff.md — line/row change-review grammar (ui-diff, add/remove/context rows).
  • code.md — fenced-code evidence chrome (ui-code, line numbers + add/del/hl states; never parses).
  • spark.md — inline datawords / word-sized microcharts (ui-spark, host-normalised --v).
  • sidenote.md — Tufte margin notes (ui-sidenote numbered, ui-marginnote plain).
  • textref.md — deep-link a citation to the exact cited sentence (ui-textref + ::target-text paint).
  • bullet.md — Stephen-Few bullet graph: measure vs target vs grayscale bands (ui-bullet, host-normalised --v/--t).
  • term.md — inline glossary term + definition popover and end-of-report <dl> (ui-term/ui-def/ui-glossary).
  • toc.md — sticky scrollspy table-of-contents rail (ui-toc, aria-current active section).
  • tree.md — hierarchy outline on nested <details> (ui-tree branches/leaves; disclosure group, not an ARIA tree).
  • connectors.md — leader lines between DOM elements.
  • renderer.md — the live theme resolved for canvas, WebGL and SVG renderers.
  • spotlight.md — guided-focus overlay.
  • crosshair.md — plot ruler + pinned readout.
  • selection.md — cross-cutting selection-emphasis vocabulary.

Contract & governance

  • Package maintenance or agent integration — start with architecture.md, stability.md, and ../llms.txt.
  • architecture.md — the layered architecture, the repository layout, drift control, and release gating.
  • stability.md — what is contractual (and what is a convenience preset) across versions.
  • package-contract.md — the generated package manifest matrix: every export, shipped path, and artifact provenance row. (generated — do not hand-edit)
  • release.md — the release runbook.
  • repository-map.md — the top-level directory map: what each directory owns, which are authored vs generated, and what to regenerate after editing each.
  • adding-a-primitive.md — the end-to-end playbook for adding a new primitive: layer choice, CSS/classes/tokens, exports, the docs/demo/e2e matrices, regeneration, and gates.

Architecture Decision Records

Migrations