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

package/dist/docs/checkbox/api.md

@@ -18,7 +18,7 @@
 | reportValidity (JS only) | `reportValidity() => boolean` | `-` | Checks validity and shows the browser's validation message if invalid |
 | required | `boolean` | `false` | Whether the checkbox must be checked before form submission. |
 | resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
-| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true }` | - |
+| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
 | validationMessage (JS only) | `string` | `-` | Returns the validation message if the checkbox is invalid, otherwise an empty string |
 | validity (JS only) | `ValidityState` | `-` | Returns the validity state of the checkbox |
 | value | `string \| null` | `null` | The value submitted when the checkbox is checked. |
@@ -140,7 +140,7 @@ A required checkbox is invalid until it is checked. For requiring at least one o
 
 
 - Type: `object`
-- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true }`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
 
 ##### validationMessage (JS only)
 

package/dist/docs/checkbox/checkbox.md

@@ -4,6 +4,180 @@
 
 Checkbox lets users select one or more options. Use it for independent yes/no choices, multi-select lists, and terms or consent confirmations.
 
+# Checkbox Styling
+
+The checkbox component provides a comprehensive styling API through CSS custom properties (tokens).
+
+## Styling API
+
+### Label Tokens
+
+Customize the appearance of the label text:
+
+```css
+--w-c-checkbox-label-font-size: var(--w-font-size-m);
+--w-c-checkbox-label-line-height: var(--w-line-height-m);
+```
+
+### Control Tokens
+
+Customize the checkbox control (the box itself):
+
+```css
+--w-c-checkbox-control-size: 2rem;
+--w-c-checkbox-gap: 8px;
+--w-c-checkbox-radius: 4px;
+--w-c-checkbox-border-width: 1px;
+```
+
+### Color Tokens - Default State
+
+```css
+--w-c-checkbox-bg: var(--w-s-color-background);
+--w-c-checkbox-border-color: var(--w-s-color-border-strong);
+--w-c-checkbox-icon-color: var(--w-s-color-icon-inverted);
+```
+
+### Color Tokens - Checked State
+
+```css
+--w-c-checkbox-bg-checked: var(--w-s-color-background-primary);
+--w-c-checkbox-border-color-checked: var(--w-s-color-border-primary);
+--w-c-checkbox-checked-icon: var(--w-icon-toggle-checked);
+```
+
+### Color Tokens - Invalid State
+
+```css
+--w-c-checkbox-border-color-invalid: var(--w-s-color-border-negative);
+--w-c-checkbox-bg-invalid-checked: var(--w-s-color-background-negative);
+```
+
+### Color Tokens - Disabled State
+
+```css
+--w-c-checkbox-bg-disabled: var(--w-s-color-background-disabled-subtle);
+--w-c-checkbox-border-color-disabled: var(--w-s-color-border-disabled);
+--w-c-checkbox-bg-disabled-checked: var(--w-s-color-background-disabled);
+```
+
+### Focus Tokens
+
+```css
+--w-c-checkbox-outline-width: 2px;
+--w-c-checkbox-outline-color: var(--w-s-color-border-focus);
+--w-c-checkbox-outline-offset: var(--w-outline-offset, 1px);
+```
+
+### Animation Tokens
+
+```css
+--w-c-checkbox-transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
+```
+
+## Parts
+
+For advanced styling needs beyond tokens, you can target internal elements using CSS parts:
+
+- `::part(base)` - The wrapper `<label>` element
+- `::part(control)` - The visual checkbox control (the box)
+- `::part(input)` - The native `<input type="checkbox">` element
+- `::part(label)` - The label content wrapper
+
+```css
+w-checkbox::part(control) {
+  /* Custom styling for the checkbox box */
+  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+}
+
+w-checkbox::part(label) {
+  /* Custom styling for label text */
+  text-transform: uppercase;
+}
+```
+
+## Example Usage
+
+### Customizing Size
+
+```css
+w-checkbox {
+  --w-c-checkbox-control-size: 2.4rem;
+  --w-c-checkbox-gap: 12px;
+}
+```
+
+### Customizing Colors
+
+```css
+w-checkbox {
+  --w-c-checkbox-bg-checked: var(--w-s-color-background-success);
+  --w-c-checkbox-border-color-checked: var(--w-s-color-border-success);
+}
+```
+
+### Customizing Border Radius
+
+```css
+w-checkbox {
+  --w-c-checkbox-radius: 8px; /* More rounded */
+}
+
+/* Or fully rounded */
+w-checkbox {
+  --w-c-checkbox-radius: 50%;
+}
+```
+
+### Customizing Focus Outline
+
+```css
+w-checkbox {
+  --w-c-checkbox-outline-width: 3px;
+  --w-c-checkbox-outline-color: var(--w-s-color-border-info);
+  --w-c-checkbox-outline-offset: 2px;
+}
+```
+
+### Disabling Transitions
+
+```css
+w-checkbox {
+  --w-c-checkbox-transition: none;
+}
+```
+
+### Using Parts for Advanced Styling
+
+```css
+/* Add a subtle shadow to the checkbox */
+w-checkbox::part(control) {
+  box-shadow: inset 0 1px 3px rgba(0,0,0,0.1);
+}
+
+/* Style the label with custom spacing */
+w-checkbox::part(label) {
+  padding-left: 4px;
+  font-weight: 500;
+}
+```
+
+## Label Content
+
+Unlike textfield/textarea components, checkbox labels accept rich HTML content via the default slot:
+
+```html
+<w-checkbox>
+  I agree to the <a href="/terms">terms and conditions</a>
+</w-checkbox>
+
+<w-checkbox>
+  <strong>Important:</strong> Check this box
+</w-checkbox>
+```
+
+Style the label content directly or use `::part(label)` to target the wrapper.
+
 ### `<w-checkbox>` API
 
 #### Properties
