@warp-ds/elements 2.10.0-next.15 → 2.10.0-next.18

package/dist/docs/combobox/combobox.md

@@ -163,22 +163,22 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| autocomplete | `string \| undefined` | `'off'` | The autocomplete attribute passed to the internal input. |
+| autocomplete | `string \| undefined` | `"off"` | The autocomplete attribute passed to the internal input. |
 | disable-static-filtering | `boolean` | `false` | Whether built-in client-side filtering is disabled. |
 | disabled | `boolean` | `false` | Whether the combobox is disabled. |
-| help-text | `string \| undefined` | `''` | Help text displayed below the input. |
+| help-text | `string \| undefined` | `""` | Help text displayed below the input. |
 | invalid | `boolean` | `false` | Whether the combobox is visually invalid. |
-| label | `string \| undefined` | `''` | The label displayed above the input. |
+| label | `string \| undefined` | `""` | The label displayed above the input. |
 | match-text-segments | `boolean` | `false` | Whether matching text segments in options are highlighted. |
-| name | `string \| undefined` | `''` | The name submitted with the combobox value. |
+| name | `string \| undefined` | `""` | The name submitted with the combobox value. |
 | open-on-focus | `boolean` | `false` | Whether the option list opens when the input receives focus. |
 | optional | `boolean` | `false` | Whether to show optional text next to the label. |
 | options | `ComboboxOption[]` | `[]` | The available options to select from. |
-| placeholder | `string \| undefined` | `''` | Placeholder text displayed when the input is empty. |
+| placeholder | `string \| undefined` | `""` | Placeholder text displayed when the input is empty. |
 | required | `boolean` | `false` | Whether the combobox is required before form submission. |
 | resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
 | select-on-blur | `boolean` | `true` | Whether the active option is selected when the input loses focus. |
-| value | `string` | `''` | The selected or typed value. |
+| value | `string` | `""` | The selected or typed value. |
 
 ### Property Details
 
@@ -189,7 +189,7 @@ The autocomplete attribute passed to the internal input.
 Defaults to `off`. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token.
 
 - Type: `string | undefined`
-- Default: `'off'`
+- Default: `"off"`
 
 #### disable-static-filtering
 
@@ -216,7 +216,7 @@ Help text displayed below the input.
 Use this for supporting guidance or validation feedback.
 
 - Type: `string | undefined`
-- Default: `''`
+- Default: `""`
 
 #### invalid
 
@@ -234,7 +234,7 @@ The label displayed above the input.
 Use this to give the combobox a visible and accessible name.
 
 - Type: `string | undefined`
-- Default: `''`
+- Default: `""`
 
 #### match-text-segments
 
@@ -252,7 +252,7 @@ The name submitted with the combobox value.
 Use this when the combobox belongs to a form and its value should be included in form data.
 
 - Type: `string | undefined`
-- Default: `''`
+- Default: `""`
 
 #### open-on-focus
 
@@ -288,7 +288,7 @@ Placeholder text displayed when the input is empty.
 Use this as a short hint for the expected input. Do not use placeholder text as a replacement for a label.
 
 - Type: `string | undefined`
-- Default: `''`
+- Default: `""`
 
 #### required
 
@@ -322,5 +322,5 @@ The selected or typed value.
 When an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label.
 
 - Type: `string`
-- Default: `''`
+- Default: `""`
 

package/dist/docs/datepicker/api.md

@@ -7,8 +7,8 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | calendar (JS only) | `HTMLDivElement` | `-` | - |
-| day-format | `string` | `'PPPP'` | The date format used for calendar day accessible names. |
-| header-format | `string` | `'MMMM yyyy'` | The date format used in the calendar header. |
+| day-format | `string` | `"PPPP"` | The date format used for calendar day accessible names. |
+| header-format | `string` | `"MMMM yyyy"` | The date format used in the calendar header. |
 | input (JS only) | `HTMLInputElement` | `-` | - |
 | isCalendarOpen (JS only) | `boolean` | `false` | - |
 | isDayDisabled (JS only) | `((day: Date) => boolean) \| undefined` | `-` | Function used to disable dates in the calendar. |
