The top-of-screen header pattern with title, leading back action, and trailing actions.
Restructure — rename, split, and collapse the variant matrix
Today four components share the "Header" prefix but solve four different problems. The base Header (this one) should be renamed Section Header, its 8 boolean slots collapsed into 3 props (
preamble, leadingMedia, trailing), and the sibling "Header - *" components either renamed by role or merged into existing primitives. See the Family Restructure section below for the full plan.In Context
Section headers sit above grouped content — a list of transactions, a set of services, a carousel of offers — to label the section and optionally expose a trailing action.
Live Preview
Heading
Description goes here
Properties
preamble
description
leading media
trailing
DS Health
Reusable
Partial
Works across many screen sections, but boolean slots force consumers to think in invalid combinations (icon + left illustration + right illustration all true?).
Self-contained
Pass
Owns its typography, spacing, and color tokens. No external state required.
Consistent
Warn
The "Header" name is shared with three structurally different components (Centered, With Logo, Transaction). Property model (8 booleans) conflicts with the enum-slot model used by other components in the DS.
Composable
Warn
Actionable slots (link, edit, counter) are drawn in-place rather than accepting Button/Badge/Link instances. Consumers can't swap in their own action component.
Behavior
| State | iOS | Android | Figma Property | Notes |
|---|---|---|---|---|
| Default | Yes | Yes | 16 variants | The only state today — no pressed/disabled/focused. |
| Trailing action pressed | N/A | N/A | Not modeled | Link, edit, counter should be real Button/Link instances that carry their own pressed state. |
| Disabled | N/A | N/A | Not modeled | Section headers are informational — no disabled variant needed. |
| Focused (a11y) | N/A | N/A | — | Focus lives on the trailing action, not the header itself. |
Open Issues
- Family-wide naming conflict. "Header" prefix conflates 4 roles (section header, page banner, brand bar, detail hero). Rename each by role. C1 · Layer Structure & Naming
- 8 boolean props, 256 theoretical combos, 16 built. The boolean model implies combinations that don't exist. Collapse
icon+left illustrationintoleadingMedia, andright illustration+link+edit+counterintotrailing. C2 · Variant & Property Naming - Trailing actions aren't real components. Link ("View All"), Edit, and Counter are drawn in-place rather than accepting Button / Badge / Link instances. Breaks composition and blocks state handling (pressed, disabled). C4 · Native Mappability
- No pressed/disabled states on the actionable slots. Natively, those slots need full state coverage — at minimum pressed + disabled. C5 · Interaction State Coverage
- No Code Connect mappings. Trivial once slots are enumerated. C7 · Code Connect Linkability
Design Recommendations
- Rename to "Section Header". Unambiguously signals in-screen section title; frees "Header" namespace. Rename
- Collapse to 3 props —
preamble?,leadingMedia?: icon | illustration,trailing?: illustration | link | edit | counter— plus the requiredtitle. Eliminates invalid combos, drops variant count from 16 to ~6 canonical patterns. Property - Promote actionable slots to real components. "View All" becomes a Text Button instance. "Edit" becomes an Icon Button. "Counter" becomes a Badge instance. Each carries its own pressed/disabled states. Composition
- Move "Header - Transaction" out of the family. It's a card hero, not a header. Rename to Detail Hero and rehome near Visual Popup. Family
- Merge "Header - With Logo" into Title Bar. Add
leading = title | logoslot to Title Bar instead of maintaining a second app-bar component. Family - See siblings: Header - Centered, Header - With Logo, Header - Transaction. Restructure is a family-wide decision. Family
Styles
Title only (baseline)
DES DEV
The simplest variant — a bare title. This is the baseline the other 15 variants layer slots onto.
Heading
Properties
preamble
description
leading
trailing
Properties
preamble no
description no
leading none
trailing none
Colors
Surface #FFFFFF
Title #0A2757
Preamble #005CE5
Description #6780A9
Link #005CE5
Icon #005CE5
Typography
Title style Heading/L — BarkAda 18/24
Color text/primary · #0A2757
Layout
Width Fill
Height 58 (hug)
Padding 0
Gap (stacked slots) space/space-4
Title — Colors
Baseline header: just the heading on a white surface. Card stroke is invisible by default.
| Role | Token | Default |
|---|---|---|
| Surface bg | main/header/surface | #FFFFFF |
| Heading | text/primary/headline/section | #0A2757 |
Full stack (preamble + title + description)
DES DEV
All three text slots filled. This is the canonical "announce a section" pattern.
Preamble
Heading
Description goes here
Properties
preamble
description
leading
trailing
Properties
preamble yes
description yes
leading none
trailing none
Colors
Surface #FFFFFF
Preamble #005CE5
Title #0A2757
Description #6780A9
Icon #005CE5
Layout
Padding 24 horizontal · 16 vertical
Title size 22 / 26
Preamble size 14 / 14
Description size 12 / 18
Typography
Preamble Label/S caps · 12/16 · text/brand
Title Heading/L · 18/24 · text/primary
Description Body/S · 12/16 · text/secondary
Full Stack — Colors
Tier-three layout with eyebrow preamble, heading, and supporting description.
| Role | Token | Default |
|---|---|---|
| Surface bg | main/header/surface | #FFFFFF |
| Preamble | text/accent/eyebrow | #005CE5 |
| Heading | text/primary/headline/section | #0A2757 |
| Description | text/primary/body/secondary | #6780A9 |
Title + trailing link
DES DEV
Title on the left, "View All" link on the right. Common list-section pattern.
Heading
Properties
preamble
description
leading
trailing
Properties
preamble no
description no
leading none
trailing link
Colors
Surface #FFFFFF
Title #0A2757
Description #6780A9
Border #E5EBF4
Layout
Padding H 24px
Padding V 16px
Border bottom 1px solid
Title size 22 / 26
Typography
Title style Primary/Headlines/Section
Title font Proxima Soft Bold · 22 / 26
Title + Link — Colors
Heading followed by a trailing hyperlink (e.g. "See all").
| Role | Token | Default |
|---|---|---|
| Surface bg | main/header/surface | #FFFFFF |
| Heading | text/primary/headline/section | #0A2757 |
| Link label | text/accent/link | #005CE5 |
Title + trailing edit
DES DEV
Title left, pencil icon + "Edit details" link right. Used on profile/settings sections.
Heading
Properties
preamble
description
leading
trailing
Properties
preamble no
description no
leading none
trailing edit
Colors
Surface #FFFFFF
Title #0A2757
Description #6780A9
Border #E5EBF4
Layout
Padding H 24px
Padding V 16px
Border bottom 1px solid
Title size 22 / 26
Typography
Title style Primary/Headlines/Section
Title font Proxima Soft Bold · 22 / 26
Title + Edit — Colors
Heading followed by an edit affordance (icon + hyperlink label).
| Role | Token | Default |
|---|---|---|
| Surface bg | main/header/surface | #FFFFFF |
| Heading | text/primary/headline/section | #0A2757 |
| Edit icon | icon/accent | #005CE5 |
| Edit label | text/accent/link | #005CE5 |
Title + trailing counter
DES DEV
Title left, numeric counter pill right. Used on inbox/notifications.
Heading
Properties
preamble
description
leading
trailing
Properties
preamble no
description no
leading none
trailing counter
Colors
Surface #FFFFFF
Title #0A2757
Description #6780A9
Border #E5EBF4
Layout
Padding H 24px
Padding V 16px
Border bottom 1px solid
Title size 22 / 26
Typography
Title style Primary/Headlines/Section
Title font Proxima Soft Bold · 22 / 26
Title + Counter — Colors
Heading followed by a count chip (e.g. unread badge, item total).
| Role | Token | Default |
|---|---|---|
| Surface bg | main/header/surface | #FFFFFF |
| Heading | text/primary/headline/section | #0A2757 |
| Counter chip bg | main/counter/surface | #EEF2F9 |
| Counter value | text/primary/body/secondary | #6780A9 |
Property Mapping
| Figma Property | SwiftUI | Compose |
|---|---|---|
preamble: boolean | preamble?: String | preamble: String? |
| (implicit) | title: String | title: String (required) |
description: boolean | description?: String | description: String? |
icon + left illustration | leadingMedia?: icon | illustration | leadingMedia: EBLeadingMedia? |
right illustration + link + edit + counter | trailing?: illustration | link | edit | counter | trailing: EBHeaderTrailing? |
Accessibility
| Requirement | iOS | Android |
|---|---|---|
| Heading trait | Apply .accessibilityAddTraits(.isHeader) to the title. | Apply Modifier.semantics { heading() } to the title text. |
| Trailing action label | Link/Edit/Counter must each carry their own accessibility label. Counter should announce count ("12 unread"). | Same — each trailing slot owns its own semantics. |
| Minimum touch target | Trailing interactive element must be ≥44×44pt. | Trailing interactive element must be ≥48×48dp. |
| Reading order | Preamble → Title → Description → Trailing. VoiceOver follows DOM order. | Same reading order — TalkBack follows composition order. |
Criteria Scorecard
| ID | Criterion | Status | Notes |
|---|---|---|---|
| C1 | Layer Structure & Naming | Requires Rework | "Header" prefix shared with 3 structurally different components. Rename to Section Header. |
| C2 | Variant & Property Naming | Requires Rework | 8 booleans → 3 props (preamble, leadingMedia, trailing). Drops 16 variants to ~6 canonical patterns. |
| C3 | Token Coverage | Ready | Typography and color bound to DS tokens. |
| C4 | Native Mappability | Needs Refinement | Maps to a simple EBSectionHeader view/composable once slots collapse. Trailing actions should be real Button/Badge instances, not drawn. |
| C5 | Interaction State Coverage | Needs Refinement | Header itself is static; trailing actions inherit Button/Link state coverage once they become instances. |
| C6 | Asset & Icon Quality | Needs Refinement | Confirm leading/trailing "illustration" slots accept vector instances (Avatar / Icon / custom). Placeholder circle suggests unverified. |
| C7 | Code Connect Linkability | Not Mapped | Cannot map until property model collapses and trailing slots resolve to real components. |
Variants Inventory (16 total)
Today: 8 independent boolean properties — preamble, description, icon, left illustration, right illustration, link, edit, counter. 2⁸ = 256 theoretical combos, only 16 built — most combinations are either invalid or unsupported.
| Group | Count | Slots enabled |
|---|---|---|
| Text-only | 4 | preamble × description permutations |
| With right icon (top-aligned) | 4 | preamble × description × icon |
| With leading illustration | 2 | description × left illustration |
| With trailing illustration | 2 | description × right illustration |
| With link (View All) | 2 | description × link |
| With edit | 1 | edit only |
| With counter | 1 | counter only |
1.0.0 — April 2026Major
Initial Assessment · node 18430:2919
Verdict: Restructure — Rename to Section Header, collapse 8 boolean props into 3 slots (
Architecturepreamble, leadingMedia, trailing). OpenFamily restructure plan — 4 "Header*" components should be renamed by role; "With Logo" merges into Title Bar; "Transaction" moves out of family. Open
FamilyTrailing actions should be real components — Link/Edit/Counter should be Text Button / Icon Button / Badge instances, not drawn in-place. Open
C4C7 — Code Connect — Blocked until property model collapses. Open
C7