@@ -24,7 +198,7 @@ Checkbox lets users select one or more options. Use it for independent yes/no ch
 | reportValidity (JS only) | `reportValidity() => boolean` | `-` | Checks validity and shows the browser's validation message if invalid |
 | required | `boolean` | `false` | Whether the checkbox must be checked before form submission. |
 | resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
-| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true }` | - |
+| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
 | validationMessage (JS only) | `string` | `-` | Returns the validation message if the checkbox is invalid, otherwise an empty string |
 | validity (JS only) | `ValidityState` | `-` | Returns the validity state of the checkbox |
 | value | `string \| null` | `null` | The value submitted when the checkbox is checked. |
@@ -146,7 +320,7 @@ A required checkbox is invalid until it is checked. For requiring at least one o
 
 
 - Type: `object`
-- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true }`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
 
 ##### validationMessage (JS only)
 

package/dist/docs/checkbox/styling.md

@@ -0,0 +1,173 @@
+# Checkbox Styling
+
+The checkbox component provides a comprehensive styling API through CSS custom properties (tokens).
+
+## Styling API
+
+### Label Tokens
+
+Customize the appearance of the label text:
+
+```css
+--w-c-checkbox-label-font-size: var(--w-font-size-m);
+--w-c-checkbox-label-line-height: var(--w-line-height-m);
+```
+
+### Control Tokens
+
+Customize the checkbox control (the box itself):
+
+```css
+--w-c-checkbox-control-size: 2rem;
+--w-c-checkbox-gap: 8px;
+--w-c-checkbox-radius: 4px;
+--w-c-checkbox-border-width: 1px;
+```
+
+### Color Tokens - Default State
+
+```css
+--w-c-checkbox-bg: var(--w-s-color-background);
+--w-c-checkbox-border-color: var(--w-s-color-border-strong);
+--w-c-checkbox-icon-color: var(--w-s-color-icon-inverted);
+```
+
+### Color Tokens - Checked State
+
+```css
+--w-c-checkbox-bg-checked: var(--w-s-color-background-primary);
+--w-c-checkbox-border-color-checked: var(--w-s-color-border-primary);
+--w-c-checkbox-checked-icon: var(--w-icon-toggle-checked);
+```
+
+### Color Tokens - Invalid State
+
+```css
+--w-c-checkbox-border-color-invalid: var(--w-s-color-border-negative);
+--w-c-checkbox-bg-invalid-checked: var(--w-s-color-background-negative);
+```
+
+### Color Tokens - Disabled State
+
+```css
+--w-c-checkbox-bg-disabled: var(--w-s-color-background-disabled-subtle);
+--w-c-checkbox-border-color-disabled: var(--w-s-color-border-disabled);
+--w-c-checkbox-bg-disabled-checked: var(--w-s-color-background-disabled);
+```
+
+### Focus Tokens
+
+```css
+--w-c-checkbox-outline-width: 2px;
+--w-c-checkbox-outline-color: var(--w-s-color-border-focus);
+--w-c-checkbox-outline-offset: var(--w-outline-offset, 1px);
+```
+
+### Animation Tokens
+
+```css
+--w-c-checkbox-transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
+```
+
+## Parts
+
+For advanced styling needs beyond tokens, you can target internal elements using CSS parts:
+
+- `::part(base)` - The wrapper `<label>` element
+- `::part(control)` - The visual checkbox control (the box)
+- `::part(input)` - The native `<input type="checkbox">` element
+- `::part(label)` - The label content wrapper
+
+```css
+w-checkbox::part(control) {
+  /* Custom styling for the checkbox box */
+  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+}
+
+w-checkbox::part(label) {
+  /* Custom styling for label text */
+  text-transform: uppercase;
+}
+```
+
+## Example Usage
+
+### Customizing Size
+
+```css
+w-checkbox {
+  --w-c-checkbox-control-size: 2.4rem;
+  --w-c-checkbox-gap: 12px;
+}
+```
+
+### Customizing Colors
+
+```css
+w-checkbox {
+  --w-c-checkbox-bg-checked: var(--w-s-color-background-success);
+  --w-c-checkbox-border-color-checked: var(--w-s-color-border-success);
+}
+```
+
+### Customizing Border Radius
+
+```css
+w-checkbox {
+  --w-c-checkbox-radius: 8px; /* More rounded */
+}
+
+/* Or fully rounded */
+w-checkbox {
+  --w-c-checkbox-radius: 50%;
+}
+```
+
+### Customizing Focus Outline
+
+```css
+w-checkbox {
+  --w-c-checkbox-outline-width: 3px;
+  --w-c-checkbox-outline-color: var(--w-s-color-border-info);
+  --w-c-checkbox-outline-offset: 2px;
+}
+```
+
+### Disabling Transitions
+
+```css
+w-checkbox {
+  --w-c-checkbox-transition: none;
+}
+```
+
+### Using Parts for Advanced Styling
+
+```css
+/* Add a subtle shadow to the checkbox */
+w-checkbox::part(control) {
+  box-shadow: inset 0 1px 3px rgba(0,0,0,0.1);
+}
+
+/* Style the label with custom spacing */
+w-checkbox::part(label) {
+  padding-left: 4px;
+  font-weight: 500;
+}
+```
+
+## Label Content
+
+Unlike textfield/textarea components, checkbox labels accept rich HTML content via the default slot:
+
+```html
+<w-checkbox>
+  I agree to the <a href="/terms">terms and conditions</a>
+</w-checkbox>
+
+<w-checkbox>
+  <strong>Important:</strong> Check this box
+</w-checkbox>
+```
+
+Style the label content directly or use `::part(label)` to target the wrapper.

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

