{
  "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": "background",
  "name": "Background",
  "category": "Layout",
  "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-layout-background--playground",
        "name": "Playground",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "Playground",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--playground&viewMode=story"
      },
      {
        "id": "cloaked-design-system-layout-background--centered",
        "name": "Centered",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "Centered",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--centered&viewMode=story"
      },
      {
        "id": "cloaked-design-system-layout-background--top-aligned",
        "name": "Top Aligned",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "TopAligned",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--top-aligned&viewMode=story"
      },
      {
        "id": "cloaked-design-system-layout-background--space-between",
        "name": "Space Between",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "SpaceBetween",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--space-between&viewMode=story"
      },
      {
        "id": "cloaked-design-system-layout-background--with-padding",
        "name": "With Padding",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "WithPadding",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--with-padding&viewMode=story"
      },
      {
        "id": "cloaked-design-system-layout-background--safe-area-top",
        "name": "Safe Area Top",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "SafeAreaTop",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--safe-area-top&viewMode=story"
      },
      {
        "id": "cloaked-design-system-layout-background--safe-area-bottom",
        "name": "Safe Area Bottom",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "SafeAreaBottom",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--safe-area-bottom&viewMode=story"
      },
      {
        "id": "cloaked-design-system-layout-background--safe-area-both",
        "name": "Safe Area Both",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "SafeAreaBoth",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--safe-area-both&viewMode=story"
      },
      {
        "id": "cloaked-design-system-layout-background--not-filled",
        "name": "Not Filled",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "NotFilled",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--not-filled&viewMode=story"
      },
      {
        "id": "cloaked-design-system-layout-background--dark-theme",
        "name": "Dark Theme",
        "title": "Cloaked Design System/Layout/Background",
        "exportName": "DarkTheme",
        "source_path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
        "source_digest": "ecfeafc17b05e71ef1803996af11476f971e62d57e13d63efee48f4ef43e2bd3",
        "status": "preview",
        "local_url": "/storybook/iframe.html?id=cloaked-design-system-layout-background--dark-theme&viewMode=story"
      }
    ],
    "name": "Background",
    "id": "background",
    "category": "Layout"
  },
  "stories_source": {
    "path": "packages/design-system/src/components/layout/Background/Background.stories.tsx",
    "code": "import React from 'react';\nimport type { Meta, StoryObj } from '@storybook/react-vite';\nimport { Background, type BackgroundAlign, type BackgroundJustify } from './Background';\nimport { Card } from '../../cards/Card/Card';\nimport { HStack } from '../HStack/HStack';\nimport { Text } from '../../primitives/Text/Text';\nimport {\n    SAFE_AREA_OPTIONS,\n    SPACE_OPTIONS,\n    SURFACE_OPTIONS,\n    disabledControl,\n    selectArgType,\n} from '../../../storybook/controlOptions';\n\nconst BACKGROUND_ALIGN_OPTIONS = ['start', 'center', 'end', 'stretch'] as const satisfies readonly BackgroundAlign[];\nconst BACKGROUND_JUSTIFY_OPTIONS = [\n    'start',\n    'center',\n    'end',\n    'between',\n] as const satisfies readonly BackgroundJustify[];\n\nconst Panel = ({ title = 'Detail title', body = 'Centered content inside a Background container.' }) => (\n    <Card>\n        <Card.Body gap='sm' align='center'>\n            <Text variant='h3'>{title}</Text>\n            <Text variant='body-small' color='secondary'>\n                {body}\n            </Text>\n        </Card.Body>\n    </Card>\n);\n\nconst meta: Meta<typeof Background> = {\n    title: 'Cloaked Design System/Layout/Background',\n    component: Background,\n    parameters: {\n        a11y: { test: 'error' },\n        layout: 'fullscreen',\n        docs: {\n            description: {\n                component:\n                    'Parent container for detail, modal, and standalone screens: it paints a `page`/`surface` ' +\n                    'background, fills the available height, and centers its content by default. Use it when a ' +\n                    'screen needs a surface plus alignment but not the sticky route chrome of `Screen` — e.g. a ' +\n                    'confirmation, paywall, or empty state. Lay out the content inside with `VStack`/`HStack`/' +\n                    '`Grid`. It is a flex column, so `align` is the horizontal (cross) axis and `justify` the ' +\n                    'vertical (main) axis: `justify=\"between\"` pins content to the top and bottom edges.',\n            },\n        },\n    },\n    args: {\n        children: <Panel />,\n    },\n    argTypes: {\n        children: disabledControl,\n        surface: {\n            ...selectArgType(SURFACE_OPTIONS),\n            description:\n                'Background token painted behind the content. Defaults to `page`; use `surface` for the raised canvas.',\n        },\n        align: {\n            ...selectArgType(BACKGROUND_ALIGN_OPTIONS),\n            description: 'Horizontal (cross-axis) alignment of content. Defaults to `center`.',\n        },\n        justify: {\n            ...selectArgType(BACKGROUND_JUSTIFY_OPTIONS),\n            description: 'Vertical (main-axis) distribution of content. Defaults to `start` (top).',\n        },\n        fill: {\n            description:\n                'Fill the available height (`min-height: 100%`). Defaults to `true`; set `false` to size to content.',\n        },\n        safeArea: {\n            ...selectArgType(SAFE_AREA_OPTIONS),\n            description: 'Which edges add `env(safe-area-inset-*)` on top of padding. Defaults to `none`.',\n        },\n        padding: { ...selectArgType(SPACE_OPTIONS), description: 'Uniform inner padding, in `--cds-space-*` steps.' },\n        paddingX: {\n            ...selectArgType(SPACE_OPTIONS),\n            description: 'Horizontal padding override, in `--cds-space-*` steps.',\n        },\n        paddingY: {\n            ...selectArgType(SPACE_OPTIONS),\n            description: 'Vertical padding override, in `--cds-space-*` steps.',\n        },\n        paddingTop: { ...selectArgType(SPACE_OPTIONS), description: 'Top padding override, in `--cds-space-*` steps.' },\n        paddingRight: {\n            ...selectArgType(SPACE_OPTIONS),\n            description: 'Right padding override, in `--cds-space-*` steps.',\n        },\n        paddingBottom: {\n            ...selectArgType(SPACE_OPTIONS),\n            description: 'Bottom padding override, in `--cds-space-*` steps.',\n        },\n        paddingLeft: {\n            ...selectArgType(SPACE_OPTIONS),\n            description: 'Left padding override, in `--cds-space-*` steps.',\n        },\n    },\n    decorators: [Story => <div style={{ height: '60vh' }}>{Story()}</div>],\n};\nexport default meta;\ntype Story = StoryObj<typeof Background>;\n\nexport const Playground: Story = {};\n\nexport const Centered: Story = {\n    parameters: {\n        docs: {\n            description: { story: 'The default: content centered horizontally and pinned to the top vertically.' },\n        },\n    },\n    args: { children: <Panel />, justify: 'center' },\n};\n\nexport const TopAligned: Story = {\n    parameters: {\n        docs: {\n            description: { story: 'The `surface` token for a raised canvas, with content starting at the top edge.' },\n        },\n    },\n    args: { surface: 'surface', children: <Panel title='Top aligned' body='Content starts from the top edge.' /> },\n};\n\nexport const SpaceBetween: Story = {\n    parameters: {\n        docs: {\n            description: {\n                story: '`justify=\"between\"` + `align=\"stretch\"` pins a header to the top and a footer to the bottom.',\n            },\n        },\n    },\n    args: {\n        justify: 'between',\n        align: 'stretch',\n        padding: 24,\n        children: (\n            <>\n                <Panel title='Header block' body='Pinned near the top.' />\n                <HStack justify='between' align='center'>\n                    <Text variant='body-small' color='secondary'>\n                        Footer copy\n                    </Text>\n                    <Text variant='body-small'>Action</Text>\n                </HStack>\n            </>\n        ),\n    },\n};\n\nexport const WithPadding: Story = {\n    parameters: {\n        docs: { description: { story: 'Uniform padding with a larger top inset via a per-edge override.' } },\n    },\n    args: {\n        padding: 24,\n        paddingTop: 40,\n        children: <Panel title='Padded route' body='Uniform padding with a larger top inset.' />,\n    },\n};\n\nexport const SafeAreaTop: Story = {\n    parameters: {\n        docs: {\n            description: {\n                story: '`safeArea=\"top\"` adds the top device inset above the configured padding (the notch/status bar).',\n            },\n        },\n    },\n    args: {\n        safeArea: 'top',\n        paddingX: 24,\n        children: <Panel title='Top safe area' body='Adds env(safe-area-inset-top) to the top padding.' />,\n    },\n};\n\nexport const SafeAreaBottom: Story = {\n    parameters: {\n        docs: { description: { story: '`safeArea=\"bottom\"` reserves the home-indicator inset below the content.' } },\n    },\n    args: {\n        safeArea: 'bottom',\n        paddingX: 24,\n        children: <Panel title='Bottom safe area' body='Adds env(safe-area-inset-bottom) to the bottom padding.' />,\n    },\n};\n\nexport const SafeAreaBoth: Story = {\n    parameters: {\n        docs: { description: { story: '`safeArea=\"both\"` insets top and bottom for full-bleed detail screens.' } },\n    },\n    args: {\n        safeArea: 'both',\n        paddingX: 24,\n        children: <Panel title='Safe area' body='Adds top and bottom safe-area insets.' />,\n    },\n};\n\nexport const NotFilled: Story = {\n    parameters: {\n        docs: {\n            description: {\n                story: '`fill={false}` sizes the surface to its content instead of filling the parent height.',\n            },\n        },\n    },\n    args: {\n        fill: false,\n        padding: 24,\n        children: <Panel title='Content height' body='The surface hugs its content when fill is off.' />,\n    },\n};\n\nexport const DarkTheme: Story = {\n    globals: { theme: 'dark' },\n    args: {\n        surface: 'surface',\n        justify: 'center',\n        children: <Panel title='Dark surface' body='Surfaces inherit theme tokens without local color styles.' />,\n    },\n};\n"
  },
  "specification": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Background",
      "status": "preview",
      "version": "1.0.0",
      "summary": "A detail-screen container that paints a surface, fills height, and aligns its content with token-scale padding and safe-area insets."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "Flex column that paints the surface and lays out content. Structural container.",
        "required": true
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "container": {
          "label": "Container",
          "description": "The single background container."
        }
      },
      "sizes": {},
      "surfaces": {
        "page": {
          "label": "Page",
          "description": "Paints the page background."
        },
        "surface": {
          "label": "Surface",
          "description": "Paints the raised surface background."
        }
      },
      "alignments": {
        "start": {
          "label": "Start"
        },
        "center": {
          "label": "Center"
        },
        "end": {
          "label": "End"
        },
        "stretch": {
          "label": "Stretch"
        }
      },
      "justifications": {
        "start": {
          "label": "Start"
        },
        "center": {
          "label": "Center"
        },
        "end": {
          "label": "End"
        },
        "between": {
          "label": "Between"
        }
      }
    },
    "variants": [
      {
        "id": "container",
        "label": "Container",
        "description": "Surface-painting layout container.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "content-padding",
        "label": "Content padding",
        "kind": "example-only",
        "token": "--cds-space-24",
        "value": 24,
        "unit": "px",
        "appliesTo": [
          "root"
        ],
        "notes": "Representative value: padding is author-configurable and accepts any step on the spacing scale. 24 is the value rendered and verified by the WithPadding story."
      }
    ],
    "layout": {
      "alignment": "align sets the horizontal (cross) axis; justify sets the vertical (main) axis.",
      "flow": "A flex column that fills height by default and centers content.",
      "notes": [
        "Use Screen when a route needs sticky header/footer chrome; use Background for a plain centered surface."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Inherited",
          "description": "Background sets no type; children own their text. Ramp noted for parity.",
          "token": "--cds-type-body-size"
        }
      ],
      "colors": [
        {
          "label": "Page surface",
          "description": "The page surface paints the page background.",
          "token": "--cds-bg-page"
        },
        {
          "label": "Raised surface",
          "description": "The surface option paints the raised background.",
          "token": "--cds-bg-surface"
        }
      ]
    },
    "states": [
      {
        "id": "page",
        "label": "Page",
        "description": "Page background surface."
      },
      {
        "id": "surface",
        "label": "Surface",
        "description": "Raised background surface."
      },
      {
        "id": "not-filled",
        "label": "Not filled",
        "description": "fill=false sizes the surface to its content."
      }
    ],
    "behavior": [
      {
        "label": "Fill",
        "description": "fill (default) makes the surface fill the parent height."
      },
      {
        "label": "Safe area",
        "description": "safeArea adds env(safe-area-inset-*) on top of the configured padding."
      }
    ],
    "accessibility": [
      {
        "label": "Presentational",
        "description": "Background is a layout container and adds no roles."
      },
      {
        "label": "Safe insets",
        "description": "Safe-area insets keep content clear of the notch and home indicator."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Alignment",
        "description": "justify=between with align=stretch pins a header to the top and a footer to the bottom."
      },
      {
        "label": "Per-edge padding",
        "description": "Per-edge padding overrides layer on top of the uniform padding."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "None",
          "description": "Background does not animate on its own."
        }
      ],
      "haptics": [
        {
          "label": "None",
          "description": "A layout container requests no haptics."
        }
      ]
    },
    "platformDifferences": []
  },
  "specification_source": "packages/design-system/src/components/layout/Background/Background.spec.json",
  "guidance": {
    "summary": "A detail-screen container that paints a surface, fills height, and aligns its content with token-scale padding and safe-area insets.",
    "guidance": [
      {
        "heading": "Overview",
        "body": "Parent container for detail, modal, and standalone screens: it paints a `page` / `surface`\nbackground, fills the available height, and centers its content by default."
      },
      {
        "heading": "When to use",
        "body": "Reach for `Background` when a screen needs a **surface plus alignment but not the sticky route\nchrome** of `Screen` — a confirmation, paywall, or empty state. It is a flex column, so `align`\nis the horizontal (cross) axis and `justify` the vertical (main) axis; `justify=\"between\"` pins\ncontent to the top and bottom edges.\n\n-   Building a **full route** with a header, scrolling body, and footer? Use `Screen`.\n-   Laying out the content **inside** the surface? Use `VStack` / `HStack` / `Grid`."
      }
    ],
    "usage": [],
    "examples": [],
    "source": "packages/design-system/src/components/layout/Background/Background.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-background",
    "json": "/data/visual/components/background.json",
    "storybook": "/storybook/?path=/story/cloaked-design-system-layout-background--playground"
  }
}