@@ -25,7 +25,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | todayCell (JS only) | `HTMLTableCellElement` | `-` | - |
 | toggleButton (JS only) | `HTMLButtonElement` | `-` | - |
 | value | `string \| undefined` | `-` | The selected date value. |
-| weekday-format | `string` | `'EEEEEE'` | The weekday format shown above the calendar grid. |
+| weekday-format | `string` | `"EEEEEE"` | The weekday format shown above the calendar grid. |
 | weeks (JS only) | `unknown` | `-` | - |
 | wrapper (JS only) | `HTMLDivElement` | `-` | - |
 
@@ -45,7 +45,7 @@ The date format used for calendar day accessible names.
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
 
 - Type: `string`
-- Default: `'PPPP'`
+- Default: `"PPPP"`
 
 #### header-format
 
@@ -54,7 +54,7 @@ The date format used in the calendar header.
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
 
 - Type: `string`
-- Default: `'MMMM yyyy'`
+- Default: `"MMMM yyyy"`
 
 #### input (JS only)
 
@@ -189,7 +189,7 @@ The weekday format shown above the calendar grid.
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
 
 - Type: `string`
-- Default: `'EEEEEE'`
+- Default: `"EEEEEE"`
 
 #### weeks (JS only)
 

package/dist/docs/datepicker/datepicker.md

@@ -207,8 +207,8 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | calendar (JS only) | `HTMLDivElement` | `-` | - |
-| day-format | `string` | `'PPPP'` | The date format used for calendar day accessible names. |
-| header-format | `string` | `'MMMM yyyy'` | The date format used in the calendar header. |
+| day-format | `string` | `"PPPP"` | The date format used for calendar day accessible names. |
+| header-format | `string` | `"MMMM yyyy"` | The date format used in the calendar header. |
 | input (JS only) | `HTMLInputElement` | `-` | - |
 | isCalendarOpen (JS only) | `boolean` | `false` | - |
 | isDayDisabled (JS only) | `((day: Date) => boolean) \| undefined` | `-` | Function used to disable dates in the calendar. |
@@ -225,7 +225,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | todayCell (JS only) | `HTMLTableCellElement` | `-` | - |
 | toggleButton (JS only) | `HTMLButtonElement` | `-` | - |
 | value | `string \| undefined` | `-` | The selected date value. |
-| weekday-format | `string` | `'EEEEEE'` | The weekday format shown above the calendar grid. |
+| weekday-format | `string` | `"EEEEEE"` | The weekday format shown above the calendar grid. |
 | weeks (JS only) | `unknown` | `-` | - |
 | wrapper (JS only) | `HTMLDivElement` | `-` | - |
 
@@ -245,7 +245,7 @@ The date format used for calendar day accessible names.
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
 
 - Type: `string`
-- Default: `'PPPP'`
+- Default: `"PPPP"`
 
 #### header-format
 
@@ -254,7 +254,7 @@ The date format used in the calendar header.
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
 
 - Type: `string`
-- Default: `'MMMM yyyy'`
+- Default: `"MMMM yyyy"`
 
 #### input (JS only)
 
