opui-css 4.1.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 5.0.0 - 2026-05-21
+
+### Breaking
+
+This is technically very breaking, but with a little prompting from you it's probably not a big deal for you. Hopefully you'll understand the reasoning behind this.
+
+Every OPUI-owned class now has a `ui-` prefix. This eliminates collisions with consumer styles and makes library classes self-identifying in the DOM.
+
+- Component prop API is **unchanged**: `<Button size="small" variant="outlined" color="primary">` works exactly as before.
+- Raw HTML / CSS users **must** rename every library class. `<button class="button outlined">` → `<button class="ui-button ui-outlined">`. `.button { ... }` overrides → `.ui-button { ... }`.
+- CSS custom properties (`--primary`, `--surface-default`, `--size-3`, …) are unchanged.
+- The framework component renders prefixed classes (`<button class="ui-button ui-small ui-outlined ui-primary">`); only the rendered HTML changes, not the public prop API.
+- **Divider**, **Progress**, **Table**, **Tabs**, and **Description List** now render and style prefixed classes end-to-end (`.ui-divider`, `.ui-progress`, `.ui-table`, `.ui-tab-label`, `.ui-tab-panel`, `.ui-term`). Plain `<hr>`, `<progress>`, and `<table>` elements no longer pick up library styles unless the class is present.
+- **Toggle Button**: pressed state no longer adds an unprefixed `selected` class.
+- **Avatar**: removed unused `spacing` prop and related group gap classes.
+
+#### Migration
+
+Run a project-wide find/replace per token, prompt or whatever. Below are all the classes that got a `ui-` prefix.
+
+<details>
+<summary>Migrated classes</summary>
+
+`abbr`, `accordion`, `actions`, `align-end`, `anchor`, `anchor-floating`, `auto-fit`, `avatar`, `backdrop-transparent`, `badge`, `badge-indicator`, `block-end`, `block-start`, `blockquote`, `border-filled`, `border-primary`, `border-tonal`, `border-top`, `bordered`, `button`, `button-group`, `callout`, `caption`, `card`, `checkbox`, `chip`, `cite`, `close-button`, `code-block`, `content`, `critical`, `dark`, `default`, `del`, `dense`, `description`, `description-list`, `dfn`, `dialog`, `disabled`, `divider`, `dot`, `dotted`, `drawer`, `elevated`, `end`, `end-end`, `end-start`, `end-text`, `exiting`, `field`, `field-description`, `field-group`, `fieldset`, `fieldset-item`, `filled`, `footer`, `form`, `gutterless`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `header`, `hgroup`, `icon`, `icon-button`, `icon-checked`, `icon-only`, `icon-unchecked`, `info`, `inline-end`, `inline-start`, `ins`, `inset`, `invisible`, `item`, `kbd`, `label`, `large`, `legend`, `light`, `link`, `list`, `mark`, `multiline`, `neutral`, `not-rich-text`, `outlined`, `overline`, `p`, `prefix`, `primary`, `progress`, `radio`, `range`, `rich-text`, `rounded`, `row`, `s`, `samp`, `scroll-lock`, `select`, `small`, `spacious`, `spread`, `squared`, `squircle`, `sr-only`, `stack`, `start`, `start-start`, `start-text`, `sub`, `success`, `suffix`, `sup`, `switch`, `tab-input`, `tab-label`, `tab-panel`, `table`, `tabs`, `term`, `text`, `text-field`, `textarea`, `title`, `toast`, `toggle-button`, `toggle-group`, `tonal`, `tooltip`, `transparent`, `u`, `value`, `var`, `vertical`, `warning`, `with-arrow`, `x-small`.
+
+</details>
+
+After the search/replace, do a visual smoke test — there is no automated codemod for consumer projects.
+
 ## 4.1.0 - 2026-05-18
 
 ### Breaking

package/MIGRATING.md

