{
  "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",
  "summary": "A circular frosted-glass action button that floats over screen content in the bottom-right corner.",
  "documentation": {
    "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."
  },
  "source": {
    "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
    "code": "import React, { useEffect, useState } from 'react';\nimport { cn } from '../../../utilities';\nimport { useHaptic } from '../../../hooks/useHaptic';\nimport type { HapticFeedback } from '../../../tokens/CdsHaptic';\nimport { Spinner } from '../../status/Spinner/Spinner';\nimport styles from './FloatingActionButton.module.scss';\n\n/**\n * Props for the floating action button. There is no `disabled` — `loading` is the only state that\n * blocks a press.\n */\nexport interface FloatingActionButtonProps {\n    /** Glyph rendered in the circle, usually an `Icon`. */\n    icon: React.ReactNode;\n    /** Accessible name for the action. */\n    ariaLabel: string;\n    /** Fires on tap. Omitted, the button renders inert without looking disabled. */\n    onPress?: () => void;\n    /** Swaps the icon for a Spinner and prevents interaction. */\n    loading?: boolean;\n    /** Animates the button out and unmounts it, e.g. while a sheet is open. */\n    hidden?: boolean;\n    /** Haptic feedback for successful presses. Defaults to `true` (`light`). */\n    haptic?: HapticFeedback;\n    /** Class hook for composite styling, e.g. lifting `bottom` above a tab bar. */\n    className?: string;\n    style?: React.CSSProperties;\n    /** Selector on the `<button>`. Gone from the DOM once a `hidden` exit finishes, not just invisible. */\n    testId?: string;\n}\n\ntype Visibility = 'visible' | 'entering' | 'exiting' | 'hidden';\n\n/**\n * Web counterpart of the iOS `FloatingActionButton`: a frosted-glass circle\n * fixed to the screen's bottom-right. Intentionally NOT portaled — a transformed\n * Stackflow activity becomes its containing block, so it rides push/pop screen\n * transitions like the native `safeAreaInset` version. The default inset clears\n * the safe area only; screens above a tab bar lift `bottom` via `className`.\n */\nexport function FloatingActionButton({\n    icon,\n    ariaLabel,\n    onPress,\n    loading,\n    hidden,\n    haptic = true,\n    className,\n    style,\n    testId,\n}: FloatingActionButtonProps) {\n    const [visibility, setVisibility] = useState<Visibility>(hidden ? 'hidden' : 'visible');\n    const fireHaptic = useHaptic('light');\n\n    useEffect(() => {\n        setVisibility(prev => {\n            if (hidden) return prev === 'hidden' ? prev : 'exiting';\n            // 'exiting' must restart as 'entering', or the pending exit\n            // animation would unmount a FAB whose latest prop says visible.\n            return prev === 'hidden' || prev === 'exiting' ? 'entering' : prev;\n        });\n    }, [hidden]);\n\n    if (visibility === 'hidden') {\n        return null;\n    }\n\n    const handlePress = () => {\n        fireHaptic(haptic);\n        onPress?.();\n    };\n\n    const handleAnimationEnd = (event: React.AnimationEvent<HTMLButtonElement>) => {\n        // Child animations (e.g. the Spinner) bubble; only settle on our own.\n        if (event.target !== event.currentTarget) return;\n        setVisibility(prev => {\n            if (prev === 'exiting') return 'hidden';\n            if (prev === 'entering') return 'visible';\n            return prev;\n        });\n    };\n\n    return (\n        <button\n            type='button'\n            className={cn(\n                styles.fab,\n                visibility === 'entering' && styles.entering,\n                visibility === 'exiting' && styles.exiting,\n                loading && styles.loading,\n                className\n            )}\n            style={style}\n            onClick={loading || !onPress ? undefined : handlePress}\n            onAnimationEnd={handleAnimationEnd}\n            disabled={loading}\n            aria-label={ariaLabel}\n            aria-busy={loading || undefined}\n            data-testid={testId}\n        >\n            <span className={cn(styles.content, loading && styles.contentHidden)}>{icon}</span>\n            {loading && (\n                <span className={styles.loadingIndicator}>\n                    <Spinner size='md' tone='primary' />\n                </span>\n            )}\n        </button>\n    );\n}\n"
  },
  "spec": {
    "$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."
      }
    ]
  },
  "spec_source": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.spec.json",
  "guidance_source": {
    "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.mdx",
    "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec, UsageTable } from '../../../../.storybook/blocks';\nimport * as FloatingActionButtonStories from './FloatingActionButton.stories';\nimport floatingActionButtonSpec from './FloatingActionButton.spec.json';\n\n<Meta of={FloatingActionButtonStories} />\n\n# FloatingActionButton\n\nA 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).\n\n<Canvas of={FloatingActionButtonStories.Playground} />\n\n## Use when\n\n<UsageTable\n    rows={[\n        {\n            variant: 'FloatingActionButton',\n            use: 'The one always-available creation action on a scrolling screen — compose, add, new item.',\n            avoid: 'Footer CTAs of a linear flow (use a full-width primary Button); more than one per screen; actions that need a visible label.',\n        },\n    ]}\n/>\n\n## Anchoring\n\nThe 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.\n\n## States\n\n`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.\n\n<Canvas of={FloatingActionButtonStories.Loading} />\n<Canvas of={FloatingActionButtonStories.HiddenToggle} />\n\n## Dark theme\n\n<Canvas of={FloatingActionButtonStories.DarkTheme} />\n\n## Design Guidelines\n\n<ComponentSpec spec={floatingActionButtonSpec} />\n\n## Props\n\n<Controls of={FloatingActionButtonStories.Playground} />\n"
  },
  "props": [
    {
      "name": "icon",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": true,
      "description": "Glyph rendered in the circle, usually an `Icon`.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 14
      }
    },
    {
      "name": "ariaLabel",
      "type": "string",
      "declared_type": "string",
      "required": true,
      "description": "Accessible name for the action.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 16
      }
    },
    {
      "name": "onPress",
      "type": "(() => void) | undefined",
      "declared_type": "() => void",
      "required": false,
      "description": "Fires on tap. Omitted, the button renders inert without looking disabled.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 18
      }
    },
    {
      "name": "loading",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Swaps the icon for a Spinner and prevents interaction.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 20
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "hidden",
      "type": "boolean | undefined",
      "declared_type": "boolean",
      "required": false,
      "description": "Animates the button out and unmounts it, e.g. while a sheet is open.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 22
      },
      "values": [
        false,
        true
      ],
      "values_complete": true
    },
    {
      "name": "haptic",
      "type": "HapticFeedback | undefined",
      "declared_type": "HapticFeedback",
      "required": false,
      "description": "Haptic feedback for successful presses. Defaults to `true` (`light`).",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 24
      },
      "values": [
        "error",
        "heavy",
        "light",
        "medium",
        "selection",
        "success",
        "warning",
        false,
        true
      ],
      "values_complete": true,
      "default": "true",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Class hook for composite styling, e.g. lifting `bottom` above a tab bar.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 26
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 27
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Selector on the `<button>`. Gone from the DOM once a `hidden` exit finishes, not just invisible.",
      "source": {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 29
      }
    }
  ],
  "prop_shapes": {},
  "examples": [],
  "tokens": [
    {
      "name": "--cds-size-48",
      "light": "48px",
      "dark": "48px"
    },
    {
      "name": "--cds-radius-full",
      "light": "9999px",
      "dark": "9999px"
    },
    {
      "name": "--cds-space-16",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-blur-subtle",
      "light": "16px",
      "dark": "16px"
    },
    {
      "name": "--cds-fab-container",
      "light": "#ffffff99",
      "dark": "#ffffff1a"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    }
  ],
  "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": [
    {
      "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"
    }
  ],
  "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<typeof FloatingActionButton> = {\n    parameters: { a11y: { test: 'error' } },\n    title: 'Cloaked Design System/Primitives/FloatingActionButton',\n    component: FloatingActionButton,\n    args: {\n        icon: <Icon name='add' size='medium' />,\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            <div style={PHONE_FRAME}>\n                <Text variant='body-small' color='secondary'>\n                    Screen content\n                </Text>\n                <Story />\n            </div>\n        ),\n    ],\n};\nexport default meta;\ntype Story = StoryObj<typeof FloatingActionButton>;\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: () => <HiddenToggleDemo />,\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        <VStack gap={12} align='start'>\n            <Button variant='secondary' size='sm' onPress={() => setHidden(prev => !prev)} testId='fab-toggle-hidden'>\n                {hidden ? 'Show FAB' : 'Hide FAB'}\n            </Button>\n            <FloatingActionButton\n                icon={<Icon name='add' size='medium' />}\n                ariaLabel='Create'\n                hidden={hidden}\n                onPress={() => undefined}\n                testId='fab-hidden-toggle'\n            />\n        </VStack>\n    );\n}\n"
  },
  "links": {
    "human": "/component-floatingactionbutton",
    "json": "/data/components/floatingactionbutton.json",
    "markdown": "/data/components/floatingactionbutton.md",
    "storybook": "/storybook/?path=/story/cloaked-design-system-primitives-floatingactionbutton--playground"
  },
  "contract_status": "preview",
  "contract_kind": "source-derived",
  "approval": "required",
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "FloatingActionButton",
    "public_path": "FloatingActionButton",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "FloatingActionButton",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
          "line": 41
        },
        "props_type": "FloatingActionButtonProps",
        "props": [
          {
            "name": "icon",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": true,
            "description": "Glyph rendered in the circle, usually an `Icon`.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 14
            }
          },
          {
            "name": "ariaLabel",
            "type": "string",
            "declared_type": "string",
            "required": true,
            "description": "Accessible name for the action.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 16
            }
          },
          {
            "name": "onPress",
            "type": "(() => void) | undefined",
            "declared_type": "() => void",
            "required": false,
            "description": "Fires on tap. Omitted, the button renders inert without looking disabled.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 18
            }
          },
          {
            "name": "loading",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Swaps the icon for a Spinner and prevents interaction.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 20
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "hidden",
            "type": "boolean | undefined",
            "declared_type": "boolean",
            "required": false,
            "description": "Animates the button out and unmounts it, e.g. while a sheet is open.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 22
            },
            "values": [
              false,
              true
            ],
            "values_complete": true
          },
          {
            "name": "haptic",
            "type": "HapticFeedback | undefined",
            "declared_type": "HapticFeedback",
            "required": false,
            "description": "Haptic feedback for successful presses. Defaults to `true` (`light`).",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 24
            },
            "values": [
              "error",
              "heavy",
              "light",
              "medium",
              "selection",
              "success",
              "warning",
              false,
              true
            ],
            "values_complete": true,
            "default": "true",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Class hook for composite styling, e.g. lifting `bottom` above a tab bar.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 26
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 27
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Selector on the `<button>`. Gone from the DOM once a `hidden` exit finishes, not just invisible.",
            "source": {
              "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
              "line": 29
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/primitives/FloatingActionButton/FloatingActionButton.tsx",
        "line": 12,
        "name": "FloatingActionButtonProps",
        "code": "export interface FloatingActionButtonProps {\n    /** Glyph rendered in the circle, usually an `Icon`. */\n    icon: React.ReactNode;\n    /** Accessible name for the action. */\n    ariaLabel: string;\n    /** Fires on tap. Omitted, the button renders inert without looking disabled. */\n    onPress?: () => void;\n    /** Swaps the icon for a Spinner and prevents interaction. */\n    loading?: boolean;\n    /** Animates the button out and unmounts it, e.g. while a sheet is open. */\n    hidden?: boolean;\n    /** Haptic feedback for successful presses. Defaults to `true` (`light`). */\n    haptic?: HapticFeedback;\n    /** Class hook for composite styling, e.g. lifting `bottom` above a tab bar. */\n    className?: string;\n    style?: React.CSSProperties;\n    /** Selector on the `<button>`. Gone from the DOM once a `hidden` exit finishes, not just invisible. */\n    testId?: string;\n}"
      },
      {
        "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."
  },
  "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"
    }
  },
  "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."
    }
  ],
  "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."
  }
}