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

package/dist/docs/textfield/styling.md

@@ -1 +1,96 @@
 ## Styling API
+
+This section documents the supported styling hooks for `<w-textfield>`.
+
+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.
+
+### Parts
+
+The textfield exposes a minimal set of parts that can be targeted for last‑mile layout or typography tweaks.
+
+| Part | Targets | Typical use |
+|---|---|---|
+| `input` | native input element | minor typography or spacing tweaks |
+
+Example:
+
+```css
+w-textfield::part(input) {
+  letter-spacing: 0.5px;
+}
+```
+
+Parts are intended as an **escape hatch**.
+Prefer component tokens for anything state‑ or size‑related.
+
+
+### Component tokens
+
+Component tokens (`--w-c-input-*`) act as inputs to the textfield styling.
+They can be set directly on the component or inherited from a parent container.
+
+These tokens are **shared across textfield, textarea, and select** for consistent form styling.
+
+```css
+.form-section {
+  --w-c-input-label-font-weight: 600;
+  --w-c-input-help-text-color: var(--w-s-color-text);
+}
+```
+
+Defaults are defined internally; setting a token is always optional.
+
+
+#### Label tokens
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-label-color` | label text color | `--w-s-color-text` |
+| `--w-c-input-label-font-size` | label font size | `--w-font-size-s` |
+| `--w-c-input-label-line-height` | label line height | `--w-line-height-s` |
+| `--w-c-input-label-font-weight` | label font weight | `700` |
+| `--w-c-input-label-padding-bottom` | space below label | `0.4rem` |
+| `--w-c-input-label-cursor` | cursor when hovering label | `pointer` |
+| `--w-c-input-label-display` | label display mode | `block` |
+
+
+#### Optional indicator tokens
+
+When `optional` attribute is set, these tokens control the "(optional)" text styling:
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-optional-color` | optional text color | `--w-s-color-text-subtle` |
+| `--w-c-input-optional-font-size` | optional text font size | `--w-font-size-s` |
+| `--w-c-input-optional-line-height` | optional text line height | `--w-line-height-s` |
+| `--w-c-input-optional-font-weight` | optional text font weight | `400` |
+| `--w-c-input-optional-padding-left` | space before optional text | `0.8rem` |
+
+
+#### Help text tokens
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-help-text-color` | help text color (normal state) | `--w-s-color-text-subtle` |
+| `--w-c-input-help-text-color-invalid` | help text color when invalid | `--w-s-color-text-negative` |
+| `--w-c-input-help-text-font-size` | help text font size | `--w-font-size-xs` |
+| `--w-c-input-help-text-line-height` | help text line height | `--w-line-height-xs` |
+| `--w-c-input-help-text-margin-top` | space above help text | `0.4rem` |
+| `--w-c-input-help-text-display` | help text display mode | `block` |
+
+
+## Implementation notes
+
+### Shared token system
+
+Textfield shares its label, optional indicator, and help text tokens with `w-textarea` and `w-select`. This ensures consistent form styling across all text input components.
+
+### Affix accessibility
+
+Due to shadow DOM boundaries, affix content (prefix/suffix slots) cannot be connected to the input via ARIA references. For non-interactive affixes like currency symbols or unit labels, consider including that information in the main `label` or `placeholder` text instead for better screen reader support.

package/dist/docs/textfield/textfield.md

@@ -183,6 +183,101 @@ The readonly boolean attribute makes the w-textfield's text content immutable. U
 
 ## Styling API
 
+This section documents the supported styling hooks for `<w-textfield>`.
+
+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.
+
+### Parts
+
+The textfield exposes a minimal set of parts that can be targeted for last‑mile layout or typography tweaks.
+
+| Part | Targets | Typical use |
+|---|---|---|
+| `input` | native input element | minor typography or spacing tweaks |
+
+Example:
+
+```css
+w-textfield::part(input) {
+  letter-spacing: 0.5px;
+}
+```
+
+Parts are intended as an **escape hatch**.
+Prefer component tokens for anything state‑ or size‑related.
+
+
+### Component tokens
+
+Component tokens (`--w-c-input-*`) act as inputs to the textfield styling.
+They can be set directly on the component or inherited from a parent container.
+
+These tokens are **shared across textfield, textarea, and select** for consistent form styling.
+
+```css
+.form-section {
+  --w-c-input-label-font-weight: 600;
+  --w-c-input-help-text-color: var(--w-s-color-text);
+}
+```
+
+Defaults are defined internally; setting a token is always optional.
+
+
+#### Label tokens
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-label-color` | label text color | `--w-s-color-text` |
+| `--w-c-input-label-font-size` | label font size | `--w-font-size-s` |
+| `--w-c-input-label-line-height` | label line height | `--w-line-height-s` |
+| `--w-c-input-label-font-weight` | label font weight | `700` |
+| `--w-c-input-label-padding-bottom` | space below label | `0.4rem` |
+| `--w-c-input-label-cursor` | cursor when hovering label | `pointer` |
+| `--w-c-input-label-display` | label display mode | `block` |
+
+
+#### Optional indicator tokens
+
+When `optional` attribute is set, these tokens control the "(optional)" text styling:
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-optional-color` | optional text color | `--w-s-color-text-subtle` |
+| `--w-c-input-optional-font-size` | optional text font size | `--w-font-size-s` |
+| `--w-c-input-optional-line-height` | optional text line height | `--w-line-height-s` |
+| `--w-c-input-optional-font-weight` | optional text font weight | `400` |
+| `--w-c-input-optional-padding-left` | space before optional text | `0.8rem` |
+
+
+#### Help text tokens
+
+| Token | Purpose | Default |
+|---|---|---|
+| `--w-c-input-help-text-color` | help text color (normal state) | `--w-s-color-text-subtle` |
+| `--w-c-input-help-text-color-invalid` | help text color when invalid | `--w-s-color-text-negative` |
+| `--w-c-input-help-text-font-size` | help text font size | `--w-font-size-xs` |
+| `--w-c-input-help-text-line-height` | help text line height | `--w-line-height-xs` |
+| `--w-c-input-help-text-margin-top` | space above help text | `0.4rem` |
+| `--w-c-input-help-text-display` | help text display mode | `block` |
+
+
+## Implementation notes
+
+### Shared token system
+
+Textfield shares its label, optional indicator, and help text tokens with `w-textarea` and `w-select`. This ensures consistent form styling across all text input components.
+
+### Affix accessibility
+
+Due to shadow DOM boundaries, affix content (prefix/suffix slots) cannot be connected to the input via ARIA references. For non-interactive affixes like currency symbols or unit labels, consider including that information in the main `label` or `placeholder` text instead for better screen reader support.
+
 ## `<w-textfield>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -205,6 +300,7 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | min-length | `number \| undefined` | `-` | **Deprecated**: Use the native `minlength` attribute |
 | minlength | `number \| undefined` | `-` | For `text`, `search`, `url`, `tel`, `email` and `password` fields, sets the [minimum string length](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength) required. |
 | name | `string \| undefined` | `-` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form. |
