From f99fc5d81169002552210cadee4256954eee5333 Mon Sep 17 00:00:00 2001
From: Jan Librowski <janlibrowski@gmail.com>
Date: Thu, 20 Aug 2026 22:04:14 +0200
Subject: [PATCH 1/8] feat(ui): add Chip component

Compact tag in the DS 2.0 solid and outline treatments, four sizes,
optional prefix icon and close affordance. Sized and colored per the
Chips and Tag component set in the DS 2.0 Figma file; the chip tokens
and wb/radius/50 live in _provisional.css until the token export ships
them. The outline background is two stacked fills by design: the brand
surface under a translucent theme overlay.
---
 .changeset/chips-component.md                 |  5 ++
 .../ui/src/components/chips/chips.module.css  | 65 +++++++++++++++++++
 packages/ui/src/components/chips/chips.tsx    | 51 +++++++++++++++
 packages/ui/src/components/chips/index.ts     |  1 +
 packages/ui/src/index.ts                      |  1 +
 packages/ui/src/styles/_provisional.css       | 15 +++++
 packages/ui/vite.config.mts                   |  1 +
 7 files changed, 139 insertions(+)
 create mode 100644 .changeset/chips-component.md
 create mode 100644 packages/ui/src/components/chips/chips.module.css
 create mode 100644 packages/ui/src/components/chips/chips.tsx
 create mode 100644 packages/ui/src/components/chips/index.ts

diff --git a/.changeset/chips-component.md b/.changeset/chips-component.md
new file mode 100644
index 000000000..c3f808c1d
--- /dev/null
+++ b/.changeset/chips-component.md
@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/ui': minor
+---
+
+Add the `Chip` component — a compact tag in the DS 2.0 solid and outline treatments, four sizes (`s`–`xl`), optional prefix icon and close affordance.
diff --git a/packages/ui/src/components/chips/chips.module.css b/packages/ui/src/components/chips/chips.module.css
new file mode 100644
index 000000000..e1bfed537
--- /dev/null
+++ b/packages/ui/src/components/chips/chips.module.css
@@ -0,0 +1,65 @@
+@layer ui.component {
+  .chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    border-radius: var(--wb-radius-50);
+    white-space: nowrap;
+  }
+
+  .solid {
+    background-color: var(--wb-components-chips-solid);
+    color: var(--wb-components-chips-solid-text);
+  }
+
+  .outline {
+    /* Two fills, as designed: the brand surface under the theme overlay. */
+    background-color: var(--wb-components-chips-inset-outline);
+    background-image: linear-gradient(
+      var(--wb-components-chips-overlay-outline),
+      var(--wb-components-chips-overlay-outline)
+    );
+    border: 0.0625rem solid var(--wb-components-chips-inset-outline);
+    color: var(--wb-components-chips-inset-outline);
+  }
+
+  .s {
+    height: 0.875rem;
+    padding-inline: 0.25rem;
+  }
+
+  .m {
+    height: 1rem;
+    padding-inline: 0.25rem;
+  }
+
+  .l {
+    height: 1.25rem;
+    padding-inline: 0.375rem;
+  }
+
+  .xl {
+    height: 1.375rem;
+    padding-inline: 0.375rem;
+  }
+
+  .icon,
+  .close {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .icon > svg,
+  .close svg {
+    width: 0.625rem;
+    height: 0.625rem;
+  }
+
+  .close {
+    padding: 0;
+    border: none;
+    background: none;
+    color: inherit;
+    cursor: pointer;
+  }
+}
diff --git a/packages/ui/src/components/chips/chips.tsx b/packages/ui/src/components/chips/chips.tsx
new file mode 100644
index 000000000..0d1ab59a5
--- /dev/null
+++ b/packages/ui/src/components/chips/chips.tsx
@@ -0,0 +1,51 @@
+import { X } from '@phosphor-icons/react';
+import clsx from 'clsx';
+import type { ReactNode } from 'react';
+
+import styles from './chips.module.css';
+
+export type ChipProps = {
+  /**
+   * The tag text.
+   */
+  label: string;
+  /**
+   * Solid renders on the neutral chip surface; outline renders the brand
+   * outline treatment.
+   * @default 'solid'
+   */
+  variant?: Variant;
+  /**
+   * @default 'm'
+   */
+  size?: Size;
+  /**
+   * Icon rendered before the label.
+   */
+  prefixIcon?: ReactNode;
+  /**
+   * When provided, a close affordance is rendered and invokes this callback.
+   */
+  onClose?: () => void;
+  className?: string;
+};
+
+type Variant = 'solid' | 'outline';
+type Size = 's' | 'm' | 'l' | 'xl';
+
+/**
+ * Compact tag for labeling and filtering, in the two DS 2.0 treatments.
+ */
+export function Chip({ label, variant = 'solid', size = 'm', prefixIcon, onClose, className }: ChipProps) {
+  return (
+    <span className={clsx(styles['chip'], styles[variant], styles[size], className)}>
+      {prefixIcon && <span className={styles['icon']}>{prefixIcon}</span>}
+      <span className="wb-text-label-s">{label}</span>
+      {onClose && (
+        <button type="button" className={styles['close']} aria-label={`Remove ${label}`} onClick={onClose}>
+          <X />
+        </button>
+      )}
+    </span>
+  );
+}
diff --git a/packages/ui/src/components/chips/index.ts b/packages/ui/src/components/chips/index.ts
new file mode 100644
index 000000000..ffd127cac
--- /dev/null
+++ b/packages/ui/src/components/chips/index.ts
@@ -0,0 +1 @@
+export * from './chips';
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index d50590eba..932463d2c 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -8,6 +8,7 @@ export * from './components/accordion';
 export * from './components/avatar';
 export * from './components/button';
 export * from './components/checkbox';
