@recursica/adapter-mantine-v8 1.0.0

package/src/components/Checkbox/CheckboxGroup.tsx

@@ -0,0 +1,147 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  Checkbox as MantineCheckbox,
+  type CheckboxGroupProps as MantineCheckboxGroupProps,
+} from "@mantine/core";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  omitUnsupportedProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import styles from "./Checkbox.module.css";
+
+import { type RecursicaCheckboxGroupProps as BaseRecursicaCheckboxGroupProps } from "@recursica/adapter-common";
+
+export interface RecursicaCheckboxGroupProps
+  extends Omit<
+      MantineCheckboxGroupProps,
+      "size" | "labelProps" | "defaultValue" | "value"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaCheckboxGroupProps {}
+
+export type CheckboxGroupProps =
+  RecursicaOverStyled<RecursicaCheckboxGroupProps>;
+
+export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
+  function CheckboxGroup(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label Wrappers
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      // Base Mantine Extracted Attributes
+      label,
+      description,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      children,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      ...rest
+    } = props;
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls sizing via Checkbox.module.css variables, not Mantine's native size scale.
+    ] as const satisfies readonly (keyof MantineCheckboxGroupProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    ) as Partial<typeof rest>;
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Mantine's own `Checkbox.Group` always establishes a context whose `value` defaults to
+    // `[]` (see @mantine/core's `useUncontrolled({ finalValue: [] })`), and its `Checkbox` spreads
+    // that context-derived `checked` *after* the individually-passed `checked` prop — so any
+    // `Checkbox` nested in a real `Checkbox.Group`, even one given neither `value` nor
+    // `defaultValue`, has its own `checked` prop silently forced to `false`. Callers who only want
+    // this component for its layout (item-gap spacing), not array-tracked selection — e.g.
+    // `TransferList`'s ungrouped rows, which pass each `Checkbox` its own controlled `checked` —
+    // must skip Mantine's real group primitive entirely rather than hand it an empty value.
+    const isArrayControlled = value !== undefined || defaultValue !== undefined;
+
+    return (
+      <WithReadOnlyWrapper
+        className={className}
+        style={style as React.CSSProperties}
+        controlMaxWidth="var(--recursica_ui-kit_components_checkbox-item_properties_max-width)"
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        labelElement="div" // Strictly override. ARIA grouping prohibits interactive checkboxes nested natively inside <label>.
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        description={description}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        withAsterisk={withAsterisk}
+        id={id}
+        readOnly={readOnly && !!readOnlyComponent}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          isArrayControlled ? (
+            <MantineCheckbox.Group
+              ref={ref}
+              /* Natively bind local disabled lock dynamically */
+              {...(sanitizedProps as unknown as MantineCheckboxGroupProps)}
+              disabled={readOnly || (restRecord as any).disabled}
+              value={value as any}
+              defaultValue={defaultValue as any}
+            >
+              <div className={styles.groupRoot} data-layout={formLayout}>
+                {children}
+              </div>
+            </MantineCheckbox.Group>
+          ) : (
+            <div
+              ref={ref}
+              {...(sanitizedProps as Record<string, unknown>)}
+              role="group"
+              className={styles.groupRoot}
+              data-layout={formLayout}
+            >
+              {children}
+            </div>
+          )
+        }
+      />
+    );
+  },
+);
+
+CheckboxGroup.displayName = "CheckboxGroup";

package/src/components/Checkbox/USAGE.md

@@ -0,0 +1,48 @@
+# Checkbox - Usage Guide
+
+This document describes how to integrate and use the `Checkbox` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Checkbox } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Checkbox } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <Checkbox label="Accept terms and conditions" defaultChecked />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Checkbox Alignment with Multi-line Labels
+
+Checkbox visually aligns to the first line of a wrapping, multi-line label.
+
+### Checkbox.Group
+
+`Checkbox.Group` integrates with the same label, description, and error props as other Recursica form components.

