# Chip

A compact pill in one of four shapes: selectable, command, removable, or readonly. Never more than one.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/controls/Chip/Chip.tsx

## Guidance

{
  "summary": "A compact pill in one of four shapes: selectable, command, removable, or readonly. Never more than one.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A compact pill in one of four shapes. A selectable chip takes `onPress` with `selected`. A command\nchip takes `onPress` alone. A removable chip takes `onRemove`. A readonly chip takes neither, for a\nlocked member of a chip set. Reach for `Tag` when the pill is a standalone marker or status label,\nand `Dropdown` for a trigger that opens a menu."
    },
    {
      "heading": "The shapes are different elements",
      "body": "This is the reason Chip and Tag are separate components, and the reason press and remove cannot be\ncombined:\n\n| Shape        | Element                                     | Focus stops |\n| ------------ | ------------------------------------------- | ----------- |\n| selectable   | `<button aria-pressed>`                     | 1           |\n| command      | `<button>`                                  | 1           |\n| removable    | `<span>` with a nested remove `<button>`    | 1           |\n| readonly     | `<span>` with no focus stop                 | 0           |\n| press+remove | would need a `<button>` inside a `<button>` | 2           |\n\n`ChipProps` is a discriminated union, so the last row cannot be written. Passing `onPress` and\n`onRemove` together is a type error rather than a runtime surprise.\n\n`selected` is what separates the first two rows. A chip that reports `aria-pressed=\"false\"` forever\ntells assistive technology it is an unselected member of a selection set — wrong for a chip that\njust opens an explainer. Omit `selected` and the attribute goes away with it."
    },
    {
      "heading": "Use when",
      "body": "`size` is `sm` for inline value tokens and `md` for filter rows. `disabled` sets the native disabled\nattribute and dims the chip. `removeLabel` is required on a removable chip: the × carries no visible\ntext, so a generic default would ship a row of buttons all announcing the same thing."
    },
    {
      "heading": "Put a set in a ChipGroup",
      "body": "A bare row of chips reads to assistive technology as loose controls with no relationship. `ChipGroup`\ngives the set an accessible name and owns the row layout, including the wrap and scroll behavior."
    }
  ],
  "usage": [
    {
      "variant": "onPress + selected",
      "use": "A filter toggle where `selected` marks the active option — website filters, feedback options.",
      "avoid": "Combining with onRemove. A trigger that opens a menu is a Dropdown, not a Chip.",
      "axis": "Job"
    },
    {
      "variant": "onPress alone",
      "use": "A one-off command — a risk chip that opens an explainer. `ariaLabel` names it when the visible label is not a complete phrase.",
      "avoid": "A member of a selection set. Pass `selected` there so the toggle state is announced.",
      "axis": "Job"
    },
    {
      "variant": "onRemove",
      "use": "A removable value token — entered emails, phones, and addresses in the data-removal profile, where the × selector suffixes the chip testId with `-remove`.",
      "avoid": "A filter — a removable chip is an entered value, not a toggle.",
      "axis": "Job"
    },
    {
      "variant": "no handler",
      "use": "A readonly, locked member of a chip set — the protected primary name sitting inline with removable name chips.",
      "avoid": "A standalone marker or status label. Use a Tag there.",
      "axis": "Job"
    }
  ],
  "examples": [
    {
      "kind": "do",
      "caption": "Give a chip `onPress`, or give it `onRemove`, or leave both off for a readonly member."
    },
    {
      "kind": "do",
      "caption": "Pass `selected` only when the chip really is a toggle."
    },
    {
      "kind": "do",
      "caption": "Use a readonly chip for a locked value inside a chip set, like the primary name in a value list."
    },
    {
      "kind": "dont",
      "caption": "Reach for a readonly Chip as a standalone marker or status label. That is a `Tag`."
    }
  ],
  "source": "packages/design-system/src/components/controls/Chip/Chip.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "onPress",
      "type": "(() => void) | (() => void) | undefined",
      "declared_type": "() => void",
      "required": false,
      "description": "Fires on tap. Its presence is what makes the root a button.\nUnavailable here: the remove button owns the only focus stop.\nUnavailable here: a readonly chip has no press. Add `onPress` to make it interactive.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 38
      }
    },
    {
      "name": "selected",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Selected state, exposed as `aria-pressed`.\nUnavailable here: a command has no selected state. Pass `selected` to get a toggle.\nUnavailable here: a removable value has no selected state.\nUnavailable here: a readonly chip has no selected state.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 40
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "onRemove",
      "type": "never",
      "declared_type": "never",
      "required": false,
      "description": "Unavailable here: a selectable chip cannot also be removable.\nUnavailable here: a command chip cannot also be removable.\nFires from the remove button only, never from the chip body.\nUnavailable here: a readonly chip cannot be removed. Add `onRemove` to make it removable.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 42
      },
      "forbidden": true
    },
    {
      "name": "removeLabel",
      "type": "never",
      "declared_type": "never",
      "required": false,
      "description": "Unavailable here: there is no remove affordance to name.\nAccessible name for the remove button. Name the value, as in `Remove sriram@example.com`.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 44
      },
      "forbidden": true
    },
    {
      "name": "ariaLabel",
      "type": "never",
      "declared_type": "never",
      "required": false,
      "description": "Unavailable here: the visible label names a toggle whose state `aria-pressed` carries.\nReplaces the visible label as the accessible name when the label alone lacks context.\nUnavailable here: the remove button carries the accessible name, via `removeLabel`.\nUnavailable here: the visible label is the whole accessible name.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 46
      },
      "forbidden": true
    },
    {
      "name": "busy",
      "type": "never",
      "declared_type": "never",
      "required": false,
      "description": "Unavailable here: only a removable chip has an in-flight removal to report.\nShows a spinner in place of the remove icon and blocks the button while its removal is in flight.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 48
      },
      "forbidden": true
    },
    {
      "name": "children",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": true,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 17
      }
    },
    {
      "name": "size",
      "type": "ChipSize",
      "declared_type": "ChipSize",
      "required": true,
      "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 19
      },
      "values": [
        "md",
        "sm"
      ],
      "values_complete": true
    },
    {
      "name": "disabled",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Blocks press and remove alike, and dims the chip.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 21
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "leading",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": false,
      "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 23
      }
    },
    {
      "name": "haptic",
      "type": "HapticFeedback | undefined",
      "declared_type": "HapticFeedback",
      "required": false,
      "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 25
      },
      "values": [
        "error",
        "heavy",
        "light",
        "medium",
        "selection",
        "success",
        "warning",
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 26
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 27
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
      "source": {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 29
      }
    }
  ],
  "prop_shapes": {
    "SelectableChipProps": [
      {
        "name": "onPress",
        "type": "() => void",
        "declared_type": "() => void",
        "required": true,
        "description": "Fires on tap. Its presence is what makes the root a button.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 38
        }
      },
      {
        "name": "selected",
        "type": "boolean",
        "declared_type": "boolean",
        "required": true,
        "description": "Selected state, exposed as `aria-pressed`.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 40
        },
        "values": [
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "onRemove",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: a selectable chip cannot also be removable.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 42
        },
        "forbidden": true
      },
      {
        "name": "removeLabel",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: there is no remove affordance to name.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 44
        },
        "forbidden": true
      },
      {
        "name": "ariaLabel",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: the visible label names a toggle whose state `aria-pressed` carries.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 46
        },
        "forbidden": true
      },
      {
        "name": "busy",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: only a removable chip has an in-flight removal to report.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 48
        },
        "forbidden": true
      },
      {
        "name": "children",
        "type": "React.ReactNode",
        "declared_type": "React.ReactNode",
        "required": true,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 17
        }
      },
      {
        "name": "size",
        "type": "ChipSize",
        "declared_type": "ChipSize",
        "required": true,
        "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 19
        },
        "values": [
          "md",
          "sm"
        ],
        "values_complete": true
      },
      {
        "name": "disabled",
        "type": "boolean | undefined",
        "declared_type": "boolean",
        "required": false,
        "description": "Blocks press and remove alike, and dims the chip.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 21
        },
        "values": [
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "leading",
        "type": "React.ReactNode",
        "declared_type": "React.ReactNode",
        "required": false,
        "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 23
        }
      },
      {
        "name": "haptic",
        "type": "HapticFeedback | undefined",
        "declared_type": "HapticFeedback",
        "required": false,
        "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 25
        },
        "values": [
          "error",
          "heavy",
          "light",
          "medium",
          "selection",
          "success",
          "warning",
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "className",
        "type": "string | undefined",
        "declared_type": "string",
        "required": false,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 26
        }
      },
      {
        "name": "style",
        "type": "React.CSSProperties | undefined",
        "declared_type": "React.CSSProperties",
        "required": false,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 27
        }
      },
      {
        "name": "testId",
        "type": "string | undefined",
        "declared_type": "string",
        "required": false,
        "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 29
        }
      }
    ],
    "CommandChipProps": [
      {
        "name": "onPress",
        "type": "() => void",
        "declared_type": "() => void",
        "required": true,
        "description": "Fires on tap. Its presence is what makes the root a button.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 57
        }
      },
      {
        "name": "ariaLabel",
        "type": "string | undefined",
        "declared_type": "string",
        "required": false,
        "description": "Replaces the visible label as the accessible name when the label alone lacks context.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 59
        }
      },
      {
        "name": "selected",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: a command has no selected state. Pass `selected` to get a toggle.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 61
        },
        "forbidden": true
      },
      {
        "name": "onRemove",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: a command chip cannot also be removable.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 63
        },
        "forbidden": true
      },
      {
        "name": "removeLabel",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: there is no remove affordance to name.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 65
        },
        "forbidden": true
      },
      {
        "name": "busy",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: only a removable chip has an in-flight removal to report.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 67
        },
        "forbidden": true
      },
      {
        "name": "children",
        "type": "React.ReactNode",
        "declared_type": "React.ReactNode",
        "required": true,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 17
        }
      },
      {
        "name": "size",
        "type": "ChipSize",
        "declared_type": "ChipSize",
        "required": true,
        "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 19
        },
        "values": [
          "md",
          "sm"
        ],
        "values_complete": true
      },
      {
        "name": "disabled",
        "type": "boolean | undefined",
        "declared_type": "boolean",
        "required": false,
        "description": "Blocks press and remove alike, and dims the chip.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 21
        },
        "values": [
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "leading",
        "type": "React.ReactNode",
        "declared_type": "React.ReactNode",
        "required": false,
        "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 23
        }
      },
      {
        "name": "haptic",
        "type": "HapticFeedback | undefined",
        "declared_type": "HapticFeedback",
        "required": false,
        "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 25
        },
        "values": [
          "error",
          "heavy",
          "light",
          "medium",
          "selection",
          "success",
          "warning",
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "className",
        "type": "string | undefined",
        "declared_type": "string",
        "required": false,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 26
        }
      },
      {
        "name": "style",
        "type": "React.CSSProperties | undefined",
        "declared_type": "React.CSSProperties",
        "required": false,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 27
        }
      },
      {
        "name": "testId",
        "type": "string | undefined",
        "declared_type": "string",
        "required": false,
        "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 29
        }
      }
    ],
    "RemovableChipProps": [
      {
        "name": "onRemove",
        "type": "() => void",
        "declared_type": "() => void",
        "required": true,
        "description": "Fires from the remove button only, never from the chip body.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 76
        }
      },
      {
        "name": "removeLabel",
        "type": "string",
        "declared_type": "string",
        "required": true,
        "description": "Accessible name for the remove button. Name the value, as in `Remove sriram@example.com`.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 78
        }
      },
      {
        "name": "busy",
        "type": "boolean | undefined",
        "declared_type": "boolean",
        "required": false,
        "description": "Shows a spinner in place of the remove icon and blocks the button while its removal is in flight.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 80
        },
        "values": [
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "onPress",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: the remove button owns the only focus stop.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 82
        },
        "forbidden": true
      },
      {
        "name": "selected",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: a removable value has no selected state.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 84
        },
        "forbidden": true
      },
      {
        "name": "ariaLabel",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: the remove button carries the accessible name, via `removeLabel`.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 86
        },
        "forbidden": true
      },
      {
        "name": "children",
        "type": "React.ReactNode",
        "declared_type": "React.ReactNode",
        "required": true,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 17
        }
      },
      {
        "name": "size",
        "type": "ChipSize",
        "declared_type": "ChipSize",
        "required": true,
        "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 19
        },
        "values": [
          "md",
          "sm"
        ],
        "values_complete": true
      },
      {
        "name": "disabled",
        "type": "boolean | undefined",
        "declared_type": "boolean",
        "required": false,
        "description": "Blocks press and remove alike, and dims the chip.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 21
        },
        "values": [
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "leading",
        "type": "React.ReactNode",
        "declared_type": "React.ReactNode",
        "required": false,
        "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 23
        }
      },
      {
        "name": "haptic",
        "type": "HapticFeedback | undefined",
        "declared_type": "HapticFeedback",
        "required": false,
        "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 25
        },
        "values": [
          "error",
          "heavy",
          "light",
          "medium",
          "selection",
          "success",
          "warning",
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "className",
        "type": "string | undefined",
        "declared_type": "string",
        "required": false,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 26
        }
      },
      {
        "name": "style",
        "type": "React.CSSProperties | undefined",
        "declared_type": "React.CSSProperties",
        "required": false,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 27
        }
      },
      {
        "name": "testId",
        "type": "string | undefined",
        "declared_type": "string",
        "required": false,
        "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 29
        }
      }
    ],
    "ReadonlyChipProps": [
      {
        "name": "onPress",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: a readonly chip has no press. Add `onPress` to make it interactive.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 96
        },
        "forbidden": true
      },
      {
        "name": "selected",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: a readonly chip has no selected state.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 98
        },
        "forbidden": true
      },
      {
        "name": "onRemove",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: a readonly chip cannot be removed. Add `onRemove` to make it removable.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 100
        },
        "forbidden": true
      },
      {
        "name": "removeLabel",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: there is no remove affordance to name.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 102
        },
        "forbidden": true
      },
      {
        "name": "ariaLabel",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: the visible label is the whole accessible name.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 104
        },
        "forbidden": true
      },
      {
        "name": "busy",
        "type": "never",
        "declared_type": "never",
        "required": false,
        "description": "Unavailable here: only a removable chip has an in-flight removal to report.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 106
        },
        "forbidden": true
      },
      {
        "name": "children",
        "type": "React.ReactNode",
        "declared_type": "React.ReactNode",
        "required": true,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 17
        }
      },
      {
        "name": "size",
        "type": "ChipSize",
        "declared_type": "ChipSize",
        "required": true,
        "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 19
        },
        "values": [
          "md",
          "sm"
        ],
        "values_complete": true
      },
      {
        "name": "disabled",
        "type": "boolean | undefined",
        "declared_type": "boolean",
        "required": false,
        "description": "Blocks press and remove alike, and dims the chip.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 21
        },
        "values": [
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "leading",
        "type": "React.ReactNode",
        "declared_type": "React.ReactNode",
        "required": false,
        "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 23
        }
      },
      {
        "name": "haptic",
        "type": "HapticFeedback | undefined",
        "declared_type": "HapticFeedback",
        "required": false,
        "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 25
        },
        "values": [
          "error",
          "heavy",
          "light",
          "medium",
          "selection",
          "success",
          "warning",
          false,
          true
        ],
        "values_complete": true
      },
      {
        "name": "className",
        "type": "string | undefined",
        "declared_type": "string",
        "required": false,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 26
        }
      },
      {
        "name": "style",
        "type": "React.CSSProperties | undefined",
        "declared_type": "React.CSSProperties",
        "required": false,
        "description": "",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 27
        }
      },
      {
        "name": "testId",
        "type": "string | undefined",
        "declared_type": "string",
        "required": false,
        "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 29
        }
      }
    ]
  },
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Chip",
    "public_path": "Chip",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Chip",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
          "line": 121
        },
        "props_type": "ChipProps",
        "props": [
          {
            "name": "onPress",
            "type": "(() => void) | (() => void) | undefined",
            "declared_type": "() => void",
            "required": false,
            "description": "Fires on tap. Its presence is what makes the root a button.\nUnavailable here: the remove button owns the only focus stop.\nUnavailable here: a readonly chip has no press. Add `onPress` to make it interactive.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 38
            }
          },
          {
            "name": "selected",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Selected state, exposed as `aria-pressed`.\nUnavailable here: a command has no selected state. Pass `selected` to get a toggle.\nUnavailable here: a removable value has no selected state.\nUnavailable here: a readonly chip has no selected state.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 40
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "onRemove",
            "type": "never",
            "declared_type": "never",
            "required": false,
            "description": "Unavailable here: a selectable chip cannot also be removable.\nUnavailable here: a command chip cannot also be removable.\nFires from the remove button only, never from the chip body.\nUnavailable here: a readonly chip cannot be removed. Add `onRemove` to make it removable.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 42
            },
            "forbidden": true
          },
          {
            "name": "removeLabel",
            "type": "never",
            "declared_type": "never",
            "required": false,
            "description": "Unavailable here: there is no remove affordance to name.\nAccessible name for the remove button. Name the value, as in `Remove sriram@example.com`.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 44
            },
            "forbidden": true
          },
          {
            "name": "ariaLabel",
            "type": "never",
            "declared_type": "never",
            "required": false,
            "description": "Unavailable here: the visible label names a toggle whose state `aria-pressed` carries.\nReplaces the visible label as the accessible name when the label alone lacks context.\nUnavailable here: the remove button carries the accessible name, via `removeLabel`.\nUnavailable here: the visible label is the whole accessible name.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 46
            },
            "forbidden": true
          },
          {
            "name": "busy",
            "type": "never",
            "declared_type": "never",
            "required": false,
            "description": "Unavailable here: only a removable chip has an in-flight removal to report.\nShows a spinner in place of the remove icon and blocks the button while its removal is in flight.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 48
            },
            "forbidden": true
          },
          {
            "name": "children",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": true,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 17
            }
          },
          {
            "name": "size",
            "type": "ChipSize",
            "declared_type": "ChipSize",
            "required": true,
            "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 19
            },
            "values": [
              "md",
              "sm"
            ],
            "values_complete": true
          },
          {
            "name": "disabled",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Blocks press and remove alike, and dims the chip.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 21
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "leading",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": false,
            "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 23
            }
          },
          {
            "name": "haptic",
            "type": "HapticFeedback | undefined",
            "declared_type": "HapticFeedback",
            "required": false,
            "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 25
            },
            "values": [
              "error",
              "heavy",
              "light",
              "medium",
              "selection",
              "success",
              "warning",
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 26
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 27
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
            "source": {
              "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
              "line": 29
            }
          }
        ],
        "branches": [
          {
            "name": "SelectableChipProps",
            "props": [
              {
                "name": "onPress",
                "type": "() => void",
                "declared_type": "() => void",
                "required": true,
                "description": "Fires on tap. Its presence is what makes the root a button.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 38
                }
              },
              {
                "name": "selected",
                "type": "boolean",
                "declared_type": "boolean",
                "required": true,
                "description": "Selected state, exposed as `aria-pressed`.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 40
                },
                "values": [
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "onRemove",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: a selectable chip cannot also be removable.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 42
                },
                "forbidden": true
              },
              {
                "name": "removeLabel",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: there is no remove affordance to name.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 44
                },
                "forbidden": true
              },
              {
                "name": "ariaLabel",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: the visible label names a toggle whose state `aria-pressed` carries.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 46
                },
                "forbidden": true
              },
              {
                "name": "busy",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: only a removable chip has an in-flight removal to report.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 48
                },
                "forbidden": true
              },
              {
                "name": "children",
                "type": "React.ReactNode",
                "declared_type": "React.ReactNode",
                "required": true,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 17
                }
              },
              {
                "name": "size",
                "type": "ChipSize",
                "declared_type": "ChipSize",
                "required": true,
                "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 19
                },
                "values": [
                  "md",
                  "sm"
                ],
                "values_complete": true
              },
              {
                "name": "disabled",
                "type": "boolean | undefined",
                "declared_type": "boolean",
                "required": false,
                "description": "Blocks press and remove alike, and dims the chip.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 21
                },
                "values": [
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "leading",
                "type": "React.ReactNode",
                "declared_type": "React.ReactNode",
                "required": false,
                "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 23
                }
              },
              {
                "name": "haptic",
                "type": "HapticFeedback | undefined",
                "declared_type": "HapticFeedback",
                "required": false,
                "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 25
                },
                "values": [
                  "error",
                  "heavy",
                  "light",
                  "medium",
                  "selection",
                  "success",
                  "warning",
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "className",
                "type": "string | undefined",
                "declared_type": "string",
                "required": false,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 26
                }
              },
              {
                "name": "style",
                "type": "React.CSSProperties | undefined",
                "declared_type": "React.CSSProperties",
                "required": false,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 27
                }
              },
              {
                "name": "testId",
                "type": "string | undefined",
                "declared_type": "string",
                "required": false,
                "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 29
                }
              }
            ]
          },
          {
            "name": "CommandChipProps",
            "props": [
              {
                "name": "onPress",
                "type": "() => void",
                "declared_type": "() => void",
                "required": true,
                "description": "Fires on tap. Its presence is what makes the root a button.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 57
                }
              },
              {
                "name": "ariaLabel",
                "type": "string | undefined",
                "declared_type": "string",
                "required": false,
                "description": "Replaces the visible label as the accessible name when the label alone lacks context.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 59
                }
              },
              {
                "name": "selected",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: a command has no selected state. Pass `selected` to get a toggle.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 61
                },
                "forbidden": true
              },
              {
                "name": "onRemove",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: a command chip cannot also be removable.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 63
                },
                "forbidden": true
              },
              {
                "name": "removeLabel",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: there is no remove affordance to name.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 65
                },
                "forbidden": true
              },
              {
                "name": "busy",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: only a removable chip has an in-flight removal to report.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 67
                },
                "forbidden": true
              },
              {
                "name": "children",
                "type": "React.ReactNode",
                "declared_type": "React.ReactNode",
                "required": true,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 17
                }
              },
              {
                "name": "size",
                "type": "ChipSize",
                "declared_type": "ChipSize",
                "required": true,
                "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 19
                },
                "values": [
                  "md",
                  "sm"
                ],
                "values_complete": true
              },
              {
                "name": "disabled",
                "type": "boolean | undefined",
                "declared_type": "boolean",
                "required": false,
                "description": "Blocks press and remove alike, and dims the chip.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 21
                },
                "values": [
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "leading",
                "type": "React.ReactNode",
                "declared_type": "React.ReactNode",
                "required": false,
                "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 23
                }
              },
              {
                "name": "haptic",
                "type": "HapticFeedback | undefined",
                "declared_type": "HapticFeedback",
                "required": false,
                "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 25
                },
                "values": [
                  "error",
                  "heavy",
                  "light",
                  "medium",
                  "selection",
                  "success",
                  "warning",
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "className",
                "type": "string | undefined",
                "declared_type": "string",
                "required": false,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 26
                }
              },
              {
                "name": "style",
                "type": "React.CSSProperties | undefined",
                "declared_type": "React.CSSProperties",
                "required": false,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 27
                }
              },
              {
                "name": "testId",
                "type": "string | undefined",
                "declared_type": "string",
                "required": false,
                "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 29
                }
              }
            ]
          },
          {
            "name": "RemovableChipProps",
            "props": [
              {
                "name": "onRemove",
                "type": "() => void",
                "declared_type": "() => void",
                "required": true,
                "description": "Fires from the remove button only, never from the chip body.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 76
                }
              },
              {
                "name": "removeLabel",
                "type": "string",
                "declared_type": "string",
                "required": true,
                "description": "Accessible name for the remove button. Name the value, as in `Remove sriram@example.com`.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 78
                }
              },
              {
                "name": "busy",
                "type": "boolean | undefined",
                "declared_type": "boolean",
                "required": false,
                "description": "Shows a spinner in place of the remove icon and blocks the button while its removal is in flight.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 80
                },
                "values": [
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "onPress",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: the remove button owns the only focus stop.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 82
                },
                "forbidden": true
              },
              {
                "name": "selected",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: a removable value has no selected state.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 84
                },
                "forbidden": true
              },
              {
                "name": "ariaLabel",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: the remove button carries the accessible name, via `removeLabel`.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 86
                },
                "forbidden": true
              },
              {
                "name": "children",
                "type": "React.ReactNode",
                "declared_type": "React.ReactNode",
                "required": true,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 17
                }
              },
              {
                "name": "size",
                "type": "ChipSize",
                "declared_type": "ChipSize",
                "required": true,
                "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 19
                },
                "values": [
                  "md",
                  "sm"
                ],
                "values_complete": true
              },
              {
                "name": "disabled",
                "type": "boolean | undefined",
                "declared_type": "boolean",
                "required": false,
                "description": "Blocks press and remove alike, and dims the chip.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 21
                },
                "values": [
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "leading",
                "type": "React.ReactNode",
                "declared_type": "React.ReactNode",
                "required": false,
                "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 23
                }
              },
              {
                "name": "haptic",
                "type": "HapticFeedback | undefined",
                "declared_type": "HapticFeedback",
                "required": false,
                "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 25
                },
                "values": [
                  "error",
                  "heavy",
                  "light",
                  "medium",
                  "selection",
                  "success",
                  "warning",
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "className",
                "type": "string | undefined",
                "declared_type": "string",
                "required": false,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 26
                }
              },
              {
                "name": "style",
                "type": "React.CSSProperties | undefined",
                "declared_type": "React.CSSProperties",
                "required": false,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 27
                }
              },
              {
                "name": "testId",
                "type": "string | undefined",
                "declared_type": "string",
                "required": false,
                "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 29
                }
              }
            ]
          },
          {
            "name": "ReadonlyChipProps",
            "props": [
              {
                "name": "onPress",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: a readonly chip has no press. Add `onPress` to make it interactive.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 96
                },
                "forbidden": true
              },
              {
                "name": "selected",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: a readonly chip has no selected state.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 98
                },
                "forbidden": true
              },
              {
                "name": "onRemove",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: a readonly chip cannot be removed. Add `onRemove` to make it removable.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 100
                },
                "forbidden": true
              },
              {
                "name": "removeLabel",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: there is no remove affordance to name.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 102
                },
                "forbidden": true
              },
              {
                "name": "ariaLabel",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: the visible label is the whole accessible name.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 104
                },
                "forbidden": true
              },
              {
                "name": "busy",
                "type": "never",
                "declared_type": "never",
                "required": false,
                "description": "Unavailable here: only a removable chip has an in-flight removal to report.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 106
                },
                "forbidden": true
              },
              {
                "name": "children",
                "type": "React.ReactNode",
                "declared_type": "React.ReactNode",
                "required": true,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 17
                }
              },
              {
                "name": "size",
                "type": "ChipSize",
                "declared_type": "ChipSize",
                "required": true,
                "description": "Height and padding tier. `sm` suits inline value tokens, `md` filter rows.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 19
                },
                "values": [
                  "md",
                  "sm"
                ],
                "values_complete": true
              },
              {
                "name": "disabled",
                "type": "boolean | undefined",
                "declared_type": "boolean",
                "required": false,
                "description": "Blocks press and remove alike, and dims the chip.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 21
                },
                "values": [
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "leading",
                "type": "React.ReactNode",
                "declared_type": "React.ReactNode",
                "required": false,
                "description": "Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 23
                }
              },
              {
                "name": "haptic",
                "type": "HapticFeedback | undefined",
                "declared_type": "HapticFeedback",
                "required": false,
                "description": "Haptic feedback for successful presses. Defaults to `true` (`selection`).",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 25
                },
                "values": [
                  "error",
                  "heavy",
                  "light",
                  "medium",
                  "selection",
                  "success",
                  "warning",
                  false,
                  true
                ],
                "values_complete": true
              },
              {
                "name": "className",
                "type": "string | undefined",
                "declared_type": "string",
                "required": false,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 26
                }
              },
              {
                "name": "style",
                "type": "React.CSSProperties | undefined",
                "declared_type": "React.CSSProperties",
                "required": false,
                "description": "",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 27
                }
              },
              {
                "name": "testId",
                "type": "string | undefined",
                "declared_type": "string",
                "required": false,
                "description": "Selector for the chip. A removable chip's × derives `${testId}-remove` from it.",
                "source": {
                  "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
                  "line": 29
                }
              }
            ]
          }
        ],
        "constraints": [
          {
            "kind": "union",
            "rule": "Props must satisfy one complete branch; a forbidden prop cannot be supplied.",
            "branches": [
              "SelectableChipProps",
              "CommandChipProps",
              "RemovableChipProps",
              "ReadonlyChipProps"
            ]
          }
        ],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 10,
        "name": "ChipSize",
        "code": "export type ChipSize = 'sm' | 'md';"
      },
      {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 16,
        "name": "ChipBaseProps",
        "code": "interface ChipBaseProps {\n    children: React.ReactNode;\n    /** Height and padding tier. `sm` suits inline value tokens, `md` filter rows. */\n    size: ChipSize;\n    /** Blocks press and remove alike, and dims the chip. */\n    disabled?: boolean;\n    /** Optional leading visual, usually an `Icon`, `Avatar`, or `SFIcon`. */\n    leading?: React.ReactNode;\n    /** Haptic feedback for successful presses. Defaults to `true` (`selection`). */\n    haptic?: HapticFeedback;\n    className?: string;\n    style?: React.CSSProperties;\n    /** Selector for the chip. A removable chip's × derives `${testId}-remove` from it. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 36,
        "name": "SelectableChipProps",
        "code": "export interface SelectableChipProps extends ChipBaseProps {\n    /** Fires on tap. Its presence is what makes the root a button. */\n    onPress: () => void;\n    /** Selected state, exposed as `aria-pressed`. */\n    selected: boolean;\n    /** Unavailable here: a selectable chip cannot also be removable. */\n    onRemove?: never;\n    /** Unavailable here: there is no remove affordance to name. */\n    removeLabel?: never;\n    /** Unavailable here: the visible label names a toggle whose state `aria-pressed` carries. */\n    ariaLabel?: never;\n    /** Unavailable here: only a removable chip has an in-flight removal to report. */\n    busy?: never;\n}"
      },
      {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 55,
        "name": "CommandChipProps",
        "code": "export interface CommandChipProps extends ChipBaseProps {\n    /** Fires on tap. Its presence is what makes the root a button. */\n    onPress: () => void;\n    /** Replaces the visible label as the accessible name when the label alone lacks context. */\n    ariaLabel?: string;\n    /** Unavailable here: a command has no selected state. Pass `selected` to get a toggle. */\n    selected?: never;\n    /** Unavailable here: a command chip cannot also be removable. */\n    onRemove?: never;\n    /** Unavailable here: there is no remove affordance to name. */\n    removeLabel?: never;\n    /** Unavailable here: only a removable chip has an in-flight removal to report. */\n    busy?: never;\n}"
      },
      {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 74,
        "name": "RemovableChipProps",
        "code": "export interface RemovableChipProps extends ChipBaseProps {\n    /** Fires from the remove button only, never from the chip body. */\n    onRemove: () => void;\n    /** Accessible name for the remove button. Name the value, as in `Remove sriram@example.com`. */\n    removeLabel: string;\n    /** Shows a spinner in place of the remove icon and blocks the button while its removal is in flight. */\n    busy?: boolean;\n    /** Unavailable here: the remove button owns the only focus stop. */\n    onPress?: never;\n    /** Unavailable here: a removable value has no selected state. */\n    selected?: never;\n    /** Unavailable here: the remove button carries the accessible name, via `removeLabel`. */\n    ariaLabel?: never;\n}"
      },
      {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 94,
        "name": "ReadonlyChipProps",
        "code": "export interface ReadonlyChipProps extends ChipBaseProps {\n    /** Unavailable here: a readonly chip has no press. Add `onPress` to make it interactive. */\n    onPress?: never;\n    /** Unavailable here: a readonly chip has no selected state. */\n    selected?: never;\n    /** Unavailable here: a readonly chip cannot be removed. Add `onRemove` to make it removable. */\n    onRemove?: never;\n    /** Unavailable here: there is no remove affordance to name. */\n    removeLabel?: never;\n    /** Unavailable here: the visible label is the whole accessible name. */\n    ariaLabel?: never;\n    /** Unavailable here: only a removable chip has an in-flight removal to report. */\n    busy?: never;\n}"
      },
      {
        "path": "packages/design-system/src/components/controls/Chip/Chip.tsx",
        "line": 114,
        "name": "ChipProps",
        "code": "export type ChipProps = SelectableChipProps | CommandChipProps | RemovableChipProps | ReadonlyChipProps;"
      },
      {
        "path": "packages/design-system/src/tokens/CdsHaptic.ts",
        "line": 6,
        "name": "HapticFeedback",
        "code": "export type HapticFeedback = boolean | HapticType;"
      },
      {
        "path": "packages/design-system/src/tokens/HapticType.ts",
        "line": 2,
        "name": "HapticType",
        "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Chip",
      "status": "preview",
      "version": "2.3.0",
      "summary": "A compact pill in one of four shapes: selectable, command, removable, or readonly. Never more than one."
    },
    "parts": [
      {
        "id": "container",
        "label": "Container",
        "description": "A button for a selectable or command chip, a span for a removable or readonly one. Owns size, selected, and disabled.",
        "required": true
      },
      {
        "id": "leading",
        "label": "Leading visual",
        "description": "Optional icon or avatar before the value."
      },
      {
        "id": "content",
        "label": "Content",
        "description": "Visible value or filter label."
      },
      {
        "id": "remove-action",
        "label": "Remove action",
        "description": "The independently named button on a removable chip, and its only focus stop."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "selectable": {
          "label": "Selectable",
          "description": "Toggles its own state. Renders a button carrying aria-pressed."
        },
        "command": {
          "label": "Command",
          "description": "Runs a one-off action. Renders a button with no aria-pressed."
        },
        "removable": {
          "label": "Removable",
          "description": "Holds a value the user can dismiss. Renders a span with a nested remove button."
        },
        "readonly": {
          "label": "Readonly",
          "description": "A locked member of a chip set. Renders a span with no remove button and no focus stop."
        }
      },
      "sizes": {
        "sm": {
          "label": "Small"
        },
        "md": {
          "label": "Medium"
        }
      }
    },
    "variants": [
      {
        "id": "selectable",
        "label": "Selectable",
        "description": "`onPress` with `selected`. One focus stop, on the chip itself.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      },
      {
        "id": "command",
        "label": "Command",
        "description": "`onPress` without `selected`, plus an optional `ariaLabel`. One focus stop, on the chip itself.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      },
      {
        "id": "removable",
        "label": "Removable",
        "description": "`onRemove`. One focus stop, on the remove affordance.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      },
      {
        "id": "readonly",
        "label": "Readonly",
        "description": "Neither `onPress` nor `onRemove`. Renders a span with no focus stop.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [
      {
        "id": "sm",
        "label": "Small",
        "description": "24-unit inline value token."
      },
      {
        "id": "md",
        "label": "Medium",
        "description": "32-unit filter or standalone value chip."
      }
    ],
    "measurements": [
      {
        "id": "small-min-height",
        "label": "Small chip minimum height",
        "kind": "exact",
        "token": "--cds-size-24",
        "value": 24,
        "unit": "px",
        "appliesTo": [
          "container",
          "sm"
        ]
      },
      {
        "id": "medium-min-height",
        "label": "Medium chip minimum height",
        "kind": "exact",
        "token": "--cds-size-32",
        "value": 32,
        "unit": "px",
        "appliesTo": [
          "container",
          "md"
        ]
      },
      {
        "id": "medium-content-gap",
        "label": "Medium content gap",
        "kind": "exact",
        "token": "--cds-space-8",
        "value": 8,
        "unit": "px",
        "appliesTo": [
          "leading",
          "content",
          "trailing",
          "remove-action",
          "md"
        ]
      }
    ],
    "layout": {
      "alignment": "All visible parts align on the pill center line and the container hugs its content.",
      "flow": "Optional leading visual, content, then the remove action on a removable chip.",
      "notes": [
        "Assign exactly one shape: selectable, command, removable, or readonly.",
        "Use readonly for a locked member of a chip set, and Tag for a standalone marker or status label.",
        "Use Dropdown for a trigger that opens a menu.",
        "Put a set in a ChipGroup rather than a bare row."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Chip content",
          "description": "Use body-small text at both chip sizes.",
          "token": "--cds-type-body-small-size"
        }
      ],
      "colors": [
        {
          "label": "Default surface",
          "description": "Use the semantic input container.",
          "token": "--cds-input-container"
        },
        {
          "label": "Selected surface",
          "description": "Use the inverse background for selected filters.",
          "token": "--cds-bg-inverse"
        },
        {
          "label": "Selected content",
          "description": "Use inverse text on the selected inverse surface.",
          "token": "--cds-text-inverse"
        },
        {
          "label": "Content",
          "description": "Use primary text emphasis for the represented value.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Remove action",
          "description": "Use secondary text emphasis for the remove icon.",
          "token": "--cds-text-secondary"
        }
      ]
    },
    "states": [
      {
        "id": "default",
        "label": "Default",
        "description": "Shows the neutral pill treatment."
      },
      {
        "id": "selected",
        "label": "Selected",
        "description": "Inverse fill and inverse text on a selectable chip, exposed as `aria-pressed`."
      },
      {
        "id": "pressed",
        "label": "Pressed",
        "description": "Temporary press feedback on a selectable or command chip."
      },
      {
        "id": "disabled",
        "label": "Disabled",
        "description": "Sets the native disabled attribute and dims the chip."
      },
      {
        "id": "removing",
        "label": "Removing",
        "description": "On a removable chip, shows a spinner in place of the remove icon and blocks the remove button while its removal is in flight, exposed as `aria-busy`."
      }
    ],
    "behavior": [
      {
        "label": "Selectable press",
        "description": "Invoke onPress on tap and expose the pressed state. The root is a real button, so activation is native."
      },
      {
        "label": "Command press",
        "description": "Invoke onPress on tap without reporting any selection state. Use this shape when the chip runs a one-off action, such as opening an explainer."
      },
      {
        "label": "Remove",
        "description": "Invoke onRemove only from the independently labelled remove action."
      },
      {
        "label": "One shape per chip",
        "description": "A chip is exactly one of selectable, command, removable, or readonly. The props are a discriminated union, so onPress and onRemove cannot be combined (two focus stops would require a button inside a button), selected is what picks selectable over command, and a chip with neither handler is readonly."
      },
      {
        "label": "Readonly member versus a standalone marker",
        "description": "A readonly chip is a locked member of a chip set, so it stays in the chip family alongside its removable siblings. A standalone marker or status label is a Tag, and a pill that opens a menu is a Dropdown."
      }
    ],
    "accessibility": [
      {
        "label": "Selectable semantics",
        "description": "A selectable chip is a button carrying aria-pressed and the native disabled attribute."
      },
      {
        "label": "Command semantics",
        "description": "A command chip is a button with no aria-pressed, because a permanent unpressed toggle state misreports a one-off action. Give it ariaLabel when the visible label is not a complete name."
      },
      {
        "label": "Removable semantics",
        "description": "The body of a removable chip takes no focus. Its remove button is the only focus stop."
      },
      {
        "label": "Readonly semantics",
        "description": "A readonly chip is a span with no role and no focus stop, so it is announced as text alongside its interactive siblings."
      },
      {
        "label": "Remove name",
        "description": "Every remove action carries a value-specific accessible label and a stable test identifier. removeLabel is required, so there is no generic fallback to fall back to."
      },
      {
        "label": "Grouping",
        "description": "Put a set of chips in a ChipGroup so they are announced as one group."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Concise values",
        "description": "Keep chip labels short enough to remain scannable in wrapping rows."
      },
      {
        "label": "Value-specific removal",
        "description": "Name remove actions with the represented value or category when context is not obvious."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Press feedback",
          "description": "Use subtle opacity and scale feedback and remove scale under reduced-motion preferences."
        }
      ],
      "haptics": [
        {
          "label": "Successful interaction",
          "description": "Request the selection haptic after an enabled press or removal."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "web"
        ],
        "description": "Web renders no focus ring and no keyboard activation handler for either shape.",
        "rationale": "The only consumers are a touch iOS WKWebView and a harness previewing that same UI, so a keyboard affordance here would be dead code."
      }
    ]
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-size-24",
      "light": "24px",
      "dark": "24px"
    },
    {
      "name": "--cds-size-32",
      "light": "32px",
      "dark": "32px"
    },
    {
      "name": "--cds-space-8",
      "light": "8px",
      "dark": "8px"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-input-container",
      "light": "#f3f1ed",
      "dark": "#232321"
    },
    {
      "name": "--cds-bg-inverse",
      "light": "#0b0b0a",
      "dark": "#0b0b0a"
    },
    {
      "name": "--cds-text-inverse",
      "light": "#ffffff",
      "dark": "#ffffff"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    },
    {
      "name": "--cds-text-secondary",
      "light": "#646260",
      "dark": "#ffffff99"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-controls-chip--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/controls/Chip/Chip.stories.tsx

- [Filter Chips](/storybook/iframe.html?id=cloaked-design-system-controls-chip--filter-chips&viewMode=story) | export: FilterChips | source: packages/design-system/src/components/controls/Chip/Chip.stories.tsx

- [Command Chips](/storybook/iframe.html?id=cloaked-design-system-controls-chip--command-chips&viewMode=story) | export: CommandChips | source: packages/design-system/src/components/controls/Chip/Chip.stories.tsx

- [Removable Values](/storybook/iframe.html?id=cloaked-design-system-controls-chip--removable-values&viewMode=story) | export: RemovableValues | source: packages/design-system/src/components/controls/Chip/Chip.stories.tsx

- [Readonly Member](/storybook/iframe.html?id=cloaked-design-system-controls-chip--readonly-member&viewMode=story) | export: ReadonlyMember | source: packages/design-system/src/components/controls/Chip/Chip.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-controls-chip--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/controls/Chip/Chip.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.