+export * from './components/chips';
 export * from './components/collapsible';
 export * from './components/date-picker';
 export * from './components/edge';
diff --git a/packages/ui/src/styles/_provisional.css b/packages/ui/src/styles/_provisional.css
index 2a5a192cb..003b65350 100644
--- a/packages/ui/src/styles/_provisional.css
+++ b/packages/ui/src/styles/_provisional.css
@@ -19,5 +19,20 @@
     --wb-font-size-300: 1.5rem;
     --wb-font-size-350: 1.75rem;
     --wb-font-size-400: 2rem;
+
+    --wb-radius-50: 0.25rem;
+    --wb-components-chips-inset-outline: var(--ax-colors-acc1-500);
+  }
+
+  html[data-theme='light'] {
+    --wb-components-chips-solid: var(--ax-colors-gray-300);
+    --wb-components-chips-solid-text: var(--ax-colors-gray-800);
+    --wb-components-chips-overlay-outline: color-mix(in srgb, var(--ax-colors-gray-100) 85%, transparent);
+  }
+
+  html[data-theme='dark'] {
+    --wb-components-chips-solid: var(--ax-colors-gray-650);
+    --wb-components-chips-solid-text: var(--ax-colors-gray-100);
+    --wb-components-chips-overlay-outline: var(--ax-colors-gray-900-75);
   }
 }