+| optional | `boolean` | `false` | Whether to show the optional indicator after the label. |
 | pattern | `string \| undefined` | `-` | Sets a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) that the input's value must [match to pass validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#pattern) |
 | placeholder | `string \| undefined` | `-` | Shown in the textfield when it doesn't have a value |
 | prefixSlotChange (JS only) | `prefixSlotChange() => void` | `-` | - |
@@ -330,6 +426,13 @@ The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/
 - Type: `string | undefined`
 - Default: `-`
 
+#### optional
+
+Whether to show the optional indicator after the label.
+
+- Type: `boolean`
+- Default: `false`
+
 #### pattern
 
 Sets a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) that the input's value must [match to pass validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#pattern)

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { WarpIcon, WIcon } from "./packages/icon/icon.ts";
 import type { WarpTextField } from "./packages/textfield/textfield.ts";
+import type { WarpIcon, WIcon } from "./packages/icon/icon.ts";
 import type { WarpAffix } from "./packages/affix/affix.ts";
 import type { WarpAlert } from "./packages/alert/alert.ts";
 import type { WarpLink } from "./packages/link/link.ts";
@@ -237,33 +237,6 @@ type BaseEvents = {
   onPaste?: (event: ClipboardEvent) => void;
 };
 
-export type WarpIconProps = {
-  /** Icon filename (without .svg) */
-  name?: WarpIcon["name"];
-  /** Size: small, medium, large or pixel value (e.g. "32px"). */
-  size?: WarpIcon["size"];
-  /** Locale used for `<title>` text.
-
-Reads the `lang` attribute from `<html>`, falls back to 'en'. */
-  locale?: WarpIcon["locale"];
-};
-
-export type WarpIconSolidJsProps = {
-  /** Icon filename (without .svg) */
-  "prop:name"?: WarpIcon["name"];
-  /** Size: small, medium, large or pixel value (e.g. "32px"). */
-  "prop:size"?: WarpIcon["size"];
-  /** Locale used for `<title>` text.
-
-Reads the `lang` attribute from `<html>`, falls back to 'en'. */
-  "prop:locale"?: WarpIcon["locale"];
-
-  /** Set the innerHTML of the element */
-  innerHTML?: string;
-  /** Set the textContent of the element */
-  textContent?: string | number;
-};
-
 export type WarpTextFieldProps = {
   /** Keep in mind that using disabled in its current form is an anti-pattern.
 
@@ -281,6 +254,8 @@ or on its own to show a help text. */
   /** Use in combination with `invalid` to show as a validation error message,
 or on its own to show a help text. */
   helpText?: WarpTextField["helpText"];
+  /** Whether to show the optional indicator after the label. */
+  optional?: WarpTextField["optional"];
   /** Sets the [size](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#size) (width) of the input field to fit the expected length of inputs. */
   size?: WarpTextField["size"];
   /** Use with `type="number"` to set the [maximum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength). */
@@ -350,6 +325,8 @@ or on its own to show a help text. */
   /** Use in combination with `invalid` to show as a validation error message,
 or on its own to show a help text. */
   "prop:helpText"?: WarpTextField["helpText"];
+  /** Whether to show the optional indicator after the label. */
+  "prop:optional"?: WarpTextField["optional"];
   /** Sets the [size](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#size) (width) of the input field to fit the expected length of inputs. */
   "prop:size"?: WarpTextField["size"];
   /** Use with `type="number"` to set the [maximum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength). */
@@ -407,6 +384,33 @@ similar to the accessible input [masking example from Filament Group](https://fi
   textContent?: string | number;
 };
 
+export type WarpIconProps = {
+  /** Icon filename (without .svg) */
+  name?: WarpIcon["name"];
+  /** Size: small, medium, large or pixel value (e.g. "32px"). */
+  size?: WarpIcon["size"];
+  /** Locale used for `<title>` text.
+
+Reads the `lang` attribute from `<html>`, falls back to 'en'. */
+  locale?: WarpIcon["locale"];
+};
+
+export type WarpIconSolidJsProps = {
+  /** Icon filename (without .svg) */
+  "prop:name"?: WarpIcon["name"];
+  /** Size: small, medium, large or pixel value (e.g. "32px"). */
+  "prop:size"?: WarpIcon["size"];
+  /** Locale used for `<title>` text.
+
+Reads the `lang` attribute from `<html>`, falls back to 'en'. */
+  "prop:locale"?: WarpIcon["locale"];
+
+  /** Set the innerHTML of the element */
+  innerHTML?: string;
+  /** Set the textContent of the element */
+  textContent?: string | number;
+};
+
 export type WarpAffixProps = {
   /**  */
   "aria-label"?: WarpAffix["ariaLabel"];
@@ -2312,21 +2316,6 @@ Placeholder text should not be used as a substitute for labeling the element wit
 };
 
 export type CustomElements = {
-  /**
-   *
-   *
-   * ## Attributes & Properties
-   *
-   * Component attributes and properties that can be applied to the element or by using JavaScript.
-   *
-   * - `name`: Icon filename (without .svg)
-   * - `size`: Size: small, medium, large or pixel value (e.g. "32px").
-   * - `locale`: Locale used for `<title>` text.
-   *
-   * Reads the `lang` attribute from `<html>`, falls back to 'en'.
-   */
-  "w-icon": Partial<WarpIconProps & BaseProps<WarpIcon> & BaseEvents>;
-
   /**
    * A single-line input component used for entering and editing textual or numeric data.
    *
@@ -2343,6 +2332,7 @@ export type CustomElements = {
    * - `label`: Either a `label` or an `aria-label` must be provided.
    * - `help-text`/`helpText`: Use in combination with `invalid` to show as a validation error message,
    * or on its own to show a help text.
+   * - `optional`: Whether to show the optional indicator after the label.
    * - `size`: Sets the [size](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#size) (width) of the input field to fit the expected length of inputs.
    * - `max`: Use with `type="number"` to set the [maximum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength).
    * - `min`: Use with `type="number"` to set the [minimum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength).
@@ -2375,7 +2365,7 @@ export type CustomElements = {
    * Areas where markup can be added to the component.
    *
    * - `suffix`: Use with `<w-affix>` to include a suffix, for example the unit for a number (e. g. km or sek).
-   * - `prefix`: Use with `<w-affix>` to include a prefix, for example a search icon.
+   * - `prefix`: Use with `<w-affix>` to include a prefix, for example a search icon. ## Accessibility Note for Affixes Due to shadow DOM boundaries, affix content cannot be connected to the input via ARIA references. For non-interactive affixes (text labels like currency symbols), consider including that information in the main label or placeholder text instead for better screen reader support.
    *
    * ## Methods
    *
@@ -2390,9 +2380,34 @@ export type CustomElements = {
     WarpTextFieldProps & BaseProps<WarpTextField> & BaseEvents
   >;
 
+  /**
+   *
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `name`: Icon filename (without .svg)
+   * - `size`: Size: small, medium, large or pixel value (e.g. "32px").
+   * - `locale`: Locale used for `<title>` text.
+   *
+   * Reads the `lang` attribute from `<html>`, falls back to 'en'.
+   */
+  "w-icon": Partial<WarpIconProps & BaseProps<WarpIcon> & BaseEvents>;
+
   /**
    * This component is usually used in other components like form elements to show a prefix or suffix. See for example `w-textfield`.
    *
+   * ## Accessibility Note
+   * Due to shadow DOM encapsulation, ARIA attributes (like `aria-describedby`, `aria-labelledby`)
+   * cannot reference elements across shadow boundaries. This means:
+   * - Non-interactive affixes (text labels, icons) cannot be connected to the parent input via ARIA
+   * - Interactive affixes (buttons) must have their own `aria-label` (already implemented)
+   * - Do NOT attempt to reference affix content from parent components via ARIA ID references - it won't work
+   *
+   * For non-interactive labels (e.g., currency symbols), consider including the information in the
+   * main label or placeholder instead of relying on ARIA to announce affix content.
+   *
    * [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-affix--docs)
    *
    * ## Attributes & Properties
@@ -3502,8 +3517,8 @@ type ReactCustomElementProps<T extends HTMLElement, Props> = Omit<
   Props;
 
 type CustomElementInstances = {
-  "w-icon": WarpIcon;
   "w-textfield": WarpTextField;
+  "w-icon": WarpIcon;
   "w-affix": WarpAffix;
   "w-alert": WarpAlert;
   "w-link": WarpLink;
@@ -3542,8 +3557,8 @@ type CustomElementInstances = {
 };
 
 type CustomElementComponentProps = {
-  "w-icon": WarpIconProps;
   "w-textfield": WarpTextFieldProps;
+  "w-icon": WarpIconProps;
   "w-affix": WarpAffixProps;
   "w-alert": WarpAlertProps;
   "w-link": WarpLinkProps;
@@ -3588,23 +3603,6 @@ export type ReactCustomElements = {
 };
 
 export type CustomElementsSolidJs = {
-  /**
-   *
-   *
-   * ## Attributes & Properties
-   *
-   * Component attributes and properties that can be applied to the element or by using JavaScript.
-   *
-   * - `name`: Icon filename (without .svg)
-   * - `size`: Size: small, medium, large or pixel value (e.g. "32px").
-   * - `locale`: Locale used for `<title>` text.
-   *
-   * Reads the `lang` attribute from `<html>`, falls back to 'en'.
-   */
-  "w-icon": Partial<
-    WarpIconProps & WarpIconSolidJsProps & BaseProps<WarpIcon> & BaseEvents
-  >;
-
   /**
    * A single-line input component used for entering and editing textual or numeric data.
    *
@@ -3621,6 +3619,7 @@ export type CustomElementsSolidJs = {
    * - `label`: Either a `label` or an `aria-label` must be provided.
    * - `help-text`/`helpText`: Use in combination with `invalid` to show as a validation error message,
    * or on its own to show a help text.
+   * - `optional`: Whether to show the optional indicator after the label.
    * - `size`: Sets the [size](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#size) (width) of the input field to fit the expected length of inputs.
    * - `max`: Use with `type="number"` to set the [maximum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength).
    * - `min`: Use with `type="number"` to set the [minimum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength).
@@ -3653,7 +3652,7 @@ export type CustomElementsSolidJs = {
    * Areas where markup can be added to the component.
    *
    * - `suffix`: Use with `<w-affix>` to include a suffix, for example the unit for a number (e. g. km or sek).
-   * - `prefix`: Use with `<w-affix>` to include a prefix, for example a search icon.
+   * - `prefix`: Use with `<w-affix>` to include a prefix, for example a search icon. ## Accessibility Note for Affixes Due to shadow DOM boundaries, affix content cannot be connected to the input via ARIA references. For non-interactive affixes (text labels like currency symbols), consider including that information in the main label or placeholder text instead for better screen reader support.
    *
    * ## Methods
    *
@@ -3671,9 +3670,36 @@ export type CustomElementsSolidJs = {
       BaseEvents
   >;
 
+  /**
+   *
+   *
+   * ## Attributes & Properties
+   *
+   * Component attributes and properties that can be applied to the element or by using JavaScript.
+   *
+   * - `name`: Icon filename (without .svg)
+   * - `size`: Size: small, medium, large or pixel value (e.g. "32px").
+   * - `locale`: Locale used for `<title>` text.
+   *
+   * Reads the `lang` attribute from `<html>`, falls back to 'en'.
+   */
+  "w-icon": Partial<
+    WarpIconProps & WarpIconSolidJsProps & BaseProps<WarpIcon> & BaseEvents
+  >;
+
   /**
    * This component is usually used in other components like form elements to show a prefix or suffix. See for example `w-textfield`.
    *
+   * ## Accessibility Note
+   * Due to shadow DOM encapsulation, ARIA attributes (like `aria-describedby`, `aria-labelledby`)
+   * cannot reference elements across shadow boundaries. This means:
+   * - Non-interactive affixes (text labels, icons) cannot be connected to the parent input via ARIA
+   * - Interactive affixes (buttons) must have their own `aria-label` (already implemented)
+   * - Do NOT attempt to reference affix content from parent components via ARIA ID references - it won't work
+   *
+   * For non-interactive labels (e.g., currency symbols), consider including the information in the
+   * main label or placeholder instead of relying on ARIA to announce affix content.
+   *
    * [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-affix--docs)
    *
    * ## Attributes & Properties

package/dist/packages/affix/affix-styles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Affix component styles using the internal token pattern with a public styling API.
+ *
+ * Public API tokens (customizable):
+ * - Wrapper: --w-c-affix-*
+ * - Label: --w-c-affix-label-*
+ */
+export declare const affixStyles: import("lit").CSSResult;

package/dist/packages/affix/affix-styles.js

@@ -0,0 +1,108 @@
+import { css } from "lit";
+/**
+ * Affix component styles using the internal token pattern with a public styling API.
+ *
+ * Public API tokens (customizable):
+ * - Wrapper: --w-c-affix-*
+ * - Label: --w-c-affix-label-*
+ */
+export const affixStyles = css `
+	/* Wrapper component tokens with semantic fallbacks */
+	:host {
+		/* Internal tokens - not part of public API */
+		--_wrapper-bg: var(--w-c-affix-wrapper-bg, transparent);
+		--_wrapper-border-radius: var(--w-c-affix-wrapper-border-radius, 0.4rem);
+		--_wrapper-padding-left: var(--w-c-affix-wrapper-padding-left, 1.2rem);
+		--_wrapper-padding-right: var(--w-c-affix-wrapper-padding-right, 1.2rem);
+		--_wrapper-width-with-label: var(
+			--w-c-affix-wrapper-width-with-label,
+			max-content
+		);
+		--_wrapper-width-with-icon: var(--w-c-affix-wrapper-width-with-icon, 4rem);
+
+		/* Label tokens */
+		--_label-color: var(--w-c-affix-label-color, var(--w-s-color-text));
+		--_label-font-size: var(--w-c-affix-label-font-size, var(--w-font-size-xs));
+		--_label-line-height: var(
+			--w-c-affix-label-line-height,
+			var(--w-line-height-xs)
+		);
+		--_label-font-weight: var(--w-c-affix-label-font-weight, 700);
+		--_label-cursor: var(--w-c-affix-label-cursor, default);
+	}
+
+	/* Base wrapper styles (applied to all variants) */
+	[part="wrapper"] {
+		position: absolute;
+		top: 0;
+		bottom: 0;
+		display: flex;
+		justify-content: center;
+		align-items: center;
+		background-color: var(--_wrapper-bg);
+		border-radius: var(--_wrapper-border-radius);
+		-webkit-font-smoothing: antialiased;
+		-moz-osx-font-smoothing: grayscale;
+	}
+
+	/* Prefix positioning */
+	:host([slot="prefix"]) [part="wrapper"] {
+		left: 0;
+	}
+
+	/* Suffix positioning */
+	:host([slot="suffix"]) [part="wrapper"] {
+		right: 0;
+	}
+
+	/* Width variants */
+	[part="wrapper"].has-label {
+		width: var(--_wrapper-width-with-label);
+	}
+
+	:host([slot="prefix"]) [part="wrapper"].has-label {
+		padding-left: var(--_wrapper-padding-left);
+	}
+
+	:host([slot="suffix"]) [part="wrapper"].has-label {
+		padding-right: var(--_wrapper-padding-right);
+	}
+
+	[part="wrapper"].has-icon {
+		width: var(--_wrapper-width-with-icon);
+	}
+
+	/* Label styling */
+	[part="label"] {
+		display: block;
+		position: relative;
+		font-size: var(--_label-font-size);
+		line-height: var(--_label-line-height);
+		font-weight: var(--_label-font-weight);
+		color: var(--_label-color);
+		cursor: var(--_label-cursor);
+		padding-bottom: 0;
+	}
+
+	/* Button wrapper for interactive variants */
+	button[part="wrapper"] {
+		border: none;
+		outline: none;
+		cursor: pointer;
+	}
+
+	/* Focus styles for interactive variants */
+	button[part="wrapper"]:focus {
+		outline: 2px solid var(--w-s-color-border-focus);
+		outline-offset: var(--w-outline-offset, -2px);
+	}
+
+	button[part="wrapper"]:focus-visible {
+		outline: 2px solid var(--w-s-color-border-focus);
+		outline-offset: var(--w-outline-offset, -2px);
+	}
+
+	button[part="wrapper"]:not(:focus-visible) {
+		outline: none;
+	}
+`;

package/dist/packages/affix/affix.d.ts

@@ -4,6 +4,16 @@ declare const WarpAffix_base: import("@open-wc/form-control").Constructor<import
 /**
  * This component is usually used in other components like form elements to show a prefix or suffix. See for example `w-textfield`.
  *
+ * ## Accessibility Note
+ * Due to shadow DOM encapsulation, ARIA attributes (like `aria-describedby`, `aria-labelledby`)
+ * cannot reference elements across shadow boundaries. This means:
+ * - Non-interactive affixes (text labels, icons) cannot be connected to the parent input via ARIA
+ * - Interactive affixes (buttons) must have their own `aria-label` (already implemented)
+ * - Do NOT attempt to reference affix content from parent components via ARIA ID references - it won't work
+ *
+ * For non-interactive labels (e.g., currency symbols), consider including the information in the
+ * main label or placeholder instead of relying on ARIA to announce affix content.
+ *
  * [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-affix--docs)
  */
 declare class WarpAffix extends WarpAffix_base {
@@ -40,14 +50,7 @@ declare class WarpAffix extends WarpAffix_base {
     icon: string | null;
     static styles: import("lit").CSSResult[];
     /** @internal */
-    get _classBase(): {
-        wrapper: string;
-        wrapperWithLabel: string;
-        wrapperWithIcon: string;
-        label: string;
-    };
-    /** @internal */
-    get _classes(): string;
+    get _wrapperClasses(): string;
     /** @internal */
     resetContainingTextField(e: Event): void;
     /** @internal */