@ponchia/ui 0.6.0 → 0.6.3

package/css/forms.css

@@ -77,6 +77,16 @@
   opacity: 0.5;
 }
 
+/* Read-only is editable-looking but not editable; give it a distinct, quieter
+   cue (muted fill + default cursor) so it doesn't read as a live field. Not
+   disabled — value still submits and the field stays focusable/selectable.
+   (component audit C28.) */
+.ui-input:read-only:not(:disabled),
+.ui-textarea:read-only:not(:disabled) {
+  background: var(--panel-soft);
+  cursor: default;
+}
+
 /* Disabled affordance parity. The text inputs above style :disabled directly;
    the controls that WRAP a native input (switch/check/segmented) showed no
    disabled cue and their label kept cursor:pointer — a lie. Mirror the cue via
@@ -94,6 +104,8 @@
 /* Keep autofilled fields on-theme — the UA's yellow fill otherwise paints over
    the monochrome surface and breaks the contrast story. (forms review C24.) */
 .ui-input:autofill,
+.ui-select:autofill,
+.ui-textarea:autofill,
 .ui-search input:autofill {
   -webkit-text-fill-color: var(--text);
   box-shadow: inset 0 0 0 100rem var(--bg-elevated);
@@ -106,6 +118,58 @@
   border-color: var(--danger);
 }
 
+/* Wrapper controls (switch / check / segmented) hide their native <input>, so
+   the `[aria-invalid]` the validator sets on it paints nothing — a sighted,
+   non-AT user couldn't see the error (WCAG 1.4.1). Mirror the invalid cue onto
+   the visible surface via :has(), the same way the disabled cue is mirrored.
+   (component audit C7.) */
+.ui-check:has(input[aria-invalid='true']) input {
+  outline: 2px solid var(--danger);
+  outline-offset: 1px;
+}
+
+.ui-switch:has(input[aria-invalid='true']) .ui-switch__track {
+  border-color: var(--danger);
+}
+
+.ui-segmented:has(input[aria-invalid='true']) {
+  border-color: var(--danger);
+}
+
+/* Forced colours flatten `var(--danger)` to a system colour identical to the
+   resting border, so the invalid border becomes indistinguishable from a valid
+   one and sighted HCM users lose the only error cue (WCAG 1.4.1). The switch got
+   a forced-colors block; the error family did not. Re-assert the state on a
+   NON-colour channel — a thicker, doubled border — that survives HCM, and prefix
+   the error hint with a glyph so the message itself carries the error.
+   (component audit C5.) */
+@media (forced-colors: active) {
+  .ui-input[aria-invalid='true'],
+  .ui-select[aria-invalid='true'],
+  .ui-textarea[aria-invalid='true'] {
+    border-style: double;
+    border-width: 3px;
+  }
+
+  /* Same NON-colour re-assertion for the wrapper controls (C7): a thicker,
+     doubled outline/border survives the HCM colour flattening. */
+  .ui-check:has(input[aria-invalid='true']) input {
+    outline-width: 3px;
+    outline-style: double;
+  }
+
+  .ui-switch:has(input[aria-invalid='true']) .ui-switch__track,
+  .ui-segmented:has(input[aria-invalid='true']) {
+    border-style: double;
+    border-width: 3px;
+  }
+
+  .ui-hint--error::before,
+  .ui-error-summary__title::before {
+    content: '⚠ ';
+  }
+}
+
 .ui-hint {
   color: var(--text-dim);
   font-size: var(--text-2xs);
@@ -139,14 +203,18 @@
   border-end-end-radius: var(--radius-md);
 }
 