diff --git a/packages/ui/vite.config.mts b/packages/ui/vite.config.mts
index dfc38300b..daf4d3cd3 100644
--- a/packages/ui/vite.config.mts
+++ b/packages/ui/vite.config.mts
@@ -19,6 +19,7 @@ const componentEntries = [
   'avatar',
   'button',
   'checkbox',
+  'chips',
   'collapsible',
   'date-picker',
   'edge',

From 5838857396c06078cdfad9836aedf951c1c3076d Mon Sep 17 00:00:00 2001
From: Jan Librowski <janlibrowski@gmail.com>
Date: Thu, 20 Aug 2026 22:04:20 +0200
Subject: [PATCH 2/8] refactor(sdk): render the conditions counter tag with
 Chip

The local .tag treatment is replaced by the UI Chip component; the
class keeps only its layout margins and the tag background variable
goes away with it.
---
 .changeset/conditions-tag-chip.md                         | 5 +++++
 .../dynamic-conditions-control.module.css                 | 8 --------
 .../dynamic-conditions-control.tsx                        | 4 ++--
 3 files changed, 7 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/conditions-tag-chip.md

diff --git a/.changeset/conditions-tag-chip.md b/.changeset/conditions-tag-chip.md
new file mode 100644
index 000000000..5cca5b8f2
--- /dev/null
+++ b/.changeset/conditions-tag-chip.md
@@ -0,0 +1,5 @@
+---
+'@workflowbuilder/sdk': patch
+---
+
+The dynamic-conditions counter tag is rendered with the UI `Chip` component; it picks up the DS 2.0 neutral chip surface.
diff --git a/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.module.css b/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.module.css
index 40681cb9b..e17e2686b 100644
--- a/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.module.css
+++ b/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.module.css
@@ -2,8 +2,6 @@
   --wb-conditions-form-border-color: var(--ax-ui-stroke-primary-default); /* missing token */
   --wb-conditions-form-border-radius: 0.75rem; /* missing token */
   --wb-conditions-form-header-color: var(--ax-public-form-label-color);
-
-  --wb-conditions-form-tag-bg-color: var(--ax-chips-neutral-bg);
 }
 
 .container {
@@ -27,12 +25,6 @@
 }
 
 .tag {
-  composes: ax-public-p10 from global;
-
-  display: inline-block;
   margin-top: 0.25rem;
-  padding: 0.25rem 0.5rem;
-  border-radius: 0.25rem;
-  background-color: var(--wb-conditions-form-tag-bg-color);
   margin-right: auto;
 }
diff --git a/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.tsx b/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.tsx
index ef6327bab..99beb7c6f 100644
--- a/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.tsx
+++ b/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.tsx
@@ -1,4 +1,4 @@
-import { NavButton } from '@workflowbuilder/ui';
+import { Chip, NavButton } from '@workflowbuilder/ui';
 import clsx from 'clsx';
 import { useCallback, useRef } from 'react';
 import { useTranslation } from 'react-i18next';
@@ -49,7 +49,7 @@ function DynamicConditionsControl(props: DynamicConditionsControlProps) {
         </NavButton>
       </div>
       <Dependencies conditions={data} onClick={openEditorModal} disabled={isDisabled} />
-      <span className={styles['tag']}>{t('totalNumber', { count: data.length })}</span>
+      <Chip size="l" className={styles['tag']} label={t('totalNumber', { count: data.length })} />
     </div>
   );
 }

From 1e2947f8cc1fa739e66fc2f5efabf3091e05561c Mon Sep 17 00:00:00 2001
From: Jan Librowski <janlibrowski@gmail.com>
Date: Thu, 20 Aug 2026 22:04:28 +0200
Subject: [PATCH 3/8] docs: add the Chip component page

Example, usage snippet, and generated props table. The component
defines no ax-public-* variables (deprecated contract), so the CSS
variables section renders the standard empty state.
---
 apps/docs/scripts/ui-components.mjs           |  1 +
 .../docs/src/components/ui-examples/chips.tsx | 15 +++++++++
 .../docs/ui-library/ui-components/chips.mdx   | 33 +++++++++++++++++++
 3 files changed, 49 insertions(+)
 create mode 100644 apps/docs/src/components/ui-examples/chips.tsx
 create mode 100644 apps/docs/src/content/docs/ui-library/ui-components/chips.mdx

diff --git a/apps/docs/scripts/ui-components.mjs b/apps/docs/scripts/ui-components.mjs
index 03f4d47a1..2ca13c574 100644
--- a/apps/docs/scripts/ui-components.mjs
+++ b/apps/docs/scripts/ui-components.mjs
@@ -20,6 +20,7 @@ export const COMPONENTS = [
     dir: 'button',
   },
   { slug: 'checkbox', name: 'Checkbox', propsType: 'CheckboxProps', dir: 'checkbox' },
+  { slug: 'chips', name: 'Chip', propsType: 'ChipProps', dir: 'chips' },
   { slug: 'collapsible', name: 'Collapsible', propsType: 'CollapsibleProps', dir: 'collapsible' },
   { slug: 'date-picker', name: 'DatePicker', propsType: 'DatePickerProps', dir: 'date-picker' },
   { slug: 'icon-switch', name: 'IconSwitch', propsType: 'IconSwitchProps', dir: 'switch/icon-switch' },
