{ "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", "summary": "A detail-screen container that paints a surface, fills height, and aligns its content with token-scale padding and safe-area insets.", "documentation": { "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." }, "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "code": "import React from 'react';\nimport { cn } from '../../../utilities';\nimport { resolvePadding } from '../resolvePadding';\nimport type { PaddingProps } from '../resolvePadding';\nimport { resolveSafeAreaPadding } from '../Screen/screenSafeArea';\nimport styles from './Background.module.scss';\n\nexport type BackgroundSurface = 'page' | 'surface';\nexport type BackgroundAlign = 'start' | 'center' | 'end' | 'stretch';\nexport type BackgroundJustify = 'start' | 'center' | 'end' | 'between';\nexport type BackgroundSafeArea = 'none' | 'top' | 'bottom' | 'both';\n\nconst ALIGN: Record = {\n start: 'flex-start',\n center: 'center',\n end: 'flex-end',\n stretch: 'stretch',\n};\n\nconst JUSTIFY: Record = {\n start: 'flex-start',\n center: 'center',\n end: 'flex-end',\n between: 'space-between',\n};\n\n/**\n * Props for the detail-screen surface container. Reach for Screen instead when the route\n * needs sticky header or footer chrome.\n */\nexport interface BackgroundProps extends PaddingProps {\n /** Background token the surface paints. Defaults to `page`. */\n surface?: BackgroundSurface;\n /** Horizontal alignment of content. Defaults to `center`. */\n align?: BackgroundAlign;\n /** Vertical distribution of content. Defaults to `start` (top). */\n justify?: BackgroundJustify;\n /** Fill the available height (`min-height: 100%`). Defaults to true. */\n fill?: boolean;\n /** Adds safe-area insets to padding edges. Defaults to `'none'`. */\n safeArea?: BackgroundSafeArea;\n style?: React.CSSProperties;\n className?: string;\n children?: React.ReactNode;\n /** Optional test selector, placed on the root element. */\n testId?: string;\n}\n\n/**\n * Parent container for detail-screen layouts: paints a surface, fills height,\n * and centers its content by default with configurable alignment.\n */\nexport function Background({\n surface = 'page',\n align = 'center',\n justify = 'start',\n fill = true,\n safeArea = 'none',\n style: styleProp,\n className,\n children,\n testId,\n ...paddingRest\n}: BackgroundProps) {\n const paddingStyles = resolvePadding(paddingRest);\n const style: React.CSSProperties = {\n alignItems: ALIGN[align],\n justifyContent: JUSTIFY[justify],\n ...paddingStyles,\n ...resolveSafeAreaPadding(safeArea, paddingStyles),\n ...styleProp,\n };\n\n return (\n \n {children}\n \n );\n}\n" }, "spec": { "$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": [] }, "spec_source": "packages/design-system/src/components/layout/Background/Background.spec.json", "guidance_source": { "path": "packages/design-system/src/components/layout/Background/Background.mdx", "code": "import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';\nimport { ComponentSpec } from '../../../../.storybook/blocks';\nimport * as Stories from './Background.stories';\nimport backgroundSpec from './Background.spec.json';\n\n\n\n# Background\n\nParent container for detail, modal, and standalone screens: it paints a `page` / `surface`\nbackground, fills the available height, and centers its content by default.\n\n\n\n## When to use\n\nReach 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`.\n\n\n\n## Design Guidelines\n\n\n\n## Props\n\n\n" }, "props": [ { "name": "surface", "type": "BackgroundSurface | undefined", "declared_type": "BackgroundSurface", "required": false, "description": "Background token the surface paints. Defaults to `page`.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 33 }, "values": [ "page", "surface" ], "values_complete": true, "default": "'page'", "default_kind": "source-expression" }, { "name": "align", "type": "BackgroundAlign | undefined", "declared_type": "BackgroundAlign", "required": false, "description": "Horizontal alignment of content. Defaults to `center`.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 35 }, "values": [ "center", "end", "start", "stretch" ], "values_complete": true, "default": "'center'", "default_kind": "source-expression" }, { "name": "justify", "type": "BackgroundJustify | undefined", "declared_type": "BackgroundJustify", "required": false, "description": "Vertical distribution of content. Defaults to `start` (top).", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 37 }, "values": [ "between", "center", "end", "start" ], "values_complete": true, "default": "'start'", "default_kind": "source-expression" }, { "name": "fill", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Fill the available height (`min-height: 100%`). Defaults to true.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 39 }, "values": [ false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "safeArea", "type": "BackgroundSafeArea | undefined", "declared_type": "BackgroundSafeArea", "required": false, "description": "Adds safe-area insets to padding edges. Defaults to `'none'`.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 41 }, "values": [ "both", "bottom", "none", "top" ], "values_complete": true, "default": "'none'", "default_kind": "source-expression" }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 42 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 43 } }, { "name": "children", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 44 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector, placed on the root element.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 46 } }, { "name": "padding", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Padding on all four sides.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 10 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingX", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Horizontal padding (left + right). Overrides `padding` on the X axis.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 12 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingY", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Vertical padding (top + bottom). Overrides `padding` on the Y axis.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 14 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingTop", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Top padding. Overrides `paddingY` and `padding`.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 16 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingRight", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Right padding. Overrides `paddingX` and `padding`.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 18 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingBottom", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Bottom padding. Overrides `paddingY` and `padding`.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 20 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingLeft", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Left padding. Overrides `paddingX` and `padding`.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 22 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true } ], "prop_shapes": {}, "examples": [], "tokens": [ { "name": "--cds-space-24", "light": "24px", "dark": "24px" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-bg-page", "light": "#f3f1ed", "dark": "#141410" }, { "name": "--cds-bg-surface", "light": "#ffffff", "dark": "#1b1b18" } ], "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": [ { "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" } ], "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 \n \n {title}\n \n {body}\n \n \n \n);\n\nconst meta: Meta = {\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: ,\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 =>
{Story()}
],\n};\nexport default meta;\ntype Story = StoryObj;\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: , 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: },\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 \n \n \n Footer copy\n \n Action\n \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: ,\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: ,\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: ,\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: ,\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: ,\n },\n};\n\nexport const DarkTheme: Story = {\n globals: { theme: 'dark' },\n args: {\n surface: 'surface',\n justify: 'center',\n children: ,\n },\n};\n" }, "links": { "human": "/component-background", "json": "/data/components/background.json", "markdown": "/data/components/background.md", "storybook": "/storybook/?path=/story/cloaked-design-system-layout-background--playground" }, "contract_status": "preview", "contract_kind": "source-derived", "approval": "required", "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "Background", "public_path": "Background", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "Background", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 53 }, "props_type": "BackgroundProps", "props": [ { "name": "surface", "type": "BackgroundSurface | undefined", "declared_type": "BackgroundSurface", "required": false, "description": "Background token the surface paints. Defaults to `page`.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 33 }, "values": [ "page", "surface" ], "values_complete": true, "default": "'page'", "default_kind": "source-expression" }, { "name": "align", "type": "BackgroundAlign | undefined", "declared_type": "BackgroundAlign", "required": false, "description": "Horizontal alignment of content. Defaults to `center`.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 35 }, "values": [ "center", "end", "start", "stretch" ], "values_complete": true, "default": "'center'", "default_kind": "source-expression" }, { "name": "justify", "type": "BackgroundJustify | undefined", "declared_type": "BackgroundJustify", "required": false, "description": "Vertical distribution of content. Defaults to `start` (top).", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 37 }, "values": [ "between", "center", "end", "start" ], "values_complete": true, "default": "'start'", "default_kind": "source-expression" }, { "name": "fill", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Fill the available height (`min-height: 100%`). Defaults to true.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 39 }, "values": [ false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "safeArea", "type": "BackgroundSafeArea | undefined", "declared_type": "BackgroundSafeArea", "required": false, "description": "Adds safe-area insets to padding edges. Defaults to `'none'`.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 41 }, "values": [ "both", "bottom", "none", "top" ], "values_complete": true, "default": "'none'", "default_kind": "source-expression" }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 42 } }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 43 } }, { "name": "children", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 44 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector, placed on the root element.", "source": { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 46 } }, { "name": "padding", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Padding on all four sides.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 10 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingX", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Horizontal padding (left + right). Overrides `padding` on the X axis.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 12 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingY", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Vertical padding (top + bottom). Overrides `padding` on the Y axis.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 14 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingTop", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Top padding. Overrides `paddingY` and `padding`.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 16 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingRight", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Right padding. Overrides `paddingX` and `padding`.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 18 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingBottom", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Bottom padding. Overrides `paddingY` and `padding`.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 20 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true }, { "name": "paddingLeft", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Left padding. Overrides `paddingX` and `padding`.", "source": { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 22 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 8, "name": "BackgroundSurface", "code": "export type BackgroundSurface = 'page' | 'surface';" }, { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 9, "name": "BackgroundAlign", "code": "export type BackgroundAlign = 'start' | 'center' | 'end' | 'stretch';" }, { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 10, "name": "BackgroundJustify", "code": "export type BackgroundJustify = 'start' | 'center' | 'end' | 'between';" }, { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 11, "name": "BackgroundSafeArea", "code": "export type BackgroundSafeArea = 'none' | 'top' | 'bottom' | 'both';" }, { "path": "packages/design-system/src/components/layout/Background/Background.tsx", "line": 31, "name": "BackgroundProps", "code": "export interface BackgroundProps extends PaddingProps {\n /** Background token the surface paints. Defaults to `page`. */\n surface?: BackgroundSurface;\n /** Horizontal alignment of content. Defaults to `center`. */\n align?: BackgroundAlign;\n /** Vertical distribution of content. Defaults to `start` (top). */\n justify?: BackgroundJustify;\n /** Fill the available height (`min-height: 100%`). Defaults to true. */\n fill?: boolean;\n /** Adds safe-area insets to padding edges. Defaults to `'none'`. */\n safeArea?: BackgroundSafeArea;\n style?: React.CSSProperties;\n className?: string;\n children?: React.ReactNode;\n /** Optional test selector, placed on the root element. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/components/layout/resolvePadding.ts", "line": 8, "name": "PaddingProps", "code": "export interface PaddingProps {\n /** Padding on all four sides. */\n padding?: CdsSpace;\n /** Horizontal padding (left + right). Overrides `padding` on the X axis. */\n paddingX?: CdsSpace;\n /** Vertical padding (top + bottom). Overrides `padding` on the Y axis. */\n paddingY?: CdsSpace;\n /** Top padding. Overrides `paddingY` and `padding`. */\n paddingTop?: CdsSpace;\n /** Right padding. Overrides `paddingX` and `padding`. */\n paddingRight?: CdsSpace;\n /** Bottom padding. Overrides `paddingY` and `padding`. */\n paddingBottom?: CdsSpace;\n /** Left padding. Overrides `paddingX` and `padding`. */\n paddingLeft?: CdsSpace;\n}" }, { "path": "packages/design-system/src/tokens/CdsSpace.ts", "line": 8, "name": "PUI_SPACES", "code": "PUI_SPACES = [0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 72, 80, 96, 120, 240] as const" }, { "path": "packages/design-system/src/tokens/CdsSpace.ts", "line": 13, "name": "CdsSpace", "code": "export type CdsSpace = (typeof PUI_SPACES)[number];" } ], "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." } }