-.ui-input-group > .ui-input:focus-visible {
-  z-index: 1; /* keep the focus ring above the adjacent addon border */
+.ui-input-group > .ui-input:focus-visible,
+.ui-input-group > .ui-select:focus-visible {
+  z-index: 1; /* keep the focus ring above the adjacent addon border (select too — audit C29) */
 }
 
 .ui-input-group__addon {
   align-items: center;
   background: var(--panel-soft);
-  border: 1px solid var(--line);
+
+  /* Match the wrapped control's `--line-strong` border so the prefix/suffix seam
+     isn't a fainter cap than the field it abuts. (component audit C33.) */
+  border: 1px solid var(--line-strong);
   color: var(--text-dim);
   display: flex;
   font-size: var(--text-sm);

package/css/legend.css

@@ -90,10 +90,13 @@
   inline-size: 1.1rem;
 }
 
-/* Glyph/symbol swatch — fill an `.ui-icon` mask with the series colour. */
+/* Glyph/symbol swatch — fill an `.ui-icon` mask with the series colour. Match the
+   __swatch fallback chain exactly (--chart-color → --chart-1 → --accent): without
+   the --chart-1 layer, a symbol and a swatch for the SAME series diverge to two
+   colours whenever a theme overrides --chart-1. (audit C22.) */
 .ui-legend__symbol {
   block-size: 0.95rem;
-  color: var(--chart-color, var(--accent));
+  color: var(--chart-color, var(--chart-1, var(--accent)));
   flex: 0 0 auto;
   inline-size: 0.95rem;
 }

package/css/motion.css

@@ -52,6 +52,28 @@
   }
 }
 