diff --git a/apps/docs/src/components/ui-examples/chips.tsx b/apps/docs/src/components/ui-examples/chips.tsx
new file mode 100644
index 000000000..ed6151ef2
--- /dev/null
+++ b/apps/docs/src/components/ui-examples/chips.tsx
@@ -0,0 +1,15 @@
+import { Tag } from '@phosphor-icons/react';
+import { Chip } from '@workflowbuilder/ui';
+
+import { ComponentPreview } from './component-preview';
+
+export function ChipsExample() {
+  return (
+    <ComponentPreview>
+      <Chip label="tag label" />
+      <Chip label="tag label" variant="outline" />
+      <Chip label="with icon" size="l" prefixIcon={<Tag />} />
+      <Chip label="removable" size="l" variant="outline" onClose={() => {}} />
+    </ComponentPreview>
+  );
+}
diff --git a/apps/docs/src/content/docs/ui-library/ui-components/chips.mdx b/apps/docs/src/content/docs/ui-library/ui-components/chips.mdx
new file mode 100644
index 000000000..e4493f346
--- /dev/null
+++ b/apps/docs/src/content/docs/ui-library/ui-components/chips.mdx
@@ -0,0 +1,33 @@
+---
+title: Chip
+description: Compact tag for labeling and filtering, in solid and outline treatments.
+---
+
+import CssVariablesTable from '../../../../components/api/css-variables-table.astro';
+import PropsTable from '../../../../components/api/props-table.astro';
+import { ChipsExample } from '../../../../components/ui-examples/chips';
+
+A `Chip` is a compact tag in one of two Design System 2.0 treatments: `solid`
+on the neutral chip surface, or `outline` with the brand border and accent.
+Four sizes (`s`, `m`, `l`, `xl`), an optional prefix icon, and an optional
+close affordance.
+
+<ChipsExample client:visible />
+
+## Usage
+
+```tsx
+import { Chip } from '@workflowbuilder/ui';
+
+function Example() {
+  return <Chip label="tag label" variant="outline" size="l" onClose={() => remove()} />;
+}
+```
+
+## Props
+
+<PropsTable slug="chips" />
+
+## CSS variables
+
+<CssVariablesTable slug="chips" />

From 21f8a79fb43b15bd52b1d0f347a9272b6a0e1a0a Mon Sep 17 00:00:00 2001
From: Jan Librowski <janlibrowski@gmail.com>
Date: Thu, 20 Aug 2026 22:34:33 +0200
Subject: [PATCH 4/8] fix(ui): apply Chip review findings

The dark outline overlay aliased gray-900-75, whose exported value is
the documented pre-2.0 bug (50% alpha instead of 75) - mixed from
gray-900 directly, like the light theme already does. The close button
gets the standard focus-visible ring. Variant and Size are renamed to
ChipVariant/ChipSize and exported - the bare names shadowed two
existing public types and rendered misleadingly in the generated props
table. Chip now forwards its ref and native span attributes, and the
close affordance takes an overridable closeLabel. The outline stroke
is an inset ring instead of a border so outline and solid chips render
the same width. Spacing metrics bind the space/size primitives from
the provisional set.
---
 .changeset/conditions-tag-chip.md             |  2 +-
 .../docs/src/components/ui-examples/chips.tsx | 10 ++--
 .../dynamic-conditions-control.module.css     |  1 -
 .../ui/src/components/chips/chips.module.css  | 21 +++++---
 packages/ui/src/components/chips/chips.tsx    | 51 +++++++++++--------
 packages/ui/src/styles/_provisional.css       |  5 +-
 6 files changed, 56 insertions(+), 34 deletions(-)

diff --git a/.changeset/conditions-tag-chip.md b/.changeset/conditions-tag-chip.md
index 5cca5b8f2..6b9f17cde 100644
--- a/.changeset/conditions-tag-chip.md
+++ b/.changeset/conditions-tag-chip.md
@@ -2,4 +2,4 @@
 '@workflowbuilder/sdk': patch
 ---
 
