@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/background-field.md

@@ -0,0 +1,62 @@
+## What it is
+
+One component that paints nine compiled ambient fields behind its content: `dot-grid` (the default), `line-grid`, `mesh`, `aurora`, `wave`, `beams`, `glow`, `stripes`, `grain`.
+
+It is chrome, never content. The painted layer is `aria-hidden` and takes no pointer events, the caller gives the element its size, and the field fills whatever box it lands in and inherits that box's border radius. Yield content into it and the content sits above the paint.
+
+Reach for it when a surface needs texture rather than an image. If you want a scrim over content, that is **Backdrop**; if you want a decorative shape that is part of the composition rather than behind it, that is not this.
+
+## The contract
+
+```
+@variant?  — 'dot-grid' (default) | 'line-grid' | 'mesh' | 'aurora' | 'wave'
+             | 'beams' | 'glow' | 'stripes' | 'grain'
+@animated? — ambient motion; OFF by default
+@scale?    — pattern size multiplier, clamped 0.25–4 (1 = the field's natural cell)
+@speed?    — motion rate, clamped 0.05–6; ignored when @animated is false
+@opacity?  — strength of the whole painted stack, 0–1
+@hue?      — primary colour; any CSS colour or a token reference
+@hue2?     — second colour: mesh, aurora, wave, beams, glow
+@hue3?     — third colour: aurora, wave, mesh
+@fade?     — 'none' | 'edges' | 'bottom' | 'top'
+<:default> — content stacked above the field
+```
+
+**The arg is `@variant` rather than the obvious `field`, and that is a platform trap rather than a naming preference.** An `Args` key named `field` makes the realm's lint endpoint inject a phantom card-api `field` import and then fail on it.
+
+**Motion is off by default.** A background is chrome, and chrome that moves by default is a tax on every card that renders one. `@speed` of zero or less also counts as off. **`grain` is exempt in the other direction**: it never animates, whatever `@animated` says, because honest film grain needs per-frame noise and a drifting static noise tile reads as sliding sandpaper.
+
+**Every numeric arg is clamped and every colour goes through the kit's CSS guard**, so a rejected value drops its declaration and the field's own default stands.
+
+**Each field renders exactly the layers it uses** — one for `grain`, two for the grids and `mesh`, three for `aurora` and `wave`. An unused empty layer is cheap but not free, and this is the component that sits under everything.
+
+**The paint wrapper clips, not the root.** Layers are deliberately oversized so a drifting pattern never shows its own edge; clipping them on the wrapper rather than on the element means yielded content is never cut off.
+
+**The overhang invariant is the non-obvious part.** A drifting layer travels `--pretui-field-dx/dy` and has to stay covered for the whole trip, so each axis overhangs by at least the unsigned drift distance — `max()` of that and 25%, not a sum, so a tall box does not pay twice. Without it a coarse tile in a short box walks its own edge into view near the end of its cycle.
+
+## Prior art
+
+Three upstreams, all of them catalogues rather than components: **react-bits' Backgrounds** category (Aurora, DotGrid, GridMotion, Waves, Particles, Silk, Topography and some fifty others), **cult-ui's** `bg-*` and `hero-*` families, and **fancy's** AnimatedGradientWithSvg.
+
+Where Pretui is better: **one import and one arg instead of a component per effect**, and **color from theme tokens instead of hardcoded palettes**, so a theme restyles every ambient surface in the product at once. Motion is compositor-driven with no animation frame loop, and `prefers-reduced-motion` lands on the base rule — which _is_ the resting state, so a reduced-motion reader gets a still, deliberate field rather than a frozen midpoint of a loop.
+
+Where it is thinner, and the cuts were deliberate: **the shader and particle cohort is gone** — react-bits' Ballpit, MetaBalls and LiquidEther and cult-ui's shader heroes need a rendering engine, and this component owns none. **The mouse-follow variants are gone**, because a background that tracks the cursor cannot be screenshotted honestly. And nine fields is not fifty-five: the CSS-drivable subset covers the gradient, grid, wave and glow families, and anything outside it is not here at all.
+
+## Accessibility
+
+- **The paint layer is `aria-hidden` and `pointer-events: none`.** It contributes nothing to the accessibility tree and cannot intercept a click meant for the content above it. That is the whole accessibility design, and it is the right one: this is decoration.
+- **`prefers-reduced-motion` stops every field.** Because the base rule is the resting state rather than frame zero of a keyframe, the still frame is composed rather than arbitrary.
+- **Contrast is the caller's problem, and it is a real one.** Text yielded over `mesh`, `aurora` or `glow` sits on a gradient whose luminance varies across the box, so a contrast ratio measured at one point does not hold at another. `@opacity` and `@fade` are the levers; neither is checked, and nothing warns.
+- **The field carries no name and no role**, so a surface whose _meaning_ is partly carried by its texture — a status conveyed by which field is painted — is conveying it invisibly.
+
+## Theming
+
+Caller-facing: `--pretui-field-scale`, `--pretui-field-opacity`, `--pretui-field-speed`, `--pretui-field-hue`, `--pretui-field-hue-2`, `--pretui-field-hue-3` — each written by the matching arg after its guard.
+
+Derived on the element: `--pretui-field-cell` (22px × scale) and `--pretui-field-tile` (120px × scale), the two sizes every field's geometry is built from.
+
+Per-layer internals, set by the field rules rather than by callers: `--pretui-field-o0` / `--pretui-field-o1` (layer opacity), `--pretui-field-fx0` / `--pretui-field-fy0` / `--pretui-field-fx1` / `--pretui-field-fy1` (offsets), `--pretui-field-r0` / `--pretui-field-r1` (rotation), `--pretui-field-s0` / `--pretui-field-s1` (scale), `--pretui-field-dx` / `--pretui-field-dy` with `--pretui-field-over-x` / `--pretui-field-over-y` (drift and its matching overhang).
+
+Hue defaults are per field — the `--chart-*` channel for the pattern fields, `--foreground` for `grain` — so a theme that retunes its chart palette retunes every ambient surface with it, and a theme that changes `--foreground` changes the grain's weight in both light and dark without touching this component.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/background-field.usage.gts