@@ -1,3 +1,25 @@
+# Migrating from v4 to v5
+
+v5 prefixes every OPUI-owned class with `ui-`. The component prop API is unchanged; only the rendered class names change.
+
+If you use the framework component (e.g. `<Button size="small" variant="outlined">`), you don't need to do anything — the component emits the prefixed classes for you.
+
+If you use raw HTML or write CSS that targets library classes, you must rename every reference:
+
+```diff
+- <button class="button outlined small">Save</button>
++ <button class="ui-button ui-outlined ui-small">Save</button>
+```
+
+```diff
+- .button.filled { /* override */ }
++ .ui-button.ui-filled { /* override */ }
+```
+
+The full list of renamed tokens is in [CHANGELOG.md](./CHANGELOG.md#500). Run a project-wide find/replace per token, then visually smoke test.
+
+CSS custom properties (`--primary`, `--surface-default`, `--size-3`, …) are unchanged.
+
 # Migrating from v3 to v4
 
 v4 is a full re-platform.
@@ -78,7 +100,7 @@ import { Button, Dialog, Tabs } from "opui-css/astro"
 
 `astro` is an _optional_ peer — only required if you actually import from `opui-css/astro`. Pure-CSS consumers won't see a peer warning.
 
-The components emit the same class names the v3 docs documented, so existing styles keep working.
+Astro components emit prefixed `ui-` classes (see the v4 → v5 section at the top of this file). Raw HTML and CSS overrides must use those prefixed names.
 
 ## 8. Cascade layers
 

package/README.md

@@ -38,7 +38,7 @@ Drop a pre-bundled stylesheet into any page and use the documented class names:
 ```html
 <link rel="stylesheet" href="https://unpkg.com/opui-css/dist/opui.css" />
 
-<button class="button primary">Click me</button>
+<button class="ui-button ui-primary">Click me</button>
 ```
 
 `dist/opui.css` is a single self-contained file (Open Props + normalize + theme + every component + utils, in the correct cascade layers). `dist/opui.components.css` is the same minus tokens and reset for users who already have those.

package/components/AGENTS.md

@@ -68,32 +68,33 @@ const { as: Tag = Astro.props.href ? "a" : "button", ...rest } = Astro.props
 - **Override**: Allow manual override via the `as` prop.
 
 ### Styling Inheritance
-Components should often inherit styles from others (e.g., `Dialog` looking like a `Card`). Use conditional classes to apply the inherited base class.
+Components should often inherit styles from others (e.g., `Dialog` looking like a `Card`). Use conditional classes to apply the inherited base class. All library classes are prefixed with `ui-`.
 
 ```astro
-<dialog class:list={["dialog", { card: variant }, variant, className]} {...rest}>
+<dialog class:list={["ui-dialog", { "ui-card": variant }, variant && `ui-${variant}`, className]} {...rest}>
 ```
 
 ---
 
 ## 3. Class Management
 
-Use `class:list` exclusively. Follow this order for readability:
-1.  **Component Base Class**: The primary CSS class (e.g., `"button"`).
-2.  **State Objects**: Boolean flags (e.g., `{ active, disabled, error }`).
-3.  **Variant Props**: Direct string values from props (e.g., `size`, `variant`).
-4.  **External Class**: Always include `className` at the end to allow for overrides.
+Use `class:list` exclusively. Every library-owned class is prefixed with `ui-`; the public prop API stays unprefixed (`<Button size="small" variant="outlined">`) and the component interpolates the prefix when rendering.
+
+Follow this order for readability:
+1.  **Component Base Class**: The primary CSS class, prefixed (e.g., `"ui-button"`).
+2.  **State Objects**: Boolean flags as quoted prefixed keys (e.g., `{ "ui-disabled": disabled }`).
+3.  **Variant Props**: Interpolate the prefix from the prop value (e.g., `size && \`ui-${size}\``).
+4.  **External Class**: Always include `className` at the end to allow for overrides. Do not prefix `className`.
 
 ```astro
 <div
   class:list={[
-    "chip",
+    "ui-chip",
     {
-      multiline: isMultiline,
-      selected,
+      "ui-multiline": isMultiline,
     },
-    size,
-    variant,
+    size && `ui-${size}`,
+    variant && `ui-${variant}`,
     className,
   ]}
 >
@@ -107,9 +108,9 @@ Use `class:list` exclusively. Follow this order for readability:
 For simple text-based components, provide both a `label` prop and a default slot.
 
 ```astro
-<div class="component">
+<div class="ui-component">
   { (label || Astro.slots.has("default")) && (
-    <span class="text">
+    <span class="ui-text">
       {label}
       <slot />
     </span>
@@ -121,10 +122,10 @@ For simple text-based components, provide both a `label` prop and a default slot
 Use named slots for specific functional areas. Check for existence before rendering wrapper tags.
 
 ```astro
-<div class="card">
+<div class="ui-card">
   {Astro.slots.has("header") && <header><slot name="header" /></header>}
   <slot />
-  {Astro.slots.has("actions") && <footer class="actions"><slot name="actions" /></footer>}
+  {Astro.slots.has("actions") && <footer class="ui-actions"><slot name="actions" /></footer>}
 </div>
 ```
 
@@ -136,10 +137,10 @@ Use named slots for specific functional areas. Check for existence before render
 Most inputs should be wrapped in a `<label>` to provide a larger hit area and built-in accessibility.
 
 ```astro
-<label class:list={["field", { disabled, error }]}>
-  <span class="label">{label}</span>
+<label class:list={["ui-field", { "ui-disabled": disabled, "ui-critical": error }]}>
+  <span class="ui-label">{label}</span>
   <input type="text" {...rest} />
-  {endText && <span class="end-text">{endText}</span>}
+  {endText && <span class="ui-end-text">{endText}</span>}
 </label>
 ```
 

package/components/Accordion/Accordion.astro

@@ -18,7 +18,7 @@ const contentId = $id("content")
 
 <details
   name={name}
-  class:list={["accordion", "card", variant, className]}
+  class:list={["ui-accordion", "ui-card", variant && `ui-${variant}`, className]}
   open={open}
   {...rest}
 >
@@ -27,14 +27,14 @@ const contentId = $id("content")
   <summary id={summaryId} aria-controls={contentId}><slot name="summary" /><slot name="marker" /></summary>
 
   <!-- Content -->
-  <div id={contentId} class="content" role="region" aria-labelledby={summaryId}>
+  <div id={contentId} class="ui-content" role="region" aria-labelledby={summaryId}>
     <slot />
   </div>
 
   <!-- Actions -->
   {
     Astro.slots.has("actions") && (
-      <div class="actions">
+      <div class="ui-actions">
         <slot name="actions" />
       </div>
     )

package/components/Anchor/Anchor.astro

@@ -35,7 +35,7 @@ const positionArea = alignment
   : {}
 ---
 
-<span class:list={["anchor", className]} style={positionArea} {...rest}>
+<span class:list={["ui-anchor", className]} style={positionArea} {...rest}>
   {
     isHover ? (
       <span {...({ interestfor: id } as any)}>
@@ -45,7 +45,7 @@ const positionArea = alignment
       <slot />
     )
   }
-  <span class="anchor-floating" id={id} popover={isHover ? "hint" : undefined}>
+  <span class="ui-anchor-floating" id={id} popover={isHover ? "hint" : undefined}>
     <slot name="anchored" />
   </span>
 </span>

package/components/Avatar/Avatar.astro

@@ -6,7 +6,6 @@ type Props = {
   class?: string
   href?: string
   isGroup?: boolean
-  spacing?: "small" | "x-small"
   src?: string
   variant?: "squared" | "rounded" | "squircle"
 }
@@ -19,7 +18,6 @@ const {
   class: className,
   href,
   isGroup,
-  spacing,
   src,
   variant,
   ...rest
@@ -31,12 +29,8 @@ const Tag = as || (href ? "a" : "div")
 <!-- prettier-ignore -->
 <Tag
   class:list={[
-    { avatar: !isGroup },
-    !isGroup && variant,
-    {
-      "gap-small": isGroup && spacing === "small",
-      "gap-x-small": isGroup && spacing === "x-small",
-    },
+    { "ui-avatar": !isGroup },
+    !isGroup && variant && `ui-${variant}`,
     className,
   ]}
   href={href}

package/components/Badge/Badge.astro

@@ -36,19 +36,24 @@ const positionArea =
 <Anchor
   alignment={positionArea}
   class:list={[
-    "badge",
+    "ui-badge",
     {
-      dot,
-      invisible,
+      "ui-dot": dot,
+      "ui-invisible": invisible,
     },
-    alignment,
+    alignment && `ui-${alignment}`,
     className,
-    color,
+    color && `ui-${color}`,
   ]}
   {...rest}
 >
   <slot />
-  <span class="badge-indicator" slot="anchored" aria-label={label?.toString()}
-    >{dot ? "" : label}</span
+  <span
+    class="ui-badge-indicator"
+    slot="anchored"
+    aria-label={label?.toString()}
   >
+    {dot ? "" : label}
+    {!dot && <slot name="indicator" />}
+  </span>
 </Anchor>

package/components/Button/Button.astro

@@ -39,7 +39,7 @@ const isButton = Tag === "button"
 
 <!-- prettier-ignore -->
 <Tag
-  class:list={["button", { disabled: isButton && disabled }, size, variant, color, className]}
+  class:list={["ui-button", { "ui-disabled": isButton && disabled }, size && `ui-${size}`, variant && `ui-${variant}`, color && `ui-${color}`, className]}
   disabled={isButton ? disabled : undefined}
   href={href}
   {...rest}><slot /></Tag>

package/components/ButtonGroup/ButtonGroup.astro

@@ -21,7 +21,7 @@ const {
 ---
 
 <div
-  class:list={["button-group", color, size, variant, orientation, className]}
+  class:list={["ui-button-group", color && `ui-${color}`, size && `ui-${size}`, variant && `ui-${variant}`, orientation && `ui-${orientation}`, className]}
   role="group"
   {...rest}
 >

package/components/Callout/Callout.astro

@@ -13,7 +13,7 @@ const { class: className, severity, variant, ...rest } = Astro.props
 
 <article
   role="note"
-  class:list={["callout", variant, severity, className]}
+  class:list={["ui-callout", variant && `ui-${variant}`, severity && `ui-${severity}`, className]}
   {...rest}
 >
   <slot name="icon">
@@ -63,11 +63,11 @@ const { class: className, severity, variant, ...rest } = Astro.props
       )
     }
   </slot>
-  <div class="content">
+  <div class="ui-content">
     {
       Astro.slots.has("title") && (
         <!-- prettier-ignore -->
-        <h3 class="title"><slot name="title" /></h3>
+        <h3 class="ui-title"><slot name="title" /></h3>
       )
     }
     <slot />

package/components/Card/Card.astro

@@ -10,7 +10,7 @@ export const title = "Card"
 const { variant, actionsAlign, class: className, ...rest } = Astro.props
 ---
 
-<div class:list={["card", variant, className]} {...rest}>
+<div class:list={["ui-card", variant && `ui-${variant}`, className]} {...rest}>
   {
     Astro.slots.has("header") && (
       <hgroup>
@@ -20,7 +20,7 @@ const { variant, actionsAlign, class: className, ...rest } = Astro.props
   }
   {
     Astro.slots.has("content") && (
-      <div class="content">
+      <div class="ui-content">
         <slot name="content" />
       </div>
     )
@@ -28,7 +28,7 @@ const { variant, actionsAlign, class: className, ...rest } = Astro.props
   <slot />
   {
     Astro.slots.has("actions") && (
-      <div class:list={["actions", actionsAlign && `align-${actionsAlign}`]}>
+      <div class:list={["ui-actions", actionsAlign && `ui-align-${actionsAlign}`]}>
         <slot name="actions" />
       </div>
     )

package/components/Checkbox/Checkbox.astro

@@ -45,11 +45,11 @@ const finalName = name || currentFieldName
 
 <label
   class:list={[
-    "checkbox",
-    size,
+    "ui-checkbox",
+    size && `ui-${size}`,
     {
-      stack,
-      spread,
+      "ui-stack": stack,
+      "ui-spread": spread,
     },
     className,
   ]}
@@ -66,11 +66,11 @@ const finalName = name || currentFieldName
     {value}
     {...rest}
   />
-  <!-- prettier-ignore --><span class:list={[hideLabel ? "sr-only" : "label"]}><slot /></span>
+  <!-- prettier-ignore --><span class:list={[hideLabel ? "ui-sr-only" : "ui-label"]}><slot /></span>
   {
     Astro.slots.has("end-text") && (
       <!-- prettier-ignore -->
-      <span id={endTextId} class="end-text"><slot name="end-text" /></span>
+      <span id={endTextId} class="ui-end-text"><slot name="end-text" /></span>
     )
   }
 </label>

package/components/Chip/Chip.astro

@@ -25,13 +25,13 @@ const {
 <!-- prettier-ignore -->
 <Tag
   class:list={[
-    "chip",
+    "ui-chip",
     {
-      multiline,
+      "ui-multiline": multiline,
     },
-    size,
-    variant,
+    size && `ui-${size}`,
+    variant && `ui-${variant}`,
     className,
   ]}
   {...rest}
-><slot name="start" /><slot />{label && <span class="text">{label}</span>}<slot name="end" /></Tag>
+><slot name="start" /><slot />{label && <span class="ui-text">{label}</span>}<slot name="end" /></Tag>

package/components/ClassicSelect/ClassicSelect.astro

@@ -45,10 +45,10 @@ const labelId = $id("select-label")
 
 <label
   class:list={[
-    "select",
-    size,
+    "ui-select",
+    size && `ui-${size}`,
     {
-      filled: variant === "filled",
+      "ui-filled": variant === "filled",
     },
     className,
   ]}
@@ -57,10 +57,10 @@ const labelId = $id("select-label")
   {
     label && (
       <!-- prettier-ignore -->
-      <span class="label" id={labelId}>{label}</span>
+      <span class="ui-label" id={labelId}>{label}</span>
     )
   }
-  <span class="field">
+  <span class="ui-field">
     <select
       aria-labelledby={label ? labelId : undefined}
       disabled={disabled}
@@ -77,7 +77,7 @@ const labelId = $id("select-label")
   {
     endText && (
       <!-- prettier-ignore -->
-      <span class="end-text">{endText}</span>
+      <span class="ui-end-text">{endText}</span>
     )
   }
 </label>

package/components/DescriptionList/Description.astro

@@ -7,6 +7,6 @@ type Props = {
 const { class: className, ...rest } = Astro.props
 ---
 
-<dd class:list={["description", className]} {...rest}>
+<dd class:list={["ui-description", className]} {...rest}>
   <slot />
 </dd>

package/components/DescriptionList/DescriptionList.astro

@@ -12,8 +12,8 @@ const { bordered, class: className, ...rest } = Astro.props
 
 <dl
   class:list={[
-    "description-list",
-    { bordered: bordered, dotted: bordered === "dotted" },
+    "ui-description-list",
+    { "ui-bordered": bordered, "ui-dotted": bordered === "dotted" },
     className,
   ]}
   {...rest}

package/components/DescriptionList/Item.astro

@@ -7,6 +7,6 @@ type Props = {
 const { class: className, ...rest } = Astro.props
 ---
 
-<div class:list={["item", className]} {...rest}>
+<div class:list={["ui-item", className]} {...rest}>
   <slot />
 </div>

package/components/DescriptionList/Term.astro

@@ -7,6 +7,6 @@ type Props = {
 const { class: className, ...rest } = Astro.props
 ---
 
-<dt class:list={["term", className]} {...rest}>
+<dt class:list={["ui-term", className]} {...rest}>
   <slot />
 </dt>

package/components/Dialog/Dialog.astro

@@ -12,7 +12,7 @@ const { actionsAlign, class: className, closedby, ...rest } = Astro.props
 ---
 
 <dialog
-  class:list={["dialog card elevated", className]}
+  class:list={["ui-dialog ui-card ui-elevated", className]}
   closedby={closedby}
   {...rest}
 >
@@ -25,7 +25,7 @@ const { actionsAlign, class: className, closedby, ...rest } = Astro.props
   }
   {
     Astro.slots.has("content") && (
-      <div class="content">
+      <div class="ui-content">
         <slot name="content" />
       </div>
     )
@@ -33,7 +33,7 @@ const { actionsAlign, class: className, closedby, ...rest } = Astro.props
   <slot />
   {
     Astro.slots.has("actions") && (
-      <div class:list={["actions", actionsAlign && `align-${actionsAlign}`]}>
+      <div class:list={["ui-actions", actionsAlign && `ui-align-${actionsAlign}`]}>
         <slot name="actions" />
       </div>
     )

package/components/Divider/Divider.astro

@@ -11,4 +11,7 @@ const { class: className, variant, ...rest } = Astro.props
 const variantClass = variant ? `border-${variant}` : ""
 ---
 
-<hr class:list={["divider", className, variantClass]} {...rest} />
+<hr
+  class:list={["ui-divider", className, variantClass && `ui-${variantClass}`]}
+  {...rest}
+/>

package/components/Drawer/Drawer.astro

@@ -28,11 +28,11 @@ const drawerId = id || $id("drawer")
 <dialog
   closedby={closedby}
   class:list={[
-    "drawer",
-    side,
+    "ui-drawer",
+    side && `ui-${side}`,
     {
-      "backdrop-transparent": backdrop === "transparent",
-      "scroll-lock": scrollLock,
+      "ui-backdrop-transparent": backdrop === "transparent",
+      "ui-scroll-lock": scrollLock,
     },
     className,
   ]}
@@ -41,7 +41,7 @@ const drawerId = id || $id("drawer")
 >
   {Astro.slots.has("header") && <slot name="header" />}
 
-  <div class="content">
+  <div class="ui-content">
     <slot name="content" />
   </div>
 

package/components/Drawer/DrawerFooter.astro

@@ -9,6 +9,6 @@ export const title = "Drawer Footer"
 const { class: className, ...rest } = Astro.props
 ---
 
-<div class:list={["footer", className]} {...rest}>
+<div class:list={["ui-footer", className]} {...rest}>
   <slot />
 </div>

package/components/Drawer/DrawerHeader.astro

@@ -12,7 +12,7 @@ export const title = "Drawer Header"
 const { class: className, heading, ...rest } = Astro.props
 ---
 
-<div class:list={["header", className]} {...rest}>
+<div class:list={["ui-header", className]} {...rest}>
   {heading && <span>{heading}</span>}
   <slot />
   <IconButton onclick="this.closest('dialog').close()" title="Close">

package/components/FieldDescription/FieldDescription.astro

@@ -10,4 +10,4 @@ const { class: className, ...rest } = Astro.props
 ---
 
 <!-- prettier-ignore -->
-<p class:list={["field-description", className]} {...rest}><slot /></p>
+<p class:list={["ui-field-description", className]} {...rest}><slot /></p>

package/components/FieldGroup/FieldGroup.astro

@@ -24,7 +24,7 @@ try {
 ---
 
 <div
-  class:list={["field-group", direction, className]}
+  class:list={["ui-field-group", direction && `ui-${direction}`, className]}
   {...rest}
   role="group"
   set:html={html}

package/components/FieldLegend/FieldLegend.astro

@@ -12,4 +12,4 @@ const isLegend = Tag === "legend"
 ---
 
 <!-- prettier-ignore -->
-<Tag class:list={[{ legend: !isLegend }, className]} {...rest}><slot /></Tag>
+<Tag class:list={[{ "ui-legend": !isLegend }, className]} {...rest}><slot /></Tag>

package/components/FieldSet/FieldSet.astro

@@ -10,6 +10,6 @@ export const title = "Field Set"
 const { as: Tag = "fieldset", class: className, ...rest } = Astro.props
 ---
 
-<Tag class:list={["fieldset", className]} {...rest}>
+<Tag class:list={["ui-fieldset", className]} {...rest}>
   <slot />
 </Tag>

package/components/Form/Form.astro

@@ -10,6 +10,6 @@ export const title = "Form"
 const { as: Tag = "form", class: className, ...rest } = Astro.props
 ---
 
-<Tag class:list={["form", className]} {...rest}>
+<Tag class:list={["ui-form", className]} {...rest}>
   <slot />
 </Tag>

package/components/IconButton/IconButton.astro

@@ -23,4 +23,4 @@ const {
 ---
 
 <!-- prettier-ignore -->
-<Tag class:list={["icon-button", size, variant, color, className]} href={href} {...rest}><slot /></Tag>
+<Tag class:list={["ui-icon-button", size && `ui-${size}`, variant && `ui-${variant}`, color && `ui-${color}`, className]} href={href} {...rest}><slot /></Tag>

package/components/List/List.astro

@@ -21,13 +21,13 @@ const {
 
 <ul
   class:list={[
-    "list",
+    "ui-list",
     {
-      bordered,
-      dense,
-      gutterless,
+      "ui-bordered": bordered,
+      "ui-dense": dense,
+      "ui-gutterless": gutterless,
     },
-    variant,
+    variant && `ui-${variant}`,
     className,
   ]}
   {...rest}