Cloaked Design SystemOrganization

SectionHeader

A standalone content heading row with optional leading and trailing slots, sized small, default, or large.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

11 stories

Default selectedOpen canvas

Example source

packages/design-system/src/components/organization/SectionHeader/SectionHeader.stories.tsxExport Default

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

A standalone content heading row with optional leading and trailing slots, sized small, default, or large.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { SectionHeader } from '@cloakedinc/design-system';

SectionHeaderSectionHeaderProps

packages/design-system/src/components/organization/SectionHeader/SectionHeader.tsx:58

Prop	Type	Presence	Notes
`size`	`SectionHeaderSize \| undefined`	Optional	Controls block padding and slot alignment, not the title's type size. Defaults to `default`.Source default: `'default'`
`title`	`string`	Required	Section label. Always renders as a level-3 heading, whatever visual scale `size` sets.
`contrast`	`SectionHeaderContrast \| undefined`	Optional	Title contrast for the surface. Defaults to `default`; use `inverse` on a tinted or inverted backdrop.Source default: `'default'`
`description`	`React.ReactNode`	Optional	Secondary line shown beneath the title (used by the large size).
`leading`	`React.ReactNode`	Optional	Leading content (e.g. an icon) shown before the title block.
`trailing`	`React.ReactNode`	Optional	Trailing control or status — dropdown, action text, value, or icon.
`trailingAlign`	`"center" \| "top" \| "baseline" \| undefined`	Optional	Cross-axis alignment of the trailing slot. Defaults to `center`; `top` pins it to the title line above a description, and `baseline` sits text trailing content on the title's baseline.Source default: `'center'`
`className`	`string \| undefined`	Optional
`style`	`React.CSSProperties \| undefined`	Optional
`testId`	`string \| undefined`	Optional	Selector for the header row; `leading` and `trailing` content carry their own.
`padding`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Padding on all four sides.
`paddingX`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Horizontal padding (left + right). Overrides `padding` on the X axis.
`paddingY`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Vertical padding (top + bottom). Overrides `padding` on the Y axis.
`paddingTop`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Top padding. Overrides `paddingY` and `padding`.
`paddingRight`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Right padding. Overrides `paddingX` and `padding`.
`paddingBottom`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Bottom padding. Overrides `paddingY` and `padding`.
`paddingLeft`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Left padding. Overrides `paddingX` and `padding`.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

A titled heading row above a body section, with optional leading and trailing slots for an icon or an action.

When to use

Reach for SectionHeader to label a standalone group on a page or screen — "Scan history", "Your info" — especially when the heading carries a trailing control (a Dropdown filter, an "Edit" action, a value). It bundles the title, optional description, and slots so you don't hand-assemble type and spacing.

Just a run of styled text with no section role? Use Text directly.
A label inside a List that groups the rows under it? Use List.Section, not this.
Only a horizontal rule between blocks, no title? Use Divider.
Route-level chrome (back button, title bar)? Use Screen.Header.

Component specification

$schema

../../../specs/component-spec.schema.json

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.

Allowed Design Choices

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
Applies To: root

Id: default-top-inset
Label: Default top inset
Kind: exact
Token: --cds-space-48
Value: 48
Unit: px
Applies To: root

Id: inline-inset
Label: Horizontal inset (default)
Kind: exact
Token: --cds-space-20
Value: 20
Unit: px
Applies To: 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.

Typography And Color

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.

Content Adaptation

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.

Motion Haptics

Motion

Label: Static
Description: SectionHeader does not animate.

Haptics

Label: No feedback
Description: The heading requests no haptics; trailing controls own any feedback.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1