-The dynamic-conditions counter tag is rendered with the UI `Chip` component; it picks up the DS 2.0 neutral chip surface.
+The dynamic-conditions counter tag is rendered with the UI `Chip` component. Same neutral surface colors; the tag gets the DS 2.0 chip metrics — 10px label (was 12px) in a 20px-tall pill with slightly tighter padding.
diff --git a/apps/docs/src/components/ui-examples/chips.tsx b/apps/docs/src/components/ui-examples/chips.tsx
index ed6151ef2..31054357e 100644
--- a/apps/docs/src/components/ui-examples/chips.tsx
+++ b/apps/docs/src/components/ui-examples/chips.tsx
@@ -6,10 +6,12 @@ import { ComponentPreview } from './component-preview';
 export function ChipsExample() {
   return (
     <ComponentPreview>
-      <Chip label="tag label" />
-      <Chip label="tag label" variant="outline" />
-      <Chip label="with icon" size="l" prefixIcon={<Tag />} />
-      <Chip label="removable" size="l" variant="outline" onClose={() => {}} />
+      <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+        <Chip label="tag label" />
+        <Chip label="tag label" variant="outline" />
+        <Chip label="with icon" size="l" prefixIcon={<Tag />} />
+        <Chip label="removable" size="l" variant="outline" onClose={() => {}} />
+      </div>
     </ComponentPreview>
   );
 }
diff --git a/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.module.css b/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.module.css
index e17e2686b..6c0231e74 100644
--- a/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.module.css
+++ b/packages/sdk/src/features/json-form/controls/dynamic-conditions-control/dynamic-conditions-control.module.css
@@ -26,5 +26,4 @@
 
 .tag {
   margin-top: 0.25rem;
-  margin-right: auto;
 }
diff --git a/packages/ui/src/components/chips/chips.module.css b/packages/ui/src/components/chips/chips.module.css
index e1bfed537..e014b589c 100644
--- a/packages/ui/src/components/chips/chips.module.css
+++ b/packages/ui/src/components/chips/chips.module.css
@@ -2,7 +2,7 @@
   .chip {
     display: inline-flex;
     align-items: center;
-    gap: 0.25rem;
+    gap: var(--wb-space-50);
     border-radius: var(--wb-radius-50);
     white-space: nowrap;
   }
@@ -19,28 +19,30 @@
       var(--wb-components-chips-overlay-outline),
       var(--wb-components-chips-overlay-outline)
     );
-    border: 0.0625rem solid var(--wb-components-chips-inset-outline);
+    /* An inset ring, not a border: Figma's inside stroke overlaps the padding,
+       a CSS border would add to it and widen the chip. */
+    box-shadow: inset 0 0 0 var(--wb-size-12) var(--wb-components-chips-inset-outline);
     color: var(--wb-components-chips-inset-outline);
   }
 
   .s {
     height: 0.875rem;
-    padding-inline: 0.25rem;
+    padding-inline: var(--wb-space-50);
   }
 
   .m {
     height: 1rem;
-    padding-inline: 0.25rem;
+    padding-inline: var(--wb-space-50);
   }
 
   .l {
     height: 1.25rem;
-    padding-inline: 0.375rem;
+    padding-inline: var(--wb-space-75);
   }
 
   .xl {
     height: 1.375rem;
-    padding-inline: 0.375rem;
+    padding-inline: var(--wb-space-75);
   }
 
   .icon,
@@ -49,7 +51,7 @@
     align-items: center;
   }
 
-  .icon > svg,
+  .icon svg,
   .close svg {
     width: 0.625rem;
     height: 0.625rem;
@@ -61,5 +63,10 @@
     background: none;
     color: inherit;
     cursor: pointer;
+
+    &:focus-visible {
+      box-shadow: 0 0 0 2px var(--ax-focus-ring-element);
+      outline: none;
+    }
   }
 }
diff --git a/packages/ui/src/components/chips/chips.tsx b/packages/ui/src/components/chips/chips.tsx
index 0d1ab59a5..f43f9c3cf 100644
--- a/packages/ui/src/components/chips/chips.tsx
+++ b/packages/ui/src/components/chips/chips.tsx
@@ -1,6 +1,6 @@
 import { X } from '@phosphor-icons/react';
 import clsx from 'clsx';
