{ "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": "button", "name": "Button", "category": "Primitives", "contract_status": "preview", "contract_kind": "curated", "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "preview", "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-primitives-button--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/Button", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "source_digest": "4c471332d6da310075e36b2c3ff9b1b4f17c74cc60a3bc9079400f9db51c98cc", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-button--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-button--icon-only", "name": "Icon Only", "title": "Cloaked Design System/Primitives/Button", "exportName": "IconOnly", "source_path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "source_digest": "4c471332d6da310075e36b2c3ff9b1b4f17c74cc60a3bc9079400f9db51c98cc", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-button--icon-only&viewMode=story" }, { "id": "cloaked-design-system-primitives-button--with-slots", "name": "With Slots", "title": "Cloaked Design System/Primitives/Button", "exportName": "WithSlots", "source_path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "source_digest": "4c471332d6da310075e36b2c3ff9b1b4f17c74cc60a3bc9079400f9db51c98cc", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-button--with-slots&viewMode=story" }, { "id": "cloaked-design-system-primitives-button--danger", "name": "Danger", "title": "Cloaked Design System/Primitives/Button", "exportName": "Danger", "source_path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "source_digest": "4c471332d6da310075e36b2c3ff9b1b4f17c74cc60a3bc9079400f9db51c98cc", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-button--danger&viewMode=story" }, { "id": "cloaked-design-system-primitives-button--full-width", "name": "Full Width", "title": "Cloaked Design System/Primitives/Button", "exportName": "FullWidth", "source_path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "source_digest": "4c471332d6da310075e36b2c3ff9b1b4f17c74cc60a3bc9079400f9db51c98cc", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-button--full-width&viewMode=story" }, { "id": "cloaked-design-system-primitives-button--one-primary", "name": "One Primary", "title": "Cloaked Design System/Primitives/Button", "exportName": "OnePrimary", "source_path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "source_digest": "4c471332d6da310075e36b2c3ff9b1b4f17c74cc60a3bc9079400f9db51c98cc", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-button--one-primary&viewMode=story" }, { "id": "cloaked-design-system-primitives-button--two-primaries", "name": "Two Primaries", "title": "Cloaked Design System/Primitives/Button", "exportName": "TwoPrimaries", "source_path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "source_digest": "4c471332d6da310075e36b2c3ff9b1b4f17c74cc60a3bc9079400f9db51c98cc", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-button--two-primaries&viewMode=story" }, { "id": "cloaked-design-system-primitives-button--state-matrix", "name": "State Matrix", "title": "Cloaked Design System/Primitives/Button", "exportName": "StateMatrix", "source_path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "source_digest": "4c471332d6da310075e36b2c3ff9b1b4f17c74cc60a3bc9079400f9db51c98cc", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-button--state-matrix&viewMode=story" }, { "id": "cloaked-design-system-primitives-button--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Primitives/Button", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "source_digest": "4c471332d6da310075e36b2c3ff9b1b4f17c74cc60a3bc9079400f9db51c98cc", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-button--dark-theme&viewMode=story" } ], "name": "Button", "id": "button", "category": "Primitives" }, "stories_source": { "path": "packages/design-system/src/components/primitives/Button/Button.stories.tsx", "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { HStack } from '../../layout/HStack/HStack';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { disabledControl, hapticArgType, selectArgType } from '../../../storybook/controlOptions';\nimport { Text } from '../Text/Text';\nimport { Icon } from '../Icon/Icon';\nimport { Button, type ButtonSize, type ButtonTone, type ButtonVariant } from './Button';\n\nconst BUTTON_VARIANTS = ['primary', 'secondary', 'tertiary', 'link'] as const satisfies readonly ButtonVariant[];\nconst BUTTON_TONES = ['default', 'danger'] as const satisfies readonly ButtonTone[];\nconst BUTTON_SIZES = ['sm', 'md'] as const satisfies readonly ButtonSize[];\nconst SIZE_LABELS: Record = { sm: 'Small', md: 'Medium' };\n\ninterface ButtonState {\n key: string;\n label: string;\n props: { disabled?: boolean; loading?: boolean };\n}\nconst BUTTON_STATES: ButtonState[] = [\n { key: 'default', label: 'Default', props: {} },\n { key: 'disabled', label: 'Disabled', props: { disabled: true } },\n { key: 'loading', label: 'Loading', props: { loading: true } },\n];\n\n// A bounded stand-in for a phone footer so `fullWidth` has real width to stretch into\n// (the centered story canvas would otherwise shrink-wrap the button to its label).\nconst FOOTER_CONTAINER: React.CSSProperties = {\n width: 320,\n padding: 'var(--cds-space-16)',\n border: 'var(--cds-border-width-default) dashed var(--cds-divider)',\n borderRadius: 'var(--cds-radius-lg)',\n};\n\nconst meta: Meta = {\n parameters: { a11y: { test: 'error' } },\n title: 'Cloaked Design System/Primitives/Button',\n component: Button,\n args: {\n variant: 'primary',\n tone: 'default',\n size: 'md',\n children: 'Continue',\n },\n argTypes: {\n variant: {\n ...selectArgType(BUTTON_VARIANTS),\n description:\n 'Action hierarchy: `primary` (one per view) · `secondary` · `tertiary` (borderless full-size text) · `link` (inline).',\n },\n tone: {\n ...selectArgType(BUTTON_TONES),\n description: 'Semantic action tone, independent of hierarchy. Use `danger` for destructive actions.',\n },\n size: {\n ...selectArgType(BUTTON_SIZES),\n description: 'Height/padding tier — `md` for standalone CTAs, `sm` for dense rows and inline groups.',\n },\n icon: {\n ...disabledControl,\n description: 'Glyph for an icon-only button; requires `ariaLabel` and excludes text/slots.',\n },\n leading: { ...disabledControl, description: 'Visual before the label (usually an `Icon`); text buttons only.' },\n trailing: { ...disabledControl, description: 'Visual after the label (usually an `Icon`); text buttons only.' },\n onPress: { ...disabledControl, description: 'Press handler; a button with no handler renders inert.' },\n haptic: {\n ...hapticArgType,\n description: 'Haptic fired on a successful press. Defaults to `true` (a light tap).',\n },\n testId: { ...disabledControl, description: 'Kebab-case selector hook for tests and engine-mcp targeting.' },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {};\n\nexport const IconOnly: Story = {\n parameters: {\n docs: {\n description: {\n story:\n '`icon` + required `ariaLabel` and no children — a compact glyph-only tap target. Icon-only ' +\n '`secondary` renders as a soft-filled circle (the DS 4.5 close/dismiss affordance).',\n },\n },\n },\n args: { variant: 'primary', icon: , ariaLabel: 'Next' },\n};\n\nexport const WithSlots: Story = {\n parameters: {\n docs: {\n description: {\n story: '`leading`/`trailing` slots frame the label — use for affordance cues, not icon-only.',\n },\n },\n },\n args: {\n variant: 'secondary',\n leading: ,\n trailing: ,\n children: 'Review item',\n },\n};\n\nexport const Danger: Story = {\n parameters: {\n docs: {\n description: {\n story: '`tone=\"danger\"` communicates a destructive action without changing its hierarchy.',\n },\n },\n },\n args: {\n tone: 'danger',\n children: 'Delete identity',\n testId: 'button-danger',\n },\n};\n\nexport const FullWidth: Story = {\n parameters: {\n docs: {\n description: {\n story: '`fullWidth` stretches the button to fill its container — the standard footer CTA. Shown in a phone-width footer.',\n },\n },\n },\n render: () => (\n
\n \n
\n ),\n};\n\nexport const OnePrimary: Story = {\n parameters: {\n docs: {\n description: { story: 'One `primary` sets the priority; supporting actions step down to `secondary`.' },\n },\n },\n render: () => (\n \n \n \n \n ),\n};\n\nexport const TwoPrimaries: Story = {\n parameters: {\n docs: {\n description: {\n story: 'Two saturated `primary` buttons compete — neither reads as the priority.',\n },\n },\n },\n render: () => (\n \n \n \n \n ),\n};\n\nexport const StateMatrix: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'Every `variant` × `size` × state, for both text and icon-only buttons. Rows are variants; ' +\n 'columns are default / disabled / loading.',\n },\n },\n },\n render: () => (\n \n \n \n \n ),\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n parameters: {\n docs: { description: { story: 'Every `variant` on the dark surface, text and icon-only.' } },\n },\n render: () => (\n \n \n {BUTTON_VARIANTS.map(variant => (\n undefined}\n testId={`button-dark-${variant}`}\n >\n {variant}\n \n ))}\n \n \n {BUTTON_VARIANTS.map(variant => (\n }\n ariaLabel={`${variant} icon`}\n onPress={() => undefined}\n testId={`button-dark-icon-${variant}`}\n />\n ))}\n \n \n ),\n};\n\nfunction MatrixSection({ kind }: { kind: 'text' | 'icon' }) {\n return (\n \n {kind === 'text' ? 'Text buttons' : 'Icon buttons'}\n {BUTTON_SIZES.map(size => (\n \n \n {SIZE_LABELS[size]}\n \n {BUTTON_VARIANTS.map(variant => (\n \n \n {variant}\n \n {BUTTON_STATES.map(state => (\n \n ))}\n \n ))}\n \n ))}\n \n );\n}\n\nfunction MatrixButton({\n kind,\n variant,\n size,\n state,\n}: {\n kind: 'text' | 'icon';\n variant: ButtonVariant;\n size: ButtonSize;\n state: ButtonState;\n}) {\n const testId = `button-${kind}-${variant}-${size}-${state.key}`;\n\n if (kind === 'icon') {\n return (\n }\n ariaLabel={`${variant} ${size} ${state.label}`}\n onPress={() => undefined}\n testId={testId}\n {...state.props}\n />\n );\n }\n\n return (\n \n );\n}\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "Button", "status": "preview", "version": "1.0.0", "summary": "A pressable action primitive with text, optional leading or trailing content, or an icon-only presentation." }, "parts": [ { "id": "container", "label": "Container", "description": "Owns the tap target, action hierarchy treatment, size, and state." }, { "id": "label", "label": "Label", "description": "Names the action for text buttons." }, { "id": "leading", "label": "Leading visual", "description": "Optional visual placed before a text label." }, { "id": "trailing", "label": "Trailing visual", "description": "Optional visual placed after a text label." }, { "id": "icon", "label": "Icon", "description": "The sole visible part of an icon-only button." }, { "id": "loading-indicator", "label": "Loading indicator", "description": "Replaces visible content while preserving the button geometry during loading." } ], "allowedDesignChoices": { "variants": { "primary": { "label": "Primary" }, "secondary": { "label": "Secondary" }, "tertiary": { "label": "Tertiary", "description": "A deliberate web-only extension." }, "link": { "label": "Link" } }, "sizes": { "sm": { "label": "Small" }, "md": { "label": "Medium" } } }, "variants": [ { "id": "primary", "label": "Primary", "description": "Filled treatment for the highest-priority action in a group.", "platforms": [ "ios", "android", "web" ] }, { "id": "secondary", "label": "Secondary", "description": "Outlined text treatment; icon-only secondary buttons use the filled secondary container.", "platforms": [ "ios", "android", "web" ] }, { "id": "tertiary", "label": "Tertiary", "description": "Chrome-free text treatment that retains the full text-button tap target.", "platforms": [ "web" ] }, { "id": "link", "label": "Link", "description": "Inline, lowest-emphasis action without button padding.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [ { "id": "sm", "label": "Small", "description": "Compact text or icon action for dense layouts." }, { "id": "md", "label": "Medium", "description": "Default standalone text or icon action." } ], "measurements": [ { "id": "text-md-height", "label": "Medium text button height", "kind": "exact", "token": "--cds-size-56", "value": 56, "unit": "px", "appliesTo": [ "text", "md" ] }, { "id": "text-md-horizontal-padding", "label": "Medium text button horizontal padding", "kind": "exact", "token": "--cds-space-32", "value": 32, "unit": "px", "appliesTo": [ "text", "md" ] }, { "id": "text-md-vertical-spacing", "label": "Medium text button vertical spacing", "kind": "automatic", "appliesTo": [ "text", "md" ], "notes": "The exact 56px height centers the label and owns the vertical inset." }, { "id": "text-sm-vertical-padding", "label": "Small text button vertical padding", "kind": "exact", "token": "--cds-space-8", "value": 8, "unit": "px", "appliesTo": [ "text", "sm" ] }, { "id": "text-sm-horizontal-padding", "label": "Small text button horizontal padding", "kind": "exact", "token": "--cds-space-20", "value": 20, "unit": "px", "appliesTo": [ "text", "sm" ] }, { "id": "content-gap", "label": "Content gap", "kind": "exact", "token": "--cds-space-4", "value": 4, "unit": "px", "appliesTo": [ "text", "leading", "trailing" ], "notes": "Reconciles the design gap of 4px with the prior web implementation gap of 8px." }, { "id": "icon-md-size", "label": "Medium icon-only button size", "kind": "exact", "token": "--cds-size-40", "value": 40, "unit": "px", "appliesTo": [ "icon", "md" ] }, { "id": "icon-sm-size", "label": "Small icon-only button size", "kind": "exact", "token": "--cds-size-24", "value": 24, "unit": "px", "appliesTo": [ "icon", "sm" ] }, { "id": "large-pill-radius", "label": "Large primary and secondary radius", "kind": "exact", "token": "--cds-radius-full", "value": "full", "unit": "none", "appliesTo": [ "text", "md", "primary", "secondary" ] } ], "layout": { "alignment": "Label, slots, icon, and loading indicator are centered in both axes.", "flow": "Text buttons lay out leading visual, label, and trailing visual in one row; icon-only buttons render one icon.", "notes": [ "Full-width text buttons stretch to their parent while preserving centered content.", "Icon-only secondary buttons use the filled secondary container rather than the text-button outline." ] }, "typographyAndColor": { "typography": [ { "label": "Medium text", "description": "Uses the 16px body style.", "token": "--cds-type-body-size" }, { "label": "Small text", "description": "Uses the 14px body-small style.", "token": "--cds-type-body-small-size" }, { "label": "Link text", "description": "Uses the compact link style.", "token": "--cds-type-link-size" } ], "colors": [ { "label": "Primary container", "description": "Theme-aware primary action fill.", "token": "--cds-button-primary-container" }, { "label": "Primary text", "description": "Theme-aware foreground on the primary fill.", "token": "--cds-button-primary-text" }, { "label": "Secondary container", "description": "Theme-aware fill for icon-only secondary buttons.", "token": "--cds-button-secondary-container" }, { "label": "Secondary text", "description": "Theme-aware foreground for secondary and tertiary text.", "token": "--cds-button-secondary-text" } ] }, "states": [ { "id": "active", "label": "Active", "description": "Available for press and uses the selected variant treatment." }, { "id": "disabled", "label": "Disabled", "description": "Blocks presses and applies --cds-opacity-disabled." }, { "id": "loading", "label": "Loading", "description": "Blocks presses, hides the visible content, and centers a Spinner without changing geometry." } ], "behavior": [ { "label": "Press", "description": "Calls onPress once for an enabled, non-loading button." }, { "label": "Loading", "description": "Treats loading as disabled and exposes the busy state to assistive technology." }, { "label": "Haptic", "description": "Requests the light semantic haptic after a successful press unless haptics are disabled." } ], "accessibility": [ { "label": "Icon-only label", "description": "Every icon-only button requires an accessible ariaLabel that names the action." }, { "label": "Native semantics", "description": "Renders a native button element and forwards disabled and aria-busy state." }, { "label": "Loading name", "description": "Keeps the original visible label in the accessibility tree while the Spinner is shown." } ], "contentAdaptation": [ { "label": "Action labels", "description": "Use short verb-led labels; full-width layouts absorb longer localized text." }, { "label": "Slots", "description": "Use leading and trailing visuals only when they clarify the action; icon-only buttons do not accept text slots." } ], "motionHaptics": { "motion": [ { "label": "Press feedback", "description": "Uses the shared button press treatment and respects reduced-motion preferences." } ], "haptics": [ { "label": "Default feedback", "description": "Uses a light haptic for successful presses when a native bridge is available." } ] }, "platformDifferences": [ { "platforms": [ "web" ], "description": "The tertiary variant is web-only; it is not part of the shared cross-platform component set.", "rationale": "Commit e85ed8f16 added the intentional chrome-free app treatment, so the difference remains documented instead of being removed during design reconciliation." } ] }, "specification_source": "packages/design-system/src/components/primitives/Button/Button.spec.json", "guidance": { "summary": "Make the next action clear with one primary button and quieter supporting actions.", "when_to_use": [ "Initiate an action that changes the current state.", "Show one primary action per view.", "Use danger tone when the action is destructive." ], "avoid": [ "Using a button to navigate to another URL; use a link.", "Treating the link variant as an anchor.", "Disabling an action without explaining what is needed." ], "accessibility": [ "Use a descriptive visible label, or ariaLabel for icon-only buttons.", "Loading preserves the label, sets aria-busy, and blocks duplicate presses.", "Keyboard focus is visible in both themes." ], "constraints": [ "Text buttons use children and optional leading/trailing content.", "Icon-only buttons require icon and ariaLabel and cannot have children or leading/trailing.", "Always renders type=button. A form must explicitly request submission." ] }, "links": { "human": "/component-button", "json": "/data/visual/components/button.json", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-button--playground" } }