{
  "version": "0.2.0-preview.1",
  "content_digest": "70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721",
  "status": "preview",
  "authority": {
    "repository": "cloakedinc/design",
    "path": "packages/design-system",
    "catalog": "packages/design-system/catalog.json",
    "status": "preview"
  },
  "provenance": {
    "repo": "cloakedinc/automation",
    "commit": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "path": "packages/design-system",
    "imported_spec_status": "approved"
  },
  "adaptations": [
    {
      "id": "button-content-gap",
      "status": "preview",
      "description": "Use the specification's 4px content gap instead of the inherited 8px implementation gap."
    },
    {
      "id": "keyboard-focus",
      "status": "preview",
      "description": "Add visible Button and Input keyboard focus and an overridable inset focus default for shared button resets, including FAQ cards and ListItem rows."
    },
    {
      "id": "supporting-text-contrast",
      "status": "preview",
      "description": "Map light secondary text to the existing grey-04-strong primitive for readable helper text on white and cream."
    },
    {
      "id": "danger-text-contrast",
      "status": "preview",
      "description": "Separate readable danger text/borders from destructive fills; preserve the primary danger-button fill and label pair."
    },
    {
      "id": "preview-status",
      "status": "preview",
      "description": "Local components, specs and token adaptations await human sign-off; upstream approved status is provenance only."
    },
    {
      "id": "motion-comparison-accessibility",
      "status": "preview",
      "description": "Preserve the original MotionShowcase comparisons while requiring explicit replay, responding to live reduced-motion changes, and keeping duration tracks usable on small screens."
    },
    {
      "id": "list-item-ownership",
      "status": "preview",
      "description": "List owns listitem wrappers for its content rows, while section labels stay outside the row count and standalone rows retain their existing semantics."
    },
    {
      "id": "card-delta-text-contrast",
      "status": "preview",
      "description": "Mix Card.Delta foregrounds from 60% existing tone solid and 40% primary text for readable contrast in both themes; preserve the four original tone fills."
    },
    {
      "id": "carousel-keyboard-access",
      "status": "preview",
      "description": "Keep all native-scrolling carousel slide controls exposed to assistive technology and keyboard navigation; pause autoplay while focus is inside the carousel."
    }
  ],
  "id": "select",
  "name": "Select",
  "category": "Forms",
  "contract_status": "preview",
  "contract_kind": "source-derived",
  "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."
  },
  "approval": "required",
  "visual_reference": {
    "stories": [
      {
        "id": "cloaked-design-system-forms-select--playground",
        "name": "Playground",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "Playground",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--playground&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-select--selected",
        "name": "Selected",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "Selected",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--selected&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-select--raised-on-canvas",
        "name": "Raised On Canvas",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "RaisedOnCanvas",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--raised-on-canvas&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-select--with-field",
        "name": "With Field",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "WithField",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--with-field&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-select--invalid-in-field",
        "name": "Invalid In Field",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "InvalidInField",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--invalid-in-field&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-select--disabled",
        "name": "Disabled",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "Disabled",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--disabled&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-select--state-matrix",
        "name": "State Matrix",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "StateMatrix",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--state-matrix&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-select--bottom-sheet-interaction",
        "name": "Bottom Sheet Interaction",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "BottomSheetInteraction",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--bottom-sheet-interaction&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-select--long-options",
        "name": "Long Options",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "LongOptions",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--long-options&viewMode=story"
      },
      {
        "id": "cloaked-design-system-forms-select--dark-theme",
        "name": "Dark Theme",
        "title": "Cloaked Design System/Forms/Select",
        "exportName": "DarkTheme",
        "source_path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
        "source_digest": "51ceb09c649a2e375d0f66ae4ff90fdff63ec0ae885b43dede6dbef5338bda40",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-forms-select--dark-theme&viewMode=story"
      }
    ],
    "name": "Select",
    "id": "select",
    "category": "Forms"
  },
  "stories_source": {
    "path": "packages/design-system/src/components/forms/Select/Select.stories.tsx",
    "code": "import React, { useState } from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { Icon } from '../../primitives/Icon/Icon';\nimport { disabledControl, hapticArgType, selectArgType } from '../../../storybook/controlOptions';\nimport { Field } from '../Field/Field';\nimport { Select, type SelectProps, type SelectSurface } from './Select';\n\nconst SELECT_SURFACES = ['default', 'raised'] as const satisfies readonly SelectSurface[];\n\nconst CONTACT_OPTIONS = [\n    { value: 'email', label: 'Email', leading: <Icon name='mail' size='small' /> },\n    { value: 'phone', label: 'Phone', leading: <Icon name='phone' size='small' /> },\n    { value: 'sms', label: 'SMS', leading: <Icon name='message' size='small' /> },\n];\n\nconst meta: Meta<typeof Select> = {\n    title: 'Cloaked Design System/Forms/Select',\n    component: Select,\n    parameters: {\n        a11y: { test: 'error' },\n        stage: 'form-control',\n        docs: {\n            description: {\n                component:\n                    'A single-choice form control that opens a native-feeling bottom sheet (BottomSheet + Menu) instead ' +\n                    'of a desktop dropdown — the mobile pattern for picking one `SelectOption`. Use it when the ' +\n                    'choice set is short and mutually exclusive; reach for `RadioGroup` when every option should be ' +\n                    'visible at once, or `Autocomplete` when the list is long enough to need type-to-filter. Renders ' +\n                    'a hidden `<input>` so it submits inside a native form. Pair with `Field` for a label; only pass ' +\n                    'the standalone `error` prop when used outside `Field`.',\n            },\n        },\n    },\n    args: {\n        value: '',\n        ariaLabel: 'Preferred contact method',\n        options: CONTACT_OPTIONS,\n        testId: 'select-story',\n    },\n    argTypes: {\n        options: {\n            ...disabledControl,\n            description: 'Selectable `SelectOption[]`; each has a `value`, `label`, optional `leading`.',\n        },\n        surface: {\n            ...selectArgType(SELECT_SURFACES),\n            description:\n                'Trigger background: `default` on a page, `raised` when sitting on an already-elevated surface.',\n        },\n        onChange: {\n            ...disabledControl,\n            description: 'Called with the next option `value` when the sheet confirms a choice.',\n        },\n        haptic: { ...hapticArgType, description: 'Haptic fired on selection. Defaults to `true` (`selection`).' },\n        value: { control: 'text', description: 'Currently selected option `value`; empty shows the `placeholder`.' },\n        placeholder: { control: 'text', description: 'Trigger text shown while no value is selected.' },\n        invalid: {\n            control: 'boolean',\n            description: 'Paints the invalid ring. A parent Field sets this from its own `error`.',\n        },\n        disabled: { control: 'boolean', description: 'Blocks opening the sheet and dims the trigger.' },\n    },\n};\nexport default meta;\ntype Story = StoryObj<typeof Select>;\n\nfunction ControlledSelect(args: SelectProps) {\n    const [value, setValue] = useState(args.value);\n    return <Select {...args} value={value} onChange={setValue} />;\n}\n\nexport const Playground: Story = {\n    render: args => <ControlledSelect {...args} />,\n};\n\nexport const Selected: Story = {\n    parameters: { docs: { description: { story: 'Trigger showing a chosen option with its leading icon.' } } },\n    args: { value: 'email' },\n};\n\nexport const RaisedOnCanvas: Story = {\n    parameters: {\n        stage: 'page',\n        docs: {\n            description: {\n                story: 'The `raised` white trigger on the cream page canvas, where the `default` cream fill would disappear. Every other story shows `default` on the white surface it is built for.',\n            },\n        },\n    },\n    args: { value: 'email', surface: 'raised', testId: 'select-surface-raised' },\n};\n\nexport const WithField: Story = {\n    parameters: {\n        docs: { description: { story: 'Wrapped in `Field` so the label and aria wiring come from the field.' } },\n    },\n    render: function WithFieldStory() {\n        const [value, setValue] = useState('');\n        return (\n            <Field label='Preferred contact method'>\n                <Select value={value} onChange={setValue} options={CONTACT_OPTIONS} testId='select-with-field' />\n            </Field>\n        );\n    },\n};\n\nexport const InvalidInField: Story = {\n    parameters: {\n        docs: { description: { story: 'Field owns the message; the trigger turns red through context.' } },\n    },\n    render: args => (\n        <Field label='Contact method' error='Choose one contact method.'>\n            <Select {...args} />\n        </Field>\n    ),\n    args: { testId: 'select-error' },\n};\n\nexport const Disabled: Story = {\n    parameters: { docs: { description: { story: 'Disabled trigger cannot open the sheet.' } } },\n    args: { value: 'phone', disabled: true, testId: 'select-disabled' },\n};\n\nexport const StateMatrix: Story = {\n    parameters: { docs: { description: { story: 'Empty, selected, error, and disabled triggers side by side.' } } },\n    render: () => (\n        <VStack gap={16}>\n            <Select value='' ariaLabel='Empty select' options={CONTACT_OPTIONS} testId='select-matrix-empty' />\n            <Select\n                value='email'\n                ariaLabel='Selected select'\n                options={CONTACT_OPTIONS}\n                testId='select-matrix-selected'\n            />\n            <Select value='' ariaLabel='Error select' options={CONTACT_OPTIONS} invalid testId='select-matrix-error' />\n            <Select\n                value='phone'\n                ariaLabel='Disabled select'\n                options={CONTACT_OPTIONS}\n                disabled\n                testId='select-matrix-disabled'\n            />\n        </VStack>\n    ),\n};\n\nexport const BottomSheetInteraction: Story = {\n    parameters: {\n        docs: {\n            description: {\n                story: 'Open the trigger to see the BottomSheet + Menu option sheet; the sheet derives its test id with a `-sheet` suffix.',\n            },\n        },\n    },\n    render: args => <ControlledSelect {...args} />,\n    args: {\n        sheetTitle: 'Preferred contact method',\n        testId: 'select-bottom-sheet',\n    },\n};\n\nexport const LongOptions: Story = {\n    parameters: {\n        docs: { description: { story: 'Long option labels wrap inside the sheet without truncating the trigger.' } },\n    },\n    args: {\n        ariaLabel: 'Long option select',\n        options: [\n            { value: 'long-email', label: 'Email me whenever there is a meaningful privacy update' },\n            { value: 'long-phone', label: 'Call only when a recovery action needs approval' },\n        ],\n        testId: 'select-long-options',\n    },\n};\n\nexport const DarkTheme: Story = {\n    globals: { theme: 'dark' },\n    parameters: { docs: { description: { story: 'Trigger and error tokens on the dark theme.' } } },\n    render: () => (\n        <VStack gap={16}>\n            <Select value='email' ariaLabel='Selected select' options={CONTACT_OPTIONS} testId='select-dark-selected' />\n            <Select value='' ariaLabel='Error select' options={CONTACT_OPTIONS} invalid testId='select-dark-error' />\n        </VStack>\n    ),\n};\n"
  },
  "specification": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Select",
      "status": "preview",
      "version": "2.0.0",
      "summary": "A single-choice form control whose trigger opens a mobile option sheet and mirrors the committed value into form submission."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "Stacks the hidden form value and the visible trigger."
      },
      {
        "id": "form-value",
        "label": "Form value",
        "description": "Hidden native input carrying name, value, disabled, and required state."
      },
      {
        "id": "trigger",
        "label": "Trigger",
        "description": "Displays the placeholder or selected label and opens the option dialog."
      },
      {
        "id": "trigger-label",
        "label": "Trigger label",
        "description": "Truncates the current option label without displacing the affordance."
      },
      {
        "id": "chevron",
        "label": "Chevron",
        "description": "Trailing visual indicating that the trigger reveals choices."
      },
      {
        "id": "sheet",
        "label": "Option sheet",
        "description": "Modal surface containing the single-select Menu."
      },
      {
        "id": "option",
        "label": "Option",
        "description": "Menu row with optional leading content, disabled state, and selected check."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "sheet": {
          "label": "Sheet",
          "description": "The form trigger presents one short, fixed choice list in a modal sheet."
        }
      },
      "sizes": {},
      "surfaces": {
        "default": {
          "label": "Default",
          "description": "Uses the semantic input container."
        },
        "raised": {
          "label": "Raised",
          "description": "Uses the raised surface when placed directly on the page canvas."
        }
      }
    },
    "variants": [
      {
        "id": "sheet",
        "label": "Sheet",
        "description": "Single-choice form trigger backed by a modal Menu.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "trigger-height",
        "label": "Trigger height",
        "kind": "exact",
        "token": "--cds-size-56",
        "value": 56,
        "unit": "px",
        "appliesTo": [
          "trigger"
        ]
      },
      {
        "id": "trigger-leading-padding",
        "label": "Trigger leading padding",
        "kind": "exact",
        "token": "--cds-space-20",
        "value": 20,
        "unit": "px",
        "appliesTo": [
          "trigger",
          "trigger-label"
        ]
      },
      {
        "id": "trigger-trailing-padding",
        "label": "Trigger trailing padding",
        "kind": "exact",
        "token": "--cds-space-20",
        "value": 20,
        "unit": "px",
        "appliesTo": [
          "trigger",
          "chevron"
        ]
      }
    ],
    "layout": {
      "alignment": "Trigger label remains leading and flexible while the chevron remains trailing.",
      "flow": "Hidden form value and visible trigger share one root; the trigger presents a modal list of options.",
      "notes": [
        "Use RadioGroup when all choices should remain visible.",
        "Use Autocomplete when a long or dynamic list needs type-to-filter."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Trigger label",
          "description": "Use the body ramp for placeholder and selected option text.",
          "token": "--cds-type-body-size"
        }
      ],
      "colors": [
        {
          "label": "Default surface",
          "description": "Use the semantic input container.",
          "token": "--cds-input-container"
        },
        {
          "label": "Raised surface",
          "description": "Use the raised semantic surface.",
          "token": "--cds-bg-surface"
        },
        {
          "label": "Selected label",
          "description": "Use primary text emphasis for the committed value.",
          "token": "--cds-text-primary"
        },
        {
          "label": "Placeholder and chevron",
          "description": "Use secondary text emphasis before selection and for the affordance.",
          "token": "--cds-text-secondary"
        },
        {
          "label": "Validation",
          "description": "Use the solid danger role for invalid border and copy.",
          "token": "--cds-status-danger-solid"
        }
      ]
    },
    "states": [
      {
        "id": "empty",
        "label": "Empty",
        "description": "Shows placeholder copy and an empty form value."
      },
      {
        "id": "selected",
        "label": "Selected",
        "description": "Shows the current option label and selected option in the sheet."
      },
      {
        "id": "open",
        "label": "Open",
        "description": "Exposes expanded state and presents the labelled option dialog."
      },
      {
        "id": "invalid",
        "label": "Invalid",
        "description": "Shows the danger border and invalid semantics. The corrective message belongs to the enclosing Field."
      },
      {
        "id": "disabled",
        "label": "Disabled",
        "description": "Disables form submission, opening, focus interaction, and option changes."
      }
    ],
    "behavior": [
      {
        "label": "Open",
        "description": "Present the option sheet only from an enabled trigger."
      },
      {
        "label": "Select",
        "description": "Emit the next option value, close the sheet, and mirror the controlled value into the hidden input."
      },
      {
        "label": "Form submission",
        "description": "Submit the controlled string under the optional name; required surfaces as aria-required on the trigger only, since the hidden input skips native constraint validation."
      }
    ],
    "accessibility": [
      {
        "label": "Trigger name and state",
        "description": "Associate a visible Field label or accessible label and expose dialog popup, expanded, required, invalid, and described-by states."
      },
      {
        "label": "Option sheet",
        "description": "Name the modal and its single-select listbox from the field or explicit sheet title."
      },
      {
        "label": "Options",
        "description": "Expose selected and disabled state for every option."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Long selected labels",
        "description": "Truncate the one-line trigger label while allowing full labels to wrap in option rows."
      },
      {
        "label": "Placeholder",
        "description": "Name the choice being requested instead of repeating a generic Select instruction."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Sheet presentation",
          "description": "Delegate opening and dismissal motion to Modal; selection closes the sheet without animating the trigger geometry."
        }
      ],
      "haptics": [
        {
          "label": "Selection feedback",
          "description": "Request the selection haptic after an enabled option is chosen."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "web"
        ],
        "description": "Web mirrors the selected value into a hidden input and uses an ARIA dialog/listbox composition rather than a native HTML select.",
        "rationale": "The mobile bottom-sheet interaction is the cross-platform product pattern, while the hidden input preserves web form submission."
      }
    ]
  },
  "specification_source": "packages/design-system/src/components/forms/Select/Select.spec.json",
  "guidance": {
    "summary": "A single-choice form control whose trigger opens a mobile option sheet and mirrors the committed value into form submission.",
    "guidance": [
      {
        "heading": "Overview",
        "body": "A form control for picking **one** value from a short, known list. The trigger opens a\nnative-feeling bottom sheet (`BottomSheet` + `Menu`) and submits a hidden `<input>`."
      },
      {
        "heading": "When to use",
        "body": "Reach for `Select` when the choice is a single required value drawn from a short, fixed set —\na preferred contact method, a state, a category. It is the mobile equivalent of a `<select>`:\nthe options stay hidden until tapped.\n\n-   List long enough that you'd want to type to narrow it? Use `Autocomplete` — it filters as you type.\n-   Want every option visible inline without opening a sheet? Use `RadioGroup` (or `SegmentedControl` for 2–4).\n-   Just need a trigger + floating panel with no form-value semantics? Use `Dropdown` with a `Menu`.\n\nIn-app it backs the data-removal profile fields (`FormField.tsx`) and the exposures broker filter\n(`BrokerListSection.tsx`). Pair it with `Field` for a label and validation copy — the Field's\n`error` turns this trigger red on its own; `invalid` is the escape hatch outside a `Field`."
      }
    ],
    "usage": [],
    "examples": [],
    "source": "packages/design-system/src/components/forms/Select/Select.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."
  },
  "links": {
    "human": "/component-select",
    "json": "/data/visual/components/select.json",
    "storybook": "/storybook/?path=/story/cloaked-design-system-forms-select--playground"
  }
}