{ "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": "sectionheader", "name": "SectionHeader", "category": "Organization", "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-organization-sectionheader--default", "name": "Default", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "Default", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--default&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--small", "name": "Small", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "Small", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--small&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--large", "name": "Large", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "Large", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--large&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--with-leading", "name": "With Leading", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "WithLeading", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--with-leading&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--with-dropdown", "name": "With Dropdown", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "WithDropdown", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--with-dropdown&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--with-action", "name": "With Action", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "WithAction", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--with-action&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--with-value", "name": "With Value", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "WithValue", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--with-value&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--compared-with-list-section", "name": "Compared With List Section", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "ComparedWithListSection", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--compared-with-list-section&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--dark-theme", "name": "Dark Theme", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "DarkTheme", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--dark-theme&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--inverse", "name": "Inverse", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "Inverse", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--inverse&viewMode=story" }, { "id": "cloaked-design-system-organization-sectionheader--guttered-container", "name": "Guttered Container", "title": "Cloaked Design System/Organization/SectionHeader", "exportName": "GutteredContainer", "source_path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "source_digest": "84fc6c885a4975d3205d3f9ec5e770e1c55fcde859a49adbffa746816e847d1d", "status": "preview", "local_url": "/storybook/iframe.html?id=cloaked-design-system-organization-sectionheader--guttered-container&viewMode=story" } ], "name": "SectionHeader", "id": "sectionheader", "category": "Organization" }, "stories_source": { "path": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsx", "code": "import type { Meta, StoryObj } from '@storybook/react-vite';\nimport React from 'react';\nimport { SectionHeader } from './SectionHeader';\nimport { Dropdown } from '../../controls/Dropdown/Dropdown';\nimport { List } from '../List/List';\nimport { Text } from '../../primitives/Text/Text';\nimport { IconTile } from '../../primitives/IconTile/IconTile';\nimport { VStack } from '../../layout/VStack/VStack';\nimport { disabledControl, selectArgType } from '../../../storybook/controlOptions';\n\nconst SECTION_HEADER_SIZES = ['small', 'default', 'large'] as const;\nconst SECTION_HEADER_CONTRASTS = ['default', 'inverse'] as const;\n\nconst meta: Meta = {\n title: 'Cloaked Design System/Organization/SectionHeader',\n component: SectionHeader,\n parameters: {\n a11y: { test: 'error' },\n docs: {\n description: {\n component:\n 'Standalone content heading row for page/body sections. Use List.Section for labels inside a List and Screen.Header for route chrome.',\n },\n },\n },\n argTypes: {\n size: {\n ...selectArgType(SECTION_HEADER_SIZES),\n description: 'Title scale: `small` (body), `default` (20px h3), `large` (h3 paired with a description).',\n },\n title: { control: 'text', description: 'Visible section title.' },\n contrast: {\n ...selectArgType(SECTION_HEADER_CONTRASTS),\n description: 'Title contrast: `default` (primary text) or `inverse` (inherits a tinted/inverted surface).',\n },\n description: {\n control: 'text',\n description: 'Secondary line beneath the title (mainly for the `large` size).',\n },\n leading: {\n ...disabledControl,\n description: 'Leading node (e.g. an icon or `IconTile`) shown before the title block.',\n },\n trailing: {\n ...disabledControl,\n description: 'Trailing control or status — `Dropdown`, action text, value, or icon.',\n },\n },\n};\nexport default meta;\ntype Story = StoryObj;\n\nexport const Default: Story = { args: { title: 'Scan history' } };\n\nexport const Small: Story = { args: { size: 'small', title: 'Scan history' } };\n\nexport const Large: Story = {\n args: {\n size: 'large',\n title: 'Monitor my data',\n description: 'Your exposure dropped 22% this week.',\n },\n};\n\nexport const WithLeading: Story = {\n args: {\n title: 'Monitoring',\n leading: ,\n },\n parameters: {\n docs: { description: { story: 'Uses the `leading` slot for an icon before the title block.' } },\n },\n};\n\nexport const WithDropdown: Story = {\n args: {\n title: 'Scan history',\n trailing: ,\n },\n};\n\nexport const WithAction: Story = {\n args: {\n title: 'Your info',\n trailing: (\n \n Edit\n \n ),\n },\n};\n\nexport const WithValue: Story = {\n args: {\n title: 'Completed tasks',\n trailing: (\n \n 70%\n \n ),\n },\n};\n\nexport const ComparedWithListSection: Story = {\n render: () => (\n \n \n Action} />\n \n Use this for standalone content headings outside list grouping.\n \n \n\n \n \n \n \n \n \n \n \n ),\n};\n\nexport const DarkTheme: Story = {\n args: { title: 'Recent activity' },\n globals: { theme: 'dark' },\n};\n\nexport const Inverse: Story = {\n render: () => (\n \n \n \n ),\n};\n\nexport const GutteredContainer: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'The 20px inline inset is a default, not a fixed value. A container that already owns the page ' +\n 'gutter passes `paddingX={0}` so the title is not double-inset. The block axis stays owned by the ' +\n 'component, so zeroing the inline axis cannot collapse the heading spacing.',\n },\n },\n },\n render: () => (\n \n
\n \n
\n
\n \n
\n \n ),\n};\n" }, "specification": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "SectionHeader", "status": "preview", "version": "1.3.0", "summary": "A standalone content heading row with optional leading and trailing slots, sized small, default, or large." }, "parts": [ { "id": "root", "label": "Root", "description": "Heading row aligning leading, body, and trailing slots.", "required": true }, { "id": "leading", "label": "Leading", "description": "Optional leading visual before the title." }, { "id": "body", "label": "Body", "description": "Title and optional description column." }, { "id": "title", "label": "Title", "description": "Visible section title." }, { "id": "description", "label": "Description", "description": "Secondary line, used mainly by the large size." }, { "id": "trailing", "label": "Trailing", "description": "Optional trailing control or status. Renders as a row-level slot, or on the title's line when trailingAlign is baseline." } ], "allowedDesignChoices": { "variants": { "row": { "label": "Row", "description": "The single heading-row treatment." } }, "sizes": { "small": { "label": "Small", "description": "Body-scale title for tight groups." }, "default": { "label": "Default", "description": "The standard heading." }, "large": { "label": "Large", "description": "Larger title paired with a description." } } }, "variants": [ { "id": "row", "label": "Row", "description": "Content heading row with slots.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [ { "id": "small", "label": "Small", "description": "Body-scale title with tighter block padding." }, { "id": "default", "label": "Default", "description": "The standard 20-unit heading scale." }, { "id": "large", "label": "Large", "description": "Heading paired with a description line." } ], "measurements": [ { "id": "content-gap", "label": "Slot gap", "kind": "exact", "token": "--cds-space-12", "value": 12, "unit": "px", "appliesTo": [ "root" ] }, { "id": "default-top-inset", "label": "Default top inset", "kind": "exact", "token": "--cds-space-48", "value": 48, "unit": "px", "appliesTo": [ "root" ] }, { "id": "inline-inset", "label": "Horizontal inset (default)", "kind": "exact", "token": "--cds-space-20", "value": 20, "unit": "px", "appliesTo": [ "root" ], "notes": "Exact as shipped, but the only measurement here a caller can override: it comes from PaddingProps, so a container that already owns the page gutter passes paddingX={0}." } ], "layout": { "alignment": "Leading, body, and trailing align on the row center; the large size aligns to the top. The trailing slot can pin to the title line independently via trailingAlign='top'. trailingAlign='baseline' moves it onto the title's own line, so the two share a baseline.", "flow": "A single row: optional leading, a flexible title/description body, and an optional trailing slot.", "notes": [ "Use List.Section for labels inside a List and Screen.Header for route chrome.", "The horizontal inset is a default, not a fixed value: it comes from PaddingProps so a container that already owns the page gutter can pass paddingX={0} rather than cancelling it with an inline style. The block axis is size-derived and stays owned by the component." ] }, "typographyAndColor": { "typography": [ { "label": "Title", "description": "The default and large sizes use the h3 ramp; small uses the body ramp.", "token": "--cds-type-h3-size" }, { "label": "Description", "description": "The description uses the body ramp.", "token": "--cds-type-body-size" } ], "colors": [ { "label": "Title", "description": "Primary text for the title by default; the `contrast: inverse` prop makes the title inherit the surface color so it reads correctly on a tinted or inverted backdrop.", "token": "--cds-text-primary" }, { "label": "Description", "description": "Secondary text for the description.", "token": "--cds-text-secondary" } ] }, "states": [ { "id": "small", "label": "Small", "description": "Body-scale title with tighter block padding." }, { "id": "default", "label": "Default", "description": "Standard heading scale." }, { "id": "large", "label": "Large", "description": "Larger title with a description and top-aligned slots." } ], "behavior": [ { "label": "Size choice", "description": "Pick small for tight groups, default for standard sections, large when a description is needed." }, { "label": "Slots", "description": "Use trailing for a dropdown, action text, value, or icon." }, { "label": "Trailing alignment", "description": "The trailing slot centers with the row by default. Set trailingAlign to top to pin it to the title line when a description makes the body taller, such as a count beside a titled section. Set it to baseline when the trailing content is text smaller than the title: the slot then renders on the title's line and the two sit on one baseline, rather than merely sharing a box top." }, { "label": "Title contrast", "description": "Defaults to `default` (primary text); set `contrast` to `inverse` when the header sits on a tinted or inverted surface so the title inherits that surface's text color." } ], "accessibility": [ { "label": "Heading", "description": "The title renders as a heading so sections are navigable." }, { "label": "Trailing controls", "description": "Interactive trailing content carries its own accessible name." } ], "contentAdaptation": [ { "label": "Wrapping title", "description": "The title/description body flexes and wraps while slots stay aligned." }, { "label": "Optional slots", "description": "Leading, description, and trailing render only when provided." } ], "motionHaptics": { "motion": [ { "label": "Static", "description": "SectionHeader does not animate." } ], "haptics": [ { "label": "No feedback", "description": "The heading requests no haptics; trailing controls own any feedback." } ] }, "platformDifferences": [] }, "specification_source": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.spec.json", "guidance": { "summary": "A standalone content heading row with optional leading and trailing slots, sized small, default, or large.", "guidance": [ { "heading": "Overview", "body": "A titled heading row above a body section, with optional `leading` and `trailing` slots for an icon\nor an action." }, { "heading": "When to use", "body": "Reach for `SectionHeader` to label a standalone group on a page or screen — \"Scan history\", \"Your\ninfo\" — especially when the heading carries a trailing control (a `Dropdown` filter, an \"Edit\"\naction, a value). It bundles the title, optional description, and slots so you don't hand-assemble\ntype and spacing.\n\n- Just a run of styled text with no section role? Use `Text` directly.\n- A label _inside_ a `List` that groups the rows under it? Use `List.Section`, not this.\n- Only a horizontal rule between blocks, no title? Use `Divider`.\n- Route-level chrome (back button, title bar)? Use `Screen.Header`." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/organization/SectionHeader/SectionHeader.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-sectionheader", "json": "/data/visual/components/sectionheader.json", "storybook": "/storybook/?path=/story/cloaked-design-system-organization-sectionheader--default" } }