@@ -2,7 +2,18 @@
 
 ## Description
 
-Use `w-checkbox-group` when several checkboxes share one label, help text, optional indicator, or required validation.
+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.).
 
 ## Usage
 
@@ -280,10 +291,18 @@ Avoid option labels that only make sense visually, such as "Yes" or "This one",
 
 ## Styling API
 
-This section documents the supported styling hooks for `<w-checkbox>`.
+This section documents the supported styling hooks for `<w-checkbox>` and `<w-checkbox-group>`.
 
 Use these hooks to customize appearance without relying on internal structure or selectors.
 
+Before changing the default styles, remember that doing so can result in less consistent experiences for users across the product. Prefer defaults.
+
+- Prefer **component tokens** for size, spacing, and state styling.
+- Use **parts** only for small, local tweaks.
+- Avoid relying on internal class names or selectors.
+
+## w-checkbox
+
 ### Parts
 
 The checkbox exposes a small set of parts that can be targeted for last‑mile layout or typography tweaks.
@@ -307,12 +326,12 @@ w-checkbox::part(control) {
 }
 ```
 
-Parts are intended as an **escape hatch**.  
+Parts are intended as an **escape hatch**.
 Prefer component tokens for anything state‑ or size‑related.
 
-### Component tokens (`--w-c-checkbox-*`)
+### Component tokens
 
-Component tokens act as inputs to the checkbox styling.  
+Component tokens (`--w-c-checkbox-*`) act as inputs to the checkbox styling.
 They can be set directly on the component or inherited from a parent container.
 
 ```css