-import type { ReactNode } from 'react';
+import { HTMLAttributes, ReactNode, forwardRef } from 'react';
 
 import styles from './chips.module.css';
 
@@ -14,11 +14,11 @@ export type ChipProps = {
    * outline treatment.
    * @default 'solid'
    */
-  variant?: Variant;
+  variant?: ChipVariant;
   /**
    * @default 'm'
    */
-  size?: Size;
+  size?: ChipSize;
   /**
    * Icon rendered before the label.
    */
@@ -27,25 +27,36 @@ export type ChipProps = {
    * When provided, a close affordance is rendered and invokes this callback.
    */
   onClose?: () => void;
-  className?: string;
-};
+  /**
+   * Accessible name of the close affordance.
+   * @default `Remove ${label}`
+   */
+  closeLabel?: string;
+} & HTMLAttributes<HTMLSpanElement>;
 
-type Variant = 'solid' | 'outline';
-type Size = 's' | 'm' | 'l' | 'xl';
+export type ChipVariant = 'solid' | 'outline';
+export type ChipSize = 's' | 'm' | 'l' | 'xl';
 
 /**
  * Compact tag for labeling and filtering, in the two DS 2.0 treatments.
  */
-export function Chip({ label, variant = 'solid', size = 'm', prefixIcon, onClose, className }: ChipProps) {
-  return (
-    <span className={clsx(styles['chip'], styles[variant], styles[size], className)}>
-      {prefixIcon && <span className={styles['icon']}>{prefixIcon}</span>}
-      <span className="wb-text-label-s">{label}</span>
-      {onClose && (
-        <button type="button" className={styles['close']} aria-label={`Remove ${label}`} onClick={onClose}>
-          <X />
-        </button>
-      )}
-    </span>
-  );
-}
+export const Chip = forwardRef<HTMLSpanElement, ChipProps>(
+  ({ label, variant = 'solid', size = 'm', prefixIcon, onClose, closeLabel, className, ...rest }, ref) => {
+    return (
+      <span ref={ref} {...rest} className={clsx(styles['chip'], styles[variant], styles[size], className)}>
+        {prefixIcon && <span className={styles['icon']}>{prefixIcon}</span>}
+        <span className="wb-text-label-s">{label}</span>
+        {onClose && (
+          <button
+            type="button"
+            className={styles['close']}
+            aria-label={closeLabel ?? `Remove ${label}`}
+            onClick={onClose}
+          >
+            <X />
+          </button>
+        )}
+      </span>
+    );
+  },
+);
diff --git a/packages/ui/src/styles/_provisional.css b/packages/ui/src/styles/_provisional.css
index 003b65350..27849bc7b 100644
--- a/packages/ui/src/styles/_provisional.css
+++ b/packages/ui/src/styles/_provisional.css
@@ -21,6 +21,9 @@
     --wb-font-size-400: 2rem;
 
     --wb-radius-50: 0.25rem;
+    --wb-space-50: 0.25rem;
+    --wb-space-75: 0.375rem;
+    --wb-size-12: 0.0625rem;
     --wb-components-chips-inset-outline: var(--ax-colors-acc1-500);
   }
 
@@ -33,6 +36,6 @@
   html[data-theme='dark'] {
     --wb-components-chips-solid: var(--ax-colors-gray-650);
     --wb-components-chips-solid-text: var(--ax-colors-gray-100);
-    --wb-components-chips-overlay-outline: var(--ax-colors-gray-900-75);
+    --wb-components-chips-overlay-outline: color-mix(in srgb, var(--ax-colors-gray-900) 75%, transparent);
   }
 }

From b3b2e262790fcfef9b641ff814f1dd6637613176 Mon Sep 17 00:00:00 2001
From: Jan Librowski <janlibrowski@gmail.com>
Date: Fri, 21 Aug 2026 01:31:14 +0200
Subject: [PATCH 5/8] docs(ui): sharpen Chip prop contracts