+/* Scroll-driven reveal (`.ui-scroll-reveal`). Unlike the time-based uiRise, a
+   scroll timeline can FREEZE part-way: an element near the document bottom can't
+   scroll far enough to finish its range, so a fade-to-opacity-1 would strand the
+   content permanently transparent. Reach full opacity early (35%) and hold it,
+   so even a partially-driven reveal is fully legible — only the last few px of
+   the rise are left unfinished. (component audit C9.) */
+@keyframes uiScrollReveal {
+  0% {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+
+  35% {
+    opacity: 1;
+  }
+
+  100% {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
 @keyframes uiDotIn {
   0% {
     opacity: 0;
@@ -158,10 +180,13 @@
   animation: uiMatrixReveal var(--duration-slow) var(--ease-out) both;
 }
 
-/* Stagger children: set --i on each child (or use nth-child cap). */
+/* Stagger children: set --i on each child (or use nth-child cap). Cap the manual
+   --i path at index 6 (360ms) to match the .ui-stagger--auto ceiling — a long
+   list with --i:30 would otherwise hold the last child at opacity:0 for 1.8s
+   before popping in. (audit C32.) */
 .ui-stagger > * {
   animation: uiRise var(--duration-slow) var(--ease-spring) both;
-  animation-delay: calc(var(--i, 0) * 60ms);
+  animation-delay: calc(min(var(--i, 0), 6) * 60ms);
 }
 
 .ui-stagger--auto > *:nth-child(1) {
@@ -193,11 +218,17 @@
 }
 
 /* Reveal-on-scroll: add .ui-reveal, then toggle .is-visible (e.g. from an
-   IntersectionObserver you own) to play it in. For a ZERO-JS reveal, use
-   `.ui-scroll-reveal` (scroll-driven, CSS-only) instead — that is the path for
-   an LLM-authored or no-build report. The hidden initial state below is gated
-   on `scripting: enabled`, so with scripting OFF the content is fully visible
-   and never silently hidden behind a script that will never run. */
+   IntersectionObserver you own) to play it in.
+
+   ⚠ `.ui-reveal` requires you to wire that observer. The hidden initial state is
+   gated only on `scripting: enabled` — it can't detect whether an observer is
+   actually attached, so merely loading bronto.js (or any script) hides every
+   `.ui-reveal` until YOUR code adds `.is-visible`. If you add the class and never
+   wire the toggle, the content stays invisible. For an LLM-authored or no-build
+   report, DON'T use `.ui-reveal` — use `.ui-scroll-reveal` below (scroll-driven,
+   CSS-only, no observer, and it can never strand content invisible). With
+   scripting OFF, `.ui-reveal` content is fully visible and never silently hidden
+   behind a script that will never run. */
 @media (prefers-reduced-motion: no-preference) and (scripting: enabled) {
   .ui-reveal {
     opacity: 0;
@@ -246,10 +277,12 @@
 
 /* --- Scroll-driven (progressive enhancement) — the scroll/view timeline
    IS the engine, no JS. Everything is gated on `@supports
-   (animation-timeline: …)` so engines without it (today, Firefox/Safari)
-   keep the static end state, and on `prefers-reduced-motion: no-preference`
-   (a scroll timeline ignores animation-duration, so the global reduced-motion
-   reset below can't neutralise it — it must be gated here). --- */
+   (animation-timeline: …)` so an engine without it keeps the static end state
+   (as of 2026 Chrome 115+ and Safari 18.4+ drive scroll()/view(); Firefox is
+   the remaining holdout, still graceful via the @supports gate), and on
+   `prefers-reduced-motion: no-preference` (a scroll timeline ignores
+   animation-duration, so the global reduced-motion reset below can't neutralise
+   it — it must be gated here). --- */
 
 /* Reading-progress bar. Fixed hairline that fills with document scroll;
    unsupported → a static, empty (scaleX(0)) bar. Pair with role="progressbar"
@@ -270,6 +303,30 @@
   transform-origin: 100% 50%;
 }
 
+/* Forced colours (HCM) flatten the spinner's accent top-border and its --line
+   rest to one system colour, so the ring looks uniform with no visible sweep,
+   and the scroll-progress bar can vanish into the canvas. Re-assert distinct
+   system colours so each keeps a visible channel; AT is already covered via
+   aria-busy / role="status" / role="progressbar". (component audit C35.) */
+@media (forced-colors: active) {
+  .ui-spinner {
+    border-color: CanvasText;
+    border-block-start-color: Highlight;
+  }
+
+  .ui-scroll-progress {
+    background: Highlight;
+  }
+
+  /* HCM strips the shimmer gradient, leaving an invisible box where a loading
+     placeholder should be. Give it a system-colour border so the skeleton
+     still reads as present. Same decorative-loading family as the spinner +
+     scroll-progress above. (audit C15.) */
+  .ui-skeleton {
+    border: 1px solid CanvasText;
+  }
+}
+
 @supports (animation-timeline: scroll()) {
   @media (prefers-reduced-motion: no-preference) {
     .ui-scroll-progress {
@@ -284,13 +341,21 @@
 
 /* Reveal-on-scroll with no JS and no IntersectionObserver: the element
    rises + fades as it scrolls into view. Unsupported → fully visible
-   (the `uiRise` end state), same graceful default as `.ui-reveal`. */
+   (the keyframe end state), same graceful default as `.ui-reveal`.
+
+   The range is `entry 0% entry 100%`, NOT the old `cover 40%`: `cover` only
+   completes once the element has scrolled most of the way THROUGH the viewport,
+   which an element near the document bottom can never do — it froze part-way,
+   leaving a conclusion section permanently semi-transparent (C9). `entry`
+   completes the moment the element is fully in view, which any scroll-to-bottom
+   reaches. Paired with the early-opacity uiScrollReveal keyframe, an element
+   taller than the viewport is legible even if its range never fully completes. */
 @supports (animation-timeline: view()) {
   @media (prefers-reduced-motion: no-preference) {
     .ui-scroll-reveal {
-      animation: uiRise linear both;
+      animation: uiScrollReveal linear both;
       animation-timeline: view();
-      animation-range: entry 0% cover 40%;
+      animation-range: entry 0% entry 100%;
     }
   }
 }

package/css/overlay.css

@@ -78,14 +78,25 @@ dialog.ui-modal[open]::backdrop {
 
 /* Controlled (non-<dialog>) usage. A portal/React modal that can't be a
    native <dialog> wears the same skin + open layout via `.is-open`.
-   Backdrop, top-layer stacking and focus-trapping are then the
-   consumer's responsibility (the native <dialog> path gets them free). */
+   Backdrop and top-layer stacking are then the consumer's responsibility
+   (the native <dialog> path gets them free); focus-trapping no longer is —
+   mark the overlay `data-bronto-modal` and run `initModal` for an
+   inert-based trap + focus-return + Escape signal. */
 .ui-modal.is-open {
   animation: uiToastIn var(--duration-base) var(--ease-spring) both;
   display: grid;
   grid-template-rows: auto 1fr auto;
 }
 
+/* Background scroll-lock. A native <dialog> top layer does NOT stop the page
+   behind it scrolling, and the no-JS native path can't lock it in script — so
+   lock it in CSS, for both the native [open] dialog and the controlled .is-open
+   overlay (incl. the drawer modifier, same base). (component audit C13.) */
+html:has(dialog.ui-modal[open]),
+html:has(.ui-modal.is-open) {
+  overflow: hidden;
+}
+
 .ui-modal__head {
   align-items: flex-start;
   border-block-end: 1px solid var(--line);
@@ -150,6 +161,21 @@ dialog.ui-modal[open]::backdrop {
   }
 }
 
+/* Comfortable hit target on coarse pointers — this bespoke close button measured
+   ~26px on touch, below the 2.9rem floor the rest of the button family meets
+   (WCAG 2.5.8). Scoped to coarse so the fine-pointer (mouse) rendering, which
+   already clears 24×24, is unchanged; centre the glyph in the enlarged box.
+   (audit C3.) */
+@media (pointer: coarse) {
+  .ui-modal__close {
+    align-items: center;
+    display: inline-flex;
+    justify-content: center;
+    min-block-size: 2.9rem;
+    min-inline-size: 2.9rem;
+  }
+}
+
 /* --- Lightbox — a full-viewport <dialog> wrapping a .ui-carousel. The
    native <dialog> brings the top layer, focus-trap and Escape; initDialog
    adds open (`data-bronto-open`) + focus-return; initCarousel drives the
@@ -284,6 +310,25 @@ dialog.ui-modal[open]::backdrop {
   opacity: 1;
 }
 
+/* Menu hover/focus paints var(--bg-accent), which HCM strips, so the hovered row
+   is indistinguishable from its siblings (focus keeps the UA ring; hover has no
+   such fallback). Re-assert a system Highlight like the combobox/command rows,
+   for parity with those sibling surfaces. (component audit C22.) */
+@media (forced-colors: active) {
+  .ui-menu__item:hover,
+  .ui-menu__item:focus-visible {
+    forced-color-adjust: none;
+    background: Highlight;
+    color: HighlightText;
+  }
+
+  .ui-menu__item:hover::before,
+  .ui-menu__item:focus-visible::before {
+    background: HighlightText;
+    opacity: 1;
+  }
+}
+
 /* --- Combobox: an input with a filtered listbox popup (APG pattern,
    wired by initCombobox). Reuses the menu surface tokens. --- */
 .ui-combobox {
@@ -337,6 +382,18 @@ dialog.ui-modal[open]::backdrop {
   color: var(--text);
 }
 
+/* The active option is tracked by aria-activedescendant — it is NEVER DOM-focused,
+   so it gets no UA focus ring under HCM, and its only cue (--bg-accent) is stripped.
+   Re-assert a system Highlight like the command palette does. (audit C2.) */
+@media (forced-colors: active) {
+  .ui-combobox__option.is-active,
+  .ui-combobox__option[aria-selected='true'] {
+    forced-color-adjust: none;
+    background: Highlight;
+    color: HighlightText;
+  }
+}
+
 .ui-combobox__empty {
   color: var(--text-dim);
   font-size: var(--text-2xs);

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;
@@ -94,7 +97,11 @@
   container: bronto / inline-size;
 }
 
-@container bronto (max-width: 34rem) {
+/* 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%;
   }
@@ -168,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;
@@ -182,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);
 }
 
@@ -203,6 +216,7 @@
   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,
@@ -243,6 +257,10 @@
    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;
 }
@@ -413,13 +431,26 @@
 
 /* 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). Looking dead while staying live is the defect — kill
-   pointer activation. (a11y review C3; native :disabled already inert.) */
+   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);
 }
@@ -445,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;
   }
 }
 
@@ -492,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 {
@@ -637,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) --- */
@@ -679,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

@@ -257,6 +257,46 @@
   text-transform: uppercase;
 }
 
+/* --- 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;
+  display: grid;
+  gap: var(--space-2xs) var(--space-md);
+  grid-template-columns: minmax(9rem, 14rem) 1fr auto;
+  margin-block: var(--space-2xs);
+}
+
+.ui-meter__row .ui-meter {
+  min-inline-size: 8rem;
+}
+
+.ui-meter__label {
+  color: var(--text-soft);
+}
+
+.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

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;
+  }
+}