{
  "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": "dropdown",
  "name": "Dropdown",
  "category": "Controls",
  "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-controls-dropdown--playground",
        "name": "Playground",
        "title": "Cloaked Design System/Controls/Dropdown",
        "exportName": "Playground",
        "source_path": "packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx",
        "source_digest": "6822166cebbeb17f3bca15e430716a465992596ef4932111d4d7281dd5c4cc94",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--playground&viewMode=story"
      },
      {
        "id": "cloaked-design-system-controls-dropdown--expanded",
        "name": "Expanded",
        "title": "Cloaked Design System/Controls/Dropdown",
        "exportName": "Expanded",
        "source_path": "packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx",
        "source_digest": "6822166cebbeb17f3bca15e430716a465992596ef4932111d4d7281dd5c4cc94",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--expanded&viewMode=story"
      },
      {
        "id": "cloaked-design-system-controls-dropdown--sizes",
        "name": "Sizes",
        "title": "Cloaked Design System/Controls/Dropdown",
        "exportName": "Sizes",
        "source_path": "packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx",
        "source_digest": "6822166cebbeb17f3bca15e430716a465992596ef4932111d4d7281dd5c4cc94",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--sizes&viewMode=story"
      },
      {
        "id": "cloaked-design-system-controls-dropdown--with-bottom-sheet",
        "name": "With Bottom Sheet",
        "title": "Cloaked Design System/Controls/Dropdown",
        "exportName": "WithBottomSheet",
        "source_path": "packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx",
        "source_digest": "6822166cebbeb17f3bca15e430716a465992596ef4932111d4d7281dd5c4cc94",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--with-bottom-sheet&viewMode=story"
      },
      {
        "id": "cloaked-design-system-controls-dropdown--dark-theme",
        "name": "Dark Theme",
        "title": "Cloaked Design System/Controls/Dropdown",
        "exportName": "DarkTheme",
        "source_path": "packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx",
        "source_digest": "6822166cebbeb17f3bca15e430716a465992596ef4932111d4d7281dd5c4cc94",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-controls-dropdown--dark-theme&viewMode=story"
      }
    ],
    "name": "Dropdown",
    "id": "dropdown",
    "category": "Controls"
  },
  "stories_source": {
    "path": "packages/design-system/src/components/controls/Dropdown/Dropdown.stories.tsx",
    "code": "import React, { useState } from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { Menu } from '../Menu/Menu';\nimport { BottomSheet } from '../../overlays/BottomSheet/BottomSheet';\nimport { Icon } from '../../primitives/Icon/Icon';\nimport { disabledControl, hapticArgType, selectArgType } from '../../../storybook/controlOptions';\nimport { Dropdown, type DropdownSize } from './Dropdown';\n\nconst DROPDOWN_SIZES = ['sm', 'md'] as const satisfies readonly DropdownSize[];\n\nconst FILTER_OPTIONS = [\n    { value: 'all', label: 'All activity', leading: <Icon name='search' size='small' /> },\n    { value: 'in-progress', label: 'In progress', leading: <Icon name='clock' size='small' /> },\n    { value: 'completed', label: 'Completed', leading: <Icon name='check' size='small' /> },\n];\n\nconst meta: Meta<typeof Dropdown> = {\n    title: 'Cloaked Design System/Controls/Dropdown',\n    component: Dropdown,\n    parameters: {\n        a11y: { test: 'error' },\n        docs: {\n            description: {\n                component:\n                    'A compact trigger that shows the current value plus a chevron — it opens a picker, it is ' +\n                    'not the picker itself. Pair it with a `Menu` inside a `BottomSheet` (see ' +\n                    'WithBottomSheet): `Dropdown` owns the collapsed affordance and `expanded` state, `Menu` ' +\n                    'owns the option rows. For an always-visible switch across 2–4 options, use ' +\n                    '`SegmentedControl` instead.',\n            },\n        },\n    },\n    args: {\n        label: 'All',\n        size: 'sm',\n        expanded: false,\n        testId: 'controls-dropdown',\n    },\n    argTypes: {\n        label: { control: 'text', description: 'Visible value the trigger currently reflects.' },\n        size: {\n            ...selectArgType(DROPDOWN_SIZES),\n            description: 'Trigger size. `sm` for dense toolbars, `md` for standalone triggers. Defaults to `sm`.',\n        },\n        expanded: {\n            control: 'boolean',\n            description: 'Whether the paired menu is open; rotates the chevron and sets `aria-expanded`.',\n        },\n        onToggle: { ...disabledControl, description: 'Called on press; open the paired `Menu` sheet here.' },\n        haptic: {\n            ...hapticArgType,\n            description: 'Haptic fired on press. Defaults to `true` (`light`).',\n        },\n        ariaLabel: { control: 'text', description: 'Accessible name; falls back to `label` when omitted.' },\n    },\n};\nexport default meta;\ntype Story = StoryObj<typeof Dropdown>;\n\nfunction DropdownSheetDemo() {\n    const [open, setOpen] = useState(false);\n    const [selected, setSelected] = useState(FILTER_OPTIONS[0].value);\n    const selectedLabel = FILTER_OPTIONS.find(option => option.value === selected)?.label ?? FILTER_OPTIONS[0].label;\n\n    return (\n        <>\n            <Dropdown\n                label={selectedLabel}\n                size='sm'\n                expanded={open}\n                onToggle={() => setOpen(true)}\n                testId='activity-filter'\n            />\n            <BottomSheet isOpen={open} onDismiss={() => setOpen(false)} size='small' testId='activity-filter-sheet'>\n                <BottomSheet.Header>\n                    <BottomSheet.Title>Filter activity</BottomSheet.Title>\n                </BottomSheet.Header>\n                <Menu\n                    ariaLabel='Filter activity'\n                    selectionMode='single'\n                    value={selected}\n                    items={FILTER_OPTIONS}\n                    onSelect={value => {\n                        setSelected(value);\n                        setOpen(false);\n                    }}\n                    testId='activity-filter-menu'\n                />\n            </BottomSheet>\n        </>\n    );\n}\n\nexport const Playground: Story = {};\n\nexport const Expanded: Story = {\n    args: { expanded: true },\n    parameters: { docs: { description: { story: 'The open state: chevron rotated, `aria-expanded` true.' } } },\n};\n\nexport const Sizes: Story = {\n    parameters: { docs: { description: { story: 'Both size tiers side by side.' } } },\n    render: () => (\n        <HStack gap={12} align='center'>\n            {DROPDOWN_SIZES.map(size => (\n                <Dropdown key={size} label='All' size={size} testId={`controls-dropdown-${size}`} />\n            ))}\n        </HStack>\n    ),\n};\n\nexport const WithBottomSheet: Story = {\n    parameters: {\n        docs: {\n            description: {\n                story: 'The real pattern: trigger opens a `Menu` in a `BottomSheet` and reflects the pick.',\n            },\n        },\n    },\n    render: () => <DropdownSheetDemo />,\n};\n\nexport const DarkTheme: Story = {\n    args: { expanded: true },\n    globals: { theme: 'dark' },\n    parameters: { docs: { description: { story: 'Expanded trigger on the dark theme surface.' } } },\n};\n"
  },
  "specification": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Dropdown",
      "status": "preview",
      "version": "1.0.0",
      "summary": "A compact disclosure trigger that reflects the current value and expanded state while a parent owns the associated menu or sheet."
    },
    "parts": [
      {
        "id": "trigger",
        "label": "Trigger",
        "description": "Native button that owns size, press, focus, and expanded semantics."
      },
      {
        "id": "label",
        "label": "Value label",
        "description": "Displays the current selection or filter value."
      },
      {
        "id": "chevron",
        "label": "Chevron",
        "description": "Rotates to communicate collapsed and expanded state."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "base": {
          "label": "Base",
          "description": "One compact trigger configured through the independent size axis."
        }
      },
      "sizes": {
        "sm": {
          "label": "Small"
        },
        "md": {
          "label": "Medium"
        }
      }
    },
    "variants": [
      {
        "id": "base",
        "label": "Base",
        "description": "Value label and disclosure chevron; opened content remains parent-owned.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [
      {
        "id": "sm",
        "label": "Small",
        "description": "32-unit trigger for dense toolbars."
      },
      {
        "id": "md",
        "label": "Medium",
        "description": "40-unit trigger for standalone compact selection."
      }
    ],
    "measurements": [
      {
        "id": "small-min-height",
        "label": "Small trigger minimum height",
        "kind": "exact",
        "token": "--cds-size-32",
        "value": 32,
        "unit": "px",
        "appliesTo": [
          "trigger",
          "sm"
        ]
      },
      {
        "id": "medium-min-height",
        "label": "Medium trigger minimum height",
        "kind": "exact",
        "token": "--cds-size-40",
        "value": 40,
        "unit": "px",
        "appliesTo": [
          "trigger",
          "md"
        ]
      },
      {
        "id": "content-gap",
        "label": "Label-to-chevron gap",
        "kind": "exact",
        "token": "--cds-space-4",
        "value": 4,
        "unit": "px",
        "appliesTo": [
          "label",
          "chevron"
        ]
      }
    ],
    "layout": {
      "alignment": "Label and chevron align on the trigger center line and the trigger hugs its content.",
      "flow": "Current value label precedes the disclosure chevron.",
      "notes": [
        "Pair with Menu inside a Modal or another owned disclosure surface.",
        "Use Select when the trigger represents a form-submitted value."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Value label",
          "description": "Use body-small text at both trigger sizes.",
          "token": "--cds-type-body-small-size"
        }
      ],
      "colors": [
        {
          "label": "Trigger surface",
          "description": "Use the semantic page surface.",
          "token": "--cds-bg-page"
        },
        {
          "label": "Label and chevron",
          "description": "Use primary text emphasis.",
          "token": "--cds-text-primary"
        }
      ]
    },
    "states": [
      {
        "id": "collapsed",
        "label": "Collapsed",
        "description": "Shows a downward chevron and expanded false."
      },
      {
        "id": "expanded",
        "label": "Expanded",
        "description": "Rotates the chevron and exposes expanded true."
      },
      {
        "id": "focused",
        "label": "Focused",
        "description": "Retains native button focus indication and keyboard activation."
      }
    ],
    "behavior": [
      {
        "label": "Controlled disclosure",
        "description": "Invoke onToggle after an enabled press while the parent owns expanded state and opened content."
      },
      {
        "label": "Current value",
        "description": "Keep the visible label synchronized with the selection represented by the paired menu."
      },
      {
        "label": "No owned popup",
        "description": "Do not render options or manage dismissal inside Dropdown."
      }
    ],
    "accessibility": [
      {
        "label": "Native button",
        "description": "Expose button semantics, keyboard activation, and expanded state."
      },
      {
        "label": "Accessible name",
        "description": "Use the visible value label unless a clearer stable accessible label is provided."
      },
      {
        "label": "Opened content",
        "description": "The parent must name and manage focus for the associated menu, dialog, or sheet."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Value labels",
        "description": "Use concise labels that communicate the current selection rather than an instruction."
      },
      {
        "label": "Dense placement",
        "description": "Use small in toolbars and medium when the trigger needs a clearer standalone tap target."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Chevron rotation",
          "description": "Rotate one chevron between collapsed and expanded states instead of swapping icons."
        }
      ],
      "haptics": [
        {
          "label": "Disclosure feedback",
          "description": "Request a light haptic after the trigger is pressed."
        }
      ]
    },
    "platformDifferences": [
      {
        "platforms": [
          "web"
        ],
        "description": "Web rotates the chevron with a CSS transform while native implementations animate the equivalent platform icon.",
        "rationale": "A single transforming affordance preserves the same expanded-state cue across rendering systems."
      }
    ]
  },
  "specification_source": "packages/design-system/src/components/controls/Dropdown/Dropdown.spec.json",
  "guidance": {
    "summary": "A compact disclosure trigger that reflects the current value and expanded state while a parent owns the associated menu or sheet.",
    "guidance": [
      {
        "heading": "Overview",
        "body": "A compact trigger that shows the current value plus a chevron. It **opens** a picker — it is not\nthe picker itself. You pair it with a `Menu` inside a `BottomSheet` and drive its `expanded`\nstate."
      },
      {
        "heading": "When to use",
        "body": "Reach for `Dropdown` as the collapsed affordance for a value that lives elsewhere — a toolbar\nfilter, a compact selector where a full form field would be too heavy. `Dropdown` owns the trigger\nand chevron state; the `Menu` you open owns the option rows (see the WithBottomSheet story).\n\n-   Picking a value inside a form that should submit? Use `Select` — it carries form-value semantics and a hidden input.\n-   The floating content is a list of one-off **actions**, not values? Open a `Menu` with `selectionMode=\"none\"`.\n-   An always-visible switch across 2–4 options? Use `SegmentedControl`.\n\nIn-app it drives the activity filter in `ActivityFeed.tsx`, opening a `Menu` sheet."
      }
    ],
    "usage": [],
    "examples": [],
    "source": "packages/design-system/src/components/controls/Dropdown/Dropdown.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-dropdown",
    "json": "/data/visual/components/dropdown.json",
    "storybook": "/storybook/?path=/story/cloaked-design-system-controls-dropdown--playground"
  }
}