The label doc records why it is a string (it feeds the close
affordance's accessible name) and size gets a description - its TSDoc
was only a default tag, which the generated props table does not
surface, leaving an empty cell.
---
 packages/ui/src/components/chips/chips.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/components/chips/chips.tsx b/packages/ui/src/components/chips/chips.tsx
index f43f9c3cf..d7de9bc5a 100644
--- a/packages/ui/src/components/chips/chips.tsx
+++ b/packages/ui/src/components/chips/chips.tsx
@@ -6,7 +6,8 @@ import styles from './chips.module.css';
 
 export type ChipProps = {
   /**
-   * The tag text.
+   * The tag text. Interpolated into the close affordance's accessible name,
+   * so it stays a string.
    */
   label: string;
   /**
@@ -16,6 +17,7 @@ export type ChipProps = {
    */
   variant?: ChipVariant;
   /**
+   * Height and horizontal padding step.
    * @default 'm'
    */
   size?: ChipSize;

From cf339fe7b7ecc244c50a94665b1a80d45315ba68 Mon Sep 17 00:00:00 2001
From: Jan Librowski <janlibrowski@gmail.com>
Date: Fri, 21 Aug 2026 01:40:51 +0200
Subject: [PATCH 6/8] fix(ui): chip outline ring sits outside the box

The Figma component strokes with strokeAlign OUTSIDE; the inset ring
came from an unverified review claim of an inside stroke and ate one
pixel of the chip's padding.
---
 packages/ui/src/components/chips/chips.module.css | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/ui/src/components/chips/chips.module.css b/packages/ui/src/components/chips/chips.module.css
index e014b589c..c76a4d15b 100644
--- a/packages/ui/src/components/chips/chips.module.css
+++ b/packages/ui/src/components/chips/chips.module.css
@@ -19,9 +19,9 @@
       var(--wb-components-chips-overlay-outline),
       var(--wb-components-chips-overlay-outline)
     );
-    /* An inset ring, not a border: Figma's inside stroke overlaps the padding,
-       a CSS border would add to it and widen the chip. */
-    box-shadow: inset 0 0 0 var(--wb-size-12) var(--wb-components-chips-inset-outline);
+    /* A ring, not a border: the stroke sits outside the box (Figma
+       strokeAlign OUTSIDE), while a border would consume the padding. */
+    box-shadow: 0 0 0 var(--wb-size-12) var(--wb-components-chips-inset-outline);
     color: var(--wb-components-chips-inset-outline);
   }
 

From 5b609f768a720d30364dbce14c80f56cc36d3280 Mon Sep 17 00:00:00 2001
From: Jan Librowski <janlibrowski@gmail.com>
Date: Fri, 21 Aug 2026 02:38:18 +0200
Subject: [PATCH 7/8] docs(ui): cut chip comments down to the exceptions

Version labels in prose age badly; prop docs carry only defaults and
the close-affordance contract, and the two CSS notes state their
invariant without narrating the source.
---
 .../docs/ui-library/ui-components/chips.mdx       |  8 ++++----
 packages/ui/src/components/chips/chips.module.css |  5 ++---
 packages/ui/src/components/chips/chips.tsx        | 15 +--------------
 3 files changed, 7 insertions(+), 21 deletions(-)

diff --git a/apps/docs/src/content/docs/ui-library/ui-components/chips.mdx b/apps/docs/src/content/docs/ui-library/ui-components/chips.mdx
index e4493f346..36af95b93 100644
--- a/apps/docs/src/content/docs/ui-library/ui-components/chips.mdx
+++ b/apps/docs/src/content/docs/ui-library/ui-components/chips.mdx
@@ -7,10 +7,10 @@ import CssVariablesTable from '../../../../components/api/css-variables-table.as
 import PropsTable from '../../../../components/api/props-table.astro';
 import { ChipsExample } from '../../../../components/ui-examples/chips';
 
-A `Chip` is a compact tag in one of two Design System 2.0 treatments: `solid`
-on the neutral chip surface, or `outline` with the brand border and accent.
-Four sizes (`s`, `m`, `l`, `xl`), an optional prefix icon, and an optional
-close affordance.
+A `Chip` is a compact tag in one of two treatments: `solid` on the neutral
+chip surface, or `outline` with the brand border and accent. Four sizes
+(`s`, `m`, `l`, `xl`), an optional prefix icon, and an optional close
+affordance.
 
 <ChipsExample client:visible />
 