@@ -389,7 +389,7 @@ The weekday format shown above the calendar grid.
 The syntax is defined by [date-fns/format](https://date-fns.org/v4.1.0/docs/format).
 
 - Type: `string`
-- Default: `'EEEEEE'`
+- Default: `"EEEEEE"`
 
 #### weeks (JS only)
 

package/dist/docs/icon/api.md

@@ -8,7 +8,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 |-|-|-|-|
 | locale | `string` | `-` | Locale used for `<title>` text. |
 | name | `string` | `-` | Icon filename (without .svg) |
-| size | [`'small' \| 'medium' \| 'large' \| PixelValue \| undefined`](#small-medium-large-pixelvalue-undefined) | `"medium"` | Size: small, medium, large or pixel value (e.g. "32px"). |
+| size | [`"small" \| "medium" \| "large" \| PixelValue \| undefined`](#small-medium-large-pixelvalue-undefined) | `"medium"` | Size: small, medium, large or pixel value (e.g. "32px"). |
 
 ### Property Details
 
@@ -32,12 +32,12 @@ Icon filename (without .svg)
 
 Size: small, medium, large or pixel value (e.g. "32px").
 
-- Type: [`'small' | 'medium' | 'large' | PixelValue | undefined`](#small-medium-large-pixelvalue-undefined)
+- Type: [`"small" | "medium" | "large" | PixelValue | undefined`](#small-medium-large-pixelvalue-undefined)
 - Default: `"medium"`
 
 ### Types
 
-#### 'small' | 'medium' | 'large' | PixelValue | undefined
+#### "small" | "medium" | "large" | PixelValue | undefined
 
 `'small' | 'medium' | 'large' | `${number}px` | undefined`
 

package/dist/docs/icon/icon.md

@@ -80,7 +80,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 |-|-|-|-|
 | locale | `string` | `-` | Locale used for `<title>` text. |
 | name | `string` | `-` | Icon filename (without .svg) |
-| size | [`'small' \| 'medium' \| 'large' \| PixelValue \| undefined`](#small-medium-large-pixelvalue-undefined) | `"medium"` | Size: small, medium, large or pixel value (e.g. "32px"). |
+| size | [`"small" \| "medium" \| "large" \| PixelValue \| undefined`](#small-medium-large-pixelvalue-undefined) | `"medium"` | Size: small, medium, large or pixel value (e.g. "32px"). |
 
 ### Property Details
 
@@ -104,12 +104,12 @@ Icon filename (without .svg)
 
 Size: small, medium, large or pixel value (e.g. "32px").
 
-- Type: [`'small' | 'medium' | 'large' | PixelValue | undefined`](#small-medium-large-pixelvalue-undefined)
+- Type: [`"small" | "medium" | "large" | PixelValue | undefined`](#small-medium-large-pixelvalue-undefined)
 - Default: `"medium"`
 
 ### Types
 
-#### 'small' | 'medium' | 'large' | PixelValue | undefined
+#### "small" | "medium" | "large" | PixelValue | undefined
 
 `'small' | 'medium' | 'large' | `${number}px` | undefined`
 

package/dist/docs/index.md

@@ -14,11 +14,12 @@ Generated by `pnpm build:docs`. This file indexes the Markdown documentation shi
 | Attention | `<w-attention>` | `attention` | Attention is a versatile component for displaying contextual information and messages. It can be used for a wide range of purposes, such as tooltips, callouts, popovers, and highlights. The component is designed to be anchored to a trigger element, providing contextual information related to that element. It supports various placements and styling options to accommodate different use cases and design needs. Note: attention will soon be split into multiple components (tooltip, callout, popover, highlight) at which time this component will be deprecated. For now, use the `tooltip`, `callout`, `popover`, and `highlight` boolean properties to achieve the desired style and behavior. | [attention.md](./attention/attention.md) |
 | Badge | `<w-badge>` | `badge` | `w-badge` is used for showing a small amount of non-interactive color-categorized metadata, like a status or count. | [badge.md](./badge/badge.md) |
 | Box | `<w-box>` | `box` | Box is a layout component used for separating content areas on a page. | [box.md](./box/box.md) |
+| Breadcrumb Item | `<w-breadcrumb-item>` | `breadcrumb-item` | Represents one item in a `w-breadcrumbs` trail. Renders the slotted label as a link when `href` is set, or as text when it is not, and adds a separator after non-current items. | [breadcrumb-item.md](./breadcrumb-item/breadcrumb-item.md) |
 | Breadcrumbs | `<w-breadcrumbs>` | `breadcrumbs` | Shows the navigation structure for the current page. Renders direct child links and non-link elements as a breadcrumb trail, inserts separators between items, and exposes the trail as navigation. | [breadcrumbs.md](./breadcrumbs/breadcrumbs.md) |
 | Button | `<w-button>` | `button` | Performs an action or renders a link with button styling. Use button variants to match action priority, risk, and context. | [button.md](./button/button.md) |
 | Card | `<w-card>` | `card` | Card is a layout component used for separating content areas on a page. | [card.md](./card/card.md) |
 | Checkbox | `<w-checkbox>` | `checkbox` | Checkbox lets users select one or more options. Use it for independent yes/no choices, multi-select lists, and terms or consent confirmations. | [checkbox.md](./checkbox/checkbox.md) |
-| Checkbox Group | `<w-checkbox-group>` | `checkbox-group` | Use `w-checkbox-group` when several checkboxes share one label, help text, optional indicator, or required validation. | [checkbox-group.md](./checkbox-group/checkbox-group.md) |
+| Checkbox Group | `<w-checkbox-group>` | `checkbox-group` | Checkboxes allow users to select multiple options from a list of choices. Use with `w-checkbox`. ## Architecture Note This component uses a <div> wrapper instead of the more semantic <fieldset> element. Note that w-radio-group uses <fieldset>, which provides better accessibility and follows HTML best practices. This inconsistency exists for historical reasons and may be addressed in a future major version to align both on the more semantic approach. TODO: Align w-checkbox-group to use <fieldset> in a future major version after assessing backwards compatibility implications (CSS selectors, etc.). | [checkbox-group.md](./checkbox-group/checkbox-group.md) |
 | Combobox | `<w-combobox>` | `combobox` | A combobox element for text input with selectable options. | [combobox.md](./combobox/combobox.md) |
 | Datepicker | `<w-datepicker>` | `datepicker` | An input for dates. Uses the `lang` attribute on either the element or on `<html>` to determine the locale options. | [datepicker.md](./datepicker/datepicker.md) |
 | Expandable | `<w-expandable>` | `expandable` | Expandable is a layout component used for creating expandable content areas on a page. | [expandable.md](./expandable/expandable.md) |

package/dist/docs/radio-group/api.md

@@ -7,9 +7,9 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | disabled | `boolean` | `false` | Disables the radio group and all child radios. |
-| help-text | `string` | `''` | Help text for the radio group. |
+| help-text | `string` | `""` | Help text for the radio group. |
 | invalid | `boolean` | `false` | Marks the radio group as invalid. |
-| label | `string` | `''` | Label for the radio group. |
+| label | `string` | `""` | Label for the radio group. |
 | name | `string \| null` | `null` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form. |
 | optional | `boolean` | `false` | Whether to show optional text next to the label. |
 | required | `boolean` | `false` | Makes selecting a radio in the the group required. |
@@ -30,7 +30,7 @@ Help text for the radio group.
 If you set `required` and `invalid` the group gets a default error message, but you can override it with this attribute.
 
 - Type: `string`
-- Default: `''`
+- Default: `""`
 
 #### invalid
 
@@ -44,7 +44,7 @@ Marks the radio group as invalid.
 Label for the radio group.
 
 - Type: `string`
-- Default: `''`
+- Default: `""`
 
 #### name
 

package/dist/docs/radio-group/radio-group.md

@@ -122,123 +122,238 @@ Please consider more informative alternatives before choosing to use disabled on
 
 </elements-example>
 
-## Styling API
+# Radio and Radio Group Styling
 
-This section documents the supported styling hooks for `<w-radio>` and `<w-radio-group>`.
+This document covers the styling API for both `<w-radio>` (individual radio buttons) and `<w-radio-group>` (the container that manages them).
 
-Use these hooks to customize appearance without relying on internal structure or selectors.
+## Quick Start
 
-Before changing the default styles, remember that doing so can result in less consistent experiences for users across the product. Prefer defaults.
+```html
+<w-radio-group label="Choose a size" name="size">
+  <w-radio value="small">Small</w-radio>
+  <w-radio value="medium">Medium</w-radio>
+  <w-radio value="large">Large</w-radio>
+</w-radio-group>
+```
 
-- Prefer **component tokens** for size, spacing, and state styling.
-- Use **parts** only for small, local tweaks.
-- Avoid relying on internal class names or selectors.
+Customize via component tokens:
 
-### Parts
+```css
+/* Style all radio groups in a section */
+.settings {
+  --w-c-radio-group-gap: 12px;
+  --w-c-radio-size: 2.4rem;
+}
+```
+
+---
+
+## Styling Philosophy
 
-The radio exposes a small set of parts that can be targeted for last‑mile layout or typography tweaks.
+Before customizing, remember that changing defaults can create inconsistent experiences. Prefer the defaults.
 
-| Part | Targets | Typical use |
-|---|---|---|
-| `control` | radio control (circle) | minor alignment or sizing tweaks |
-| `label` | label content | typography tweaks |
+- **Component tokens** for size, spacing, color, and state styling
+- **Parts** only for small, one-off tweaks
+- Avoid relying on internal class names
 
-Example:
+---
 
+## Radio Group (`<w-radio-group>`)
+
+### Parts
+
+| Part | Targets | Use Case |
+|------|---------|----------|
+| `form-control` | The `<fieldset>` wrapper | Outer container tweaks |
+| `form-control-label` | The group label element | Label typography overrides |
+| `form-control-input` | Container for radio buttons | Adjust layout/flow of radios |
+| `help-text` | Help text / error message | Style hint text |
+
+**Example:**
 ```css
-w-radio::part(label) {
-  font-weight: 600;
+w-radio-group::part(form-control-label) {
+  text-transform: uppercase;
 }
 
-w-radio::part(control) {
-  margin-top: 1px;
+w-radio-group::part(form-control-input) {
+  flex-direction: row; /* horizontal radios */
 }
 ```
 
-Parts are intended as an **escape hatch**.
-Prefer component tokens for anything state‑ or size‑related.
+### Component Tokens
 
+#### Label
 
-### Component tokens
+| Token | Purpose | Default |
+|-------|---------|---------|
+| `--w-c-radio-group-label-font-size` | Label font size | `var(--w-font-size-s)` |
+| `--w-c-radio-group-label-line-height` | Label line height | `var(--w-line-height-s)` |
+| `--w-c-radio-group-label-font-weight` | Label font weight | `700` |
+| `--w-c-radio-group-label-color` | Label text color | `var(--w-s-color-text)` |
+| `--w-c-radio-group-label-color-disabled` | Label color when disabled | `var(--w-s-color-text-disabled)` |
+| `--w-c-radio-group-label-padding-bottom` | Space below label | `16px` |
+
+#### Optional Indicator
 
-Component tokens (`--w-c-radio-*`) act as inputs to the radio styling.
-They can be set directly on the component or inherited from a parent container.
+| Token | Purpose | Default |
+|-------|---------|---------|
+| `--w-c-radio-group-optional-font-weight` | "Optional" text weight | `400` |
+| `--w-c-radio-group-optional-color` | "Optional" text color | `var(--w-s-color-text-subtle)` |
+| `--w-c-radio-group-optional-margin-inline-start` | Space before "Optional" | `0.5rem` |
 
+#### Radio Spacing
+
+| Token | Purpose | Default |
+|-------|---------|---------|
+| `--w-c-radio-group-gap` | Gap between radio buttons | `16px` |
+
+#### Help Text
+
+| Token | Purpose | Default |
+|-------|---------|---------|
+| `--w-c-radio-group-help-text-margin-block-start` | Space above help text | `16px` |
+| `--w-c-radio-group-help-text-font-size` | Help text font size | `var(--w-font-size-xs)` |
+| `--w-c-radio-group-help-text-line-height` | Help text line height | `var(--w-line-height-xs)` |
+| `--w-c-radio-group-help-text-color` | Help text color | `var(--w-s-color-text-subtle)` |
+| `--w-c-radio-group-help-text-color-disabled` | Help text color when disabled | `var(--w-s-color-text-disabled)` |
+| `--w-c-radio-group-help-text-color-error` | Help text color when invalid | `var(--w-s-color-text-negative)` |
+
+**Example:**
 ```css
-.settings-panel {
-  --w-c-radio-gap: 12px;
+w-radio-group {
+  --w-c-radio-group-gap: 12px;
+  --w-c-radio-group-label-font-weight: 600;
+  --w-c-radio-group-help-text-color: var(--w-s-color-text);
 }
 ```
 
-Defaults are defined internally; setting a token is always optional.
-
+---
 
-#### Layout & size
+## Individual Radio (`<w-radio>`)
 
-| Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-gap` | space between control and label | `8px` |
-| `--w-c-radio-size` | width/height of the control | `2rem` |
-| `--w-c-radio-radius` | border radius of the control | `50%` |
-| `--w-c-radio-border-width` | border width | `1px` |
-| `--w-c-radio-checked-border-width` | border width when checked | `0.6rem` |
+### Parts
 
+| Part | Targets | Use Case |
+|------|---------|----------|
+| `base` | Wrapper containing control and label | Container-level adjustments |
+| `control` | Radio control (circle) | Alignment or sizing tweaks |
+| `label` | Label content | Typography overrides |
 
-#### Colors
+**Example:**
+```css
+w-radio::part(label) {
+  font-weight: 600;
+}
 
-| Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-bg` | control background | theme default |
-| `--w-c-radio-border-color` | control border color | theme default |
-| `--w-c-radio-border-color-checked` | border color when checked | theme default |
-| `--w-c-radio-label-color` | label text color | `currentColor` |
+w-radio::part(control) {
+  margin-top: 1px;
+}
+```
 
+### Component Tokens
 
-#### Invalid state
+#### Layout & Size
 
 | Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-border-color-invalid` | border color when invalid | theme default |
+|-------|---------|---------|
+| `--w-c-radio-gap` | Space between control and label | `8px` |
+| `--w-c-radio-size` | Width/height of control | `2rem` |
+| `--w-c-radio-radius` | Border radius | `50%` |
+| `--w-c-radio-border-width` | Border width | `1px` |
+| `--w-c-radio-checked-border-width` | Border width when checked | `0.6rem` |
 
+#### Colors
 
-#### Disabled state
+| Token | Purpose | Default |
+|-------|---------|---------|
+| `--w-c-radio-bg` | Control background | `var(--w-s-color-background)` |
+| `--w-c-radio-border-color` | Control border color | `var(--w-s-color-border-strong)` |
+| `--w-c-radio-border-color-checked` | Border when checked | `var(--w-s-color-border-selected)` |
+| `--w-c-radio-border-color-invalid` | Border when invalid | `var(--w-s-color-border-negative)` |
+| `--w-c-radio-label-color` | Label text color | `currentColor` |
+
+#### Disabled State
 
 | Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-bg-disabled` | background when disabled | theme default |
-| `--w-c-radio-border-color-disabled` | border when disabled | theme default |
-| `--w-c-radio-label-color-disabled` | label color when disabled | theme default |
-| `--w-c-radio-cursor-disabled` | cursor when disabled | `not-allowed` |
+|-------|---------|---------|
+| `--w-c-radio-bg-disabled` | Background when disabled | `var(--w-s-color-background-disabled-subtle)` |
+| `--w-c-radio-border-color-disabled` | Border when disabled | `var(--w-s-color-border-disabled)` |
+| `--w-c-radio-label-color-disabled` | Label color when disabled | `var(--w-s-color-text-disabled)` |
+| `--w-c-radio-cursor-disabled` | Cursor when disabled | `not-allowed` |
 
 #### Typography
 
 | Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-label-font-size` | label font size | theme default |
-| `--w-c-radio-label-line-height` | label line height | theme default |
-
+|-------|---------|---------|
+| `--w-c-radio-label-font-size` | Label font size | `var(--w-font-size-m)` |
+| `--w-c-radio-label-line-height` | Label line height | `var(--w-line-height-m)` |
 
 #### Focus
 
 | Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-outline-width` | focus outline width | `2px` |
-| `--w-c-radio-outline-color` | focus outline color | theme default |
-| `--w-c-radio-outline-offset` | focus outline offset | theme default |
+|-------|---------|---------|
+| `--w-c-radio-outline-width` | Focus outline width | `2px` |
+| `--w-c-radio-outline-color` | Focus outline color | `var(--w-s-color-border-focus)` |
+| `--w-c-radio-outline-offset` | Focus outline offset | `var(--w-outline-offset, 1px)` |
 
 #### Interaction
 
 | Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-cursor` | cursor in enabled state | `pointer` |
+|-------|---------|---------|
+| `--w-c-radio-cursor` | Cursor in enabled state | `pointer` |
 
 #### Motion
 
 | Token | Purpose | Default |
-|---|---|---|
-| `--w-c-radio-transition` | transition for control | `150ms cubic-bezier(0.4, 0, 0.2, 1)` |
+|-------|---------|---------|
+| `--w-c-radio-transition` | Transition for control | `border-color 150ms, border-width 150ms, background-color 150ms` |
+
+**Note:** Transitions automatically disable when `prefers-reduced-motion: reduce` is active.
+
+---
+
+## Complete Examples
+
+### Horizontal Radio Group
+
+```css
+w-radio-group::part(form-control-input) {
+  flex-direction: row;
+  flex-wrap: wrap;
+}
+```
+
+### Larger Radio Buttons
+
+```css
+w-radio {
+  --w-c-radio-size: 2.4rem;
+  --w-c-radio-checked-border-width: 0.8rem;
+}
+```
+
+### Custom Colors
+
+```css
+w-radio {
+  --w-c-radio-border-color-checked: var(--w-s-color-border-success);
+}
+```
+
+### Tighter Spacing
+
+```css
+w-radio-group {
+  --w-c-radio-group-gap: 8px;
+  --w-c-radio-group-label-padding-bottom: 8px;
+}
+```
+
+---
+
+## Architecture Note
 
-Transitions are automatically disabled when `prefers-reduced-motion: reduce` is active.
+**Radio-group uses `<fieldset>`** which is the semantic HTML element for grouping form controls. Note that `<w-checkbox-group>` currently uses `<div>` instead - this inconsistency may be addressed in a future major version to align both components on the more accessible `<fieldset>` approach.
 
 ## `<w-radio-group>` API
 
@@ -249,9 +364,9 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | disabled | `boolean` | `false` | Disables the radio group and all child radios. |
-| help-text | `string` | `''` | Help text for the radio group. |
+| help-text | `string` | `""` | Help text for the radio group. |
 | invalid | `boolean` | `false` | Marks the radio group as invalid. |
-| label | `string` | `''` | Label for the radio group. |
+| label | `string` | `""` | Label for the radio group. |
 | name | `string \| null` | `null` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the select when submitting the form. |
 | optional | `boolean` | `false` | Whether to show optional text next to the label. |
 | required | `boolean` | `false` | Makes selecting a radio in the the group required. |
@@ -272,7 +387,7 @@ Help text for the radio group.
 If you set `required` and `invalid` the group gets a default error message, but you can override it with this attribute.
 
 - Type: `string`
-- Default: `''`
+- Default: `""`
 
 #### invalid
 
@@ -286,7 +401,7 @@ Marks the radio group as invalid.
 Label for the radio group.
 
 - Type: `string`
-- Default: `''`
+- Default: `""`
 
 #### name