@ponchia/ui 0.5.0 → 0.6.3

package/css/primitives.css

@@ -71,12 +71,15 @@
   padding-inline: var(--center-gutter, var(--space-md));
 }
 
-/* Intrinsic aspect-ratio box; the media child fills it. */
+/* Intrinsic aspect-ratio box; the media child fills it. The contract is ONE
+   child (a single <img>/<video>/<iframe>). Scope the fill to :first-child rather
+   than every child: a second child would otherwise be forced to 100%/100% +
+   object-fit and stack on top, silently breaking the ratio. (audit C34.) */
 .ui-ratio {
   aspect-ratio: var(--ratio, 16 / 9);
 }
 
-.ui-ratio > * {
+.ui-ratio > :first-child {
   block-size: 100%;
   inline-size: 100%;
   object-fit: cover;
@@ -87,10 +90,18 @@
    (island-safe). Inert until applied, so existing layouts/baselines
    are unaffected. */
 .ui-cq {
-  container: var(--cq-name, bronto) / inline-size;
-}
-
-@container bronto (max-width: 34rem) {
+  /* The container-name is fixed: the `@container bronto (…)` collapse queries
+     below hardcode `bronto`. There is no `--cq-name` knob — the name is not
+     author-tunable, and an author-set `--cq-name` is simply ignored (nothing
+     reads it). Name a different container yourself if you need a custom scope. */
+  container: bronto / inline-size;
+}
+
+/* Logical `max-inline-size`, not physical `max-width`: the container is typed
+   `inline-size`, so the inline axis is the one actually tracked — the logical
+   query matches it in any writing mode (a physical `width` query silently
+   misses in a vertical WM). (component audit C34.) */
+@container bronto (max-inline-size: 34rem) {
   .ui-grid {
     --grid-min: 100%;
   }
@@ -164,7 +175,7 @@
 /* Inside an opt-in .ui-cq container, collapse to one column when the
    container (not the viewport) is narrow — keeps tiles usable in a slim
    panel. Inert without .ui-cq, so baselines are unaffected. */
-@container bronto (max-width: 30rem) {
+@container bronto (max-inline-size: 30rem) {
   .ui-statgrid,
   .ui-app-metrics {
     grid-template-columns: 1fr;
@@ -178,6 +189,12 @@
   border-radius: var(--radius-md);
   display: grid;
   gap: 0.4rem;
+
+  /* These tiles hold IDs / hashes / big numbers — the unbreakable-token case is
+     the common one. A grid item defaults to min-inline-size:auto, so a long
+     value pushes the whole statgrid track wider; allow the tile to shrink so the
+     value can wrap instead (paired with overflow-wrap on __value). (audit C5.) */
+  min-inline-size: 0;
   padding: var(--space-md);
 }
 
@@ -196,8 +213,10 @@
   font-family: var(--display);
   font-size: 1.9rem;
   font-variant-numeric: tabular-nums;
-  letter-spacing: 0.01em;
-  line-height: 1;
+  font-weight: var(--display-weight-strong);
+  letter-spacing: 0.02em;
+  line-height: 1.05;
+  overflow-wrap: anywhere; /* break an unspaced ID/hash rather than overflow (audit C5) */
 }
 
 .ui-stat__delta,
@@ -216,12 +235,32 @@
   color: var(--danger);
 }
 
+/* A direction arrow is the non-colour channel — colour alone (success/danger)
+   fails WCAG 1.4.1, so the tile carries the same ▲/▼ glyph as `.ui-delta`
+   (C13). Marked aria-hidden-equivalent by being generated content; the sign is
+   still in the author's text ("+12%"). */
+.ui-stat__delta.is-pos::before,
+.ui-app-metric__delta.is-pos::before {
+  content: '▲ ';
+  font-size: 0.85em;
+}
+
+.ui-stat__delta.is-neg::before,
+.ui-app-metric__delta.is-neg::before {
+  content: '▼ ';
+  font-size: 0.85em;
+}
+
 /* --- Numeric value vocabulary ---
    The same tabular/aligned/tone intent the table has shipped since
    0.1.0, but freed from `.ui-table` so cards, stats and inline figures
    share one P&L vocabulary. Token-identical to the table's is-num/
    is-pos/is-neg (which stay table-local). */
 .ui-num {
+  /* inline-block so `text-align: end` actually applies: on a bare inline element
+     it computes but never paints (the box is shrink-wrapped), so an author who
+     followed the docs to right-align an inline figure saw no effect. (audit C17.) */
+  display: inline-block;
   font-variant-numeric: tabular-nums;
   text-align: end;
 }
@@ -238,6 +277,58 @@
   color: var(--text-dim);
 }
 
+/* --- Trend delta ---
+   A standalone change indicator: a direction arrow (the non-colour channel,
+   WCAG 1.4.1) plus the figure, tabular so a column of deltas aligns.
+   Direction sets the glyph AND the conventional tone (up = positive,
+   down = negative). When "up" is the bad direction (latency, error rate,
+   cost, churn), add `ui-delta--invert` to swap only the tone — the arrow
+   still reports real direction. Pair with words; the arrow is visual, not a
+   substitute for stating the change. */
+.ui-delta {
+  align-items: baseline;
+  color: var(--text-soft);
+  display: inline-flex;
+  font-variant-numeric: tabular-nums;
+  gap: 0.2em;
+}
+
+.ui-delta::before {
+  font-size: 0.85em;
+}
+
+.ui-delta--up {
+  color: var(--success);
+}
+
+.ui-delta--up::before {
+  content: '▲';
+}
+
+.ui-delta--down {
+  color: var(--danger);
+}
+
+.ui-delta--down::before {
+  content: '▼';
+}
+
+.ui-delta--flat {
+  color: var(--text-dim);
+}
+
+.ui-delta--flat::before {
+  content: '—';
+}
+
+.ui-delta--invert.ui-delta--up {
+  color: var(--danger);
+}
+
+.ui-delta--invert.ui-delta--down {
+  color: var(--success);
+}
+
 /* --- Eyebrow / section label — dot-matrix face --- */
 
 .ui-eyebrow {
@@ -338,6 +429,28 @@
   opacity: 0.45;
 }
 
+/* aria-disabled keeps the element in the a11y tree but the browser does NOT
+   block activation (a real <a class="ui-button" aria-disabled> still navigates,
+   a <button> still fires). `pointer-events: none` kills POINTER activation only
+   — a focused control still fires on Enter/Space, which CSS cannot intercept. So
+   this looks-dead state is NOT keyboard-inert: for that, prefer native
+   `<button disabled>`, run `initDisabledGuard()` (it intercepts Enter/Space on
+   aria-disabled controls), or add `tabindex="-1"` (and drop `href` on a link).
+   See docs/usage.md "Disabled vs aria-disabled". (a11y review C3 / audit C4;
+   native :disabled already inert.) */
+.ui-button[aria-disabled='true'],
+.ui-link[aria-disabled='true'] {
+  pointer-events: none;
+}
+
+/* The button family dims + shows not-allowed via its `:disabled` rule above, but
+   a disabled LINK got only pointer-events:none — it looked fully live. Give it
+   the same visual disabled cue. (component audit C30.) */
+.ui-link[aria-disabled='true'] {
+  cursor: not-allowed;
+  opacity: 0.45;
+}
+
 .ui-button:active {
   transform: translateY(1px);
 }
@@ -363,8 +476,13 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
+  /* The global reduced-motion reset freezes the spin on a single frame with an
+     !important `animation-duration`, so the old non-important `1.4s` slow-spin
+     here was dead code AND left a broken, transparent-topped ring looking like a
+     rendering bug. Drop the dead rule; show a STATIC complete ring instead — a
+     still busy cue with no implied motion. (component audit C15.) */
   .ui-button[aria-busy='true']::before {
-    animation-duration: 1.4s;
+    border-block-start-color: currentcolor;
   }
 }
 
@@ -401,8 +519,8 @@
 
 .ui-link--arrow::after,
 .ui-link--cta::after {
-  border-inline-end: 1px solid currentColor;
-  border-block-start: 1px solid currentColor;
+  border-inline-end: 1px solid currentcolor;
+  border-block-start: 1px solid currentcolor;
   content: '';
   block-size: 0.42rem;
   transform: rotate(45deg);
@@ -410,6 +528,27 @@
   inline-size: 0.42rem;
 }
 
+/* RTL: the logical borders flip sides, but a fixed `rotate(45deg)` then points
+   the chevron UP rather than toward the inline-end (the reading-forward way).
+   Mirror the rotation so the resting affordance points forward in RTL too.
+   (component audit C14.) */
+[dir='rtl'] .ui-link--arrow::after,
+[dir='rtl'] .ui-link--cta::after {
+  transform: rotate(-45deg);
+}
+
+/* Standalone CTA links are tap targets, not inline prose links: on a coarse
+   pointer float them to the WCAG 2.5.8 AA 24px floor (the 2.5.8 inline-link
+   exception doesn't cover a block-level call-to-action, which is what these
+   are). Buttons already auto-grow to ~44px on coarse pointers. (component
+   audit C14.) */
+@media (pointer: coarse) {
+  .ui-link--arrow,
+  .ui-link--cta {
+    min-block-size: 1.5rem;
+  }
+}
+
 /* --- Chip / tag --- */
 
 .ui-chip {
@@ -459,6 +598,10 @@
    (the soft tint can't carry 4.5:1 small-bold tone-on-tone — WCAG). */
 .ui-badge--accent {
   background: var(--accent-soft);
+
+  /* Accent mixes 45% (vs 40% for the status tones below) on purpose: the brand
+     hue is lower-chroma here than the status hues, so it needs a touch more to
+     read at the same border weight. Intentional, not a copy-paste slip. (Q15.) */
   border-color: color-mix(in srgb, var(--accent) 45%, var(--line));
 }
 
@@ -551,6 +694,8 @@
   color: var(--text);
   font-family: var(--mono);
   margin: 0;
+  min-inline-size: 0;
+  overflow-wrap: anywhere; /* IDs/hashes/paths are the common value — break, don't overflow (audit C5) */
 }
 
 /* --- Hover (pointer only) --- */
@@ -593,7 +738,7 @@
 
   [dir='rtl'] .ui-link--arrow:hover::after,
   [dir='rtl'] .ui-link--cta:hover::after {
-    transform: translateX(-0.14rem) rotate(45deg);
+    transform: translateX(-0.14rem) rotate(-45deg);
   }
 
   .ui-chip--accent:hover {

package/css/report.css

@@ -7,6 +7,9 @@
    ========================================================================== */
 
 .ui-report {
+  /* Declare override-surface tokens first so authors can set them. */
+  --report-width: 72rem;
+  --report-padding-block: var(--space-2xl);
   --report-gap: var(--space-lg);
   --report-measure: 74ch;
   --report-page-margin: 18mm;
@@ -14,9 +17,9 @@
   color: var(--text-soft);
   display: grid;
   gap: var(--report-gap);
-  inline-size: min(100%, var(--report-width, 72rem));
+  inline-size: min(100%, var(--report-width));
   margin-inline: auto;
-  padding: var(--report-padding-block, var(--space-2xl)) var(--space-md);
+  padding: var(--report-padding-block) var(--space-md);
 }
 
 .ui-report--compact {
@@ -42,7 +45,7 @@
   padding-block: var(--space-xl) var(--space-lg);
 }
 
-.ui-report__header {
+.ui-report__head {
   align-items: end;
   border-block-end: 1px solid var(--line);
   display: flex;
@@ -56,6 +59,7 @@
   color: var(--text);
   font-family: var(--display);
   font-size: calc(var(--text-xl) * 1.35);
+  font-weight: var(--display-weight-strong);
   letter-spacing: 0;
   line-height: 1.05;
   margin: 0;
@@ -171,6 +175,7 @@
   color: var(--text);
   font-family: var(--display);
   font-size: var(--text-xl);
+  font-weight: var(--display-weight);
   letter-spacing: 0;
   line-height: 1.1;
   margin: 0;
@@ -195,8 +200,7 @@
   margin: 0;
 }
 
-.ui-report__caption,
-.ui-chart__caption {
+.ui-report__caption {
   color: var(--text-dim);
   font-family: var(--mono);
   font-size: var(--text-2xs);
@@ -216,65 +220,88 @@
   padding-block-start: var(--space-md);
 }
 
-.ui-chart {
-  border: 1px solid var(--line);
-  border-radius: var(--radius-md);
+/* --- Comparison layout ---
+   The report layer's "A vs B" / before-after grid — the side-by-side layout
+   reports lean on that the grammar was missing. Fluid-first: columns wrap to
+   a single stack on a narrow screen via auto-fit, so two panels never
+   overflow. `ui-compare__col` is one side, `ui-compare__head` labels it.
+   `ui-compare--2up` pins exactly two equal columns for a hard before/after
+   pairing (still collapsing to one column on a phone). */
+.ui-compare {
   display: grid;
-  gap: var(--space-sm);
-  padding: var(--space-md);
+  gap: var(--space-md);
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr));
 }
 
-/* The chart's data key lives in the standalone, portable `.ui-legend`
-   (css/legend.css), not here — import it beside this kit when a chart needs
-   a legend. The chart owns only its plot + bars + fallback below. */
-.ui-chart__plot {
-  display: grid;
-  gap: var(--space-xs);
+.ui-compare--2up {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
 }
 
-.ui-chart__bar {
-  --chart-value: 0%;
+@media (max-width: 33rem) {
+  .ui-compare--2up {
+    grid-template-columns: 1fr;
+  }
+}
 
+.ui-compare__col {
+  align-content: start;
   display: grid;
-  gap: 0.35rem;
+  gap: var(--space-sm);
 }
 
-/* An author `display` outranks the UA `[hidden]` rule, so re-assert it: a host
-   toggling a series (e.g. from a `bronto:legend:toggle` event) expects
-   `bar.hidden = true` to actually hide the bar. */
-.ui-chart__bar[hidden] {
-  display: none;
+.ui-compare__head {
+  color: var(--text-dim);
+  font-family: var(--mono);
+  font-size: var(--text-2xs);
+  letter-spacing: var(--tracking-wide);
+  text-transform: uppercase;
 }
 
-.ui-chart__label {
+/* --- Labelled meter row ---
+   A multi-meter block (SLO burn, error budgets, capacity) lays out as
+   label | bar | value. The bare `ui-meter` base lives in feedback.css; this is
+   the report-document grammar around it so authors stop hand-rolling the grid.
+   The bar NEVER carries the reading alone (WCAG 1.4.1) — `ui-meter__value` is
+   the data of record, and the bar clamps at 100 so an over-target figure still
+   reads correctly in the value text. Collapses to a stack on a narrow screen. */
+.ui-meter__row {
   align-items: center;
-  color: var(--text-soft);
-  display: flex;
-  font-family: var(--mono);
-  font-size: var(--text-xs);
-  gap: var(--space-sm);
-  justify-content: space-between;
+  display: grid;
+  gap: var(--space-2xs) var(--space-md);
+  grid-template-columns: minmax(9rem, 14rem) 1fr auto;
+  margin-block: var(--space-2xs);
 }
 
-.ui-chart__track {
-  background: var(--panel-soft);
-  border: 1px solid var(--line);
-  block-size: 0.8rem;
-  min-inline-size: 0;
+.ui-meter__row .ui-meter {
+  min-inline-size: 8rem;
 }
 
-.ui-chart__fill {
-  background: var(--chart-color, var(--chart-1, var(--accent)));
-  background-image: var(--chart-pattern, var(--chart-pattern-1, none));
-  background-size: var(--chart-pattern-size, 8px);
-  block-size: 100%;
-  inline-size: clamp(0%, var(--chart-value), 100%);
+.ui-meter__label {
+  color: var(--text-soft);
 }
 
-.ui-chart__fallback {
-  margin-block-start: var(--space-sm);
+.ui-meter__value {
+  color: var(--text);
+  font-family: var(--mono);
+  font-variant-numeric: tabular-nums;
+  text-align: end;
 }
 
+@media (max-width: 32rem) {
+  .ui-meter__row {
+    grid-template-columns: 1fr;
+  }
+
+  .ui-meter__value {
+    text-align: start;
+  }
+}
+
+/* A chart is NOT a bronto component — it needs scales + data binding, which the
+   analytical layer refuses to own. Theme Vega-Lite with `@ponchia/ui/vega`
+   (docs/vega.md), or hand-author a token-themed inline `<svg>`, and drop it in a
+   `.ui-report__figure` with a `.ui-report__caption` + a `.ui-legend` key. */
+
 .ui-print-only {
   display: none !important;
 }
@@ -313,27 +340,17 @@
     padding: 0;
   }
 
-  /* Meaning-carrying chart fills must survive the print "economy" default
-     (which drops backgrounds) without relying on a `.ui-print-exact`
-     ancestor. The accent on `.ui-report__summary` is a border, so it already
-     prints. (Legend swatches print-protect themselves in css/legend.css.) */
-  .ui-chart__fill {
-    -webkit-print-color-adjust: exact;
-    print-color-adjust: exact;
-  }
-
   .ui-report__cover {
     min-block-size: auto;
   }
 
   .ui-report__cover,
-  .ui-report__header,
+  .ui-report__head,
   .ui-report__section,
   .ui-report__summary,
   .ui-report__finding,
   .ui-report__evidence,
-  .ui-report__figure,
-  .ui-chart {
+  .ui-report__figure {
     break-inside: avoid;
   }
 

package/css/sidenote.css

@@ -0,0 +1,67 @@
+/* ==========================================================================
+   sidenote — opt-in Tufte-style margin notes.
+
+   A numbered `ui-sidenote` and an unnumbered `ui-marginnote` for evidence,
+   caveats, and provenance asides that belong beside the text, not in it. Wide
+   viewports float the note into the inline-end margin; narrow viewports collapse
+   it to an indented inline block. CSS counters number the sidenotes. Not
+   imported by core.css.
+
+   Boundary / wiring: the HOST owns where numbering restarts — set
+   `counter-reset: ui-sidenote` on the article (or a section) — and reserves the
+   margin gutter by giving that container
+   `padding-inline-end: calc(var(--sidenote-width) + var(--sidenote-gap))` at the
+   same breakpoint. Place each note in the DOM right after its `.ui-sidenote__ref`.
+   ========================================================================== */
+
+.ui-sidenote,
+.ui-marginnote {
+  --sidenote-width: 12rem;
+  --sidenote-gap: 2rem;
+
+  border-inline-start: 2px solid var(--line);
+  color: var(--text-dim);
+  display: block;
+  font-size: var(--text-2xs);
+  line-height: 1.5;
+  margin-block: var(--space-2xs);
+  padding-inline-start: var(--space-md);
+}
+
+/* The inline superscript that anchors a numbered sidenote. Use --accent-text,
+   not raw --accent: this is readable text and must clear WCAG AA 4.5:1 even
+   after a one-knob re-brand to a paler --accent (raw --accent drops to ~1.5:1).
+   Same accent-as-text contract as .ui-eyebrow / .ui-link--cta. (audit C6.) */
+.ui-sidenote__ref {
+  color: var(--accent-text);
+  counter-increment: ui-sidenote;
+  font-size: 0.75em;
+  vertical-align: super;
+}
+
+.ui-sidenote__ref::after {
+  content: counter(ui-sidenote);
+}
+
+/* The note repeats its number (display only — the ref already incremented).
+   --accent-text for the same WCAG-AA reason as the ref above. (audit C6.) */
+.ui-sidenote::before {
+  color: var(--accent-text);
+  content: counter(ui-sidenote) '. ';
+}
+
+/* Wide viewports: float the note into the inline-end margin. The container must
+   reserve the gutter (see header). */
+@media (min-width: 60rem) {
+  .ui-sidenote,
+  .ui-marginnote {
+    border-inline-start: 0;
+    clear: inline-end;
+    float: inline-end;
+    inline-size: var(--sidenote-width);
+    margin-block: 0;
+    margin-inline-end: calc(-1 * (var(--sidenote-width) + var(--sidenote-gap)));
+    padding-inline-start: 0;
+    text-align: start;
+  }
+}

package/css/site.css

@@ -162,11 +162,11 @@
     transform var(--duration-fast) var(--ease-spring);
 }
 
-.ui-sitenav a[aria-current] {
+.ui-sitenav a[aria-current]:not([aria-current='false']) {
   color: var(--accent-text);
 }
 
-.ui-sitenav a[aria-current]::before {
+.ui-sitenav a[aria-current]:not([aria-current='false'])::before {
   opacity: 1;
   transform: scale(1);
 }
@@ -182,6 +182,13 @@
   }
 }
 
+@media (pointer: coarse) {
+  .ui-sitenav a {
+    min-block-size: 2.9rem;
+    padding-inline: 0.9rem;
+  }
+}
+
 /* --- Mobile menu — native <details>, no JS required --- */
 
 .ui-sitemenu {
@@ -247,6 +254,13 @@
   }
 }
 
+@media (pointer: coarse) {
+  .ui-sitemenu > summary {
+    min-block-size: 2.9rem;
+    padding-inline: 0.9rem;
+  }
+}
+
 /* --- Footer --- */
 
 .ui-sitefooter {

package/css/sources.css

@@ -19,6 +19,37 @@
   --src-tone: var(--text-dim);
 }
 
+/* Standalone trust pill — wears a `.ui-src--*` tone on its own, for a bare
+   "verified" / "stale" label outside a citation or source card (the tone setters
+   below only paint a `--src-tone` custom property, so without this host a lone
+   `.ui-src--verified` validates against classes.json yet renders nothing). Tone
+   is a leading dot + a tinted border AND the author's written label, never colour
+   alone (WCAG 1.4.1). Declared before the `--*` setters so their tone wins. */
+.ui-src {
+  --src-tone: var(--text-dim);
+
+  align-items: center;
+  background: var(--panel-soft);
+  border: 1px solid color-mix(in srgb, var(--src-tone) 45%, var(--line));
+  border-radius: var(--radius-pill);
+  color: var(--text-soft);
+  display: inline-flex;
+  font-size: var(--text-2xs);
+  gap: 0.35rem;
+  padding: 0.08rem 0.55rem;
+  vertical-align: baseline;
+}
+
+.ui-src::before {
+  background: var(--src-tone);
+  border-radius: 50%;
+  block-size: 0.45rem;
+  content: '';
+  flex: none;
+  inline-size: 0.45rem;
+  print-color-adjust: exact;
+}
+
 .ui-src--verified {
   --src-tone: var(--success);
 }
@@ -169,7 +200,8 @@
    1.4.1). Keep the marks visible as CanvasText rather than letting them vanish. */
 @media (forced-colors: active) {
   .ui-citation--chip::before,
-  .ui-provenance__item::before {
+  .ui-provenance__item::before,
+  .ui-src::before {
     background: CanvasText;
   }
 
@@ -177,3 +209,13 @@
     border-inline-start-color: CanvasText;
   }
 }
+
+/* Print: an inline citation marker points into the references list, so never
+   expand its href inline. base.css expands `.ui-prose a[href^="http"]` with a
+   trailing "(url)"; on a superscript marker that dumps a full URL mid-sentence.
+   !important + print-scoped because base's rule is more specific. */
+@media print {
+  .ui-citation[href]::after {
+    content: none !important;
+  }
+}