diff --git a/packages/ui/src/components/chips/chips.module.css b/packages/ui/src/components/chips/chips.module.css
index c76a4d15b..32b69bd5c 100644
--- a/packages/ui/src/components/chips/chips.module.css
+++ b/packages/ui/src/components/chips/chips.module.css
@@ -13,14 +13,13 @@
   }
 
   .outline {
-    /* Two fills, as designed: the brand surface under the theme overlay. */
+    /* Two stacked fills: the brand surface under the theme overlay. */
     background-color: var(--wb-components-chips-inset-outline);
     background-image: linear-gradient(
       var(--wb-components-chips-overlay-outline),
       var(--wb-components-chips-overlay-outline)
     );
-    /* A ring, not a border: the stroke sits outside the box (Figma
-       strokeAlign OUTSIDE), while a border would consume the padding. */
+    /* The stroke sits outside the box; a border would consume the padding. */
     box-shadow: 0 0 0 var(--wb-size-12) var(--wb-components-chips-inset-outline);
     color: var(--wb-components-chips-inset-outline);
   }
diff --git a/packages/ui/src/components/chips/chips.tsx b/packages/ui/src/components/chips/chips.tsx
index d7de9bc5a..001f121b8 100644
--- a/packages/ui/src/components/chips/chips.tsx
+++ b/packages/ui/src/components/chips/chips.tsx
@@ -5,28 +5,18 @@ import { HTMLAttributes, ReactNode, forwardRef } from 'react';
 import styles from './chips.module.css';
 
 export type ChipProps = {
-  /**
-   * The tag text. Interpolated into the close affordance's accessible name,
-   * so it stays a string.
-   */
   label: string;
   /**
-   * Solid renders on the neutral chip surface; outline renders the brand
-   * outline treatment.
    * @default 'solid'
    */
   variant?: ChipVariant;
   /**
-   * Height and horizontal padding step.
    * @default 'm'
    */
   size?: ChipSize;
-  /**
-   * Icon rendered before the label.
-   */
   prefixIcon?: ReactNode;
   /**
-   * When provided, a close affordance is rendered and invokes this callback.
+   * When set, a close affordance is rendered and invokes this callback.
    */
   onClose?: () => void;
   /**
@@ -39,9 +29,6 @@ export type ChipProps = {
 export type ChipVariant = 'solid' | 'outline';
 export type ChipSize = 's' | 'm' | 'l' | 'xl';
 
-/**
- * Compact tag for labeling and filtering, in the two DS 2.0 treatments.
- */
 export const Chip = forwardRef<HTMLSpanElement, ChipProps>(
   ({ label, variant = 'solid', size = 'm', prefixIcon, onClose, closeLabel, className, ...rest }, ref) => {
     return (

From 172db687b83f7d27fc00d9f66a1f603ed020b0cb Mon Sep 17 00:00:00 2001
From: Jan Librowski <janlibrowski@gmail.com>
Date: Fri, 21 Aug 2026 02:44:08 +0200
Subject: [PATCH 8/8] docs(ui): drop the outline chip comments

The token names carry the layering (inset under overlay) and the
outer box-shadow ring is a standard idiom.
---
 packages/ui/src/components/chips/chips.module.css | 2 --
 1 file changed, 2 deletions(-)

diff --git a/packages/ui/src/components/chips/chips.module.css b/packages/ui/src/components/chips/chips.module.css
index 32b69bd5c..62c4b6834 100644
--- a/packages/ui/src/components/chips/chips.module.css
+++ b/packages/ui/src/components/chips/chips.module.css
@@ -13,13 +13,11 @@
   }
 
   .outline {
-    /* Two stacked fills: the brand surface under the theme overlay. */
     background-color: var(--wb-components-chips-inset-outline);
     background-image: linear-gradient(
       var(--wb-components-chips-overlay-outline),
       var(--wb-components-chips-overlay-outline)
     );
-    /* The stroke sits outside the box; a border would consume the padding. */
     box-shadow: 0 0 0 var(--wb-size-12) var(--wb-components-chips-inset-outline);
     color: var(--wb-components-chips-inset-outline);
   }