package/src/components/Chip/CHIP_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,110 @@
+# Chip Implementation Notes
+
+## Architecture decisions
+
+### Mantine DOM Structure & Label Overrides
+
+Mantine's `<Chip>` behaves like an input element (`radio` or `checkbox`). Under the hood, it renders:
+
+1. `.mantine-Chip-root` (wrapper)
+2. `input` (hidden visual structure)
+3. `.mantine-Chip-label` (The actual visible button-like pill)
+
+Because the `.label` is the primary visual surface and handles Mantine's built-in `:hover` and active states, we direct our Recursica styling natively to `.label`.
+
+### Icon and Remove Implementations
+
+To achieve this without breaking Mantine's `Chip` input architecture, we wrapped the internal `children` using a standard `span` DOM strategy:
+
+```tsx
+<span className={styles.innerWrapper}>
+  {icon}
+  <span className={styles.children}>{children}</span>
+  {onDelete}
+</span>
+```
+
+#### Intermediate Children Wrapper Span display fix:
+
+Mantine internally wraps the children passed to `Chip` in a default `<span>` which has `display: inline`. This intermediate `span` inherits the `line-height` of the `.label` container, causing the computed height of the Chip to be ~2px taller than expected. To address this, `.label > span:not(.mantineIconWrapper)` is targeted to force `display: inline-flex; align-items: center;` on that intermediate wrapper `span`, allowing it to collapse perfectly to the `16px` height of the `innerWrapper`.
+
+### Accessibility of Remove Action
+
+Because the Chip fundamentally functions as a `<label>` linked to an `<input>`, placing a raw interactive element like `<button>` directly inside the standard Chip sub-tree violates nested interactive element ARIA constraints in strict validators.
+To accommodate this, the visual "close" icon uses a `<span>` element configured with `role="button"` and `tabIndex={0}` to hook into standard keyboard activations without triggering generic nested `<form>` conflicts native to Mantine's baseline constraints.
+
+### Removing Sizing Properties
+
+During implementation, the parsed Figma design tokens natively exported specific height/padding vectors dynamically (e.g., `--recursica_ui-kit_components_chip_properties_icon-size`) rather than explicit string variants (`sm`, `md`, `lg`). Therefore, we omitted `size` conceptually from the `RecursicaChipProps` wrapper to lock down size evaluation natively against the active layer variables.
+
+### Long-label truncation was hiding the remove icon (Matt Massey, 2026-08-17)
+
+`.children` already had `text-overflow: ellipsis; overflow: hidden; white-space: nowrap;`, but
+neither it nor its parent `.innerWrapper` had `min-width: 0` — a flex child without that refuses
+to shrink below its intrinsic (full, unwrapped) content width, so `text-overflow: ellipsis` never
+actually engaged. A long label overflowed the flex row instead, and since `.deleteIcon` had no
+`flex-shrink: 0`, it got squeezed out of the clipped (`max-width`-bounded) chip entirely. Fixed by
+adding `min-width: 0` to `.innerWrapper`/`.children` and `flex-shrink: 0` to `.leadingIcon`/
+`.deleteIcon`. Reproduces easily with `FileUpload`'s file list, since its chip `max-width`
+(`--recursica_ui-kit_components_chip_properties_max-width`, 200px) is small enough that most real
+filenames overflow it.
+
+### Descenders were being clipped on `.children` and `.root` (Matt Massey, 2026-08-18)
+
+A label with a descender (e.g. the "g" in "image.png") had its bottom clipped off. Both `.children`
+and `.root.root` set plain `overflow: hidden` — needed on the x-axis so `.children`'s
+`text-overflow: ellipsis` (and `.root`'s `max-width`) actually clip long labels, but clipping the
+y-axis too cuts off any glyph ink that extends past the line box, which happens whenever the
+`text_line-height` token is tighter than the font's natural ascent+descent. Fixed by splitting both
+into `overflow-x: hidden; overflow-y: visible;` — ellipsis/max-width truncation is unaffected (still
+x-axis only), but descenders can now paint outside a too-tight line box instead of being clipped.
+`.root` has no background/border-radius of its own to protect (that's `.label`), so opening its
+y-axis has no visual side effect.
+
+### Roving tabindex support for chip groups (Matt Massey, 2026-08-17)
+
+Added two optional pass-through props — `deleteTabIndex` and `deleteIconRef` — purely so a parent
+managing a _group_ of chips (e.g. `FileUpload`'s file list, see its own `IMPLEMENTATION_NOTES.md`)
+can implement roving-tabindex/arrow-key navigation across them: set `deleteTabIndex={-1}` on every
+chip but the currently-active one, and use `deleteIconRef` to move real DOM focus there
+imperatively on arrow-key press. Both are no-ops for a standalone `Chip` (defaults: `tabIndex={0}`,
+no ref) — this doesn't change any existing single-chip behavior.
+
+### `isInteractive` was measuring the wrong signal, and leaked a pointer cursor + phantom Tab stop (Matt Massey, 2026-08-18)
+
+A `Chip` rendered with `checked` but no real handler (e.g. `FileUpload`'s `readOnly` file list —
+`<Chip checked={false} tabIndex={-1}>`, no `onDelete`) still looked and behaved clickable, from two
+separate bugs:
+
+- `isInteractive` treated `checked !== undefined` (even `false`) as proof of interactivity. That's
+  the wrong signal — a `checked`-controlled chip with no `onChange` can't actually be toggled by a
+  click (Mantine's `useUncontrolled` discards the click when `value` is externally controlled), so
+  clicking it does nothing observable regardless. `isInteractive` now only looks at whether
+  something actually responds: `onDelete`, `onClick`, or `onChange`.
+- `.label.label` never set its own `cursor`, so Mantine's base style (`cursor: pointer`, hardcoded
+  on the underlying `mantine-Chip-label` class) always leaked through, independent of whether the
+  chip was actually interactive. Reset it to `cursor: default` and added a `data-interactive`
+  attribute (driven by the fixed `isInteractive` above, set via `wrapperProps` on `MantineChip` so
+  it lands on `.root`) that re-enables `pointer` via `.root[data-interactive] .label.label` only
+  when there's a real handler.
+
+Separately, `.children`'s `overflow-x: hidden` (added for ellipsis truncation) made it a scroll
+container, and Chromium auto-adds scroll containers with actually-overflowing content to the Tab
+order — with no `tabindex` attribute at all — so a solo Tab press could land on a chip's plain
+filename text before ever reaching a real control. Switched to `overflow-x: clip`, which doesn't
+establish a scrollport (same visual clipping, still x-axis only per the descender fix above), so
+it's no longer a focus candidate. This affected every chip with long enough content, not just
+read-only ones — see `FileUpload`'s own `IMPLEMENTATION_NOTES.md` for how it surfaced there.
+
+### Selected check icon sat to the left of the leading icon instead of replacing it (Matt Massey, 2026-08-28)
+
+A checked `Chip` with a custom `icon` (leading icon) rendered both: Mantine's own default check
+icon (via its native `iconWrapper`/`checkIcon` slot, always shown whenever `checked` and its own
+`icon` prop — a different, unrelated slot — is left `undefined`) came first in the DOM, immediately
+followed by this adapter's own `.leadingIcon` span, which we always rendered regardless of checked
+state. mui-adapter's `Chip` never had this problem, since its `icon={checked ? checkIcon : icon}`
+was already a straight swap. Fixed adapter-mantine-v8 to match: the custom `.leadingIcon` span now
+only renders when `!checked`, so Mantine's native checkmark overlays/replaces it instead of sitting
+to its left. Required destructuring `checked` explicitly (previously left in `...rest` and passed
+through opaquely) so the render condition and the explicit `checked` prop on `<MantineChip>` stay
+in sync.

package/src/components/Chip/Chip.module.css

@@ -0,0 +1,288 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_disabled
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ */
+
+/* HARDCODED VALUES
+   border-style: solid;  (Baseline reset)
+   box-sizing: border-box; (Baseline reset)
+   display: inline-flex; (Baseline reset)
+   align-items: center; (Baseline reset)
+   outline: none; (Accessible fallback)
+   padding: 0; (Override mantine default)
+   background: transparent; (Override mantine default)
+ */
+
+/* EXEMPTIONS:
+   - The leading icon and the selected/check icon are mutually exclusive (Chip.tsx only renders
+     the leading icon when `!checked`; Mantine's own check icon takes over when checked) — so for
+     any given state, exactly one of `leading-icon-color`/`selected-icon-color` ever applies. The
+     other one, and the non-state-specific base `properties_leading-icon-color`/
+     `properties_close-icon-color` (superseded by the per-selection-state values actually used),
+     are never referenced by design, not missing. Same for the generic (non-leading/selected)
+     `colors_icon-color` on the error variants — the more specific leading/selected token already
+     covers it. */
+/* recursica-ignore: --recursica_ui-kit_components_chip_properties_close-icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_chip_properties_leading-icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_leading-icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_leading-icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_selected-icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_icon-color */
+/* recursica-ignore: --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_selected-icon-color */
+
+.root.root {
+  /* Set preset layout variables to override mantine defaults safely */
+  box-sizing: border-box;
+  display: inline-flex;
+
+  /* Token properties */
+  --chip-height: max-content; /* Sizing is driven by padding and line height */
+  --chip-bg: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_background-color
+  );
+  --chip-border: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_border-color
+  );
+  --chip-text: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_text-color
+  );
+  --chip-icon: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_leading-icon-color
+  );
+  --chip-close: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_properties_colors_close-icon-color
+  );
+
+  /* Override Mantine's internal variables */
+  --chip-size: max-content;
+  --chip-radius: var(
+    --recursica_ui-kit_components_chip_properties_border-radius
+  );
+
+  user-select: none;
+  overflow-x: hidden; /* HARDCODE: horizontal-only, same descender reasoning as .children below —
+    .root has no visible background of its own (that's .label), so there's nothing here that
+    needs vertical clipping */
+  overflow-y: visible;
+}
+
+/* We target the mantine label directly because that is the visible container in Mantine's Chip */
+.label.label {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+
+  /* Reset mantine styles */
+  background: transparent; /* HARDCODE: Mantine forces background styling on label */
+  cursor: default; /* HARDCODE: Mantine's own base styles hardcode cursor: pointer on this class —
+    override it to plain default, then only re-enable it below for a chip with a real handler
+    (onDelete/onClick/onChange — see Chip.tsx's `isInteractive`). A display-only chip (e.g. a
+    read-only FileUpload file list) has nothing for a click to do, so it shouldn't look clickable. */
+  border-style: solid;
+  border-width: var(--recursica_ui-kit_components_chip_properties_border-size);
+  padding: var(--recursica_ui-kit_components_chip_properties_vertical-padding)
+    var(--recursica_ui-kit_components_chip_properties_horizontal-padding);
+
+  /* Typography */
+  font-family: var(
+    --recursica_ui-kit_components_chip_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_chip_properties_text_font-size);
+  font-weight: var(
+    --recursica_ui-kit_components_chip_properties_text_font-weight
+  );
+  font-style: var(
+    --recursica_ui-kit_components_chip_properties_text_font-style
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_chip_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_chip_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_chip_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_chip_properties_text_text-transform
+  );
+
+  /* Token evaluation */
+  background-color: var(--chip-bg);
+  border-color: var(--chip-border);
+  color: var(--chip-text);
+  min-width: var(--recursica_ui-kit_components_chip_properties_min-width);
+  max-width: var(--recursica_ui-kit_components_chip_properties_max-width);
+  box-shadow: var(--recursica_ui-kit_components_chip_properties_elevation);
+
+  transition: all 0.2s ease;
+}
+
+.label.label > span:not(.mantineIconWrapper) {
+  display: inline-flex;
+  align-items: center;
+  flex: 1 1 auto; /* HARDCODE: let this anonymous wrapper actually fill/shrink to .label's real
+    width instead of sizing to its content — otherwise a long .children label overflows this
+    span well past .label's 200px max-width, and .children's own text-overflow: ellipsis never
+    engages because ITS box is still as wide as the unwrapped text (see CHIP_IMPLEMENTATION_NOTES.md) */
+  min-width: 0; /* HARDCODE: flex items default to min-width: auto (their content's min-content
+    size) — without this override, flex-shrink is a no-op and the span never shrinks below that */
+}
+
+.label.label:hover {
+  background-color: var(--chip-bg);
+}
+
+.root[data-interactive] .label.label {
+  cursor: pointer;
+}
+
+/* Default (Unselected) hover/active interactions (Mantine overrides) */
+.label.label[data-checked] {
+  --chip-bg: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_background-color
+  );
+  --chip-border: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_border-color
+  );
+  --chip-text: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_text-color
+  );
+  --chip-icon: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_selected-icon-color
+  );
+  --chip-close: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_properties_colors_close-icon-color
+  );
+}
+
+.root[data-error] .label.label {
+  --chip-bg: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_background-color
+  );
+  --chip-border: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_border-color
+  );
+  --chip-text: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_text-color
+  );
+  --chip-icon: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_leading-icon-color
+  );
+  --chip-close: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_unselected_variants_states_error_properties_colors_close-icon-color
+  );
+}
+
+.root[data-error] .label.label[data-checked] {
+  --chip-bg: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_background-color
+  );
+  --chip-border: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_border-color
+  );
+  --chip-text: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_text-color
+  );
+  --chip-icon: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_selected-icon-color
+  );
+  --chip-close: var(
+    --recursica_ui-kit_components_chip_variants_selection-states_selected_variants_states_error_properties_colors_close-icon-color
+  );
+}
+
+.root[data-disabled] .label.label {
+  opacity: var(--recursica_brand_states_disabled);
+  cursor: not-allowed;
+}
+
+/* Override Mantine's built-in check icon colors and size if we keep it */
+.mantineIconWrapper.mantineIconWrapper {
+  color: var(--chip-icon);
+  width: var(--recursica_ui-kit_components_chip_properties_icon-size);
+  height: var(--recursica_ui-kit_components_chip_properties_icon-size);
+  margin-right: var(
+    --recursica_ui-kit_components_chip_properties_icon-text-gap
+  );
+}
+
+.innerWrapper {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--recursica_ui-kit_components_chip_properties_icon-text-gap);
+  width: 100%;
+  min-width: 0; /* HARDCODE: lets .children actually shrink and ellipsize instead of overflowing */
+}
+
+.children {
+  flex-grow: 1;
+  min-width: 0; /* HARDCODE: a flex child needs this for text-overflow: ellipsis to engage at all */
+  text-overflow: ellipsis;
+  overflow-x: clip; /* HARDCODE: text-overflow: ellipsis only needs the x-axis clipped — clipping
+    y too (plain `overflow: hidden`) cut off descenders (e.g. the "g" in "image.png") whenever the
+    line-height token is tighter than the font's natural glyph extent (Matt Massey, 2026-08-18).
+    `clip` rather than `hidden` because `hidden` makes this a scroll container, and Chromium
+    auto-adds scroll containers with overflowing content to the Tab order (so a browser user can
+    arrow-key-scroll them) — `clip` doesn't create a scrollport, so long/truncated chip labels
+    (e.g. a read-only FileUpload file list) don't pick up a phantom, un-styled tab stop. */
+  overflow-y: visible;
+  white-space: nowrap;
+}
+
+.leadingIcon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0; /* HARDCODE: keep the icon from being squeezed by a long, truncating label */
+  color: var(--chip-icon);
+  width: var(--recursica_ui-kit_components_chip_properties_icon-size);
+  height: var(--recursica_ui-kit_components_chip_properties_icon-size);
+}
+
+.leadingIcon svg {
+  width: 100%;
+  height: 100%;
+}
+
+.deleteIcon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0; /* HARDCODE: keep the delete icon visible when the label truncates instead */
+  color: var(--chip-close);
+  width: var(--recursica_ui-kit_components_chip_properties_close-icon-size);
+  height: var(--recursica_ui-kit_components_chip_properties_close-icon-size);
+  cursor: pointer;
+  border-radius: 50%; /* HARDCODE: Make focus ring rounded */
+  outline: none;
+}
+
+.deleteIcon:focus-visible {
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
+.deleteIcon svg {
+  width: 100%;
+  height: 100%;
+}
+
+.root[data-icon-only] .label.label {
+  padding-left: var(
+    --recursica_ui-kit_components_chip_properties_vertical-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_chip_properties_vertical-padding
+  );
+}