@@ -0,0 +1,328 @@
+// Pretui — BackgroundField usage page. One knob rail drives the focus specimen and all nine catalogue tiles at once, so a single @hue change re-tints every field.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { BACKGROUND_FIELDS, BackgroundField } from './background-field';
+import type { BackgroundFieldFade, BackgroundFieldName } from './background-field';
+import { Chip } from './chip';
+import { Token } from './token';
+import { HUE_OPTIONS, hueArg } from '../demo-texture';
+
+// ── BackgroundField ──────────────────────────────────────────────────────
+const FADE_OPTIONS: BackgroundFieldFade[] = ['none', 'edges', 'bottom', 'top'];
+
+class BackgroundFieldUsage extends Component {
+  @tracked variant: BackgroundFieldName = 'mesh';
+  @tracked animated = true;
+  @tracked scale = 1;
+  @tracked opacity = 1;
+  @tracked speed = 1;
+  @tracked hue = 'default';
+  @tracked hue2 = 'default';
+  @tracked hue3 = 'default';
+  @tracked fade: BackgroundFieldFade = 'none';
+
+  setVariant = (v: string) => (this.variant = v as BackgroundFieldName);
+  selectVariant = (v: BackgroundFieldName) => (this.variant = v);
+  setAnimated = (v: boolean) => (this.animated = v);
+  setScale = (v: number | null) => (this.scale = v ?? 1);
+  setOpacity = (v: number | null) => (this.opacity = v ?? 1);
+  setSpeed = (v: number | null) => (this.speed = v ?? 1);
+  setHue = (v: string) => (this.hue = v);
+  setHue2 = (v: string) => (this.hue2 = v);
+  setHue3 = (v: string) => (this.hue3 = v);
+  setFade = (v: string) => (this.fade = v as BackgroundFieldFade);
+
+  get fieldNames(): BackgroundFieldName[] {
+    return BACKGROUND_FIELDS;
+  }
+  get hueOptions() {
+    return HUE_OPTIONS;
+  }
+  get fadeOptions() {
+    return FADE_OPTIONS;
+  }
+  // Selection state is computed here rather than compared in the template —
+  // the kit ships no `eq` helper, and a getter keeps the tracked read honest.
+  // `pressed` is a STRING because both consumers need an explicit "false":
+  // `aria-pressed={{false}}` drops the attribute entirely, which reads as
+  // "not a toggle button" rather than "an unpressed toggle button".
+  get catalogue() {
+    return BACKGROUND_FIELDS.map((name) => ({
+      name,
+      pressed: name === this.variant ? 'true' : 'false',
+    }));
+  }
+  get hueValue() {
+    return hueArg(this.hue);
+  }
+  get hue2Value() {
+    return hueArg(this.hue2);
+  }
+  get hue3Value() {
+    return hueArg(this.hue3);
+  }
+  get usage() {
+    let bits = [`@variant='${this.variant}'`];
+    if (this.animated) bits.push('@animated={{true}}');
+    if (this.scale !== 1) bits.push(`@scale={{${this.scale}}}`);
+    if (this.opacity !== 1) bits.push(`@opacity={{${this.opacity}}}`);
+    if (this.speed !== 1) bits.push(`@speed={{${this.speed}}}`);
+    if (this.hueValue) bits.push(`@hue='${this.hueValue}'`);
+    if (this.hue2Value) bits.push(`@hue2='${this.hue2Value}'`);
+    if (this.hue3Value) bits.push(`@hue3='${this.hue3Value}'`);
+    if (this.fade !== 'none') bits.push(`@fade='${this.fade}'`);
+    return `<BackgroundField ${bits.join(' ')}>\n  <h3>Spring lots · Wuyishan</h3>\n  <p>Da Hong Pao, first flush</p>\n</BackgroundField>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='BackgroundField'
+      @description="One component, nine compiled ambient fields. Reach for it when a surface needs atmosphere — a hero band, an empty state, a dashboard header, a card that should feel like a place rather than a box. The painted stack is aria-hidden and pointer-events:none, so it is chrome and never content (Law 6); yielded children stack above it and stay fully interactive. Every field rides theme tokens through color-mix, so it re-tints with the theme and with light/dark mode without a single dark branch — set a hue below and watch all nine change at once. Motion is CSS keyframes only (no shader, no canvas, no rAF), animates transform/opacity only, and stops dead under prefers-reduced-motion on a still resting state. Honest limits: the element has no intrinsic height, so you size it; grain is static whatever @animated says; and everything upstream that needs a shader or a particle integrator (Plasma, Galaxy, Iridescence, Dither, GridDistortion) is deliberately absent rather than faked."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='bf-wrap'>
+          <div class='bf-focus'>
+            <BackgroundField
+              class='bf-focus-paint'
+              @variant={{this.variant}}
+              @animated={{this.animated}}
+              @scale={{this.scale}}
+              @opacity={{this.opacity}}
+              @speed={{this.speed}}
+              @hue={{this.hueValue}}
+              @hue2={{this.hue2Value}}
+              @hue3={{this.hue3Value}}
+              @fade={{this.fade}}
+            >
+              <div class='bf-copy'>
+                <Chip @hue='var(--chart-2)'>Spring lots</Chip>
+                <h3 class='bf-title'>Wuyishan · first flush</h3>
+                <p class='bf-sub'>Da Hong Pao and Rou Gui from Junshan Estate
+                  Direct, cupped and priced. Content sits above the field and
+                  stays selectable — the paint never intercepts a pointer.</p>
+                <p class='bf-meta'>Field
+                  <Token @value={{this.variant}} />
+                  · 2026-04-19</p>
+              </div>
+            </BackgroundField>
+          </div>
+
+          <div class='bf-cat'>
+            <p class='bf-cat-head'>The catalogue — all nine on the same knobs.
+              Pick one to focus it.</p>
+            <ul class='bf-grid'>
+              {{#each this.catalogue key='name' as |entry|}}
+                <li class='bf-tile' data-selected={{entry.pressed}}>
+                  <BackgroundField
+                    class='bf-tile-paint'
+                    @variant={{entry.name}}
+                    @animated={{this.animated}}
+                    @scale={{this.scale}}
+                    @opacity={{this.opacity}}
+                    @speed={{this.speed}}
+                    @hue={{this.hueValue}}
+                    @hue2={{this.hue2Value}}
+                    @hue3={{this.hue3Value}}
+                    @fade={{this.fade}}
+                  />
+                  <button
+                    type='button'
+                    class='bf-pick'
+                    aria-pressed={{entry.pressed}}
+                    {{on 'click' (fn this.selectVariant entry.name)}}
+                  >{{entry.name}}</button>
+                </li>
+              {{/each}}
+            </ul>
+          </div>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='variant'
+          @options={{this.fieldNames}}
+          @value={{this.variant}}
+          @onInput={{this.setVariant}}
+          @defaultValue='dot-grid'
+          @description='Which compiled field to paint — the one knob that replaces 55 separate upstream imports. Named variant rather than field because an Args key called field makes the realm lint endpoint inject a phantom card-api import and then fail on it (platform trap, not a design choice).'
+        />
+        <Args.Bool
+          @name='animated'
+          @value={{this.animated}}
+          @onInput={{this.setAnimated}}
+          @defaultValue={{false}}
+          @description='Ambient motion on/off. Off by default — a background is chrome, and chrome that moves by default taxes every card that renders one. Grain is exempt: honest film grain needs per-frame noise, and a drifting noise tile reads as sliding sandpaper.'
+        />
+        <Args.Number
+          @name='scale'
+          @min={{0.25}}
+          @max={{4}}
+          @step={{0.25}}
+          @value={{this.scale}}
+          @onInput={{this.setScale}}
+          @defaultValue={{1}}
+          @description='Pattern size multiplier against the field’s natural cell (clamped 0.25–4). Drives --pretui-field-scale.'
+        />
+        <Args.Number
+          @name='opacity'
+          @min={{0}}
+          @max={{1}}
+          @step={{0.05}}
+          @value={{this.opacity}}
+          @onInput={{this.setOpacity}}
+          @defaultValue={{1}}
+          @description='Strength of the whole painted stack, applied once to the paint wrapper rather than per layer, so the layers keep their relative weighting. Drives --pretui-field-opacity.'
+        />
+        <Args.Number
+          @name='speed'
+          @min={{0.25}}
+          @max={{4}}
+          @step={{0.25}}
+          @value={{this.speed}}
+          @onInput={{this.setSpeed}}
+          @defaultValue={{1}}
+          @description='Motion rate multiplier (clamped 0.05–6); every field divides its own duration by it, so the layers within a field stay in their intended relationship. Ignored when @animated is false.'
+        />
+        <Args.String
+          @name='hue'
+          @options={{this.hueOptions}}
+          @value={{this.hue}}
+          @onInput={{this.setHue}}
+          @defaultValue='var(--chart-1) — var(--foreground) for grain'
+          @description='Primary field color. Any CSS color, or a token reference like var(--chart-4) — the token form is the point: it re-tints with the theme. “default” here means the arg is omitted entirely.'
+        />
+        <Args.String
+          @name='hue2'
+          @options={{this.hueOptions}}
+          @value={{this.hue2}}
+          @onInput={{this.setHue2}}
+          @defaultValue='var(--chart-3)'
+          @description='Secondary color, used by every field that layers two hues (dot-grid, line-grid, mesh, aurora, wave, beams, glow, stripes). Ignored by grain, which is a single layer.'
+        />
+        <Args.String
+          @name='hue3'
+          @options={{this.hueOptions}}
+          @value={{this.hue3}}
+          @onInput={{this.setHue3}}
+          @defaultValue='var(--chart-2)'
+          @description='Third color. Only mesh, aurora and wave compose a third layer; the other fields ignore it.'
+        />
+        <Args.String
+          @name='fade'
+          @options={{this.fadeOptions}}
+          @value={{this.fade}}
+          @onInput={{this.setFade}}
+          @defaultValue='none'
+          @description='Edge falloff masked over the whole painted stack: a soft vignette (edges) or a one-directional fade (bottom / top). Use it to hand a field back to the surface it sits on instead of ending at a hard rectangle.'
+        />
+        <Args.Yield
+          @description='The default block stacks above the field in its own positioned layer. Omit it entirely and the component renders paint only — but then you must give the element a height, since the field has no intrinsic size.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .bf-wrap {
+        display: grid;
+        gap: var(--space-5, 15px);
+      }
+      /* radius lives on the wrapper; BackgroundField’s root inherits it, which
+         is how the component is meant to be cornered — no override needed */
+      .bf-focus {
+        position: relative;
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: 0 0 0 1px var(--border);
+        overflow: hidden;
+      }
+      .bf-focus-paint {
+        min-height: 200px;
+        padding: var(--space-6, 19px);
+        box-sizing: border-box;
+      }
+      .bf-copy {
+        display: grid;
+        gap: var(--space-2, 6px);
+        justify-items: start;
+        max-width: 46ch;
+      }
+      .bf-title {
+        margin: 0;
+        font-size: var(--text-heading, 19px);
+        font-weight: var(--weight-heading, 700);
+        letter-spacing: var(--track-heading, -0.02em);
+        color: var(--foreground);
+      }
+      .bf-sub {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        line-height: 1.5;
+        color: var(--muted-foreground);
+      }
+      .bf-meta {
+        margin: 0;
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+      .bf-cat-head {
+        margin: 0 0 var(--space-3, 8px);
+        font-size: var(--text-ui-xs, 11px);
+        letter-spacing: var(--track-ui, 0.01em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+      .bf-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+        gap: var(--space-3, 8px);
+        margin: 0;
+        padding: 0;
+        list-style: none;
+      }
+      .bf-tile {
+        position: relative;
+        border-radius: var(--radius-chip, 6px);
+        box-shadow: 0 0 0 1px var(--border);
+        overflow: hidden;
+      }
+      .bf-tile[data-selected='true'] {
+        box-shadow: 0 0 0 2px var(--primary);
+      }
+      .bf-tile-paint {
+        height: 92px;
+      }
+      /* the whole tile is one real button whose content is just the field
+         name — the field itself never intercepts the pointer, so the target
+         is the tile and the accessible name is the field */
+      .bf-pick {
+        position: absolute;
+        inset: 0;
+        display: flex;
+        align-items: flex-end;
+        margin: 0;
+        padding: var(--space-2, 6px) var(--space-3, 8px);
+        border: 0;
+        background: linear-gradient(
+          to top,
+          color-mix(in oklch, var(--card) 82%, transparent) 0%,
+          transparent 58%
+        );
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--foreground);
+        cursor: pointer;
+        text-align: left;
+      }
+      .bf-pick:focus-visible {
+        outline: 2px solid var(--ring);
+        outline-offset: -2px;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_BACKGROUND_FIELD: Record<string, unknown> = {
+  BackgroundField: BackgroundFieldUsage,
+};

package/bundled-realms/pretui/components/badge.gts

@@ -0,0 +1,188 @@
+// Pretui — Badge: a count or status mark overlaid on the corner of another control.
+import Component from '@glimmer/component';
+import { VisuallyHidden } from './visually-hidden';
+import { guidFor } from '@ember/object/internals';
+import { cornerHueStyle, describesFocusable, resolveCorner, resolveCornerTone } from '../internal/corner-mark';
+import type { CornerPlacement } from '../internal/corner-mark';
+import type { PretuiTone, PretuiToneArg } from '../pretui-primitives';
+
+export interface BadgeSignature {
+  Args: {
+    /** The number to show. Omit it, or pass `@dot`, for a mark without a number. */
+    count?: number;
+    /** Above this the badge reads `max+` (default 99). */
+    max?: number;
+    /** A small dot instead of the count. */
+    dot?: boolean;
+    /** Show the badge at a count of 0 (hidden by default). */
+    showZero?: boolean;
+    /** Hide the badge without unmounting the child. */
+    invisible?: boolean;
+    /** Default 'danger'. Accepts the kit's tone spellings. */
+    tone?: PretuiToneArg;
+    /** Which corner (default 'top-end'). The physical spellings map. */
+    placement?: CornerPlacement | string;
+    /** Pull the mark in for a round child such as an Avatar. */
+    circular?: boolean;
+    /**
+     * What the count means, read after it: `@label='unread'` announces
+     * "3 unread". Without it the count is announced alone.
+     */
+    label?: string;
+  };
+  Blocks: { default: [] };
+  Element: HTMLSpanElement;
+}
+
+/**
+ * The overlay badge MUI, Ant and Mantine ship — the unread 3 on an inbox
+ * icon, 99+ on an avatar. shadcn's inline Badge is Chip in Pretui; a dot
+ * with no number is Indicator.
+ *
+ * The visible mark is `aria-hidden`: a bare "3" read in the middle of a
+ * button name means nothing. The meaning is a visually hidden run after the
+ * child — "3 unread" — and the child's first focusable element points at it
+ * with `aria-describedby`, so focusing the control reads its own name and
+ * then the count.
+ */
+export class Badge extends Component<BadgeSignature> {
+  private spokenId = guidFor(this) + '-spoken';
+  get describedBy(): string | undefined {
+    return this.spoken ? this.spokenId : undefined;
+  }
+  get tone(): PretuiTone {
+    return resolveCornerTone(this.args.tone, 'danger');
+  }
+  get max(): number {
+    return this.args.max ?? 99;
+  }
+  get hasCount(): boolean {
+    return typeof this.args.count === 'number' && Number.isFinite(this.args.count);
+  }
+  get visible(): boolean {
+    if (this.args.invisible) {
+      return false;
+    }
+    if (this.args.dot) {
+      return true;
+    }
+    if (!this.hasCount) {
+      return true;
+    }
+    return (this.args.count as number) > 0 || (this.args.showZero ?? false);
+  }
+  get isDot(): boolean {
+    return (this.args.dot ?? false) || !this.hasCount;
+  }
+  get display(): string {
+    let count = this.args.count as number;
+    return count > this.max ? `${this.max}+` : String(count);
+  }
+  get spoken(): string | undefined {
+    if (!this.visible) {
+      return undefined;
+    }
+    let words = this.hasCount ? [String(this.args.count)] : [];
+    if (this.args.label) {
+      words.push(this.args.label);
+    }
+    return words.length ? words.join(' ') : undefined;
+  }
+  get style() {
+    return cornerHueStyle(this.tone);
+  }
+
+  <template>
+    <span
+      class='pretui-badge'
+      data-placement={{resolveCorner @placement}}
+      data-circular={{if @circular 'true' 'false'}}
+      style={{this.style}}
+      data-test-pretui-badge
+      ...attributes
+      {{describesFocusable this.describedBy}}
+    >
+      {{yield}}
+      {{#if this.visible}}
+        <span
+          class='pretui-badge-mark'
+          data-dot={{if this.isDot 'true' 'false'}}
+          data-tone={{this.tone}}
+          aria-hidden='true'
+          data-test-pretui-badge-mark
+        >{{#unless this.isDot}}{{this.display}}{{/unless}}</span>
+      {{/if}}
+      {{#if this.spoken}}
+        <VisuallyHidden id={{this.spokenId}} data-test-pretui-badge-spoken>{{this.spoken}}</VisuallyHidden>
+      {{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-badge {
+          position: relative;
+          display: inline-flex;
+          vertical-align: middle;
+          --pretui-mark-inset: 0%;
+          --pretui-mark-x: 50%;
+        }
+        .pretui-badge:dir(rtl) {
+          --pretui-mark-x: -50%;
+        }
+        .pretui-badge[data-circular='true'] {
+          --pretui-mark-inset: 14%;
+        }
+        .pretui-badge-mark {
+          position: absolute;
+          z-index: 1;
+          display: inline-grid;
+          place-items: center;
+          box-sizing: border-box;
+          min-inline-size: 1.125rem;
+          block-size: 1.125rem;
+          padding-inline: 0.3rem;
+          border-radius: 999px;
+          background: var(--pretui-mark-hue);
+          color: var(--pretui-badge-ink, var(--card));
+          box-shadow: 0 0 0 2px var(--pretui-badge-ring, var(--card));
+          font-family: var(--font-sans);
+          font-size: var(--text-ui-xs, 0.66rem);
+          font-weight: 600;
+          font-variant-numeric: tabular-nums;
+          line-height: 1;
+          white-space: nowrap;
+          pointer-events: none;
+        }
+        .pretui-badge-mark[data-dot='true'] {
+          min-inline-size: 0.5rem;
+          inline-size: 0.5rem;
+          block-size: 0.5rem;
+          padding: 0;
+        }
+        .pretui-badge-mark[data-tone='warning'],
+        .pretui-badge-mark[data-tone='attention'] {
+          color: var(--foreground);
+        }
+        .pretui-badge[data-placement='top-end'] .pretui-badge-mark {
+          inset-block-start: var(--pretui-mark-inset);
+          inset-inline-end: var(--pretui-mark-inset);
+          translate: var(--pretui-mark-x) -50%;
+        }
+        .pretui-badge[data-placement='top-start'] .pretui-badge-mark {
+          inset-block-start: var(--pretui-mark-inset);
+          inset-inline-start: var(--pretui-mark-inset);
+          translate: calc(-1 * var(--pretui-mark-x)) -50%;
+        }
+        .pretui-badge[data-placement='bottom-end'] .pretui-badge-mark {
+          inset-block-end: var(--pretui-mark-inset);
+          inset-inline-end: var(--pretui-mark-inset);
+          translate: var(--pretui-mark-x) 50%;
+        }
+        .pretui-badge[data-placement='bottom-start'] .pretui-badge-mark {
+          inset-block-end: var(--pretui-mark-inset);
+          inset-inline-start: var(--pretui-mark-inset);
+          translate: calc(-1 * var(--pretui-mark-x)) 50%;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/badge.md

@@ -0,0 +1,62 @@
+## What it is
+
+A **count or status mark on the corner of another control**: the unread 3 on an inbox button, 99+ on an avatar, a dot on a tab with new activity. It wraps the control and overlays the mark on one corner.
+
+Reach for a neighbour when the mark is something else:
+
+- **Chip** is an inline label in the flow of text. That is what shadcn calls `Badge`.
+- **StatusChip** is a tone-mapped inline chip.
+- **Indicator** is a named dot with no number, such as online or live.
+
+## The contract
+
+```
+@count?, @max? (default 99), @dot?, @showZero?, @invisible?
+@tone? (default 'danger'), @placement? ('top-end' | 'top-start' | 'bottom-end' | 'bottom-start'; default 'top-end')
+@circular?, @label?
+<:default>   — the control the badge sits on
+Element: HTMLSpanElement
+```
+
+**The number is shown; the meaning is spoken.** The visible mark is `aria-hidden`, because a bare "3" read in the middle of a button name means nothing. The count, followed by `@label`, is a visually hidden run after the child: `@label='unread'` gives "3 unread". The child's first focusable element points at that run with `aria-describedby`, so focusing an inbox button reads "Messages, button, 3 unread": its own name, then the count. Existing descriptions on the child are kept.
+
+**Display rules.** Above `@max` the mark reads `99+` (or `9+` with `@max={{9}}`), and the spoken count stays exact. A count of 0 hides the badge unless `@showZero`. `@dot`, or no `@count` at all, draws a dot without a number. `@invisible` hides the mark and its announcement without unmounting the child.
+
+**Placement is logical**, so `top-end` follows the reading direction in RTL and the mark still straddles the corner, and the MUI and Mantine physical spellings (`top-right`…) map. `@circular` pulls the mark in toward a round child such as an **Avatar** so it sits on the curve, not in empty space.
+
+## Prior art
+
+**MUI `Badge`** takes `badgeContent`, `max`, `showZero`, `invisible`, `variant` (`standard | dot`), `color`, `anchorOrigin` and `overlap` (`rectangular | circular`). **Ant `Badge`** takes `count`, `overflowCount`, `dot`, `showZero`, `offset`, `color` and `status`. **Mantine** puts the overlay on `Indicator` and keeps `Badge` inline. **shadcn `Badge`** is inline only.
+
+Where Pretui is better: **the announcement is built in.** MUI and Ant render the count as plain text inside the badge, so a screen reader reads "Messages 3" or reads the number with no context. Here focus reads the child's own name and then "3 unread" as its description. **Placement is logical** rather than physical.
+
+Where it is thinner: **no `offset`** for pixel nudging; `@circular` covers the common case. There is **no custom content**: the mark is a number or a dot, not arbitrary markup. **No `status` text mode** as in Ant; use **StatusChip**.
+
+## Accessibility
+
+No APG pattern. What matters is the name.
+
+- **The mark is `aria-hidden`.** The tests assert it.
+- **The spoken run follows the child**, "3 unread", and the child's text is untouched. A focusable child is described by the run (`aria-describedby`). The tests assert the run, the exact count above `@max`, the child's name, and the description wiring.
+- **Hidden means silent.** A zero badge without `@showZero`, and an `@invisible` badge, have no spoken run either. The tests assert both.
+- **Give `@label` the meaning**, not the colour. "unread", "new", "failed builds".
+- **Live changes are not announced.** A count that ticks up while the user is elsewhere is not a live region. If the change matters right now, announce it separately, for example with **Toaster**.
+
+## Theming
+
+`--pretui-mark-hue` (set from the tone: `--destructive` by default, or `--primary`, `--pretui-info`, `--success`, `--warning`, `--pretui-attention`, `--muted-foreground`), `--pretui-badge-ink` (the number, default `--card`), `--pretui-badge-ring` (the separating ring, default `--card`), `--foreground` (ink on warning and attention hues), `--font-sans` and `--text-ui-xs`.
+
+The ring mixes against `--card`, so the mark reads as cut out of the control in any theme. The 1.125rem height, the 0.5rem dot and the half-out corner offset are fixed.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                       | Give them                         |
+| --------------------------------- | --------------------------------- |
+| MUI `<Badge badgeContent={4}>`    | `<Badge @count={{4}} @label='…'>` |
+| MUI `max` / Ant `overflowCount`   | `@max`                            |
+| MUI `variant="dot"` / Ant `dot`   | `@dot={{true}}`                   |
+| MUI `anchorOrigin` / Ant `offset` | `@placement`; no pixel offset     |
+| MUI `overlap="circular"`          | `@circular={{true}}`              |
+| shadcn `<Badge>` (inline)         | **Chip**                          |