{ "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": "floatingactionbutton", "name": "FloatingActionButton", "category": "Primitives", "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-primitives-floatingactionbutton--playground", "name": "Playground", "title": "Cloaked Design System/Primitives/FloatingActionButton", "exportName": "Playground", "source_path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsx", "source_digest": "f2ffe74f6578d1e0efae8575739c009d3f329e685bd525359e33dbc2fd6eb300", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionbutton--playground&viewMode=story" }, { "id": "cloaked-design-system-primitives-floatingactionbutton--loading", "name": "Loading", "title": "Cloaked Design System/Primitives/FloatingActionButton", "exportName": "Loading", "source_path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsx", "source_digest": "f2ffe74f6578d1e0efae8575739c009d3f329e685bd525359e33dbc2fd6eb300", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionbutton--loading&viewMode=story" }, { "id": "cloaked-design-system-primitives-floatingactionbutton--hidden-toggle", "name": "Hidden Toggle", "title": "Cloaked Design System/Primitives/FloatingActionButton", "exportName": "HiddenToggle", "source_path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsx", "source_digest": "f2ffe74f6578d1e0efae8575739c009d3f329e685bd525359e33dbc2fd6eb300", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionbutton--hidden-toggle&viewMode=story" }, { "id": "cloaked-design-system-primitives-floatingactionbutton--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Primitives/FloatingActionButton", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsx", "source_digest": "f2ffe74f6578d1e0efae8575739c009d3f329e685bd525359e33dbc2fd6eb300", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionbutton--dark-theme&viewMode=story" } ], "name": "FloatingActionButton", "id": "floatingactionbutton", "category": "Primitives" }, "stories_source": { "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.stories.tsx", "code": "import React, { useState } from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { disabledControl, hapticArgType } from '../../../storybook/controlOptions';\nimport { Button } from '../Button/Button';\nimport { Icon } from '../Icon/Icon';\nimport { Text } from '../Text/Text';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { FloatingActionButton } from './FloatingActionButton';\n\n// A transformed phone-frame stand-in: the transform makes it the containing\n// block for the FAB's `position: fixed`, exactly like a Stackflow activity —\n// so the story demonstrates real in-screen anchoring instead of escaping the\n// docs canvas.\nconst PHONE_FRAME: React.CSSProperties = {\n position: 'relative',\n width: 320,\n height: 420,\n overflow: 'hidden',\n transform: 'translateZ(0)',\n border: 'var(--cds-border-width-default) dashed var(--cds-divider)',\n borderRadius: 'var(--cds-radius-lg)',\n background: 'var(--cds-bg-page)',\n padding: 'var(--cds-space-16)',\n};\n\nconst meta: Meta = {\n parameters: { a11y: { test: 'error' } },\n title: 'Cloaked Design System/Primitives/FloatingActionButton',\n component: FloatingActionButton,\n args: {\n icon: ,\n ariaLabel: 'Create',\n },\n argTypes: {\n icon: { ...disabledControl, description: 'Glyph in the circle, usually an `Icon`.' },\n ariaLabel: { description: 'Required accessible name — the FAB never renders visible text.' },\n onPress: { ...disabledControl, description: 'Press handler; a FAB with no handler renders inert.' },\n loading: { description: 'Swaps the icon for a Spinner and prevents interaction.' },\n hidden: { description: 'Animates the FAB out (scale + fade) and unmounts it.' },\n haptic: {\n ...hapticArgType,\n description: 'Haptic fired on a successful press. Defaults to `true` (a light tap).',\n },\n className: {\n ...disabledControl,\n description: 'Override hook — e.g. lift `bottom` above a tab bar on tabbed surfaces.',\n },\n testId: { ...disabledControl, description: 'Kebab-case selector hook for tests and engine-mcp targeting.' },\n },\n decorators: [\n Story => (\n
\n \n Screen content\n \n \n
\n ),\n ],\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Playground: Story = {\n args: { testId: 'fab-playground' },\n};\n\nexport const Loading: Story = {\n parameters: {\n docs: {\n description: {\n story: '`loading` swaps the glyph for a Spinner and blocks presses, preserving the circle geometry.',\n },\n },\n },\n args: { loading: true, testId: 'fab-loading' },\n};\n\nexport const HiddenToggle: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'Flipping `hidden` scales and fades the FAB out, then unmounts it — use while a sheet is open ' +\n 'or a flow ends. Toggling back animates it in.',\n },\n },\n },\n render: () => ,\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n parameters: {\n docs: {\n description: {\n story: 'On dark surfaces the glass fill lightens the backdrop instead of whitening it.',\n },\n },\n },\n args: { testId: 'fab-dark' },\n};\n\nfunction HiddenToggleDemo() {\n const [hidden, setHidden] = useState(false);\n\n return (\n \n \n }\n ariaLabel='Create'\n hidden={hidden}\n onPress={() => undefined}\n testId='fab-hidden-toggle'\n />\n \n );\n}\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "FloatingActionButton", "status": "preview", "version": "1.0.1", "summary": "A circular frosted-glass action button that floats over screen content in the bottom-right corner." }, "parts": [ { "id": "container", "label": "Container", "description": "The fixed-position glass circle that owns the tap target, elevation, and anchoring." }, { "id": "icon", "label": "Icon", "description": "The sole visible content; every FloatingActionButton is icon-only." }, { "id": "loading-indicator", "label": "Loading indicator", "description": "Replaces the icon while preserving the circle geometry during loading." } ], "allowedDesignChoices": { "variants": { "default": { "label": "Default", "description": "Single glass treatment; there is no variant axis." } }, "sizes": { "default": { "label": "Default", "description": "Single fixed 48px diameter; there is no size axis." } } }, "variants": [ { "id": "default", "label": "Default", "description": "Frosted-glass circle with the theme text color for the glyph.", "platforms": [ "ios", "web" ] } ], "sizes": [ { "id": "default", "label": "Default", "description": "Fixed 48px circle matching the iOS component." } ], "measurements": [ { "id": "diameter", "label": "Diameter", "kind": "exact", "token": "--cds-size-48", "value": 48, "unit": "px", "appliesTo": [ "container" ] }, { "id": "corner-radius", "label": "Corner radius", "kind": "exact", "token": "--cds-radius-full", "value": "full", "unit": "none", "appliesTo": [ "container" ] }, { "id": "edge-inset", "label": "Edge inset", "kind": "exact", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "container" ], "notes": "Right and bottom inset; the bottom additionally clears env(safe-area-inset-bottom)." }, { "id": "backdrop-blur", "label": "Backdrop blur", "kind": "exact", "token": "--cds-blur-subtle", "value": 16, "unit": "px", "appliesTo": [ "container" ] } ], "layout": { "alignment": "The icon or Spinner is centered in both axes of the circle.", "flow": "Self-anchors with position: fixed to the bottom-right of its containing block.", "notes": [ "Deliberately not portaled: a transformed screen container (e.g. a Stackflow activity) becomes the containing block, so the button rides screen push/pop transitions like the iOS safeAreaInset placement.", "The default inset clears the device safe area only; screens that sit above a tab bar lift the bottom inset via className." ] }, "typographyAndColor": { "typography": [], "colors": [ { "label": "Container", "description": "Translucent frosted-glass fill paired with the backdrop blur.", "token": "--cds-fab-container" }, { "label": "Icon", "description": "Theme text color, matching the iOS glass treatment.", "token": "--cds-text-primary" } ] }, "states": [ { "id": "active", "label": "Active", "description": "Available for press; presses scale the circle to 0.97." }, { "id": "loading", "label": "Loading", "description": "Blocks presses, hides the icon, and centers a Spinner without changing geometry." }, { "id": "hidden", "label": "Hidden", "description": "Scales and fades out, then unmounts; re-showing animates back in." } ], "behavior": [ { "label": "Press", "description": "Calls onPress once for a non-loading button." }, { "label": "Loading", "description": "Treats loading as disabled and exposes the busy state to assistive technology." }, { "label": "Hide and show", "description": "The hidden prop drives a scale-and-fade transition before unmount; reduced-motion preferences collapse it to an instant swap." } ], "accessibility": [ { "label": "Accessible name", "description": "ariaLabel is required; the button never renders visible text." }, { "label": "Native semantics", "description": "Renders a native button element and forwards disabled and aria-busy state." } ], "contentAdaptation": [ { "label": "Icon only", "description": "Accepts a single glyph; use a verb-like icon (add, compose) that names the screen's primary creation action." } ], "motionHaptics": { "motion": [ { "label": "Press feedback", "description": "Scales to 0.97 over the fast duration, mirroring the iOS press treatment." }, { "label": "Hide and show", "description": "Scale-and-fade over the base duration with the standard enter and exit curves, gated by prefers-reduced-motion." } ], "haptics": [ { "label": "Default feedback", "description": "Uses a light haptic for successful presses when a native bridge is available." } ] }, "platformDifferences": [ { "platforms": [ "web" ], "description": "The glass chrome is a backdrop-filter approximation; iOS 26 uses the native interactive glassEffect and earlier iOS falls back to a solid inverted circle.", "rationale": "WKWebView content has no liquid-glass API, so the web treatment chases the iOS 26 look with a translucent fill and blur." }, { "platforms": [ "web" ], "description": "The menu-opening flavor is the sibling FloatingActionMenuButton component, mirroring the iOS split.", "rationale": "Menu triggers carry a different interaction and accessibility contract than action buttons, so the flavor is a separate component rather than a prop." } ] }, "specification_source": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.spec.json", "guidance": { "summary": "A circular frosted-glass action button that floats over screen content in the bottom-right corner.", "guidance": [ { "heading": "Overview", "body": "A frosted-glass circle that floats over screen content in the bottom-right corner,\nholding the screen's single primary creation action. The web counterpart of the iOS\n`FloatingActionButton` (glass on iOS 26; this component approximates that look with a\ntranslucent fill and backdrop blur)." }, { "heading": "Anchoring", "body": "The button anchors itself: `position: fixed`, inset `--cds-space-16` from the right and\nbottom edges plus `env(safe-area-inset-bottom)`. It is deliberately **not** portaled —\ninside a transformed screen container (a Stackflow activity) the transform becomes its\ncontaining block, so it rides push/pop transitions with the screen, exactly like the iOS\n`safeAreaInset` placement. On screens that sit above a tab bar, lift `bottom` with the\n`className` hook." }, { "heading": "States", "body": "`loading` swaps the glyph for a Spinner and blocks presses. `hidden` scales and fades the\nbutton out, then unmounts it — use it while a sheet covers the screen or the action is\ntemporarily unavailable." } ], "usage": [ { "variant": "FloatingActionButton", "use": "The one always-available creation action on a scrolling screen — compose, add, new item.", "avoid": "Footer CTAs of a linear flow (use a full-width primary Button); more than one per screen; actions that need a visible label." } ], "examples": [], "source": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.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-floatingactionbutton", "json": "/data/visual/components/floatingactionbutton.json", "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-floatingactionbutton--playground" } }