@@ -377,39 +396,33 @@ Defaults are defined internally; setting a token is always optional.
 
 Transitions are automatically disabled when `prefers-reduced-motion: reduce` is active.
 
-### Examples
 
-#### Compact checkbox
+## w-checkbox-group
 
-```css
-.filters w-checkbox {
-  --w-c-checkbox-gap: 4px;
-  --w-c-checkbox-control-size: 1.6rem;
-}
-```
+The checkbox-group component uses direct CSS styling rather than component tokens. Customization is limited to ensure consistent form control patterns across the design system.
 
-#### Rounded checkbox
+### Styling
 
-```css
-w-checkbox {
-  --w-c-checkbox-radius: 9999px;
-}
-```
+The checkbox-group provides minimal styling hooks:
 
-#### Contextual color override (advanced)
+| Element | Current styling | Note |
+|---|---|---|
+| Label | `font-size: var(--w-font-size-s)`<br>`line-height: var(--w-line-height-s)`<br>`font-weight: 700`<br>`color: var(--w-s-color-text)` | Uses semantic tokens |
+| Optional indicator | `font-weight: 400`<br>`color: var(--w-s-color-text-subtle)` | Matches form control pattern |
+| Help text | `font-size: var(--w-font-size-xs)`<br>`line-height: var(--w-line-height-xs)`<br>`color: var(--w-s-color-text-subtle)` | Error state: `--w-s-color-text-negative` |
+| Checkbox spacing | `gap: 16px` | Spacing between checkboxes |
+| Wrapper spacing | `gap: 16px` | Spacing between label and group |
 
-```css
-.danger-zone w-checkbox {
-  --w-c-checkbox-border-color-checked: red;
-}
-```
 
-### Guidelines
+## Implementation notes
+
+### 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.
+
+**Why this matters:** `<fieldset>` with `<legend>` provides automatic grouping semantics and better screen reader support. The current `<div>` + `role="group"` implementation works but requires manual ARIA wiring.
 
-- Prefer **component tokens** for size, spacing, and state styling
-- Use **parts** only for small, local tweaks
-- Avoid relying on internal class names or selectors
-- If multiple tokens are required to achieve a look, consider whether a new variant or design token is more appropriate
+**TODO:** Consider aligning w-checkbox-group to use `<fieldset>` in a future major version after assessing backwards compatibility implications (CSS selectors, etc.).
 
 ## `<w-checkbox-group>` API
 

package/dist/docs/checkbox-group/styling.md

@@ -1,9 +1,17 @@
 ## Styling API
 
-This section documents the supported styling hooks for `<w-checkbox>`.
+This section documents the supported styling hooks for `<w-checkbox>` and `<w-checkbox-group>`.
 
 Use these hooks to customize appearance without relying on internal structure or selectors.
 
