@orange-halo/components 2.1.0 → 3.0.0

package/dist/oh-alert.js

@@ -1,13 +1,13 @@
 /**
  * oh-alert
  *
- * A dismissible alert for feedback messages.
- * Subtle backgrounds only, supports rich content including links.
+ * A message box for feedback, optionally dismissible, that can hold links.
  *
  * DESIGN DECISIONS:
  * ─────────────────
  * 1. SUBTLE ONLY
- *    - Muted backgrounds, not overwhelming
+ *    - Background is the variant's color.feedback.*Subtle token; border and
+ *      icon use color.feedback.*; text stays color.text.primary
  *    - Matches badge subtle variants
  *
  * 2. DISMISSIBLE
@@ -19,11 +19,9 @@
  *    - Default slot for flexible content
  *
  * 4. ACCESSIBLE
- *    - role="alert" for important messages
- *    - Close button has accessible label
- *    - Links within inherit appropriate styling
- *
- * @element oh-alert
+ *    - role="alert" only when live is set (alerts added after first render)
+ *    - Close button has a visible text label
+ *    - Links within take the variant's feedback colour
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -34,6 +32,26 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, css, nothing } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import { OhElement, baseStyles } from "./base.js";
+/**
+ * A message box that tells the user about the result of an action or something that needs their attention.
+ *
+ * **Use it for** feedback on what just happened (saved, failed) or a notice about the page or account, near the content it's about. **Don't use it for** a short status label (use `oh-badge`); for a field's validation error (use the field's own error message); or for a message that must interrupt the user (use `oh-modal`).
+ *
+ * **Variants:** `info` (default), `success`, `warning`, `error`, each by its feedback role. Each has its own icon, so the meaning isn't carried by colour alone.
+ *
+ * **Behaviour:** with `dismissible`, a "Close" button follows the content; selecting it fires `oh-dismiss` and sets `hidden` on the alert. Content goes in the default slot and can include links.
+ *
+ * **Accessibility:** set `live` only for an alert added after the page has rendered (e.g. after submit); it adds `role="alert"` so screen readers announce it. Leave it off for alerts present on page load. Icons are `aria-hidden`; put the meaning in the text. Links show a solid outline in the current text colour on focus; the close button shows an underline.
+ *
+ * **Look:** set by tokens. Each variant uses `color.feedback.<variant>Subtle` for the background and `color.feedback.<variant>` for the border, icon and links; text is `color.text.primary`. `stroke.control` sets the border, `shape.container` the corners, `typography.body.*` the text, and `decoration.underlineThickness`, `underlineDash` and `underlinePeriod` the link underline. The close button uses `closeButton.backgroundHover`, `closeButton.shadowHover`, `elevation.offset.*`, `lift.*` and `shape.compact`.
+ *
+ * @element oh-alert
+ * @slot - The message. Can include links.
+ * @csspart alert - The alert box.
+ * @csspart content - The message wrapper.
+ * @csspart close - The close button (only when `dismissible`).
+ * @fires oh-dismiss - When the close button is selected, before the alert hides.
+ */
 let OhAlert = class OhAlert extends OhElement {
     constructor() {
         super(...arguments);
@@ -49,7 +67,7 @@ let OhAlert = class OhAlert extends OhElement {
         baseStyles,
         css `
       /* ═══════════════════════════════════════════════════════════════
-         ORANGE HALO ALERT
+         ALERT
          Subtle • Dismissible • Rich Content
          ═══════════════════════════════════════════════════════════════ */
 
@@ -65,12 +83,12 @@ let OhAlert = class OhAlert extends OhElement {
         display: flex;
         align-items: flex-start;
         gap: var(--oh-spacing-3);
-        
+
         /* Shape */
         padding: var(--oh-spacing-4);
         border-radius: var(--oh-shape-container);
-        
-        /* Chunky border like other components */
+
+        /* Border: stroke.control, like other components */
         border: var(--oh-stroke-control) solid;
       }
 
@@ -92,7 +110,7 @@ let OhAlert = class OhAlert extends OhElement {
       .alert-content {
         flex: 1;
         min-width: 0;
-        
+
         /* Typography */
         font-family: var(--oh-typography-body-font-family);
         font-size: var(--oh-typography-body-base-font-size);
@@ -100,7 +118,7 @@ let OhAlert = class OhAlert extends OhElement {
       }
 
       /* 
-       * Links within alert - dashed underline with shrink animation
+       * Links within alert: the link underline (decoration.underline*), which shrinks on hover
        * Uses background-image approach which works with ::slotted()
        */
       .alert-content ::slotted(a) {
@@ -142,38 +160,40 @@ let OhAlert = class OhAlert extends OhElement {
         display: flex;
         align-items: center;
         gap: var(--oh-spacing-1);
-        
+
         padding: var(--oh-spacing-1) var(--oh-spacing-2);
         margin: -0.25rem -0.5rem -0.25rem 0;
-        
+
         font-family: var(--oh-typography-body-font-family);
         font-size: var(--oh-typography-body-base-font-size);
         font-weight: var(--oh-typography-label-base-font-weight);
-        
+
         background: transparent;
         border: none;
         border-radius: var(--oh-shape-compact);
         cursor: pointer;
-        
+
         /* Use primary text color for contrast */
         color: var(--oh-color-text-primary);
-        
-        /* Chunky animation setup */
-        transition: 
-          transform var(--oh-motion-snappy) var(--oh-motion-ease-playful),
-          box-shadow var(--oh-motion-snappy) var(--oh-motion-ease-playful),
+
+        /* Hover and press movement come from lift.* and elevation.offset.* */
+        transition:
+          transform var(--oh-motion-snappy) var(--oh-motion-ease-emphasized),
+          box-shadow var(--oh-motion-snappy) var(--oh-motion-ease-emphasized),
           background-color var(--oh-motion-quick) ease;
       }
 
       .alert-close:hover {
         background-color: var(--oh-close-button-background-hover);
         transform: translate(var(--oh-lift-hover-md), var(--oh-lift-hover-md));
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-close-button-shadow-hover);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-close-button-shadow-hover);
       }
 
       .alert-close:active {
         transform: translate(var(--oh-lift-press-sm), var(--oh-lift-press-sm));
-        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs) 0 0 var(--oh-close-button-shadow-hover);
+        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs)
+          0 0 var(--oh-close-button-shadow-hover);
       }
 
       .alert-close:focus-visible {
@@ -270,27 +290,63 @@ let OhAlert = class OhAlert extends OhElement {
         switch (this.variant) {
             case "success":
                 return html `
-          <svg class="alert-icon" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-            <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
+          <svg
+            class="alert-icon"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path
+              fill-rule="evenodd"
+              d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z"
+              clip-rule="evenodd"
+            />
           </svg>
         `;
             case "error":
                 return html `
-          <svg class="alert-icon" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-            <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z" clip-rule="evenodd" />
+          <svg
+            class="alert-icon"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path
+              fill-rule="evenodd"
+              d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z"
+              clip-rule="evenodd"
+            />
           </svg>
         `;
             case "warning":
                 return html `
-          <svg class="alert-icon" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-            <path fill-rule="evenodd" d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z" clip-rule="evenodd" />
+          <svg
+            class="alert-icon"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path
+              fill-rule="evenodd"
+              d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z"
+              clip-rule="evenodd"
+            />
           </svg>
         `;
             case "info":
             default:
                 return html `
-          <svg class="alert-icon" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-            <path fill-rule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z" clip-rule="evenodd" />
+          <svg
+            class="alert-icon"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path
+              fill-rule="evenodd"
+              d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z"
+              clip-rule="evenodd"
+            />
           </svg>
         `;
         }
@@ -303,11 +359,11 @@ let OhAlert = class OhAlert extends OhElement {
         return html `
       <div class=${classes} role=${this.live ? "alert" : nothing} part="alert">
         ${this._getIcon()}
-        
+
         <div class="alert-content" part="content">
           <slot></slot>
         </div>
-        
+
         ${this.dismissible
             ? html `
               <button
@@ -318,7 +374,11 @@ let OhAlert = class OhAlert extends OhElement {
               >
                 <span>Close</span>
                 <svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-                  <path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd" />
+                  <path
+                    fill-rule="evenodd"
+                    d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z"
+                    clip-rule="evenodd"
+                  />
                 </svg>
               </button>
             `

package/dist/oh-alert.js.map

@@ -1 +1 @@
-{"version":3,"file":"oh-alert.js","sourceRoot":"","sources":["../src/oh-alert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;;;;;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAK3C,IAAM,OAAO,GAAb,MAAM,OAAQ,SAAQ,SAAS;IAA/B;;QA4NL,YAAO,GAAiB,MAAM,CAAC;QAG/B,gBAAW,GAAG,KAAK,CAAC;QAEpB;;;WAGG;QAEH,SAAI,GAAG,KAAK,CAAC;IAqEf,CAAC;aA1SiB,WAAM,GAAG;QACvB,UAAU;QACV,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAqNF;KACF,AAxNqB,CAwNpB;IAeM,cAAc;QACpB,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAEO,QAAQ;QACd,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;YACrB,KAAK,SAAS;gBACZ,OAAO,IAAI,CAAA;;;;SAIV,CAAC;YACJ,KAAK,OAAO;gBACV,OAAO,IAAI,CAAA;;;;SAIV,CAAC;YACJ,KAAK,SAAS;gBACZ,OAAO,IAAI,CAAA;;;;SAIV,CAAC;YACJ,KAAK,MAAM,CAAC;YACZ;gBACE,OAAO,IAAI,CAAA;;;;SAIV,CAAC;QACN,CAAC;IACH,CAAC;IAED,MAAM;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC5B,KAAK,EAAE,IAAI;YACX,CAAC,UAAU,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI;SACjC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAA;mBACI,OAAO,SAAS,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;UACtD,IAAI,CAAC,QAAQ,EAAE;;;;;;UAMf,IAAI,CAAC,WAAW;YAChB,CAAC,CAAC,IAAI,CAAA;;;;;yBAKS,IAAI,CAAC,cAAc;;;;;;;aAO/B;YACH,CAAC,CAAC,OAAO;;KAEd,CAAC;IACJ,CAAC;;AA9ED;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;wCACX;AAG/B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;4CACvB;AAOpB;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;qCAC9B;AAtOF,OAAO;IADnB,aAAa,CAAC,UAAU,CAAC;GACb,OAAO,CA2SnB"}
+{"version":3,"file":"oh-alert.js","sourceRoot":"","sources":["../src/oh-alert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;;;;;;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAIlD;;;;;;;;;;;;;;;;;;;GAmBG;AAEI,IAAM,OAAO,GAAb,MAAM,OAAQ,SAAQ,SAAS;IAA/B;;QA8NL,YAAO,GAAiB,MAAM,CAAC;QAG/B,gBAAW,GAAG,KAAK,CAAC;QAEpB;;;WAGG;QAEH,SAAI,GAAG,KAAK,CAAC;IA6Gf,CAAC;aApViB,WAAM,GAAG;QACvB,UAAU;QACV,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAuNF;KACF,AA1NqB,CA0NpB;IAeM,cAAc;QACpB,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAEO,QAAQ;QACd,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;YACrB,KAAK,SAAS;gBACZ,OAAO,IAAI,CAAA;;;;;;;;;;;;;SAaV,CAAC;YACJ,KAAK,OAAO;gBACV,OAAO,IAAI,CAAA;;;;;;;;;;;;;SAaV,CAAC;YACJ,KAAK,SAAS;gBACZ,OAAO,IAAI,CAAA;;;;;;;;;;;;;SAaV,CAAC;YACJ,KAAK,MAAM,CAAC;YACZ;gBACE,OAAO,IAAI,CAAA;;;;;;;;;;;;;SAaV,CAAC;QACN,CAAC;IACH,CAAC;IAED,MAAM;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC5B,KAAK,EAAE,IAAI;YACX,CAAC,UAAU,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI;SACjC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAA;mBACI,OAAO,SAAS,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;UACtD,IAAI,CAAC,QAAQ,EAAE;;;;;;UAMf,IAAI,CAAC,WAAW;YAChB,CAAC,CAAC,IAAI,CAAA;;;;;yBAKS,IAAI,CAAC,cAAc;;;;;;;;;;;aAW/B;YACH,CAAC,CAAC,OAAO;;KAEd,CAAC;IACJ,CAAC;;AAtHD;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;wCACX;AAG/B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;4CACvB;AAOpB;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;qCAC9B;AAxOF,OAAO;IADnB,aAAa,CAAC,UAAU,CAAC;GACb,OAAO,CAqVnB"}

package/dist/oh-badge.d.ts

@@ -1,33 +1,52 @@
 /**
  * oh-badge
  *
- * A flat, non-interactive badge for status indicators and labels.
- * Two styles per color: subtle (muted bg) and filled (strong bg).
+ * A non-interactive label for a status or category.
+ * Two types per variant: subtle and filled.
  *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. FLAT & NON-INTERACTIVE
- *    - No shadows, no hover states
+ * 1. NON-INTERACTIVE
+ *    - No shadow, no hover states, pointer-events off
  *    - Pure informational element
  *    - Not clickable
  *
- * 2. TWO INTENSITIES
- *    - Subtle: muted background, darker text
- *    - Filled: strong background, white/dark text
+ * 2. TWO TYPES
+ *    - Subtle: the variant's *Subtle background token, its role colour as text
+ *    - Filled: the role colour as background, its color.text.on* token as text
  *
  * 3. ACCESSIBLE CONTRAST
- *    - All text meets WCAG AA (4.5:1)
- *    - Filled variants use appropriate text color
- *
- * @element oh-badge
+ *    - Every text/background pair is in contrast-pairs.json, so
+ *      check:contrast checks it in every brand and mode
  */
 import { OhElement } from "./base.js";
 export type BadgeVariant = "success" | "error" | "warning" | "info" | "brand" | "accent";
-export type BadgeType = "subtle" | "filled";
+export type BadgeAppearance = "subtle" | "filled";
+/**
+ * A short, non-interactive label that shows the status or category of the thing next to it.
+ *
+ * **Use it for** a status ("Delivered", "Pending"), a count or a tag next to the item it describes. **Don't use it for** anything the user can select (use `oh-button` or a link); or for a message with more than a word or two (use `oh-alert`).
+ *
+ * **Variants:** `brand` (default) and `accent` for categories; `success`, `warning`, `error` and `info` for status. **Appearance:** `subtle` (default), for most badges; `filled`, the stronger appearance, for the one status that matters most.
+ *
+ * **Parts:** the default slot holds the text; the `icon` slot an optional leading icon, sized to the text.
+ *
+ * **Behaviour:** none. It doesn't take focus or respond to the pointer.
+ *
+ * **Accessibility:** the badge is plain text to screen readers, so the text must make sense on its own (say "Pending", don't rely on the colour). Mark a decorative icon `aria-hidden`.
+ *
+ * **Look:** set by tokens. Subtle uses the variant's `color.feedback.<variant>Subtle`, `color.brand.primarySubtle` or `color.accent.subtle` background with the role colour as text; filled uses the role colour (`color.feedback.<variant>`, `color.brand.primary`, `color.accent.default`) as background with `color.text.on<Role>` as text. `shape.compact` sets the corners; `typography.body.*`, `typography.label.base.fontWeight` and `typography.control.letterSpacing` the text.
+ *
+ * @element oh-badge
+ * @slot - The badge text.
+ * @slot icon - Optional leading icon.
+ * @csspart badge - The badge.
+ */
 export declare class OhBadge extends OhElement {
     static styles: import("lit").CSSResult[];
     variant: BadgeVariant;
-    type: BadgeType;
+    /** `subtle` (default) for most badges; `filled`, the stronger appearance, for the one status that matters most */
+    appearance: BadgeAppearance;
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/oh-badge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oh-badge.d.ts","sourceRoot":"","sources":["../src/oh-badge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AACzF,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5C,qBACa,OAAQ,SAAQ,SAAS;IACpC,OAAgB,MAAM,4BAgHpB;IAGF,OAAO,EAAE,YAAY,CAAW;IAGhC,IAAI,EAAE,SAAS,CAAY;IAE3B,MAAM;CAcP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,UAAU,EAAE,OAAO,CAAC;KACrB;CACF"}
+{"version":3,"file":"oh-badge.d.ts","sourceRoot":"","sources":["../src/oh-badge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,OAAO,GACP,QAAQ,CAAC;AACb,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAElD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBACa,OAAQ,SAAQ,SAAS;IACpC,OAAgB,MAAM,4BAgHpB;IAGF,OAAO,EAAE,YAAY,CAAW;IAEhC,kHAAkH;IAElH,UAAU,EAAE,eAAe,CAAY;IAEvC,MAAM;CAcP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,UAAU,EAAE,OAAO,CAAC;KACrB;CACF"}

package/dist/oh-badge.js

@@ -1,25 +1,23 @@
 /**
  * oh-badge
  *
- * A flat, non-interactive badge for status indicators and labels.
- * Two styles per color: subtle (muted bg) and filled (strong bg).
+ * A non-interactive label for a status or category.
+ * Two types per variant: subtle and filled.
  *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. FLAT & NON-INTERACTIVE
- *    - No shadows, no hover states
+ * 1. NON-INTERACTIVE
+ *    - No shadow, no hover states, pointer-events off
  *    - Pure informational element
  *    - Not clickable
  *
- * 2. TWO INTENSITIES
- *    - Subtle: muted background, darker text
- *    - Filled: strong background, white/dark text
+ * 2. TWO TYPES
+ *    - Subtle: the variant's *Subtle background token, its role colour as text
+ *    - Filled: the role colour as background, its color.text.on* token as text
  *
  * 3. ACCESSIBLE CONTRAST
- *    - All text meets WCAG AA (4.5:1)
- *    - Filled variants use appropriate text color
- *
- * @element oh-badge
+ *    - Every text/background pair is in contrast-pairs.json, so
+ *      check:contrast checks it in every brand and mode
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -30,18 +28,39 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, css } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import { OhElement, baseStyles } from "./base.js";
+/**
+ * A short, non-interactive label that shows the status or category of the thing next to it.
+ *
+ * **Use it for** a status ("Delivered", "Pending"), a count or a tag next to the item it describes. **Don't use it for** anything the user can select (use `oh-button` or a link); or for a message with more than a word or two (use `oh-alert`).
+ *
+ * **Variants:** `brand` (default) and `accent` for categories; `success`, `warning`, `error` and `info` for status. **Appearance:** `subtle` (default), for most badges; `filled`, the stronger appearance, for the one status that matters most.
+ *
+ * **Parts:** the default slot holds the text; the `icon` slot an optional leading icon, sized to the text.
+ *
+ * **Behaviour:** none. It doesn't take focus or respond to the pointer.
+ *
+ * **Accessibility:** the badge is plain text to screen readers, so the text must make sense on its own (say "Pending", don't rely on the colour). Mark a decorative icon `aria-hidden`.
+ *
+ * **Look:** set by tokens. Subtle uses the variant's `color.feedback.<variant>Subtle`, `color.brand.primarySubtle` or `color.accent.subtle` background with the role colour as text; filled uses the role colour (`color.feedback.<variant>`, `color.brand.primary`, `color.accent.default`) as background with `color.text.on<Role>` as text. `shape.compact` sets the corners; `typography.body.*`, `typography.label.base.fontWeight` and `typography.control.letterSpacing` the text.
+ *
+ * @element oh-badge
+ * @slot - The badge text.
+ * @slot icon - Optional leading icon.
+ * @csspart badge - The badge.
+ */
 let OhBadge = class OhBadge extends OhElement {
     constructor() {
         super(...arguments);
         this.variant = "brand";
-        this.type = "subtle";
+        /** `subtle` (default) for most badges; `filled`, the stronger appearance, for the one status that matters most */
+        this.appearance = "subtle";
     }
     static { this.styles = [
         baseStyles,
         css `
       /* ═══════════════════════════════════════════════════════════════
-         ORANGE HALO BADGE
-         Flat • Non-interactive • Informational
+         BADGE
+         Non-interactive • Informational
          ═══════════════════════════════════════════════════════════════ */
 
       :host {
@@ -52,18 +71,18 @@ let OhBadge = class OhBadge extends OhElement {
         display: inline-flex;
         align-items: center;
         gap: var(--oh-spacing-1);
-        
+
         /* Typography */
         font-family: var(--oh-typography-body-font-family);
         font-size: var(--oh-typography-body-base-font-size);
         font-weight: var(--oh-typography-label-base-font-weight);
         line-height: var(--oh-typography-heading-h1-line-height);
         letter-spacing: var(--oh-typography-control-letter-spacing);
-        
+
         /* Shape */
         padding: var(--oh-spacing-1) var(--oh-spacing-2-5);
         border-radius: var(--oh-shape-compact);
-        
+
         /* No interaction */
         pointer-events: none;
         user-select: none;
@@ -153,7 +172,7 @@ let OhBadge = class OhBadge extends OhElement {
         const classes = this.classMap({
             badge: true,
             [`badge--${this.variant}`]: true,
-            [`badge--${this.type}`]: true,
+            [`badge--${this.appearance}`]: true,
         });
         return html `
       <span class=${classes} part="badge">
@@ -168,7 +187,7 @@ __decorate([
 ], OhBadge.prototype, "variant", void 0);
 __decorate([
     property({ type: String, reflect: true })
-], OhBadge.prototype, "type", void 0);
+], OhBadge.prototype, "appearance", void 0);
 OhBadge = __decorate([
     customElement("oh-badge")
 ], OhBadge);

package/dist/oh-badge.js.map

@@ -1 +1 @@
-{"version":3,"file":"oh-badge.js","sourceRoot":"","sources":["../src/oh-badge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;;;;;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAM3C,IAAM,OAAO,GAAb,MAAM,OAAQ,SAAQ,SAAS;IAA/B;;QAoHL,YAAO,GAAiB,OAAO,CAAC;QAGhC,SAAI,GAAc,QAAQ,CAAC;IAgB7B,CAAC;aAtIiB,WAAM,GAAG;QACvB,UAAU;QACV,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA6GF;KACF,AAhHqB,CAgHpB;IAQF,MAAM;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC5B,KAAK,EAAE,IAAI;YACX,CAAC,UAAU,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI;YAChC,CAAC,UAAU,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI;SAC9B,CAAC,CAAC;QAEH,OAAO,IAAI,CAAA;oBACK,OAAO;;;;KAItB,CAAC;IACJ,CAAC;;AAlBD;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;wCACV;AAGhC;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;qCACf;AAvHhB,OAAO;IADnB,aAAa,CAAC,UAAU,CAAC;GACb,OAAO,CAuInB"}
+{"version":3,"file":"oh-badge.js","sourceRoot":"","sources":["../src/oh-badge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;AAEH,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAWlD;;;;;;;;;;;;;;;;;;;GAmBG;AAEI,IAAM,OAAO,GAAb,MAAM,OAAQ,SAAQ,SAAS;IAA/B;;QAoHL,YAAO,GAAiB,OAAO,CAAC;QAEhC,kHAAkH;QAElH,eAAU,GAAoB,QAAQ,CAAC;IAgBzC,CAAC;aAvIiB,WAAM,GAAG;QACvB,UAAU;QACV,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA6GF;KACF,AAhHqB,CAgHpB;IASF,MAAM;QACJ,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC5B,KAAK,EAAE,IAAI;YACX,CAAC,UAAU,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI;YAChC,CAAC,UAAU,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,IAAI;SACpC,CAAC,CAAC;QAEH,OAAO,IAAI,CAAA;oBACK,OAAO;;;;KAItB,CAAC;IACJ,CAAC;;AAnBD;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;wCACV;AAIhC;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;2CACH;AAxH5B,OAAO;IADnB,aAAa,CAAC,UAAU,CAAC;GACb,OAAO,CAwInB"}

package/dist/oh-breadcrumb.d.ts

@@ -1,24 +1,20 @@
 /**
  * oh-breadcrumb
  *
- * Accessible breadcrumb navigation with responsive collapse.
- *
  * DESIGN DECISIONS:
  * ─────────────────
  * 1. SEMANTIC STRUCTURE
- *    - <nav> with aria-label="Breadcrumb"
- *    - <ol> for ordered list semantics
- *    - aria-current="page" on last item
+ *    - <nav aria-label="Breadcrumb"> around an <ol>
+ *    - aria-current="page" on the last item, which is not a link
+ *    - Separators are aria-hidden
  *
- * 2. REUSES EXISTING STYLES
- *    - Link styles match oh-link (dashed underline, shrink animation)
- *    - Typography and spacing from tokens
+ * 2. LINKS MIRROR oh-link INLINE
+ *    - Same underline tokens and hover/focus behaviour, written locally
+ *      so the trail is one component
  *
  * 3. RESPONSIVE
- *    - Desktop: Full breadcrumb trail
- *    - Mobile (<640px): Collapses to "← Back to [parent]"
- *
- * @element oh-breadcrumb
+ *    - Wide viewports: the full trail
+ *    - Below `size.breakpoint.sm`: a single "Back to [parent]" link
  */
 import { nothing } from "lit";
 import { OhElement } from "./base.js";
@@ -26,6 +22,37 @@ export interface BreadcrumbItem {
     label: string;
     href?: string;
 }
+/**
+ * A breadcrumb trail showing where the current page sits in the site's hierarchy.
+ *
+ * **Use it for** pages two or more levels deep in a hierarchy. **Don't use it
+ * for** a site's main navigation (use `oh-navbar`) or for steps in a process.
+ *
+ * **Parts:** pass `items`, an array of `{ label, href }`, from the top level
+ * down. The last item is the current page and is shown as text, not a link.
+ *
+ * **Behaviour:** below the `size.breakpoint.sm` width the trail collapses to a
+ * single "Back to [parent]" link to the second-to-last item; with one item,
+ * nothing shows there. Link underlines retract on hover; keyboard focus
+ * (`:focus-visible`) shows a solid underline and a background tint.
+ * Transitions are cut short under `prefers-reduced-motion`. Renders nothing
+ * when `items` is empty.
+ *
+ * **Accessibility:** renders `<nav aria-label="Breadcrumb">` with an ordered
+ * list, `aria-current="page"` on the last item and `aria-hidden` separators.
+ * Use one breadcrumb per page.
+ *
+ * **Look:** set by tokens — `color.text.link` the links,
+ * `decoration.underlineThickness`, `decoration.underlineDash` and
+ * `decoration.underlinePeriod` their underline; `color.brand.primary` the
+ * focus underline and `color.surface.hover` the focus tint;
+ * `color.text.primary` and `typography.label.base.fontWeight` the current
+ * page; `color.text.secondary` the separators; `typography.body.*` the text;
+ * `spacing.*` the gaps; `motion.relaxed` and `motion.easeGentle` the
+ * transitions.
+ *
+ * @element oh-breadcrumb
+ */
 export declare class OhBreadcrumb extends OhElement {
     static styles: import("lit").CSSResult[];
     items: BreadcrumbItem[];

package/dist/oh-breadcrumb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oh-breadcrumb.d.ts","sourceRoot":"","sources":["../src/oh-breadcrumb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAa,OAAO,EAAE,MAAM,KAAK,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBACa,YAAa,SAAQ,SAAS;IACzC,OAAgB,MAAM,4BA8LpB;IAGF,KAAK,EAAE,cAAc,EAAE,CAAM;IAE7B,MAAM;CA4CP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,eAAe,EAAE,YAAY,CAAC;KAC/B;CACF"}
+{"version":3,"file":"oh-breadcrumb.d.ts","sourceRoot":"","sources":["../src/oh-breadcrumb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAa,OAAO,EAAE,MAAM,KAAK,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,YAAa,SAAQ,SAAS;IACzC,OAAgB,MAAM,4BA2LpB;IAGF,KAAK,EAAE,cAAc,EAAE,CAAM;IAE7B,MAAM;CA8DP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,eAAe,EAAE,YAAY,CAAC;KAC/B;CACF"}