+Before changing the default styles, remember that doing so can result in less consistent experiences for users across the product. Prefer defaults.
+
+- Prefer **component tokens** for size, spacing, and state styling.
+- Use **parts** only for small, local tweaks.
+- Avoid relying on internal class names or selectors.
+
+## w-checkbox
+
 ### Parts
 
 The checkbox exposes a small set of parts that can be targeted for last‑mile layout or typography tweaks.
@@ -27,12 +35,12 @@ w-checkbox::part(control) {
 }
 ```
 
-Parts are intended as an **escape hatch**.  
+Parts are intended as an **escape hatch**.
 Prefer component tokens for anything state‑ or size‑related.
 
-### Component tokens (`--w-c-checkbox-*`)
+### Component tokens
 
-Component tokens act as inputs to the checkbox styling.  
+Component tokens (`--w-c-checkbox-*`) act as inputs to the checkbox styling.
 They can be set directly on the component or inherited from a parent container.
 
 ```css
@@ -97,36 +105,30 @@ Defaults are defined internally; setting a token is always optional.
 
 Transitions are automatically disabled when `prefers-reduced-motion: reduce` is active.
 
-### Examples
 
-#### Compact checkbox
+## w-checkbox-group
 
-```css
-.filters w-checkbox {
-  --w-c-checkbox-gap: 4px;
-  --w-c-checkbox-control-size: 1.6rem;
-}
-```
+The checkbox-group component uses direct CSS styling rather than component tokens. Customization is limited to ensure consistent form control patterns across the design system.
 
-#### Rounded checkbox
+### Styling
 
-```css
-w-checkbox {
-  --w-c-checkbox-radius: 9999px;
-}
-```
+The checkbox-group provides minimal styling hooks:
 
-#### Contextual color override (advanced)
+| Element | Current styling | Note |
+|---|---|---|
+| Label | `font-size: var(--w-font-size-s)`<br>`line-height: var(--w-line-height-s)`<br>`font-weight: 700`<br>`color: var(--w-s-color-text)` | Uses semantic tokens |
+| Optional indicator | `font-weight: 400`<br>`color: var(--w-s-color-text-subtle)` | Matches form control pattern |
+| Help text | `font-size: var(--w-font-size-xs)`<br>`line-height: var(--w-line-height-xs)`<br>`color: var(--w-s-color-text-subtle)` | Error state: `--w-s-color-text-negative` |
+| Checkbox spacing | `gap: 16px` | Spacing between checkboxes |
+| Wrapper spacing | `gap: 16px` | Spacing between label and group |
 
-```css
-.danger-zone w-checkbox {
-  --w-c-checkbox-border-color-checked: red;
-}
-```
 
-### Guidelines
+## Implementation notes
+
+### 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.
+
+**Why this matters:** `<fieldset>` with `<legend>` provides automatic grouping semantics and better screen reader support. The current `<div>` + `role="group"` implementation works but requires manual ARIA wiring.
 
-- Prefer **component tokens** for size, spacing, and state styling
-- Use **parts** only for small, local tweaks
-- Avoid relying on internal class names or selectors
-- If multiple tokens are required to achieve a look, consider whether a new variant or design token is more appropriate
+**TODO:** Consider aligning w-checkbox-group to use `<fieldset>` in a future major version after assessing backwards compatibility implications (CSS selectors, etc.).

package/dist/docs/combobox/api.md

@@ -6,22 +6,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
 
@@ -32,7 +32,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
 
@@ -59,7 +59,7 @@ Help text displayed below the input.
 Use this for supporting guidance or validation feedback.
 
 - Type: `string | undefined`
-- Default: `''`
+- Default: `""`
 
 #### invalid
 
@@ -77,7 +77,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
 
@@ -95,7 +95,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
 
@@ -131,7 +131,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
 
@@ -165,5 +165,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: `""`