# ThemeKit — Component Reference

<!-- GENERATED by tools/gen_skill.py — do not edit by hand. Run `make skill`. -->

> Per-component API for the ThemeKit SwiftUI design system: init signature, chainable
> modifiers, and (where available) a usage snippet. Companion files: **llms.txt** (index),
> **llms-full.txt** (architecture + tokens), **llms-patterns.txt** (recipes).

## How to read this file

- **Init** — required content/bindings/actions only. Everything else is a modifier.
- **Modifiers** — chainable, copy-on-write; order does not matter.
- **Native modifiers apply too** — sizing is `.controlSize(_:)`, disabling is `.disabled(_:)`.
- **Accessibility ids** — many components expose `.a11yID(_:)` (shown in their modifier list);
  it is not a global modifier, so use SwiftUI's `.accessibilityIdentifier(_:)` where absent.

## Golden rule for every snippet below

Never hardcode a color, radius, or spacing. Read the theme from the environment
(`@Environment(\.theme) private var theme`) and pull tokens — `theme.text(.textPrimary)`,
`theme.background(.bgWhite)`, `Theme.SpacingKey.md.value`, `Theme.RadiusRole.box.value`.

## Style protocols (flexibility architecture)

| Protocol | Apply with | Covers | Built-in styles |
| --- | --- | --- | --- |
| `CardStyle` | `.cardStyle(_:)` | cards (Card, RadioCard, CheckboxCard, MenuCard…) | `.default`, `.outlined` |
| `FieldStyle` | `.fieldStyle(_:)` | text fields (TextInput, DateField, ColorField, OTPInput…) | `.default`, `.muted`, `.underlined` |
| `ChipStyle` | tonal/solid chip styles | Chip | `.tonal`, `.solid` |
| `BarStyle` | `.barStyle(_:)` | bottom/booking bars | `.default`, `.floating` |
| `MeterStyle` | `.meterStyle(_:)` | progress/meters (ProgressBar, RadialProgress, GaugeView) | `.linear`, `.striped`, `.radial` |
| `ToastStyle` | `.toastStyle(_:)` | toasts (AlertToast) | `.default`, `.capsule` |

Each has a `Configuration` struct + a `makeBody(configuration:)` requirement — like SwiftUI's
`ButtonStyle`. Full recipe in **llms-patterns.txt**.

This reference documents all **246** components (52 atoms · 110 molecules · 84 organisms). Where a component appears in the MCP dataset, its full init signature and a
usage snippet are shown; otherwise the init's required/common parameter labels are listed.

---

# Atoms (52)

_Smallest building blocks — a single visual/interactive primitive._

## AnimatedImage

Animated GIF / APNG playback with NO third-party dependency — frames and per-frame delays are decoded natively via ImageIO (`CGImageSource`) and driven by a `TimelineView(.animation)`.

```swift
init(_ url: URL?)

// usage: AnimatedImage(<URL>)
```

**Modifiers**

- `.contentMode` — How the frames fill the available space (default .fill).
- `.cornerRadius` — Clipping corner radius in points (default 0).

## Aura

```swift
Aura()
```

**Modifiers**

- `.accent` — Semantic tint of the glow; `nil` restores the default (`.primary`).
- `.color` — Semantic tint of the glow (back-compat); prefer `accent(_:)`.
- `.size` — Diameter of the blob in points (default 120).
- `.intensity` — Peak opacity of the glow, 0…1 (default 0.7).

## Avatar

```swift
init(_ content: AvatarContent)

// usage: Avatar(<AvatarContent>)
```

**Modifiers**

- `.size` — Size tier: xs / sm / md / lg (Figma 24/32/40/48).
- `.dimension` — Arbitrary point-size avatar (Ant numeric `size`), overriding the size tier.
- `.accent` — Semantic tint for the surface behind the icon/initials (content auto-contrasts); `nil` (default) keeps the `AvatarBackground` palette.
- `.fill` — Fill treatment for the semantic surface (HeroUI Avatar variants): `.solid` (default) keeps the accent's solid shade with auto-contrast content; `.soft` resolves the surface to the accent `SemanticColor`'s `.soft` shade and the content to its high-contrast `.accent` foreground.
- `.fillColor` — Surface fill behind the icon/initials (renamed from `background:` to avoid clashing with SwiftUI's `.background`, R5).
- `.shape` — Circle (default) or rounded square.
- `.bordered` — Draws a token stroke ring around the avatar (HeroUI `isBordered`) — e.g.
- `.presence` — Corner presence dot (online / away / busy …); `nil` hides it.

## AvatarGroup

Overlapping stack of avatars with a "+N" overflow bubble.

```swift
init(_ avatars: [AvatarContent])

// usage: AvatarGroup(<[AvatarContent]>)
```

**Modifiers**

- `.size` — Size tier for every avatar in the group: xs / sm / md / lg.
- `.maxVisible` — How many avatars show before collapsing into the "+N" bubble (default 4, floored at 1).
- `.accent` — Semantic tint for every member avatar's surface (content auto-contrasts); `nil` (default) keeps the `AvatarBackground` palette.
- `.fill` — Fill treatment for every member avatar's semantic surface (`.solid` default · `.soft`); the "+N" overflow bubble keeps its dark palette.
- `.fillColor` — Surface fill behind the avatars' icon/initials (matches Avatar's `.fillColor`, R5).

## Badge

Improved, token-bound rewrite of the reference BadgeView.

```swift
init(_ text: String, action: (() -> Void)? = nil)

// usage: Badge("text")
```

**Modifiers**

- `.badgeStyle` — Semantic style (system + brand variants) driving fill/foreground/border (renamed from the bare `style:` to avoid the generic clash + match `BadgeStyle`).
- `.variant` — Fill treatment: soft / solid / outline / ghost.
- `.size` — Size tier: small / medium / large / xlarge.
- `.icon` — Leading SF Symbol before the text (the Figma "Prefix" slot).
- `.trailingIcon` — A trailing SF Symbol after the text — the Figma "Suffix" slot (e.g.
- `.badgeShape` — Pill (default) or rounded-rectangle outline.
- `.badgeColor` — Overrides the text/foreground color (otherwise derived from style + variant).
- `.gradient` — Fills the badge with a horizontal gradient of semantic tokens (each hue's solid shade) instead of the style background; `nil` restores it.
- `.highlighted` — Lifts the badge off the surface with a subtle drop shadow.

## Barcode

A token-sized (but high-contrast) Code 128 barcode with an optional caption.

```swift
Barcode(value)
```

**Modifiers**

- `.height` — Bar height in points (default 56).
- `.showsValue` — Shows the value as a monospaced caption under the bars.

## Chip

Improved, token-bound rewrite of the reference BasicChip — a single clear selection API (tonal / solid) instead of the reference's nested status × mode × fullSelect × isExist matrix.

```swift
init(_ title: String, isSelected: Binding<Bool>)

// usage: Chip("title", isSelected: $isSelected)
```

**Modifiers**

- `.size` — Control size: small / medium / large — drives paddings and the enforced min-height ramp (36 / 40 / 44pt at the default text size).
- `.chipStyle` — How a selected chip is filled: tonal / solid.
- `.type` — Semantic hue — the HeroUI V3 Chip **Type** (accent / neutral / success / warning / danger).
- `.variant` — Emphasis level of a semantic chip — the HeroUI V3 Chip **Variant** (primary / secondary / tertiary / soft).
- `.onClose` — A trailing dismiss (`×`) button (HeroUI suffix remove).
- `.icon` — A leading SF Symbol before the title.
- `.rating` — A leading star + numeric rating before the title.
- `.exists` — Whether the represented item still exists; `false` strikes through and dims the chip (e.g.
- `.interactive` — Whether the chip responds to taps (a read-only display chip passes `false`).
- `.fullWidth` — Stretches the chip to fill the available width (e.g.
- `.expands` — Stretches the chip to fill the available width (e.g.

## CloseButton

A circular icon-only dismiss button.

```swift
CloseButton(action:)
```

**Modifiers**

- `.tint` — Semantic glyph tint; `nil` (default) uses the muted `textTertiary` token.
- `.systemImage` — Swaps the SF Symbol glyph (default `"xmark"`).
- `.plain` — Drops the circle fill, leaving a bare ghost glyph — for image overlays and dense chrome where the elevator surface would be noise.
- `.a11yID` — Stable accessibility-identifier namespace (the button gets `"<id>.close"`).

## CodeBlock

```swift
CodeBlock(lines)
```

**Modifiers**

- `.copyable` — Show a copy-to-clipboard button in the top-trailing corner.

## ColorSwatch

```swift
ColorSwatch(color, label:)
```

**Modifiers**

- `.shape` — `.square` (default, `RadiusRole.selector` corners) or `.circle`.
- `.size` — Chip dimension — `.small` 20 / `.medium` 28 (default) / `.large` 36pt.
- `.selected` — Draw the hero selection ring (default off).

## Confetti

A token-bound confetti burst.

```swift
Confetti()
```

**Modifiers**

- `.pieceCount` — Number of confetti pieces (default 40).
- `.colors` — Override the brand palette.
- `.duration` — Fall duration in seconds (default 2.4).

## Ribbon

A corner ribbon wrapping any content (Ant `Badge.Ribbon`).

```swift
init(_ text: String, @ViewBuilder content: () -> Content)

// usage: Ribbon("text", @ViewBuilder: { })
```

**Modifiers**

- `.accent` — Semantic color of the ribbon; `nil` restores the default (`.primary`).
- `.color` — Semantic color of the ribbon (back-compat); prefer `accent(_:)`.

## CountdownTimer

A token-bound live countdown to `deadline`.

```swift
CountdownTimer(until:)
```

**Modifiers**

- `.style` — standard / urgent colour treatment.
- `.format` — Layout: boxed / inline / text.
- `.size` — Size tier: small / medium / large.
- `.showsDays` — Shows a leading days box (default false — HH rolls days into hours).
- `.urgentBelow` — Auto-escalates to the urgent palette once fewer than `seconds` remain, and pulses on the final 10 seconds (no-op under Reduce Motion).
- `.onFinish` — Called once when the deadline passes (also immediately if already past).

## DescriptionModal

```swift
DescriptionModal(text)
```

**Modifiers**

- `.textAlignment` — Align the wrapped body text (default `.leading`, which mirrors under RTL).
- `.a11yID` — Namespaced accessibility identifier for UI tests (the text gets `"<id>.message"`).

## DividerView

A theme-driven divider: horizontal / vertical, solid / dashed, with an optional inline text label (left / center / right).

```swift
init(_ title: String? = nil)

// usage: DividerView()
```

**Modifiers**

- `.size` — Thickness tier of the (non-titled, non-dashed) divider: small / medium / large.
- `.axis` — Orientation: horizontal (default) or vertical.
- `.dashed` — Render the line as a dashed stroke.
- `.titleAlign` — Inline title placement: leading / center / trailing.

## FareFeatureRow

```swift
FareFeatureRow(feature)
```

**Modifiers**

- `.icon` — Overrides the feature model's SF Symbol; `nil` restores the model's own icon.
- `.accent` — Token-fed icon tint; `nil` keeps the status-driven colour.

## GaugeView

```swift
init(value: Double, in range: ClosedRange<Double> = 0...1, label: String? = nil)

// usage: GaugeView(value: 1)
```

**Modifiers**

- `.gaugeStyle` — Gauge rendering: circular (default) or linear.
- `.showsValue` — Toggle the inline percentage value readout.

## HelperText

```swift
HelperText(text)
```

**Modifiers**

- `.hasError` — Render the helper text in the error color (maps HeroUI `isInvalid`).
- `.hidesOnError` — Remove the helper text entirely while `hasError` is set, so a field-error line can take its place (maps HeroUI `hideOnInvalid`).
- `.links` — Turn substrings of the text into inline tappable links (rendered via `InlineText`) — e.g.
- `.a11yID` — Namespaced accessibility identifier for UI tests (the text gets `"<id>.message"`).

## Icon

Icon system.

```swift
init(systemName: String)

// usage: Icon(systemName: "systemName")
```

**Modifiers**

- `.size` — Size tier: xs / sm / md / lg / xl (12/16/20/24/32 pt).
- `.accent` — Semantic tint; `nil` (default) inherits the surrounding `foregroundStyle`.
- `.color` — Raw tint override (back-compat); prefer `accent(_:)`.

## IconTile

```swift
IconTile(systemImage)
```

**Modifiers**

- `.size`
- `.iconSize`
- `.background` — Tile background (token key, default `.bgElevatorTertiary`).
- `.iconColor` — Icon colour (text token key).
- `.accent` — Brand-tint the tile (bg = accent.bg, icon = accent.base).
- `.cornerRadius`

## InlineText

```swift
init(_ text: String, links: [(substring: String, action: () -> Void)] = [])

// usage: InlineText("text")
```

**Modifiers**

- `.accent` — Semantic base text color; `nil` (default) uses the theme's secondary text color.
- `.color` — Raw base text color (back-compat); prefer `accent(_:)`.
- `.inlineStyle` — Typography token for the body text.

## InputLabel

```swift
init(_ text: String)

// usage: InputLabel("text")
```

**Modifiers**

- `.required` — Append a required asterisk after the label text.
- `.links` — Turn substrings of the label into inline tappable links (rendered via `InlineText`) — e.g.
- `.hasInfo` — Show a trailing info glyph.
- `.onInfo` — Make the trailing info glyph tappable, capturing the tap via `action` (e.g.
- `.infoTooltip` — Attach a tooltip to the trailing info glyph, turning it into a tap-to-reveal target that shows `text` for secondary context (the HeroUI Label "show tooltip" affordance).
- `.hasError` — Render the label in the error color.

## Join

```swift
init(_ axis: Axis = .horizontal, @ViewBuilder content: () -> Content)

// usage: Join(@ViewBuilder: { })
```

**Modifiers**

- `.axis` — Layout axis of the joined controls.

## Kbd

```swift
init(_ text: String)

// usage: Kbd("text")
```

**Modifiers**

- `.size` — Size tier: xs / sm / md (default) / lg — scales font, cap side and padding.

## PointsBadge

A token-bound loyalty-points pill.

```swift
PointsBadge(points)
```

**Modifiers**

- `.unit` — The points unit, e.g.
- `.style` — earn / redeem / balance colour treatment.
- `.size` — Size tier: small / medium / large.
- `.icon` — Leading SF Symbol (default `star.circle.fill`).
- `.showsSign` — Shows a leading `＋` on earned points (default true).
- `.animatesValue` — Animates digit changes (numeric-text transition); no-op under Reduce Motion.

## PriceTag

A token-bound price label.

```swift
PriceTag(amount, currencyCode:)
```

**Modifiers**

- `.original` — A struck-through original price shown before the current one (enables the discount badge maths).
- `.originalBelow` — Stacks the struck compare-at price *below* the amount (design-system vertical form) instead of inline before it.
- `.unit` — A per-unit suffix, e.g.
- `.size` — Size tier: small / medium / large / xlarge.
- `.emphasis` — Colour emphasis of the headline price.
- `.discountBadge` — Shows a `-NN%` badge computed from the original vs current price.
- `.fractionDigits` — Decimal places to render (default 0 — travel prices are usually whole).
- `.free` — Renders "Free" instead of the amount.
- `.soldOut` — Renders "Sold out" instead of the amount.
- `.prefix` — Prefixes the price, e.g.
- `.from` — Shorthand for `.prefix("from")` — a "lead-in" price.
- `.animatesValue` — Animates digit changes (numeric-text transition); no-op under Reduce Motion.

## ProgressBar

Linear determinate progress with status colors, an optional ladder gradient, a segmented (steps) variant and a custom format label.

```swift
init(value: Double)

// usage: ProgressBar(value: 1)
```

**Modifiers**

- `.showsPercentage` — Draw the percentage label next to the bar.
- `.status` — Semantic state driving the fill color (normal / success / exception / active).
- `.barHeight` — Bar thickness in points (default 8).
- `.gradient` — Fill with a status gradient instead of a solid color.
- `.steps` — Render as a segmented (stepped) bar with this many segments.
- `.accent` — Semantic fill override; `nil` (default) keeps the status-derived fill.
- `.colors` — Raw fill/track overrides (back-compat); prefer `accent(_:)` for the fill.
- `.successSegment` — A 0...1 portion drawn in the success color on top of the fill (Ant `success.percent`).
- `.valueFormat` — Custom formatter for the percentage label (receives the 0...1 value).
- `.progressLabel` — VoiceOver name for the bar (e.g.

## StepIndicator

Segmented step indicator (e.g.

```swift
init(current: Int, total: Int)

// usage: StepIndicator(current: 1, total: 1)
```

## QRCode

A token-sized (but high-contrast) QR code.

```swift
QRCode(value)
```

**Modifiers**

- `.size` — Rendered size in points (square).

## RadialProgress

```swift
init(_ value: Double)

// usage: RadialProgress(1)
```

**Modifiers**

- `.size` — Diameter of the ring, in points.
- `.lineWidth` — Stroke width of the ring.
- `.showsLabel` — Show or hide the center label (percentage / success-fail glyph).
- `.status` — Semantic status driving the fill color and success/exception glyphs.
- `.dashboard` — Dashboard (gapped) ring variant.
- `.accent` — Semantic tint for the ring fill and glyphs; `nil` (default) derives from `status`.
- `.ringColor` — Raw ring fill override (back-compat); prefer `accent(_:)`.
- `.a11yLabel` — Spoken VoiceOver label for the ring (the value is announced separately).

## Rating

Star rating with two layouts (stars / numeric-leading), continuous fractional fill (display) or half-step interaction, a tappable review count, a custom character and a disabled state.

```swift
init(value: Double)

// usage: Rating(value: 1)
```

**Modifiers**

- `.layout` — Rating presentation: stars / numberRate / rateNumberText (default .stars).
- `.countLabel` — Review count label shown next to the rating (e.g.
- `.maxValue` — Number of glyphs / the score denominator (default 5).
- `.starSize` — Glyph point size (default 16).
- `.allowHalf` — Enables half-step interaction (and half-star tap targets).
- `.allowClear` — Re-tapping the current value clears the rating to 0 (Ant Rate `allowClear`) — interactive star layout only; VoiceOver users reach 0 through the adjustable decrement as before.
- `.symbol` — Overrides the SF Symbol used for the glyph (default "star").
- `.sentiment` — Sentiment word for the `.rateNumberText` layout (otherwise score-derived).
- `.onRate` — Makes the rating interactive: the closure receives the newly tapped value.
- `.onReviewTap` — Makes the review count label a tappable link.

## RemoteImage

Async remote image on native `AsyncImage` (no Kingfisher dependency): URL + aspect ratio (number or "16:9" string) + shimmer placeholder + failure state.

```swift
init(_ url: URL?)

// usage: RemoteImage(<URL>)
```

**Modifiers**

- `.ratio` — Numeric aspect ratio (width / height).
- `.contentMode` — How the image fills its ratio box: fill (default) or fit.
- `.cornerRadius` — Corner radius of the clip shape (ignored when `.circle()`).
- `.circle` — Clip to a circle instead of a rounded rectangle.
- `.altText` — Accessibility alt text.

## RollingNumber

Odometer / slot-machine number — each digit column rolls vertically to its new value when `value` changes (reference `RollingText`).

```swift
init(_ value: Int)

// usage: RollingNumber(1)
```

**Modifiers**

- `.size` — Digit point size.
- `.weight` — Font weight of the rolling digits.
- `.accent` — Semantic digit color; `nil` (default) uses `textPrimary`.
- `.color` — Raw digit color override (back-compat); prefer `accent(_:)`.

## ScoreBadge

```swift
init(_ score: Double, large: Bool = false)

// usage: ScoreBadge(1)
```

**Modifiers**

- `.size` — Size tier: small (default) / large — the kit's uniform size-enum axis.
- `.large` — Larger box + type — the boolean twin of the init's `large:` flag.
- `.accent` — Token-fed fill override (content auto-contrasts); `nil` keeps the stock turquoise token.

## SearchBadge

```swift
SearchBadge(text)
```

**Modifiers**

- `.colors` — Recolour the pill from theme token keys (background and/or text).
- `.icon` — A leading SF Symbol inside the pill.

## ShareButton

```swift
init(_ title: String = "Share", item: String)

// usage: ShareButton(item: "item")
```

**Modifiers**

- `.icon` — SF Symbol on the label (default `square.and.arrow.up`).
- `.size` — Kit button size ramp (height / padding / type); unset keeps the stock 44 pt chrome.
- `.accent` — Token-fed fill (label auto-contrasts); `nil` keeps the hero fill.

## Skeleton

A standalone skeleton block of an arbitrary shape and size.

```swift
init(_ shape: SkeletonShape = .rounded(8))

// usage: Skeleton()
```

**Modifiers**

- `.size` — Fixed block size in points; `nil` leaves that axis unconstrained.
- `.variant` — Animation variant: `.shimmer` (default) · `.pulse` · `.none`.
- `.highlight` — Tints the shimmer sweep with a semantic color's soft shade; `nil` restores the default token highlight.

## SkeletonGroup

Drives every group-bound skeleton in `content` from one loading flag.

```swift
SkeletonGroup(content:)
```

**Modifiers**

- `.loading` — Drive every group-bound skeleton below from this one flag (same verb as `ListView.loading()` / `Card.loading()`).
- `.skeletonOnly` — Mark the group as a pure placeholder (HeroUI `isSkeletonOnly`): its content exists only to lay out skeleton blocks, so when loading ends the whole group renders `EmptyView` and its layout wrappers collapse.

## Spinner

```swift
init()

// usage: Spinner()
```

**Modifiers**

- `.style` — Loading shape: ring (default) / dots / bars / ball / infinity.
- `.size` — Diameter in points; unset (default) follows `.controlSize(_:)` (regular = 24).
- `.lineWidth` — Stroke thickness in points, used by the ring and infinity shapes; unset (default) follows `.controlSize(_:)` (regular = 3).
- `.accent` — Semantic tint; `nil` (default) uses the theme's hero foreground.
- `.color` — Raw tint override (back-compat); prefer `accent(_:)`.

## StatusDot

```swift
init(_ kind: StatusKind, label: String? = nil)

// usage: StatusDot(<StatusKind>)
```

**Modifiers**

- `.size` — Dot diameter.
- `.pulse` — Animate an expanding pulse ring around the dot.

## SurfaceView

```swift
SurfaceView(content:)
```

**Modifiers**

- `.level` — Surface level: primary / secondary / tertiary background token, or transparent (no fill, no shadow).
- `.elevation` — Token shadow: none (default) / soft / elevated.
- `.radius` — Radius role for the container corner (default `.box`).
- `.contentPadding` — Inner content padding by spacing token (default `.md`); named so it doesn't shadow the native `.padding`.

## Swap

```swift
init(isOn: Binding<Bool>)

// usage: Swap(isOn: $isOn)
```

**Modifiers**

- `.symbols` — The two SF Symbols swapped between: `on` (shown when toggled on) and `off`.
- `.size` — Glyph point size.
- `.rotate` — Toggle the rotate-in/out transition between the two glyphs.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## SwapButton

```swift
SwapButton(systemImage, action:)
```

**Modifiers**

- `.size` — Button diameter in points (default 34).
- `.bordered` — Draw the 1pt border (default true).

## Tag

```swift
init(_ text: String, onRemove: (() -> Void)? = nil)

// usage: Tag("text")
```

**Modifiers**

- `.size` — Control size: small / large (shares Chip's ``ChipSize`` ramp) — drives the text style and token-derived paddings.
- `.icon` — Leading SF Symbol.
- `.tagStyle` — Semantic color treatment (Ant Tag colors).
- `.variant` — Fill variant: soft / solid / outline / ghost.
- `.color` — Color the tag from the full semantic palette (Ant Tag `color`) — reaches hues beyond ``tagStyle(_:)``'s status set (e.g.
- `.bordered` — Add a hairline border to a soft/solid tag (Ant `bordered`).
- `.closable` — Make the tag removable, appending the kit ``CloseButton`` after the text/trailing slot (Ant Tag `closable` + `onClose`) — the modifier twin of the `onRemove:` init argument, rendering the standard dismiss atom (muted glyph + full hit slop) instead of the bare glyph.

## CheckableTag

Ant's **CheckableTag** — a tag that toggles a bound boolean, like a lightweight selectable filter.

```swift
CheckableTag(text, isChecked:)
```

**Modifiers**

- `.icon` — Leading SF Symbol.
- `.color` — Fill color when checked (Ant CheckableTag stays hero; override per brand).

## TextLink

```swift
init(_ title: String, action: @escaping () -> Void)

// usage: TextLink("title", action: { })
```

**Modifiers**

- `.underline` — Underline the link text (default true); pass `false` for a plain link.
- `.accent` — Semantic tint for the link text; `nil` (default) uses the theme's hero text token.

## TextRotate

```swift
init(_ words: [String], interval: Double = 2)

// usage: TextRotate("words")
```

**Modifiers**

- `.textStyle` — Design-system type ramp for the rotating word (default `.headingSm`).
- `.accent` — Token-fed tint for the rotating word; `nil` keeps the hero text token.
- `.interval` — Seconds between words (clamped to ≥ 0.1) — the chainable twin of the init's `interval:` parameter.

## TiltCard

```swift
TiltCard(content:)
```

**Modifiers**

- `.maxAngle` — Maximum tilt from rest when the finger reaches an edge (default 10°).
- `.shine` — Adds a specular highlight that follows the touch point (default off).
- `.radius` — Corner radius role used to clip the shine highlight (default `.box`).

## Title

```swift
init(_ text: String)

// usage: Title("text")
```

**Modifiers**

- `.subtitle` — Secondary line rendered under the title.
- `.eyebrow` — Uppercased kicker rendered above the title.
- `.action` — Trailing action link (e.g.

## TrendChip

```swift
TrendChip(trend)
```

**Modifiers**

- `.positiveIsUp` — Whether an upward trend is the good (success-tinted) outcome.
- `.showsIcon` — Show or hide the directional arrow glyph (default on).
- `.size` — Text/glyph scale — `.small` (12pt label) matches `Stat`'s inline badge; `.medium` (14pt, default) reads well standalone.

## FlightStatusBadge

```swift
FlightStatusBadge(status)
```

**Modifiers**

- `.time` — A trailing time, e.g.
- `.label` — Override the label text.
- `.showsIcon` — Show the leading icon (default on).
- `.solid` — Solid fill (vs the default soft tint).
- `.emphasis`
- `.size` — Size ramp (default `.medium`, 24 pt).
- `.shape` — Corner treatment — `.capsule` (default) or `.rounded` at the selector radius role.
- `.pulses` — Opt-in gentle opacity pulse for urgent statuses (boarding, gate closing).
- `.icon` — Per-instance glyph override; `nil` hides the icon (≡ `showsIcon(false)`).

## SeatCell

```swift
SeatCell(seat, size:, isSelected:, isSelectable:, isRecommended:, assignedInitials: …)
```

---

# Molecules (110)

_Compositions of atoms — inputs, buttons, selectors, small layouts._

## Affix

```swift
Affix(offsetTop:, content:)
```

**Modifiers**

- `.onChange` — Fires when the pinned state changes (Ant Affix `onChange`).
- `.target` — Measure the offset within a named scroll container instead of the screen (Ant Affix `target`) — set the same name via `.coordinateSpace(name:)` on the enclosing `ScrollView`.

## AmenityGrid

A token-bound amenity grid.

```swift
AmenityGrid(amenities)
```

**Modifiers**

- `.columns` — Number of columns (default 2).
- `.size` — Size tier: small / medium / large.
- `.tint` — Overrides the icon tint (otherwise the theme accent).
- `.limit` — Shows only the first `count`, with a "+N more" expander for the rest.
- `.highlighted` — Amenities (by label) to emphasise in the accent colour.

## AnchorNav

```swift
AnchorNav(items, active:)
```

**Modifiers**

- `.onSelect` — Called when a link is tapped — wire to `proxy.scrollTo(id, anchor: .top)`.
- `.direction` — Lay the rail out horizontally (Ant Anchor `direction`).

## Autocomplete

```swift
init(_ label: String? = nil, text: Binding<String>, suggest: @escaping nonisolated(nonsending) (String) async -> [String], onSelect: @escaping (String) -> Void = { _ in })

// usage: Autocomplete(text: $text)
```

**Modifiers**

- `.placeholder` — Placeholder shown while the field is empty.
- `.maxResults` — Caps the number of suggestion rows (default 5).
- `.debounce` — Debounce interval for typeahead (async init defaults to 0.3s).
- `.suggestionEnabled` — Per-suggestion enable predicate; disabled rows are shown greyed and unselectable.
- `.onSearch` — Fires with the query text on each (debounced) change.
- `.size` — Control-height preset.
- `.clearable` — Show a trailing clear button while the field has text (on by default — Autocomplete's classic behavior; pass `false` to hide it).
- `.loading` — Shows a loading spinner in place of the clear button (caller-driven async option fetch; the built-in async provider spins automatically).
- `.infoMessages` — Validation / info messages rendered under the field (drives the border state).
- `.required` — Marks the field required: an error-token asterisk on the label (honoring `FieldDefaults.requiredIndicator`) and ", required" in the a11y label.
- `.validate` — Declarative validation (daisyUI Validator): `rules` run against the bound text at `trigger` (`.editingEnd` on blur, `.live` per keystroke, `.submit` on return).
- `.onValidation` — Reports validity after each `validate(_:on:)` pass — `true` when no error-severity failure is present.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## Breadcrumbs

```swift
init(_ crumbs: [Breadcrumbs.Crumb], maxItems: Int? = nil)

// usage: Breadcrumbs(<[Breadcrumbs.Crumb]>)
```

**Modifiers**

- `.separator` — SF Symbol drawn between crumbs (default `chevron.right`; mirrors in RTL).
- `.accent` — Token-fed tint for the current (last) crumb; `nil` keeps the primary text token.

## ButtonGroup

```swift
init(_ axis: ButtonGroupAxis = .vertical, @ViewBuilder content: @escaping () -> Content)

// usage: ButtonGroup(@ViewBuilder: <@escaping () -> Content>)
```

**Modifiers**

- `.axis` — Layout axis — a vertical stack or a wrapping side-by-side row.
- `.size` — Group size (HeroUI ButtonGroup `size`) — the shared ``ButtonSize`` token (`xxsmall … xxlarge`) every button inherits unless it set its own `.size(_:)`: `ButtonGroup { … }.size(.large)`.
- `.width` — Width behavior (HeroUI ButtonGroup `width`) — `.hug` (default) wraps tightly around the buttons; `.fill` stretches the group to the available width and distributes the buttons evenly.
- `.dividers` — Draw a hairline between adjacent buttons (HeroUI ButtonGroup dividers).
- `.dividerColor` — Tint the between-button dividers to match the buttons' context (HeroUI Divider `variant`) — pass a semantic color token; `nil` keeps the neutral theme border.

## PrimaryButton

```swift
init(_ title: String, action: @escaping () -> Void)

// usage: PrimaryButton("title", action: { })
```

**Modifiers**

- `.size` — Control size: xxsmall … large.
- `.fullWidth` — Stretch to the available width.
- `.helperText` — Caption rendered under the button.
- `.titleTextStyle` — Override the title's text style (defaults to the size's style).
- `.confirmsSuccess` — Morph the label into a success checkmark after the action completes (default: on for `task:`, off for `action:`).
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.
- `.loading` — Swap the label for a spinner and block taps while `on`.

## SecondaryButton

```swift
init(_ title: String, action: @escaping () -> Void)

// usage: SecondaryButton("title", action: { })
```

**Modifiers**

- `.size` — Control size: xxsmall … large.
- `.fullWidth` — Stretch to the available width.
- `.helperText` — Caption rendered under the button.
- `.titleTextStyle` — Override the title's text style (defaults to the size's style).
- `.confirmsSuccess` — Morph the label into a success checkmark after the action completes (default: on for `task:`, off for `action:`).
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.
- `.loading` — Swap the label for a spinner and block taps while `on`.

## OutlineButton

```swift
init(_ title: String, action: @escaping () -> Void)

// usage: OutlineButton("title", action: { })
```

**Modifiers**

- `.size` — Control size: xxsmall … large.
- `.fullWidth` — Stretch to the available width.
- `.helperText` — Caption rendered under the button.
- `.titleTextStyle` — Override the title's text style (defaults to the size's style).
- `.confirmsSuccess` — Morph the label into a success checkmark after the action completes (default: on for `task:`, off for `action:`).
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.
- `.loading` — Swap the label for a spinner and block taps while `on`.

## GhostButton

```swift
init(_ title: String, action: @escaping () -> Void)

// usage: GhostButton("title", action: { })
```

**Modifiers**

- `.size` — Control size: xxsmall … large.
- `.fullWidth` — Stretch to the available width.
- `.helperText` — Caption rendered under the button.
- `.titleTextStyle` — Override the title's text style (defaults to the size's style).
- `.confirmsSuccess` — Morph the label into a success checkmark after the action completes (default: on for `task:`, off for `action:`).
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.
- `.loading` — Swap the label for a spinner and block taps while `on`.

## LinkButton

```swift
init(_ title: String, action: @escaping () -> Void)

// usage: LinkButton("title", action: { })
```

**Modifiers**

- `.size` — Control size: xxsmall … large.
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.

## TertiaryButton

Minimal-emphasis button (HeroUI `tertiary`) — a subtle tinted surface, typically paired alongside a primary or secondary action.

```swift
TertiaryButton(title, action:)
```

**Modifiers**

- `.size` — Control size: xxsmall … large.
- `.fullWidth` — Stretch to the available width.
- `.helperText` — Caption rendered under the button.
- `.titleTextStyle` — Override the title's text style (defaults to the size's style).
- `.confirmsSuccess` — Morph the label into a success checkmark after the action completes (default: on for `task:`, off for `action:`).
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.
- `.loading` — Swap the label for a spinner and block taps while `on`.

## DangerButton

Solid destructive button (HeroUI `danger`) — for irreversible actions (delete, remove).

```swift
DangerButton(title, action:)
```

**Modifiers**

- `.size` — Control size: xxsmall … large.
- `.fullWidth` — Stretch to the available width.
- `.helperText` — Caption rendered under the button.
- `.titleTextStyle` — Override the title's text style (defaults to the size's style).
- `.confirmsSuccess` — Morph the label into a success checkmark after the action completes (default: on for `task:`, off for `action:`).
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.
- `.loading` — Swap the label for a spinner and block taps while `on`.

## DangerSoftButton

Lower-emphasis destructive button (HeroUI `dangerSoft`) — a soft red tint for cautionary actions where urgency is lower than a solid ``DangerButton``.

```swift
DangerSoftButton(title, action:)
```

**Modifiers**

- `.size` — Control size: xxsmall … large.
- `.fullWidth` — Stretch to the available width.
- `.helperText` — Caption rendered under the button.
- `.titleTextStyle` — Override the title's text style (defaults to the size's style).
- `.confirmsSuccess` — Morph the label into a success checkmark after the action completes (default: on for `task:`, off for `action:`).
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.
- `.loading` — Swap the label for a spinner and block taps while `on`.

## ThemeButton

```swift
init(_ title: String? = nil, action: @escaping () -> Void)

// usage: ThemeButton(action: { })
```

**Modifiers**

- `.variant` — Visual treatment: solid / soft / outline / ghost / link.
- `.color` — Semantic color token driving the fill/accent ladder (R4).
- `.size` — Control size: xxsmall … large.
- `.shape` — Corner treatment: rounded / pill / circle / square (circle & square are icon-only).
- `.fullWidth` — Stretch to the available width.
- `.loading` — Show the loading spinner and block taps while `on`.
- `.spinnerPlacement` — Keep the label while loading and render the spinner beside it on the given edge (HeroUI `spinnerPlacement="start"/"end"`; Ant Button `loading: { icon }`).
- `.icon` — Leading and/or trailing SF Symbol.
- `.density` — Height/padding density: `.regular` (touch, default) or `.compact` (web/HeroUI — sm/md/lg == compact small/medium/large).
- `.iconOnly` — Render as a square-footprint icon-only button at the current shape's corner — decoupled from `.circle`/`.square` (HeroUI `iconOnly`).
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.

## CalendarView

```swift
init(selection: Binding<Date?>)

// usage: CalendarView(selection: $selection)
```

**Modifiers**

- `.accent` — Token-fed accent for the selected day (today's ring/text follows the same ladder); `nil` (default) keeps the hero tokens.
- `.showsWeekdayHeader` — Show or hide the weekday-initials row (default on).
- `.firstWeekday` — Override the first day of the week — `1` = Sunday … `7` = Saturday (clamped); `nil` (default) follows the locale's convention.
- `.yearPicker` — Make the month-year header tappable to jump across months and years: day grid → year grid → month grid, then back to the chosen month.
- `.disabledDates` — Greys out and blocks every day the predicate returns `true` for (Ant `disabledDate`) — e.g.

## CalendarYearPicker

```swift
CalendarYearPicker(selection:)
```

**Modifiers**

- `.range` — Selectable year range; years outside it are dimmed and disabled.
- `.accent` — Token-fed accent for the selected year (the current-year ring/text follows the same ladder); `nil` (default) keeps the hero tokens.

## Cascader

```swift
Cascader(options, selection:)
```

**Modifiers**

- `.placeholder` — Hint shown when nothing is selected.
- `.size` — Control-height preset (Ant `size` large/middle/small).
- `.changeOnSelect` — Commit the path at every level, not only on a leaf (Ant `changeOnSelect`).
- `.clearable` — Show a trailing clear button when a path is selected (Ant `allowClear`).
- `.searchable` — Add a search field atop the dropdown; typing filters to a flat list of matching leaf paths (Ant `showSearch`).
- `.nodeEnabled` — Per-node enable predicate; disabled nodes are greyed, unselectable, and excluded from search results (kit-standard `optionEnabled` idiom).
- `.infoMessages` — Validation / info messages rendered under the field (drives the border state).

## AreaChart

```swift
AreaChart(series)
```

**Modifiers**

- `.height` — Chart height — `.compact` / `.regular` (default) / `.tall`.
- `.showsLegend` — Force the legend on/off; default shows it for two or more series.
- `.showsGrid` — Hairline grid lines (default on).
- `.curved` — Monotone curve interpolation instead of straight segments (default off).
- `.stacked` — Stack the series into cumulative bands instead of overlaid washes.
- `.locale` — Locale for value/tick formatting; defaults to the environment locale.

## BarChart

```swift
BarChart(series)
```

**Modifiers**

- `.height` — Chart height — `.compact` / `.regular` (default) / `.tall`.
- `.showsLegend` — Force the legend on/off; default shows it for two or more series.
- `.showsGrid` — Hairline grid lines (default on).
- `.mode` — `.grouped` (default) places series side by side; `.stacked` sums them.
- `.locale` — Locale for value/tick formatting; defaults to the environment locale.

## DonutChart

```swift
DonutChart(slices)
```

**Modifiers**

- `.height` — Chart height — `.compact` / `.regular` (default) / `.tall`.
- `.innerRadius` — Hole size — `.pie` (no hole) / `.ring` (default) / `.thin`.
- `.locale` — Locale for value formatting; defaults to the environment locale.

## LineChart

```swift
LineChart(series)
```

**Modifiers**

- `.height` — Chart height — `.compact` / `.regular` (default) / `.tall`.
- `.showsLegend` — Force the legend on/off; default shows it for two or more series.
- `.showsGrid` — Hairline grid lines (default on).
- `.curved` — Monotone curve interpolation instead of straight segments (default off).
- `.showsPoints` — Draw a marker at every data vertex (default off).
- `.locale` — Locale for value/tick formatting; defaults to the environment locale.

## Checkbox

Figma "Control Items" → Checkboxes.

```swift
init(_ label: String? = nil, isChecked: Binding<Bool>)

// usage: Checkbox(isChecked: $isChecked)
```

**Modifiers**

- `.type` — Visual style of the box: `.plain`, `.inner`, or `.customInner(color:)`.
- `.variant` — Surface treatment of the box: `.primary` (default — border-only, for regular backgrounds) or `.secondary` (soft fill for elevated surfaces).
- `.description` — Supporting description rendered under the title (Figma "Description").
- `.customInner` — Always fills the box with a semantic swatch (the `.customInner` type), resolved from the token's solid role — the token-bound path.
- `.indeterminate` — Renders the indeterminate (mixed) state instead of a checkmark.
- `.alignment` — Vertical alignment of the box against a multi-line label.
- `.controlPlacement` — Which side of the label the box sits on: `.leading` (default) or `.trailing`.
- `.lineThrough` — Strikes the label through while checked (HeroUI Checkbox `lineThrough`).
- `.customSize` — Overrides the box side length, bypassing the native `.controlSize` metric.
- `.accent` — Semantic tint for the selected fill/border (glyph auto-contrasts); `nil` (default) uses the hero tokens.
- `.infoMessages` — Validation / info messages rendered under the control (drives the border state).
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## CheckboxGroup

```swift
init(title: String? = nil, options: [Option], selection: Binding<Set<Option>>, label: @escaping (Option) -> String)

// usage: CheckboxGroup(options: <[Option]>, selection: $selection, label: "label")
```

**Modifiers**

- `.infoMessages` — Validation / info messages rendered under the group (drives the title color).
- `.selectAll` — Adds a "select all" master row with the given title (nil hides it).
- `.description` — Group-level supporting text rendered under the title via `HelperText` (Ant/HeroUI group `description`; E5).
- `.required` — Marks the whole group required: an error-token asterisk after the title (honoring `FieldDefaults.requiredIndicator`) and ", required" in the title's a11y label.
- `.axis` — Layout axis of the option rows: `.vertical` (default) or `.horizontal`.
- `.controlPlacement` — Which side of each row's label the box sits on: `.leading` (default) or `.trailing`, forwarded to every option row and the "select all" row.
- `.optionEnabled` — Per-option enablement predicate (nil enables every option).
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## ImageChip

A selectable remote-image tile with a selection border.

```swift
init(isSelected: Binding<Bool>, url: URL?)

// usage: ImageChip(isSelected: $isSelected, url: <URL>)
```

**Modifiers**

- `.size` — Tile size: small / medium / large.

## CompactChip

A selectable card: an optional rating + label row, then an optional logo + price row.

```swift
init(_ text: String, price: String, isSelected: Binding<Bool>)

// usage: CompactChip("text", price: "price", isSelected: $isSelected)
```

**Modifiers**

- `.imageURL` — Remote logo image shown next to the price.
- `.rating` — Star rating shown before the label (nil hides it).

## ChoseChip

A selectable card: a leading icon, a title with an optional "free" gradient badge, and a rating + description row.

```swift
init(_ title: String, isSelected: Binding<Bool>)

// usage: ChoseChip("title", isSelected: $isSelected)
```

**Modifiers**

- `.description` — Secondary line shown under the title.
- `.rating` — Star rating shown before the description (nil hides it).
- `.free` — Show the gradient "free" badge next to the title (optionally with a custom label).
- `.icon` — Leading SF Symbol shown before the texts.

## FilterChip

A dismissible filter chip in a pill (with a soft shadow) or square shape.

```swift
init(_ title: String, onDismiss: (() -> Void)? = nil)

// usage: FilterChip("title")
```

**Modifiers**

- `.shape` — Chip shape: pill (with a soft shadow) or square.
- `.closable` — Whether to show the trailing close button (default true).

## ChipGroup

A horizontally-scrolling, multi-select chip group backed by a `Set` binding.

```swift
init(title: String? = nil, options: [Option], selection: Binding<Set<Option>>, label: @escaping (Option) -> String)

// usage: ChipGroup(options: <[Option]>, selection: $selection, label: "label")
```

**Modifiers**

- `.chipStyle` — Visual style applied to every chip (matches `Chip.chipStyle`).
- `.optionEnabled` — Per-option enablement predicate (nil enables every option).
- `.removable` — Appends a trailing remove button to every chip; the callback receives the option to remove (HeroUI TagGroup `onRemove`).
- `.infoMessages` — Validation / info messages rendered under the chips (drive the title color).

## ColorArea

```swift
ColorArea(color:)
```

**Modifiers**

- `.cornerRadius` — Corner rounding, token-typed — default `.field`; capped to the plane height so a large role never over-rounds a short area.

## ColorField

```swift
init(_ label: String, selection: Binding<Color>)

// usage: ColorField("label", selection: $selection)
```

**Modifiers**

- `.supportsOpacity` — Whether the color well lets the user adjust opacity (defaults to true).
- `.size` — Control-height preset.

## ColorSlider

```swift
ColorSlider(channel, color:)
```

**Modifiers**

- `.trackHeight` — Track thickness — `.regular` (28pt, default) or `.compact` (16pt).

## ColorSwatchPicker

```swift
ColorSwatchPicker(items, selection:)
```

**Modifiers**

- `.columns` — Fixed column count (a `LazyVGrid`); `nil` (default) wraps with a `FlowLayout` sized to the container width.
- `.swatchShape` — Shape of every swatch (default `.square`).
- `.swatchSize` — Size of every swatch (default `.medium`).

## ColumnsGrid

```swift
ColumnsGrid(content:)
```

**Modifiers**

- `.columns` — Fixed number of equal columns.
- `.adaptive` — Fit as many columns as the width allows, each at least `minWidth` wide (Ant responsive Col).
- `.gutter` — Gap between cells, from a preset size (Ant Row `gutter`).

## ControlRow

```swift
ControlRow(title, isOn:)
```

**Modifiers**

- `.description` — Supporting text rendered under the label.
- `.control` — Which boolean control renders: `.toggle` (default), `.checkbox`, or `.radio`.
- `.controlPlacement` — Which side the control sits on: `.trailing` (default, switch-row style) or `.leading` (control-first, checkbox/radio style).
- `.indicator` — Replaces the built-in control with a custom trailing indicator view.
- `.required` — Append a required asterisk after the label text (via `InputLabel`).
- `.hasError` — Render the label + description in the error color and unlock the `errorText(_:)` line.
- `.errorText` — Validation message rendered under the row — shown only while `hasError`.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## CurrencyPicker

A token-bound currency picker.

```swift
CurrencyPicker(selection:, currencies:)
```

**Modifiers**

- `.showsName` — Shows the full currency name under the code (default true).
- `.searchable` — Adds a search field that filters by code or name.
- `.recents` — A "Recent" section shown above the full list (hidden while searching).

## DateField

```swift
init(_ label: String? = nil, date: Binding<Date?>)

// usage: DateField(date: $date)
```

**Modifiers**

- `.placeholder` — Placeholder shown while no date is selected.
- `.size` — Control-height preset.
- `.required` — Marks the field required: an error-token asterisk on the label (honoring `FieldDefaults.requiredIndicator`) and ", required" in the a11y label.
- `.validate` — Declarative validation (daisyUI Validator): `rules` run against the *displayed* date string (empty when no date is set) at `trigger` — `.editingEnd`/`.submit` fire when the picker is dismissed, `.live` on every change.
- `.onValidation` — Reports validity after each `validate(_:on:)` pass — `true` when no error-severity failure is present.
- `.range` — Restrict the picker to a selectable date range.
- `.style` — How the chosen date renders in the field (numeric / abbreviated / long / full / relative / custom).
- `.locale` — Override the formatting locale (defaults to the environment locale).
- `.components` — Which components the field shows and the picker edits (date / dateAndTime / time).
- `.infoMessages` — Validation / info messages rendered under the field (drives the border state).
- `.clearable` — Show a trailing clear button when a date is set.
- `.externalFocus` — Drive focus from outside (e.g.
- `.icon` — Leading SF Symbol shown inside the field.
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.

## Dropdown

```swift
Dropdown(items:, isPresented:, trigger:)
```

**Modifiers**

- `.edge` — Which corner of the trigger the panel opens from (default `.bottomLeading`).
- `.accent` — Semantic tint of the pressed-row highlight (default `.neutral`).
- `.menuWidth` — Fixed panel width in points; `nil` (default) fits the widest item.
- `.indicator` — The leading mark drawn on selected rows (default `.checkmark`).
- `.shouldCloseOnSelect` — Whether tapping an action row dismisses the menu (default `true`).

## EmojiReactionButton

```swift
EmojiReactionButton(emoji, count:, initiallyReacted:)
```

**Modifiers**

- `.size` — Control size: small (default) / medium / large — shares Chip's ``ChipSize`` vocabulary and drives the emoji/count sizes and paddings.
- `.accent` — Semantic tint for the reacted state (soft fill, border and count); `nil` (default) keeps the stock hero treatment.

## FieldButton

```swift
FieldButton(value, action:)
```

**Modifiers**

- `.label` — A small label above the value (form-field style).
- `.icon` — A leading SF Symbol.
- `.trailing` — The trailing accessory symbol (default `chevron.down`; pass `nil` to hide).
- `.placeholder` — Renders the value in the muted placeholder colour (nothing chosen yet).
- `.size` — Control-height preset.

## Fieldset

```swift
init(_ title: String, @ViewBuilder content: @escaping () -> Content)

// usage: Fieldset("title", @ViewBuilder: <@escaping () -> Content>)
```

**Modifiers**

- `.helper` — Helper text rendered under the content (nil hides it).

## FileInput

```swift
init(_ label: String? = nil, onPick: @escaping () -> Void)

// usage: FileInput(onPick: { })
```

**Modifiers**

- `.fileName` — The selected file's display name (the bound value shown beside the button).
- `.buttonTitle` — Title of the "choose file" segment.
- `.placeholder` — Placeholder shown when no file is chosen.
- `.infoMessages` — Validation / hint messages displayed below the field.
- `.onClear` — Trailing clear button handler (shown only when a file is selected).

## FilterGroup

```swift
init(title: String? = nil, options: [Option], selection: Binding<Option?>, label: @escaping (Option) -> String)

// usage: FilterGroup(options: <[Option]>, selection: $selection, label: "label")
```

**Modifiers**

- `.size` — Chip control size: small / large (default small).
- `.chipStyle` — How the selected chip is filled: tonal / solid (default solid).
- `.fullWidth` — Stretch the chips edge-to-edge instead of scrolling horizontally — for option sets known to fit the row.
- `.optionEnabled` — Per-option enablement predicate (nil enables every option).
- `.infoMessages` — Validation / info messages rendered under the chips (drive the title color).

## FilterRow

```swift
FilterRow(title, isOn:)
```

**Modifiers**

- `.count` — A trailing result count — hidden when nil or zero.
- `.icon` — An optional leading category icon (after the checkbox).
- `.showsSeparator` — Draw a hairline separator under the row.

## Flex

```swift
Flex(content:)
```

**Modifiers**

- `.direction` — Layout direction (Ant Flex `vertical`).
- `.vertical` — Stack the children vertically.
- `.gap` — Gap from a preset size (small / medium / large).
- `.justify` — Main-axis distribution (Ant Flex `justify`).
- `.align` — Cross-axis alignment (Ant Flex `align`).
- `.wrap` — Wrap onto multiple lines when horizontal (Ant Flex `wrap`).

## FlowLayout

```swift
FlowLayout(spacing:, lineSpacing:, alignment:, content:)
```

## GuestSelector

A token-bound rooms & guests picker.

```swift
GuestSelector(selection:)
```

**Modifiers**

- `.showsRooms` — Shows the Rooms row (default true — hide it for flight passenger pickers).
- `.showsInfants` — Shows the Infants row (default true).
- `.adultRange` — Allowed adult count.
- `.childRange` — Allowed children count.
- `.infantRange` — Allowed infant count.
- `.roomRange` — Allowed room count.
- `.maxTotal` — Caps the combined guest count (adults + children + infants) — e.g.
- `.onChange` — Called whenever the selection changes.

## InputAffix

The leading / trailing content of an ``InputGroup`` (Figma "Input Affix").

```swift
InputAffix(content, action:)
```

**Modifiers**

- `.icon` — Leading SF Symbol glyph (16pt).
- `.arrow` — Show a trailing selector arrow (chevron), e.g.
- `.emphasis` — Visual emphasis — `.mute` for passive units/hints, `.active` for interactive content.

## InputGroup

```swift
InputGroup(placeholder, text:)
```

**Modifiers**

- `.variant` — Surface variant — `.primary` (white + elevation) or `.secondary` (on-card muted).
- `.type` — Value kind — drives keyboard type and secure entry.
- `.gapSpaced` — Separate the affixes from the input with a divider + wider gap (Figma `gapSpace`).
- `.a11yID` — Stable accessibility identifier for UI tests.

## InputNumber

```swift
init(_ label: String? = nil, value: Binding<Int>, range: ClosedRange<Int> = 0...99)

// usage: InputNumber(value: $value)
```

**Modifiers**

- `.step` — Increment/decrement applied by the − / + steppers.
- `.precision` — Fraction digits shown and kept on commit (E11, Ant `precision`).
- `.unit` — Trailing unit suffix labelling the value (e.g.
- `.hint` — Helper text shown under the field (hidden while an error is present).
- `.errorText` — Error text + error styling; takes precedence over `hint`.
- `.size` — Control height on the field family's `TextInputSize` ramp (C2).
- `.required` — Marks the field as required: renders an error-token asterisk after the label (the `InputLabel` treatment, honoring the subtree `FieldDefaults.requiredIndicator`) and appends ", required" to the field's accessibility label (E2, HeroUI `isRequired`).
- `.validate` — Declarative validation (E3, TextInput parity): evaluates `rules` against the field's text at `trigger` and feeds the first failure into the message list / error styling automatically.
- `.large` — Legacy binary height (regular 40pt / large 48pt), superseded by the field family's size ramp.
- `.editable` — Whether the value can be typed (default true); `false` shows it read-only with steppers still active.
- `.hasInfo` — Shows an info-circle glyph next to the label.
- `.onValueChange` — Fires with the clamped value whenever it changes (stepper / type / commit).
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## InstallmentPicker

```swift
InstallmentPicker(options, selection:)
```

**Modifiers**

- `.currency` — Currency code for the amounts.
- `.accent`

## InstallmentSelector

A token-bound instalment plan picker.

```swift
InstallmentSelector(total:, options:, selection:, currencyCode:)
```

**Modifiers**

- `.interestFreeUpTo` — Instalment counts up to (and including) this are tagged "Interest-free".
- `.recommended` — Flags one plan as recommended with a badge.
- `.surcharge` — Per-plan surcharge (interest) added to the base total, keyed by instalment count.

## LanguageSwitcher

A token-bound app-language picker.

```swift
LanguageSwitcher(languages, selection:)
```

**Modifiers**

- `.variant` — Presentation archetype — `.menu` (default), `.list`, or `.inline`.
- `.showsFlags` — Shows a flag emoji before each name (default true).
- `.nativeNames` — Renders each language endonymically ("Deutsch", "العربية") — default true.
- `.accent` — Selection tint: explicit → subtree `componentDefaults` accent → the theme's hero foreground.

## MapPriceMarker

Chroma: while the environment carries the default ``ChipStyle`` the pill draws its own accent fill + border (pixel-identical to the pre-ChipStyle look — the built-ins don't know the marker's accent tokens).

```swift
MapPriceMarker(text)
```

**Modifiers**

- `.selected` — Selected/active state (accent fill + slight scale-up).
- `.accent` — Token-fed accent for the selected fill (default primary).
- `.icon` — A leading SF Symbol (e.g.
- `.pointer` — Show the downward pointer under the pill (default on).

## Masonry

```swift
Masonry(content:)
```

**Modifiers**

- `.columns` — Number of columns.
- `.spacing` — Gap between items, from a preset size.

## Mentions

```swift
Mentions(text:, options:)
```

**Modifiers**

- `.prefix` — The trigger character (Ant `prefix`).
- `.placeholder` — Placeholder shown when empty.
- `.size` — Control-height preset for the suggestion rows (the editor itself is multi-line and grows with content).

## MultiLineTextInput

Improved, token-bound rewrite of the reference MultiLineInput — a bordered TextEditor with header label, placeholder, character counter and error state.

```swift
init(_ label: String, text: Binding<String>)

// usage: MultiLineTextInput("label", text: $text)
```

**Modifiers**

- `.placeholder` — Placeholder shown while the editor is empty.
- `.characterLimit` — Caps the input length and shows a `count/limit` counter.
- `.countStyle` — How the character counter reads: `12/50` (`.count`, default) or `38 left` (`.remaining`) — TextInput parity.
- `.size` — Editor-height preset (`.xsmall` 80 … `.large` 160; defaults to `.medium`, 120).
- `.required` — Marks the editor as required: renders an error-token asterisk after the header label (the `InputLabel` treatment) and appends ", required" to the editor's accessibility label (HeroUI `isRequired`, TextInput parity).
- `.errorText` — Convenience error message appended as an `.error` `InfoMessage`.
- `.helperText` — Convenience hint appended to the message list as an `.info` `InfoMessage` (parity with `TextInput.helperText`).
- `.warningText` — Convenience warning appended to the message list as a `.warning` `InfoMessage` (parity with `TextInput.warningText`).
- `.infoMessages` — Validation / hint messages rendered beneath the editor.
- `.minHeight` — Minimum editor height (defaults to 120, R4); overrides the `size(_:)` preset.
- `.autosize` — Grows the editor with its content between `minRows` and `maxRows` lines, then scrolls (Ant `autoSize={{minRows,maxRows}}` / HeroUI `minRows`/`maxRows`).
- `.externalFocus` — Drive focus from outside (e.g.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## MultiSelect

Multiple / tags select with optional search (Ant Select mode="multiple").

```swift
init(_ label: String? = nil, options: [Option], selection: Binding<Set<Option>>, optionTitle: @escaping (Option) -> String)

// usage: MultiSelect(options: <[Option]>, selection: $selection, optionTitle: "optionTitle")
```

**Modifiers**

- `.allowsCustomTags` — Allow the user to create tags by typing free text and pressing return (Ant `mode="tags"`).
- `.placeholder` — Placeholder shown while nothing is selected.
- `.infoMessages` — Validation / info messages rendered under the field (drives the border state).
- `.optionEnabled` — Per-option enable predicate; disabled rows are shown greyed and unselectable.
- `.optionDescription` — Second line rendered under each option title in the dropdown rows (HeroUI `Select.ItemDescription`) — `.bodySm400` in the secondary text token.
- `.searchable` — Whether the dropdown shows a search field (default true).
- `.clearable` — Whether a clear-all button is offered (default true).
- `.maxTags` — Caps the visible selected-tag chips, collapsing the rest into a "+N" tag.
- `.maxSelection` — Caps how many options can be selected (E13, Ant `maxCount`).
- `.loading` — Shows a loading spinner in place of the chevron (async option fetch).
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## OTPInput

Improved, token-bound rewrite of the reference OTPInputView.

```swift
init(code: Binding<String>, onComplete: ((String) -> Void)? = nil)

// usage: OTPInput(code: $code)
```

**Modifiers**

- `.digitCount` — Number of digit boxes (default 6).
- `.characters` — Which characters the field accepts (default `.digits`).
- `.groups` — Splits the boxes into visual groups separated by a small dash, e.g.
- `.placeholder` — Per-slot placeholder: each empty, non-caret box shows the character at its position (e.g.
- `.size` — Control-height preset.
- `.secure` — Mask the entered digits (password-style dots) instead of showing them.
- `.errorText` — Inline error line (appended to `infoMessages` as `.error`, driving the error state).
- `.infoMessages` — Validation / hint messages displayed below the boxes.
- `.validate` — Declarative validation (daisyUI Validator): `rules` run against the entered code at `trigger` — `.editingEnd`/`.submit` fire when the last box fills (the OTP's completion moment), `.live` on every keystroke.
- `.onValidation` — Reports validity after each `validate(_:on:)` pass — `true` when no error-severity failure is present.
- `.resend` — Adds a countdown + "resend code" row.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## Pagination

```swift
init(current: Binding<Int>, total: Int)

// usage: Pagination(current: $current, total: 1)
```

**Modifiers**

- `.simple` — Compact "current / total" mode instead of the numbered page buttons.
- `.window` — Window size: `sibling` pages each side of the current page, `boundary` pages pinned at each end (gaps collapse to an ellipsis).
- `.jumper` — Shows a quick-jumper field that jumps straight to a typed page number.
- `.showTotal` — A leading summary label built from `(current, total)` — e.g.

## PaymentCardField

```swift
PaymentCardField(number:, expiry:, cvv:)
```

**Modifiers**

- `.holder` — Adds a cardholder-name field bound to `binding`.
- `.accent`
- `.surface` — Custom fill for the field rows, painted *inside* the ``FieldStyle`` chrome.
- `.placeholders`
- `.size` — Control-height preset for every row.
- `.infoMessages` — Validation / info messages rendered under the group (drives the rows' border state).
- `.validate` — Declarative validation (daisyUI Validator): `rules` run against the **card number** text (as displayed, space-grouped) at `trigger` — `.editingEnd`/`.submit` when the number row loses focus, `.live` per keystroke.
- `.onValidation` — Reports validity after each `validate(_:on:)` pass — `true` when no error-severity failure is present.

## PhoneField

```swift
PhoneField(label, number:)
```

**Modifiers**

- `.dialCodes` — The selectable dial codes (default: `DialCode.common`).
- `.placeholder` — Placeholder for the national-number portion (default localized "Phone number").
- `.searchablePicker` — Searchable picker list (default: `true` when the list has more than 8 entries).
- `.formatsNumber` — Groups digits as you type using the `TextInputFormatter` machinery.
- `.infoMessages` — Validation / info messages rendered under the field (drives the border state) — forwarded to the underlying `TextInput`.
- `.externalFocus` — Drive focus from outside (e.g.
- `.required` — Marks the field as required: error-token asterisk after the label + ", required" in the accessibility label — forwarded to the underlying `TextInput`.
- `.a11yID` — Sets the accessibility-identifier namespace (sub-elements get `"<id>.<element>"`) — forwarded to the underlying `TextInput`; the dial-code trigger gets `"<id>.trigger"`, picker rows `"<id>.option"`.

## PriceBreakdown

```swift
PriceBreakdown(amount, currencyCode:)
```

**Modifiers**

- `.original` — A struck-through original price (shown next to the discount badge).
- `.discountBadge` — A discount badge, e.g.
- `.unit` — A price unit, e.g.
- `.note` — A note above the price, e.g.
- `.extra` — An extra-discount line under the price (shown in error colour).
- `.size` — Size of the main price (default `.large`).
- `.emphasis` — Emphasis of the main price (default `.standard`).
- `.align` — Horizontal alignment of the stack (default `.leading`).

## PriceHistogram

A token-bound price histogram + range filter.

```swift
PriceHistogram(bins:, lowerValue:, upperValue:, in:)
```

**Modifiers**

- `.barHeight` — Max bar height in points (default 56).
- `.accent` — Overrides the selected-bar colour (otherwise the theme accent).
- `.currency` — Currency for the range / bound labels.
- `.resultCount` — Shows a live selected-range readout and how many results it matches.
- `.showsBounds` — Shows the min / max bound labels under the slider (and the range readout above).

## PriceTrendChart

```swift
PriceTrendChart(points, selection:)
```

**Modifiers**

- `.title` — A centered title (e.g.
- `.currency` — Currency code for the prices.
- `.accent` — Bar accent colour (token); `nil` (default) uses the hero foreground.
- `.selectionAccent` — Colour of the selected-day pill (token); `nil` (default) uses the primary-text/inverse pair.
- `.selectionColor` — Colour of the selected-day pill (token).
- `.barHeight` — Chart height in points (default 120).
- `.barWidth` — Fixed bar/column width — used when ``scrollable(_:)`` is on (default 26).
- `.spacing` — Gap between bars in points (default 6).
- `.cornerRadius` — Bar corner radius (radius role, default `.selector`).
- `.scrollable` — Horizontally scroll the bars (fixed width each) instead of fitting them to the width.
- `.maxDays` — Cap how many days are shown (from the start).
- `.showsAxis` — Show faint min/max price reference lines behind the bars.
- `.showsValues` — Show the selected day's price above its bar.
- `.showsWeekday` — Show the weekday caption under each day (default on).
- `.gradient` — Gradient (default) or flat bar fill.
- `.onPage` — Adds prev/next paging chevrons in the header.

## ProgressIndicator

Segmented position/progress indicator (Reference ProgressIndicator parity).

```swift
init(variant: ProgressIndicatorVariant = .carousel, current: Int, total: Int)

// usage: ProgressIndicator(current: 1, total: 1)
```

**Modifiers**

- `.size` — Bar thickness: large / medium / small / xsmall.
- `.videoProgress` — Fill fraction (0…1) of the active segment in the `.video` variant.
- `.stepText` — Step-count caption format: `.none`, `.slash` ("3 / 10"), or `.padded` ("01 | 05").
- `.cornerRadius` — Rounds the segment ends into a capsule (default `true`); `false` for square ends.

## QuantityStepper

A token-bound quantity stepper (− value +), bounded by a range.

```swift
init(value: Binding<Int>, range: ClosedRange<Int> = 0...99)

// usage: QuantityStepper(value: $value)
```

**Modifiers**

- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).
- `.step` — Increment applied by the − / + buttons (default 1; clamped to at least 1).

## RadioButton

Figma "Control Items" → Radioboxes.

```swift
init(_ label: String? = nil, isSelected: Binding<Bool>)

// usage: RadioButton(isSelected: $isSelected)
```

**Modifiers**

- `.type` — Selected-state indicator: `.select` (one-way dot) or `.check` (togglable checkmark).
- `.radioStyle` — Indicator rendering of a `.check` radio: `.plain` glyph or `.inner` dot.
- `.gap` — Gap between the radio and its label: small / medium / large.
- `.fillColor` — Override the selected-fill color (defaults to the `.bgHero` token, R4); prefer the token-fed `accent(_:)`.
- `.accent` — Semantic tint for the selected fill/border (glyph auto-contrasts); `nil` (default) uses the hero tokens.
- `.infoMessages` — Validation / info messages rendered under the control (drives the border state).
- `.alignment` — Vertical alignment of the radio against a multi-line label.
- `.controlPlacement` — Which side of the label the radio sits on: `.leading` (default) or `.trailing`.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## RadioGroup

```swift
init(title: String? = nil, options: [Option], selection: Binding<Option?>, label: @escaping (Option) -> String)

// usage: RadioGroup(options: <[Option]>, selection: $selection, label: "label")
```

**Modifiers**

- `.infoMessages` — Validation / info messages rendered under the group (drives the title color).
- `.optionEnabled` — Per-option enablement predicate (nil enables every option).
- `.optionDescription` — Supporting text rendered under each row's label (return nil for none).
- `.description` — Group-level supporting text rendered under the title via `HelperText` (Ant/HeroUI group `description`; E5).
- `.required` — Marks the whole group required: an error-token asterisk after the title (honoring `FieldDefaults.requiredIndicator`) and ", required" in the title's a11y label.
- `.controlPlacement` — Which side of each row's label the radio sits on: `.leading` (default) or `.trailing`, forwarded to every option row.
- `.accent` — Semantic tint forwarded to every radio's selected fill/border; `nil` (default) uses the hero tokens.
- `.axis` — Layout axis of the option rows: `.vertical` (default) or `.horizontal`.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## RadioButtonGroup

A connected, segmented button-style single-select radio group — a distinct API from the stacked `RadioGroup` and the enclosed `SegmentedControl`.

```swift
init(options: [Option], selection: Binding<Option?>, label: @escaping (Option) -> String)

// usage: RadioButtonGroup(options: <[Option]>, selection: $selection, label: "label")
```

**Modifiers**

- `.groupStyle` — Fill style of the group: `.solid` or `.outline`.
- `.fullWidth` — Expands the group to fill the available width, sharing it across segments.
- `.optionEnabled` — Per-option enablement predicate (nil enables every option).
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## RangeSlider

Improved, token-bound rewrite of the reference RangeSliderView — a self-contained dual-thumb slider over a numeric range (decoupled from the reference's text-field wiring).

```swift
init(lowerValue: Binding<Double>, upperValue: Binding<Double>, in bounds: ClosedRange<Double>)

// usage: RangeSlider(lowerValue: $lowerValue, upperValue: $upperValue, in: 1)
```

**Modifiers**

- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).
- `.step` — Snap increment for dragging, typed input and VoiceOver adjustments (default 1).
- `.marks` — Labeled tick marks at the given values (horizontal axis only).
- `.axis` — Lays the slider out vertically with the given track height (default 160).
- `.accent` — Semantic tint for the range fill and thumb rings; `nil` (default) keeps the hero tokens.
- `.inputs` — Shows linked numeric min/max input fields above the track.
- `.onChangeEnd` — Fires with the snapped (lower, upper) pair when a drag ends.
- `.valueLabel` — Formats the value readout shown above each thumb (e.g.

## ScrollShadow

Fades the clipped edges of a wrapped scroll view with theme-fed gradient scrims — ThemeKit's port of HeroUI Native's `ScrollShadow`.

```swift
ScrollShadow(content:)
```

**Modifiers**

- `.axis` — The scroll axis of the wrapped content (default `.vertical`).
- `.visibility` — Which edge scrims to show (default `.auto`).
- `.length` — Scrim depth along the scroll axis, as a spacing token (default `.xl`).
- `.fadeColor` — The surface the scrims fade from (default `.bgBase`) — match it to the background the scroll view sits on so the fade reads as depth, not tint.

## ScrubGallery

```swift
ScrubGallery(count:, content:)
```

**Modifiers**

- `.indicator` — Shows the segment position indicator at the bottom (default true).
- `.accent` — Semantic tint of the active indicator segment (default `.primary`).
- `.radius` — Corner radius role clipping the gallery (default `.box`).

## SearchBar

A search field with optional typeahead suggestions, a recent-searches list and submit/clear callbacks.

```swift
init(text: Binding<String>)

// usage: SearchBar(text: $text)
```

**Modifiers**

- `.placeholder` — Placeholder shown while the field is empty.
- `.size` — Control-height preset.
- `.suggestions` — Static typeahead suggestions, filtered locally as the user types (classic init only).
- `.recent` — Recent searches shown while the field is focused and empty; the optional action drives the header's Clear button.
- `.onSearch` — Fires with the query text on each (debounced) change.
- `.onSelect` — Fires when a suggestion or recent item is tapped.
- `.onCommit` — Fires with the query text on the return/search key (named to avoid SwiftUI's `.onSubmit`).
- `.backButton` — Shows a leading back chevron; the optional action fires on tap.
- `.trailingIcon` — A trailing SF Symbol button (shown when the field is empty); the optional action fires on tap (e.g.
- `.leadingIcon` — Replaces the leading SF Symbol (defaults to `"magnifyingglass"`).
- `.leadingIconColor` — Token key for the leading icon's color (defaults to `.textTertiary`).
- `.helperText` — Convenience hint rendered under the field as an `.info` `InfoMessage`; hidden while the field is invalid (an `errorText` or an error-severity `infoMessages` entry is active).
- `.errorText` — Convenience error appended to the message list as an `.error` `InfoMessage`; also flips the ambient `FieldStyle` into its error border.
- `.infoMessages` — Validation / info messages rendered under the field (their dominant severity drives the `FieldStyle` error / warning border, as in `TextInput`).
- `.externalFocus` — Drive focus from outside (e.g.
- `.debounce` — Debounce interval for typeahead / `onSearch` (async init defaults to 0.3s).
- `.maxResults` — Caps the number of suggestion rows (default 6).
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## SearchField

```swift
SearchField(placeholder, action:)
```

**Modifiers**

- `.value` — A location value — an optional leading code pill + title + subtitle.
- `.dateRange` — A date range — two badge + day columns split by a divider (pass `end: nil` for a single date).
- `.passengers` — A passenger summary — a badge + a row of icon + count tallies.
- `.icon` — A leading SF Symbol (shown when there's no code pill).
- `.iconColor` — Colour of the leading icon (foreground token key).
- `.trailing` — Trailing accessory: none (default) / chevron / clear.
- `.onClear` — Adds a clear (✕) button with its handler.
- `.background` — Card background (background token key, default `.bgWhite`).
- `.borderColor` — Border colour (border token key, default soft blue).
- `.cornerRadius` — Corner radius (radius role, default `.field`).
- `.focused` — Focused/active state (hero border).
- `.showsShadow` — Adds a soft elevation shadow.
- `.chipColors` — Recolour the code/date/count pills (background + text token keys).
- `.titleStyle` — Title text style + colour token.
- `.subtitleStyle` — Subtitle text style + colour token.
- `.placeholderColor` — Placeholder text colour token.

## SearchSummary

```swift
SearchSummary(time:, adults:)
```

**Modifiers**

- `.title` — Location title shown above the date/guests line.
- `.children` — Children count chip (hidden when `nil`).
- `.rooms` — Rooms count chip (hidden when `nil`).
- `.boxed` — Wrap in the soft pill surface (bg + hairline) — the search-bar presentation.
- `.prompt` — Empty state — replace the guest summary with a hero call-to-action (e.g.
- `.onTap` — Make the whole summary tappable (re-open the search).
- `.icons` — Override the guest icons (defaults: person / child / bed).

## SegmentedControl

```swift
init(_ items: [SegmentItem], selection: Binding<Int>)

// usage: SegmentedControl(<[SegmentItem]>, selection: $selection)
```

**Modifiers**

- `.fullWidth` — Stretch each segment to fill the available width (Ant Segmented `block`).
- `.size` — Segment height: small / medium / large (Ant Segmented `size`).
- `.shape` — Corner style — default or a fully-round pill (Ant Segmented `shape`).
- `.vertical` — Stack the segments vertically (Ant Segmented `vertical`).
- `.selectionStyle` — How the active option is drawn — the raised white `.thumb` (default), a hero-tinted `.outline` pill, or a thumbless `.tinted` soft track.
- `.dividers` — Draw a hairline between adjacent segments — pair with `.tinted()` / `.shape(.round)` for the design-system icon toggle (chart / grid switch).
- `.tinted` — The thumbless soft-track selection style, tinted with a base `color`: the track uses `color.soft`, the active option `color.accent`.
- `.accent` — Semantic tint for the `.tinted` / `.outline` selection styles (standard accent vocabulary); `nil` (default) defers to the subtree ``ComponentDefaults`` accent (set once with `.componentDefaults(accent:)`), then `.primary`.
- `.a11yID` — Sets the accessibility-identifier namespace for this component.

## Select

A single-select dropdown — a native `Menu` by default, or a searchable inline panel with section headers when `.searchable()` is on.

```swift
init(_ label: String, options: [Option], selection: Binding<Option?>, optionTitle: @escaping (Option) -> String)

// usage: Select("label", options: <[Option]>, selection: $selection, optionTitle: "optionTitle")
```

**Modifiers**

- `.placeholder` — Placeholder shown while no option is selected.
- `.clearable` — Show a trailing clear button when an option is selected.
- `.searchable` — Use the searchable inline panel instead of the native menu.
- `.listHeight` — Max height of the searchable dropdown before it scrolls (Ant `listHeight`, default 256pt).
- `.filter` — Custom match predicate for the searchable panel (Ant `filterOption`): `keep(query, option)` returns whether to keep the option.
- `.filterSort` — Order the filtered rows (Ant `filterSort`); `nil` keeps declaration order.
- `.size` — Control height of the trigger field (small / medium / large).
- `.required` — Marks the field as required: renders an error-token asterisk after the floating label (the `InputLabel` treatment, honoring the subtree `FieldDefaults.requiredIndicator`) and appends ", required" to the trigger's accessibility label (E2, HeroUI `isRequired`).
- `.infoMessages` — Validation / info messages rendered under the field (drives the border state).
- `.loading` — Shows a loading spinner in place of the chevron (async option fetch).
- `.optionEnabled` — Per-option enable predicate; disabled rows are shown greyed and unselectable.
- `.optionDescription` — Second line rendered under each option title (HeroUI `Select.ItemDescription`).
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## SelectBox

```swift
init(_ label: String? = nil, options: [Option], selection: Binding<Option?>, optionTitle: @escaping (Option) -> String)

// usage: SelectBox(options: <[Option]>, selection: $selection, optionTitle: "optionTitle")
```

**Modifiers**

- `.placeholder` — Placeholder shown while no option is selected.
- `.size` — Control height on the field family's `TextInputSize` ramp (C1).
- `.required` — Marks the field as required: renders an error-token asterisk after the label (the `InputLabel` treatment, honoring the subtree `FieldDefaults.requiredIndicator`) and appends ", required" to the trigger's accessibility label (E2, HeroUI `isRequired`).
- `.hint` — Helper text rendered under the field (hidden while an error is shown).
- `.errorText` — Error message rendered under the field (drives the error border / label color).
- `.infoMessages` — Validation / info messages rendered under the field as an `InfoMessageList` (their dominant severity drives the `FieldStyle` error / warning border, as in `TextInput`).
- `.externalFocus` — Drive focus from outside (e.g.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## Slider

```swift
init(value: Binding<Double>, in bounds: ClosedRange<Double>, label: String? = nil)

// usage: Slider(value: $value, in: 1)
```

**Modifiers**

- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).
- `.step` — Snap increment for dragging and VoiceOver adjustments (default 1).
- `.marks` — Labeled tick marks at the given values (e.g.
- `.axis` — Lays the slider out vertically with the given track height (default 160).
- `.showsValueTooltip` — Shows a value tooltip above the thumb while dragging.
- `.valueLabel` — Formats the persistent value readout on the label row (e.g.
- `.accent` — Semantic tint for the track fill and thumb; `nil` (default) keeps the hero tokens.
- `.onChangeEnd` — Fires with the snapped value when a drag ends (not on every step).

## SmartSuggestion

```swift
SmartSuggestion(message)
```

**Modifiers**

- `.label` — An accent label prefix (e.g.
- `.icon` — The leading icon (default a sparkle).
- `.accent` — Token-fed accent for the surface / label / icon (default success green); `nil` restores the default.
- `.tint` — Token-fed tint for the surface / accent (default success green).
- `.onTap` — Makes the whole banner tappable (adds a trailing chevron).
- `.action` — A trailing text action (e.g.
- `.bordered` — Draw the soft border (default on).

## SortTab

One tab of a sort bar — an icon+title, a previewed value/subtitle and a selected underline.

```swift
SortTab(option, isSelected:, action:)
```

**Modifiers**

- `.accent` — Token-fed tint for the selected underline, icon and title; `nil` (default) keeps the hero token.

## SortSummaryBar

```swift
SortSummaryBar(options, selection:)
```

**Modifiers**

- `.onMore` — Adds a trailing "more sort" button (default a sliders icon).

## Space

```swift
Space(content:)
```

**Modifiers**

- `.direction` — Layout direction (Ant Space `direction`/`orientation`).
- `.vertical` — Stack the children vertically.
- `.size` — Gap from a preset size (small / medium / large).
- `.align` — Cross-axis alignment (start / center / end / baseline).
- `.wrap` — Wrap onto multiple lines when horizontal (Ant Space `wrap`).

## Splitter

```swift
Splitter(axis, initialFraction:, first:)
```

**Modifiers**

- `.bounds` — Clamp the split fraction (Ant Panel `min` / `max`).
- `.vertical` — Stack the panes vertically (Ant Splitter `layout="vertical"`) — the kit-standard axis vocabulary (cf.

## Stat

```swift
init(title: String, value: String)

// usage: Stat(title: "title", value: "value")
```

**Modifiers**

- `.prefix` — Unit/symbol shown before the value (e.g.
- `.suffix` — Unit/symbol shown after the value.
- `.loading` — Swap the value for a skeleton placeholder while `on`.
- `.description` — Secondary caption line beside the trend.
- `.icon` — Leading figure SF Symbol.
- `.trend` — Trend badge (arrow + delta) in success/error color.

## StepperRow

```swift
StepperRow(label, value:)
```

**Modifiers**

- `.subtitle`
- `.range`
- `.step`
- `.icon`
- `.accent`

## Steps

A horizontal or vertical step / progress indicator with done / active / todo / error states, an optional progress dot, and tap-to-navigate.

```swift
init(_ steps: [Steps.Step], onSelect: ((Int) -> Void)? = nil)

// usage: Steps(<[Steps.Step]>)
```

**Modifiers**

- `.axis` — Layout orientation: horizontal / vertical.
- `.size` — Marker + label size: medium (default) / small — the kit's uniform size-enum axis.
- `.small` — Compact markers and labels — the boolean twin of `size(.small)`.
- `.progressDot` — Render minimal progress dots instead of numbered markers (Ant `progressDot`).
- `.current` — Drive the flow from a single controlled index (Ant `current`): steps before it read as done, the one at it as active, those after as todo — derived automatically, so steps can be declared without per-item state.

## SuggestionRow

```swift
SuggestionRow(title, action:)
```

**Modifiers**

- `.icon` — Leading SF Symbol (in the icon tile).
- `.iconColor` — Icon colour (text token key).
- `.iconTile` — Show the rounded tile behind the icon (default on).
- `.code` — A trailing code next to the title, e.g.
- `.subtitle` — The secondary line under the title.
- `.nested` — Renders as a nested child (indent + ↳ arrow) — e.g.
- `.selected` — Selected/active state (accent-tinted background).
- `.highlight` — Bold + tint the substring of the title matching this query (autocomplete highlight).
- `.accessory` — Trailing accessory: none (default) / chevron / add.
- `.accent` — Token-fed accent for the selected background / highlight (default primary).

## TableToggleCell

A row-height boolean toggle.

```swift
TableToggleCell(isOn:, label:)
```

## TableSelectCell

A compact menu picker over string options.

```swift
TableSelectCell(options, selection:, label:)
```

## TableSliderCell

A compact value slider, tinted with the hero token.

```swift
TableSliderCell(value:, in:, label:)
```

## TableColorCell

A system color well for editing a `Color` in place.

```swift
TableColorCell(selection:, label:)
```

## TextInput

Single floating-label text field.

```swift
init(_ label: String, text: Binding<String>)

// usage: TextInput("label", text: $text)
```

**Modifiers**

- `.placeholder` — Placeholder shown inside the field once the label floats.
- `.icon` — Leading / trailing SF Symbols shown inside the field.
- `.addons` — Static addon segments rendered before / after the field (e.g.
- `.required` — Marks the field as required: renders an error-token asterisk after the label (the `InputLabel` treatment) and appends ", required" to the field's accessibility label (HeroUI `isRequired`).
- `.secure` — Masks input as a password field with a reveal toggle.
- `.clearable` — Show a trailing clear button while the field has text.
- `.labelPlacement` — Places the label `.floating` (inside, animating up — default) or `.above` (a static ``InputLabel`` stacked over the field, HeroUI `labelPlacement`).
- `.maxLength` — Caps input at `max` characters; a soft limit (`hardLimit: false`) allows overflow and flags the counter instead.
- `.showsCount` — Shows the character counter, reading `12/50` (`.count`) or `38 left` (`.remaining`).
- `.size` — Control height preset (defaults to `.medium`, R4).
- `.formatter` — Live input formatter applied on every change (e.g.
- `.helperText` — Convenience hint appended to the message list as an `.info` `InfoMessage`.
- `.errorText` — Convenience error appended to the message list as an `.error` `InfoMessage`.
- `.warningText` — Convenience warning appended to the message list as a `.warning` `InfoMessage`.
- `.infoMessages` — Validation / info messages rendered under the field (drives the border state).
- `.validate` — Declarative validation (daisyUI Validator): evaluates `rules` at `trigger` and feeds the first failure into the message list / error styling automatically — no hand-managed `infoMessages`.
- `.onValidation` — Reports validity after each `validate(_:on:)` pass — `true` when no error-severity rule failed (e.g.
- `.externalFocus` — Drive focus from outside (e.g.
- `.keyboard` — Keyboard / autofill / return-key / capitalization traits (iOS; ignored on macOS).
- `.autocorrectionDisabled` — Disables system autocorrection for the field.
- `.onCommit` — Action fired when the user submits (named `onCommit` to avoid shadowing SwiftUI's `.onSubmit`).
- `.a11yID` — Sets the accessibility-identifier namespace for this field (its sub-elements — label, field, clear, reveal, messages — get `"<id>.<element>"`).

## ThemeController

```swift
init(options: [ThemeController.Option], selectedName: Binding<String>)

// usage: ThemeController(options: <[ThemeController.Option]>, selectedName: $selectedName)
```

**Modifiers**

- `.accent` — Token-fed tint for the active option's label; `nil` (default) keeps the hero token.
- `.fullWidth` — Stretch options to share the available width (default on); off = intrinsic widths.

## ThemeToggle

Figma "Control Items" → Switch Toggles.

```swift
init(isOn: Binding<Bool>)

// usage: ThemeToggle(isOn: $isOn)
```

**Modifiers**

- `.loading` — Swap the knob for a spinner and block interaction while `on`.
- `.symbols` — Optional SF Symbols shown inside the knob for the on / off states.
- `.trackSymbols` — Optional SF Symbols shown inside the *track*, on the side opposite the knob — the on-symbol while on, the off-symbol while off (HeroUI `Switch.StartContent`/`EndContent`).
- `.accent` — Semantic tint for the on-state track; `nil` (default) uses the hero background token.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## TimeField

```swift
init(_ label: String? = nil, time: Binding<Date?>)

// usage: TimeField(time: $time)
```

**Modifiers**

- `.placeholder` — Placeholder shown while no time is selected.
- `.size` — Control-height preset.
- `.required` — Marks the field required: an error-token asterisk on the label (honoring `FieldDefaults.requiredIndicator`) and ", required" in the a11y label.
- `.validate` — Declarative validation (daisyUI Validator): `rules` run against the *displayed* time string (empty when no time is set) at `trigger` — `.editingEnd`/`.submit` fire when the picker is dismissed, `.live` on every change.
- `.onValidation` — Reports validity after each `validate(_:on:)` pass — `true` when no error-severity failure is present.
- `.range` — Restrict the picker to a selectable time range.
- `.minuteInterval` — Snap the selected minute to the nearest multiple of `minutes` (e.g.
- `.hourCycle` — Force the displayed hour cycle (12 / 24-hour) or follow the locale (default).
- `.locale` — Override the formatting locale (defaults to the environment locale).
- `.infoMessages` — Validation / info messages rendered under the field (drives the border state).
- `.clearable` — Show a trailing clear button when a time is set.
- `.icon` — Leading SF Symbol shown inside the field (defaults to `clock`; pass `nil` to hide).
- `.a11yID` — Stable accessibility identifier, forwarded to the kit's a11y infrastructure.

## ToggleGroup

```swift
init(title: String? = nil, options: [Option], selection: Binding<Set<Option>>, label: @escaping (Option) -> String)

// usage: ToggleGroup(options: <[Option]>, selection: $selection, label: "label")
```

**Modifiers**

- `.optionDescription` — Supporting text rendered under each row's label (return nil for none).
- `.optionEnabled` — Per-option enablement predicate — disabled rows dim and their switch stops responding (nil enables every option; the kit-standard group idiom, cf.
- `.accent` — Semantic track tint forwarded to each row's `ThemeToggle`; `nil` (default) keeps the stock hero track.
- `.axis` — Lay the rows out along `axis` (vertical default; HStack/VStack mirror for RTL automatically — cf.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## Transfer

```swift
Transfer(items, target:)
```

**Modifiers**

- `.titles` — Header labels for the source and target boxes (Ant `titles`).
- `.searchable` — Show a search field in each list box, filtering its rows by title (Ant Transfer `showSearch`).
- `.itemEnabled` — Per-item enablement predicate — disabled rows dim, can't be checked and never move (nil enables every item; the kit-standard `optionEnabled` idiom, Ant Transfer per-item `disabled`).
- `.showsSelectAll` — Show a select-all checkbox in each box header that toggles every enabled, currently-visible row in that box (Ant `showSelectAll`).
- `.status` — Validation tint for the list borders (Ant `status`): normal / error / warning.
- `.onChange` — Called after items move, with the new target set, the direction, and the moved keys (Ant `onChange(targetKeys, direction, moveKeys)`).

## TreeSelect

Hierarchical (nested) select with expand/collapse and multi-selection.

```swift
init(_ label: String? = nil, nodes: [TreeNode], selection: Binding<Set<String>>, initiallyExpanded: Set<String> = [])

// usage: TreeSelect(nodes: <[TreeNode]>, selection: $selection)
```

**Modifiers**

- `.placeholder` — Placeholder shown in the field when nothing is selected.
- `.cascade` — Parent ↔ child cascade selection with tri-state (indeterminate) parents.
- `.searchable` — Show an inline search field that filters the visible nodes.
- `.loading` — Swap the node list for a loading row while `on`.
- `.nodeEnabled` — Per-node enabled predicate — disabled nodes can't be toggled.

## TreeView

```swift
TreeView(nodes, selection:)
```

**Modifiers**

- `.checkable` — Show checkboxes; checking a parent cascades to its subtree (Ant `checkable`).

## CabinClassSelector

```swift
CabinClassSelector(selection:)
```

**Modifiers**

- `.classes` — Subset + order of the offered cabins (default: all four).
- `.variant` — Presentation — superseded by the style axis: prefer `.cabinClassSelectorStyle(.segmented/.chips/.list/.cards)`, settable once per screen via the environment.
- `.showsGlyphs` — Show each cabin's SF Symbol next to its label (the `.segmented` / `.chips` styles; the `.list` rows stay text-only, matching `RadioGroup` anatomy).
- `.accent` — Semantic tint: `.segmented` switches to the tinted selection style, `.list` tints the radios, `.chips` feeds the subtree accent cascade, `.cards` tints the selected card.
- `.size` — Control-size ramp forwarded to the wrapped `SegmentedControl` / `Chip` (and the `.cards` padding step).
- `.chipsWrap` — Lay the `.chips` style out as a wrapping ``FlowLayout`` (RTL-aware) instead of a horizontal `ScrollView` — every option visible at once.
- `.label` — Override the display label per cabin (default: the canonical ``CabinClass/label``), e.g.
- `.glyph` — Override the SF Symbol per cabin (default: the canonical ``CabinClass/glyph``).
- `.description` — Per-cabin description line, rendered by the `.cards` style beneath the label (`nil` for no description on that card).

## DatePriceCard

A single selectable date+price card — the built-in cell the strip's `.grid` and `.strip` presets compose.

```swift
DatePriceCard(item, isSelected:, action:)
```

**Modifiers**

- `.currency` — Currency code for the price.
- `.cheapest` — Highlights this as the lowest fare (price shown in success green).
- `.pill` — Render as a horizontal-strip pill (rounded capsule) instead of a card.
- `.surface` — Surface token for the carded shell (default `.bgElevatorPrimary`).
- `.accent` — Semantic accent for the selected state — pill fill `soft` + border `base`, card date/price `base`, wash `bg`.
- `.cheapestTone` — Semantic tone for the lowest-fare highlight (default `.success`).
- `.pillSize` — Height ramp for the pill presentation (default `.regular`, 40 pt).

## DatePriceStrip

```swift
DatePriceStrip(items, selection:)
```

**Modifiers**

- `.currency` — Currency code for the prices.
- `.columns` — Number of columns for the grid layout — superseded by the style axis: prefer `.datePriceStripStyle(.grid(columns:))`, settable once per screen via the environment.
- `.strip` — Horizontal-strip presentation — superseded by the style axis: prefer `.datePriceStripStyle(.strip)`, settable once per screen via the environment.
- `.layout` — Layout of the strip — superseded by the style axis: prefer `.datePriceStripStyle(.grid(columns:))` / `.datePriceStripStyle(.strip)`, settable once per screen via the environment.
- `.highlightCheapest` — Auto-highlight the lowest fare in success green (default on).
- `.surface` — Surface token for the strip/chart track and the cards the style builds.
- `.accent` — Semantic accent for the selected state, forwarded to every card — pill fill `soft` + border `base`, card date/price `base`, wash `bg`.
- `.cheapestTone` — Semantic tone for the lowest-fare highlight (default `.success`).
- `.pillSize` — Height ramp for the strip-layout pills (default `.regular`, 40 pt).
- `.onPage` — Adds prev/next paging chevrons flanking the strip.

## FlightRoute

```swift
FlightRoute(from:, to:, departure:, arrival:)
```

**Modifiers**

- `.stops` — Number of stops (0 = direct, shown in the accent colour).
- `.nextDay` — Marks the arrival as landing the next day (adds a "+1").
- `.pathColor` — Path/direct-label colour (foreground token key, default success green).
- `.accent` — Semantic accent override for the track/glyph/direct label; `nil` (the default) keeps the ``pathColor(_:)`` token.
- `.track` — Track presentation — superseded by the style axis: prefer `.flightRouteStyle(.path/.inline/.arc/.dots)`, settable once per screen via the environment.
- `.size` — Type ramp — steps the time / code / duration styles together (default `.regular`, the stock mapping).
- `.cityNames` — Optional city names rendered as a second line under each airport code.
- `.durationText` — Override the computed duration label ("2h 30m"); `nil` restores the computed text.
- `.stopsTone` — Semantic tone for the 1+-stop label (default tertiary text).

## LayoverRow

```swift
LayoverRow(duration:, airport:)
```

**Modifiers**

- `.warning` — A short/long-connection warning shown below (in warning colour).
- `.variant` — Presentation — superseded by the style axis: prefer `.layoverRowStyle(.line/.pill/.banner)`, settable once per screen via the environment.
- `.lineStyle` — Style of the flanking connector lines — `.dashed` (default), `.solid`, or `.hidden`.
- `.layoverLabel` — Localise the "layover" word (English default).
- `.icon`
- `.accent`

## PassengerRow

```swift
PassengerRow(name, action:)
```

**Modifiers**

- `.type` — Passenger type badge, e.g.
- `.subtitle`
- `.seat` — A trailing seat chip, e.g.
- `.status` — A trailing status badge, e.g.
- `.avatar` — Use an ``Avatar`` (initials / image / symbol) instead of the default person icon.
- `.icon`
- `.onEdit` — Adds a trailing edit (pencil) button.
- `.onRemove` — Adds a trailing remove (✕) button (``onEdit(_:)`` takes precedence).
- `.accessory`
- `.accent`
- `.bordered` — Wrap in a bordered card surface (default off — flush list row).
- `.surface` — Surface fill of the bordered card (background token key, default `.bgBase`).
- `.selectable` — Selectable mode — a leading checkbox mirrors the binding and tapping the row toggles it (the row `action` still fires).

## RecentSearchRow

```swift
RecentSearchRow(from:, to:, action:)
```

**Modifiers**

- `.roundTrip` — Round-trip route (⇄ arrow) instead of one-way (→).
- `.dates`
- `.passengers`
- `.icon` — Leading icon-tile glyph, or `nil` to drop the tile (e.g.
- `.onRemove` — Adds a trailing remove (✕) button instead of the chevron.
- `.onSearch` — Trailing filled **search** button (magnifier) instead of the chevron/remove — turns the row into a "mini search bar" summary that re-runs the search when tapped.
- `.searchAccent` — Fill color of the ``onSearch(_:)`` button (default `.neutral` ink).
- `.accent` — Brand-tints the leading icon tile (default: neutral tile).
- `.variant` — Chrome — superseded by the style axis: prefer `.recentSearchRowStyle(.plain/.bordered/.pill)`, settable once per list via the environment (and joined by the new `.card` tile).
- `.bordered` — Wrap in a bordered surface (default off — flush list row).
- `.pill` — Fully-rounded **capsule** surface — a pill that sits on a colored band (the search-result mini bar).
- `.surface` — Surface fill of surfaced styles (background token key).
- `.radius` — Corner-radius role of surfaced styles.
- `.via` — Intermediate stops for a multi-city route — renders IST → FRA → JFK instead of the fixed from → to pair.
- `.tileSize` — Size ramp of the leading icon tile (default `.md`).

## SeatLegend

```swift
SeatLegend(tiers:, palette:, perRow:)
```

**Modifiers**

- `.showsPremium` — Backward-compatible: adds a "Premium econ." key to the default legend.
- `.tiers` — The fare tiers to key (replaces the current set).
- `.palette` — The palette the swatches resolve their colours from — pass the same one the map uses so the key always matches.
- `.perRow` — Entries per row in the `.rows` style — superseded by the style axis: prefer `.seatLegendStyle(.rows(perRow:))`, settable once per screen via the environment.
- `.showsSelected` — Whether the synthetic "Selected" entry is appended (default `true`).
- `.showsOccupied` — Whether the synthetic "Occupied" entry is appended (default `true`).
- `.entry` — Appends a custom key (e.g.
- `.swatchShape` — The swatch silhouette — pass the map's ``SeatShape`` so the key matches the seats (``SeatMap`` forwards its own automatically).
- `.swatchSize` — Steps the swatch size alongside a map using the same ``SeatSizeRamp``.
- `.orientation` — Layout direction of the entries — superseded by the style axis: prefer `.seatLegendStyle(.rows(perRow:))` / `.seatLegendStyle(.vertical)` / `.seatLegendStyle(.inline)`, settable once per screen via the environment.

## TripTypeToggle

```swift
TripTypeToggle(options, selection:)
```

**Modifiers**

- `.icons` — Per-option leading SF Symbols (aligned to `options` by index).
- `.accent` — Token-fed accent for the selected pill (default primary).
- `.fullWidth` — Stretch pills to fill the width (default on); off = intrinsic width.
- `.surface` — Token-fed track fill behind the pills (default `.bgBase` — a soft, low-contrast track that reads well on a white card).
- `.size` — Size ramp — steps the option height and the icon + label styles (default `.regular`).
- `.variant` — Look — superseded by the style axis: prefer `.tripTypeToggleStyle(.pill/.underline/.menu)`, settable once per screen via the environment.
- `.shape` — Corner treatment of the pill track + thumb: `.capsule` (default) or `.rounded(_:)` at a radius role.

---

# Organisms (84)

_Full sections — cards, tables, navigation, banners, domain surfaces._

## Accordion

Improved, token-bound rewrite of the reference AccordionView — a single expandable row with a @ViewBuilder body instead of type-erased AnyView models.

```swift
init(_ title: String, initiallyExpanded: Bool = false, @ViewBuilder content: @escaping () -> Content)

// usage: Accordion("title", @ViewBuilder: <@escaping () -> Content>)
```

**Modifiers**

- `.icon` — Leading SF Symbol shown before the title.
- `.subtitle` — A secondary line under the title.
- `.number` — A leading two-digit number badge (e.g.
- `.indicator` — Expand/collapse indicator glyph (chevron / plus-minus / custom).
- `.titleSize` — Title text size.
- `.density` — Header row vertical padding (default / small / large).
- `.truncateSubtitle` — Clamps the subtitle to one line while collapsed.
- `.divider` — Whether to draw the bottom divider (default true).

## AccordionGroup

A group of accordion rows with single- or multiple-open behavior (the reference `AccordionView` tracks a `Set` of open ids).

```swift
init(_ items: [Item], initiallyExpanded: Set<Item.ID> = [], title: @escaping (Item) -> String, @ViewBuilder content: @escaping (Item) -> Content)

// usage: AccordionGroup(<[Item]>, title: "title")
```

**Modifiers**

- `.mode` — Expand behavior: `.single` collapses the others when one opens (default), `.multiple` keeps them open.
- `.indicator` — Expand/collapse indicator glyph applied to every row (chevron / plus-minus / custom).
- `.surface` — Whether to draw the card chrome — background fill + stroke (default true).
- `.dividers` — Whether to draw the dividers between rows (default true).
- `.collapsible` — Whether an open item can be collapsed again (default true).
- `.itemDisabled` — Per-item disabled predicate — disabled rows render in the disabled text token and don't respond to taps.
- `.icon` — Per-item leading SF Symbol prefix shown before the title (Figma "Prefix" icon instance swap).
- `.number` — Per-item leading two-digit number badge shown before the title (numbered steps / FAQ).
- `.titleSize` — Title text size applied to every row (default preserves the compact baseline).
- `.density` — Header row vertical padding — default / small / large (Figma row height).

## ActionBar

```swift
ActionBar(count:, actions:, onClear:)
```

## Agenda

```swift
Agenda(events)
```

**Modifiers**

- `.showsDayHeaders` — Show or hide the per-day header rows (default on).
- `.locale` — Locale for date/time formatting; defaults to the environment locale.

## AgentPriceRow

```swift
AgentPriceRow(provider, action:)
```

**Modifiers**

- `.logo`
- `.icon`
- `.subtitle`
- `.rating`
- `.badge`
- `.warning`
- `.price`
- `.original`
- `.cta`
- `.recommended`
- `.accent`
- `.surface`
- `.cornerRadius`

## AlertHeader

The Figma `_AlertHeader`: an optional icon "avatar" bubble over an optional title, aligned leading or center.

```swift
AlertHeader(title)
```

**Modifiers**

- `.icon` — Icon (SF Symbol) shown in the bubble.
- `.tone` — Intent color for the glyph (default `.neutral`); the bubble stays neutral.
- `.alignment` — `Type`: `.leading` (default) or `.center`.

## AlertFooter

The Figma `_AlertFooter`.

```swift
AlertFooter()
```

**Modifiers**

- `.primaryAction` — Button One — the primary/confirming action, tinted by `tone`.
- `.secondaryAction` — Button Two — the secondary/dismissing action, neutral (Figma "Show Button Two").
- `.tone` — Intent color for the primary button (default `.neutral`).
- `.layout` — `Type`: `.auto` (default), `.horizontal`, or `.vertical`.
- `.swapActions` — Reverse the buttons' visual order (Figma "Swap Button One / Two").
- `.primaryLoading` — Externally drive the primary button's loading state (in addition to the async `task:` form's own spinner).

## AlertDialog

A modal alert dialog composed of an ``AlertHeader``, an optional body (a `message` string or a custom `.content { }` slot) and an ``AlertFooter``.

```swift
AlertDialog(title, message:)
```

**Modifiers**

- `.icon` — Header icon (SF Symbol).
- `.tone` — Intent color tinting the header glyph and the primary button (default `.neutral`).
- `.headerAlignment` — Header `Type`: `.leading` (default) or `.center`.
- `.size` — Card size tier: `.xs` / `.sm` (default) / `.md` / `.lg` / `.mobile`.
- `.footerLayout` — Footer `Type`: `.auto` (horizontal, wrapping to vertical when the labels don't fit), `.horizontal`, or `.vertical`.
- `.swapActions` — Reverse the footer buttons' visual order (Figma "Swap Button One / Two").
- `.primaryAction` — Button One — the primary/confirming action, tinted by `tone` (Figma "Show Button One").
- `.secondaryAction` — Button Two — the secondary/dismissing action, neutral (Figma "Show Button Two").
- `.closable` — Show the top-trailing close (✕) button; `handler` fires on tap.
- `.primaryLoading` — Externally drive the primary button's loading state (in addition to any async `task:` action's own spinner).

## AlertToast

Improved, token-bound rewrite of the reference AlertView — a solid-fill status banner (complements the light-surface InfoBanner).

```swift
init(_ title: String)

// usage: AlertToast("title")
```

**Modifiers**

- `.message` — Secondary line under the title.
- `.variant` — Status treatment: success / warning / danger / info / neutral / accent (drives fill + icon).
- `.icon` — Override the leading status glyph (otherwise derived from the variant).
- `.loading` — Swap the leading icon for an activity spinner while `on`.
- `.action` — Inline tappable action (e.g.
- `.onClose` — Trailing dismiss button; the handler is invoked on tap.

## BlogCard

```swift
init(title: String, @ViewBuilder media: @escaping () -> Media)

// usage: BlogCard(title: "title", @ViewBuilder: <@escaping () -> Media>)
```

**Modifiers**

- `.excerpt` — Excerpt paragraph under the title (regular layout only).
- `.compact` — Compact (media-left) variant.
- `.surface` — Surface fill (background token key) — enables the card shell.
- `.cornerRadius` — Container corner radius role — enables the card shell.
- `.elevation` — Surface elevation — enables the card shell.

## BrowserFrame

```swift
BrowserFrame(url:, content:)
```

**Modifiers**

- `.elevation` — Surface elevation: none / soft / elevated (default soft).
- `.accent` — Tint the toolbar with a semantic color; `nil` (default) uses neutral chrome.

## Callout

```swift
init(_ text: String)

// usage: Callout("text")
```

**Modifiers**

- `.variant` — Semantic status: neutral / info / success / warning / error / accent (drives accent + icon).
- `.links` — Turn substrings of the body into inline tappable links (rendered via `InlineText`) — API symmetry with `InfoBanner`, which already supports it.
- `.calloutStyle` — Surface treatment: plain (transparent) or soft (light tinted surface).
- `.showsIcon` — Show or hide the leading status icon.
- `.icon` — Override the leading status glyph (otherwise derived from the variant); `nil` restores the variant's default.
- `.action` — Trailing inline action button (title + handler).
- `.onClose` — Trailing dismiss (×) button handler.

## Card

```swift
init(_ title: String? = nil, action: (() -> Void)? = nil, @ViewBuilder content: @escaping () -> Content)

// usage: Card()
```

**Modifiers**

- `.subtitle` — Secondary line under the title in the card header.
- `.elevation` — Surface elevation: none / soft / elevated.
- `.contentPadding` — Inner content padding by spacing token (named so it doesn't shadow the native `.padding`; the `SurfaceView`/`TicketStub` twin) — resolved against the environment theme, so it re-skins with a spacing change.
- `.headerPadding` — Header-slot padding by spacing token — overrides the general `contentPadding(_:)` / theme padding for the header area only (theme twin: `--card-header-padding`).
- `.footerPadding` — Footer-slot padding by spacing token — overrides the general `contentPadding(_:)` / theme padding for the footer area only (theme twin: `--card-footer-padding`).
- `.extraAction` — Trailing header action (Ant `extra`) — renders when both title and action are set.
- `.loading` — Replace the body with a skeleton placeholder while content loads.
- `.overline` — A small eyebrow/overline label above the title (HeroUI "NEW" tag) — uppercased in a muted label style.
- `.surface` — Surface fill by background token, threaded into the active ``CardStyle``'s configuration (HeroUI `Card` `variant`): default → `.bgWhite`, `secondary` → `.bgSecondaryLight`, `tertiary` → `.bgTertiary`; HeroUI `transparent` ≈ `.cardStyle(.outlined)` instead.
- `.radius` — Corner-radius role — the card "size" axis: `.box` (default, 16), `.field` (8), or `.selector` (6).
- `.selected` — Marks the card as selected — the default / outlined styles promote the border to the hero token (HeroUI `isSelected`).

## CardStack

```swift
init(_ items: [Item], @ViewBuilder content: @escaping (Item) -> Content)

// usage: CardStack(<[Item]>, @ViewBuilder: <@escaping (Item) -> Content>)
```

**Modifiers**

- `.maxVisible` — Maximum number of cards rendered in the deck (default 3).
- `.peekOffset` — Vertical peek of each card behind the front one, token-fed (default: the legacy fixed 10pt offset).
- `.rotation` — Scatter angle in degrees applied per depth, alternating sides for a fanned-deck look (default 0 — a straight stack, today's rendering).

## Carousel

A generic paging carousel with dot indicators, optional autoplay and optional prev/next arrows.

```swift
init(_ items: [Item], loop: Bool = false, currentIndex: Binding<Int>? = nil, @ViewBuilder content: @escaping (Item) -> Content)

// usage: Carousel(<[Item]>, @ViewBuilder: <@escaping (Item) -> Content>)
```

**Modifiers**

- `.autoplay` — Advances pages automatically every `interval` seconds.
- `.arrows` — Shows prev / next arrow buttons.
- `.dots` — Shows the page-dot indicators (default true) and where they sit.
- `.fade` — Cross-fades between pages instead of sliding.

## ChatBubble

```swift
init(_ text: String, author: String? = nil, time: String? = nil)

// usage: ChatBubble("text")
```

**Modifiers**

- `.side` — Conversation side: incoming (leading) / outgoing (trailing).
- `.icon` — Leading/trailing avatar SF Symbol (positioned by `side`).
- `.accent` — Semantic tint for the bubble fill (foreground auto-contrasts); `nil` (default) keeps the side-based look.

## ColorPickerPanel

```swift
ColorPickerPanel(color:)
```

**Modifiers**

- `.showsAlpha` — Show the alpha slider (default on).
- `.showsHexField` — Show the two-way hex field (default on).
- `.swatches` — A preset-swatch row; tapping one sets the working color.

## Counter

```swift
init(segments: [Counter.Segment])

// usage: Counter(segments: <[Counter.Segment]>)
```

**Modifiers**

- `.size` — Digit-box scale: small / regular / large (default regular).
- `.accent` — Token-fed tint for the digits; `nil` (default) keeps primary text.
- `.separator` — Text drawn between the boxes (e.g.

## Coupon

```swift
init(code: String, label: String = "Kupon Kodu:", onCopy: @escaping () -> Void = {})

// usage: Coupon(code: "code")
```

**Modifiers**

- `.couponStyle` — Visual treatment: filled / outlined (dashed) / plain.
- `.size` — Size tier: small / medium / large.
- `.icon` — A leading SF Symbol, e.g.
- `.discount` — A trailing discount chip, e.g.
- `.expiry` — An expiry line under the code (block layout only), e.g.
- `.fullWidth` — Full-width block layout: label above, large code + copy below, optional expiry.
- `.block` — Full-width block layout: label above, large code + copy below, optional expiry.

## DataTable

```swift
init(columns: [DataTable<Row>.Column], rows: [Row], selection: Binding<Set<Row.ID>>? = nil)

// usage: DataTable(columns: <[DataTable<Row>.Column]>, rows: <[Row]>)
```

**Modifiers**

- `.striped` — Zebra striping on alternate rows (on by default; pass `false` to disable).
- `.pageSize` — Paginate rows at `size` per page (nil turns paging off).
- `.size` — Row density (Ant Table `size`): large / middle (default) / small — scales the header + cell vertical padding.
- `.showsHeader` — Show the column-title header strip (Ant `showHeader`; default on).
- `.selectionColumn` — Draw a leading checkbox column with a select-all header (Ant `rowSelection` checkbox mode).
- `.loading` — Replace rows with a loading placeholder while content loads.
- `.onRowTap` — Callback invoked when a row is tapped (also makes rows interactive).

## DestinationCard

A token-bound destination / favourite card.

```swift
DestinationCard(title, image:)
```

**Modifiers**

- `.surface` — Surface fill (background token key, default `.bgBase`).
- `.subtitle` — A location / description line under the title.
- `.price` — The price, rendered as a hero `PriceTag` in the footer row.
- `.rating` — A 0–5 review score, rendered as a `ScoreBadge`.
- `.ribbon` — A corner ribbon, e.g.
- `.badge` — An inline badge next to the title.
- `.tags` — Tag chips under the title (Beach, Culture…).
- `.favorite` — A favourite heart bound to a flag, top-trailing on the media.
- `.aspect` — Media aspect ratio (width ÷ height, default 4:3).
- `.overlayTitle` — Draw the title over the media (with a scrim) instead of below it.
- `.onTap` — Tap handler for the whole card.
- `.elevation` — Surface elevation: none / soft / elevated.

## Diff

```swift
init(@ViewBuilder before: @escaping () -> Before, @ViewBuilder after: @escaping () -> After)

// usage: Diff(@ViewBuilder: <@escaping () -> Before, @ViewBuilder after: @escaping () -> After>)
```

**Modifiers**

- `.aspect` — Aspect ratio of the comparison stage (default 16:9).

## Drawer

The drawer's content surface — a `heading` / body / `footer` slot stack with an optional close button and (on `.bottom` / `.top`) a grab handle.

```swift
Drawer(content:)
```

**Modifiers**

- `.showsCloseButton` — Toggles the top-trailing close button (default on).
- `.showsHandle` — Overrides the grab-handle visibility.
- `.edge` — Explicit entry edge for a standalone panel (previews, custom hosts).
- `.onClose` — Close action for the close button when the panel isn't driven by a presenter binding.

## EmptyState

Improved, token-bound rewrite of the reference EmptyCardView.

```swift
init(_ title: String? = nil)

// usage: EmptyState()
```

**Modifiers**

- `.icon` — Leading SF Symbol shown in the faded circle (symbol-media only).
- `.message` — Secondary message under the title.
- `.imageMaxHeight` — Max height of the custom/animated illustration.
- `.iconForeground` — Raw glyph-color override (back-compat); prefer the token-bound overload.
- `.iconBackground` — Raw circle-fill override (back-compat); prefer the token-bound overload.
- `.iconCircleSize` — Diameter of the icon circle.
- `.primaryAction` — Primary call-to-action button (title + handler).
- `.secondaryAction` — Secondary call-to-action button (title + handler).

## FilterList

```swift
FilterList(options, selection:)
```

**Modifiers**

- `.title` — A section title above the list.
- `.bordered` — Wrap the rows in a bordered, rounded container (the "popular filters" card).
- `.showsSeparators` — Hairline separators between rows (default on).
- `.selectAll` — Adds a "select all" master row with the given title (nil hides it).
- `.surface` — Surface fill (background token key, default `.bgBase`).

## FloatingActionButton

```swift
init(systemImage: String = "plus", actions: [FABAction] = [], action: @escaping () -> Void = {})

// usage: FloatingActionButton()
```

**Modifiers**

- `.shape` — Corner treatment of the main button: circle / square.
- `.accent` — Semantic color token driving the main button's fill (R4); `nil` (default) defers to the subtree ``ComponentDefaults`` accent (set once with `.componentDefaults(accent:)`), then `.primary`.
- `.color` — Semantic color token driving the main button's fill (R4).
- `.badge` — Count bubble on the main button (hidden when 0 or nil).

## Footer

```swift
init(columns: [Footer.Column], note: String? = nil)

// usage: Footer(columns: <[Footer.Column]>)
```

**Modifiers**

- `.surface` — Surface fill (background token key).

## Gallery

```swift
init(_ items: [Item], @ViewBuilder content: @escaping (Item) -> Content)

// usage: Gallery(<[Item]>, @ViewBuilder: <@escaping (Item) -> Content>)
```

**Modifiers**

- `.columns` — Number of grid columns (default 2).
- `.aspect` — Fixed aspect ratio applied to every cell (default `.square`).

## Hero

```swift
init(title: String)

// usage: Hero(title: "title")
```

**Modifiers**

- `.subtitle` — Supporting text under the title.
- `.cta` — Call-to-action button — renders when both title and action are set.
- `.dark` — Dark treatment: scrim overlay + inverted text (also darkens the default surface).

## HeroSurface

The default `Hero` surface.

```swift
init()

// usage: HeroSurface()
```

## HotelResultCard

```swift
HotelResultCard(name:)
```

**Modifiers**

- `.image`
- `.images`
- `.location`
- `.score`
- `.reviewsSuffix` — Localise the "reviews" suffix (English default).
- `.features`
- `.promos`
- `.price`
- `.original`
- `.discountBadge`
- `.stay`
- `.extraDiscount`
- `.badge`
- `.favorite`
- `.onSelect`
- `.accent`
- `.imageHeight`
- `.cornerRadius`
- `.elevation`
- `.surface`
- `.showsPageDots`

## ImageCollage

A gallery collage of remote images with count-aware layouts (1 / 2 / 3 / 4+) and a "+N" overlay on the last visible tile.

```swift
init(_ urls: [URL], onTap: ((Int) -> Void)? = nil)

// usage: ImageCollage(<[URL]>)
```

**Modifiers**

- `.height` — Overall collage height.
- `.spacing` — Gap between tiles.
- `.cornerRadius` — Tile corner radius.

## InfoBanner

Improved, token-bound rewrite of the reference InfoMessage.

```swift
init(_ message: String, title: String? = nil, links: [(substring: String, action: () -> Void)] = [])

// usage: InfoBanner("message")
```

**Modifiers**

- `.variant` — Semantic type: neutral / info / success / warning / error / accent — drives the surface, accent, border and leading icon.
- `.showsIcon` — Show or hide the type's leading icon.
- `.icon` — Override the leading status glyph (otherwise derived from the variant); `nil` restores the variant's default.
- `.fullWidth` — Edge-to-edge banner treatment: stretch to full width and drop the rounded corners / border (Ant Alert `banner`).
- `.action` — Trailing inline action as a lightweight text link: its label + handler.
- `.actionButton` — A first-class trailing action button (real `ThemeButton`) whose tap handler is captured on the `AlertAction`.
- `.onDismiss` — Trailing dismiss (×) button handler.

## KanbanBoard

```swift
KanbanBoard(columns:, card:)
```

**Modifiers**

- `.columnWidth` — Column width tier: compact / regular (default) / wide (Ant Pro Board / HeroUI Pro kanban column sizing).
- `.spacing` — Gap between columns by spacing token (default `.md`).

## KeyValueTable

```swift
init(rows: [KeyValueTable.Row])

// usage: KeyValueTable(rows: <[KeyValueTable.Row]>)
```

**Modifiers**

- `.title` — Heading rendered above the table.
- `.bordered` — Wraps the table in a bordered, padded surface (drawn by the active `CardStyle`).
- `.surface` — Surface fill for the bordered shell (background token key, default `.bgWhite`).

## ListRow

A flexible list row that consolidates the reference ListItem family (Default / Chevron / Checkbox / Radio / Menu / Quick-action) into one token-bound view.

```swift
init(_ title: String, action: (() -> Void)? = nil)

// usage: ListRow("title")
```

**Modifiers**

- `.subtitle` — Secondary line under the title.
- `.number` — Leading two-digit ordinal badge.
- `.size` — Title weight/size tier: small / regular / bold.
- `.icon` — Leading SF Symbol (in a circular chip).
- `.leadingImage` — Leading remote thumbnail.
- `.leadingSelection` — Leading radio selector bound to `selection`.
- `.alertCount` — Red count bubble on the leading icon.
- `.badge` — Inline badge next to the title.
- `.meta` — Per-row meta line (rating / sentiment / comment count).
- `.infos` — Bulleted info lines under the title.
- `.selected` — Active/selected background treatment.
- `.multilineTitle` — Allow the title/subtitle to wrap instead of truncating.
- `.trailing` — Trailing accessory: chevron / value / toggle / checkmark / checkbox / button / price / status.
- `.onInfo` — Trailing info button with its own action.

## ListSectionHeader

A non-interactive section-header row inside a list (Reference menu `.secondary`).

```swift
init(_ title: String)

// usage: ListSectionHeader("title")
```

**Modifiers**

- `.textStyle` — Typography of the header label (default `.labelSm700`).
- `.accent` — Token-fed tint for the header label; `nil` (default) keeps tertiary text.

## ListView

Ant-style List container: optional header/footer, bordered surface, row dividers (split), and a loading (skeleton) state.

```swift
init(_ items: [Item], @ViewBuilder row: @escaping (Item) -> Row)

// usage: ListView(<[Item]>, @ViewBuilder: <@escaping (Item) -> Row>)
```

**Modifiers**

- `.header` — Header text above the rows.
- `.footer` — Footer text below the rows.
- `.surface` — Surface variant of the list container (HeroUI `Surface` parity): `.primary` (bordered card, default), `.secondary`, `.tertiary`, or `.transparent`.
- `.bordered` — Draw the bordered card surface around the list.
- `.loading` — Replace rows with skeleton placeholders while content loads.
- `.split` — Show dividers between rows (and around header/footer).
- `.emptyText` — Text shown when there are no items (defaults to "No data").

## LocationCard

```swift
LocationCard(title:, coordinate:)
```

**Modifiers**

- `.surface` — Surface fill (background token key, default `.bgBase`).
- `.subtitle` — An address line under the title.
- `.distance` — A distance line, e.g.
- `.mapHeight` — Map preview height in points (default 140).
- `.spanMeters` — The map's visible span in meters (default 800).
- `.onTap` — Called when the card is tapped (e.g.
- `.pois` — Extra points of interest pinned on the map (nearby landmarks, transit…).
- `.directions` — Shows a "Directions" button.
- `.onDirections` — Custom handler for the Directions button (overrides the default Apple Maps launch).
- `.snapshot` — Renders a static MKMapSnapshotter image instead of a live `Map` — far cheaper in long scrolling lists (a live Map per row is expensive).

## LoyaltyCard

A token-bound loyalty membership card.

```swift
LoyaltyCard(tier:, points:)
```

**Modifiers**

- `.surface` — Back-face surface fill (background token key, default `.bgBase`).
- `.memberName` — The member's name, shown under the tier.
- `.unit` — The points unit (default `"pts"`).
- `.progress` — Progress (0…1) to the next tier, with its name.
- `.icon` — A tier SF Symbol (default `seal.fill`).
- `.gradient` — Overrides the brand gradient with semantic tokens (each hue's solid shade); `nil` restores the theme's primary 600→900 gradient.
- `.animatesValue` — Animates the points balance on change (numeric-text; no-op under Reduce Motion).
- `.membership` — A scannable membership code (QR or barcode) shown on the card back.
- `.flippable` — Lets the card flip to its membership code on tap (needs `.membership`).

## MapCallout

```swift
MapCallout(title:)
```

**Modifiers**

- `.image`
- `.subtitle`
- `.score`
- `.price`
- `.onSelect`
- `.accent` — Tints the border and CTA chevron (default: neutral border, tertiary chevron).
- `.surface`
- `.pointer`

## MenuCard

```swift
init(items: [MenuCard.Item])

// usage: MenuCard(items: <[MenuCard.Item]>)
```

**Modifiers**

- `.subtitle` — Secondary line under the title (single-link form).
- `.icon` — Leading SF Symbol for the link (single-link form).

## NavigationBar

```swift
init(items: [NavigationBar.Item], selection: Binding<Int>)

// usage: NavigationBar(items: <[NavigationBar.Item]>, selection: $selection)
```

## NotificationCard

```swift
init(title: String)

// usage: NotificationCard(title: "title")
```

**Modifiers**

- `.message` — Body text under the title.
- `.date` — Timestamp line above the title.
- `.unread` — Show the unread dot next to the timestamp.
- `.variant` — Semantic variant driving the leading icon and its color (nil = bell).
- `.onClose` — Show a trailing dismiss button invoking `action`.
- `.action` — Inline call-to-action under the message — e.g.
- `.secondaryAction` — Optional secondary inline action rendered after the primary — e.g.
- `.surface` — Surface fill (background token key, default `.bgWhite`).
- `.cornerRadius` — Container corner radius role (default `.box`).
- `.elevation` — Surface elevation (default `.soft` — the classic card shadow).

## PageHeader

```swift
init(_ title: String)

// usage: PageHeader("title")
```

**Modifiers**

- `.subtitle` — Secondary line under the title (plain-title center only).
- `.showTitle` — Hide the title (per-style `Show Title` toggle).
- `.tags` — Status tags shown next to the title.
- `.searchSummary` — Bind a ``SearchSummary`` sub-component as the center block (date/guests, optionally with a location title and the boxed pill presentation).
- `.searchField` — Replace the center with a bound search input pill.
- `.logo` — Replace the center with a brand logo (any view) — used by `.brand` chrome.
- `.onBack` — Show a leading back button invoking `action`.
- `.leading` — A custom leading icon button (menu / hamburger) instead of the back arrow.
- `.actions` — Trailing icon actions.
- `.primaryButton` — A trailing brand-soft primary pill (call-to-action).
- `.mapFilter` — A filled square filter/edit button inside the On Map search card (`.onImage` chrome + a bound ``SearchSummary``).
- `.tabs` — Accessory band: a tab row with a hero underline on `selected`.
- `.progress` — Accessory band: a hero progress line across the bottom (0…1).
- `.stepper` — Accessory band: a segmented stepper — `current` of `total` filled.

## PagingCarousel

Custom drag-paging carousel with PEEKING neighbors + threshold snap (the reference `PagingScrollView`).

```swift
init(_ items: [Item], @ViewBuilder content: @escaping (Item) -> Content)

// usage: PagingCarousel(<[Item]>, @ViewBuilder: <@escaping (Item) -> Content>)
```

**Modifiers**

- `.peek` — How much of the previous / next tile peeks at each edge (default 32pt).
- `.spacing` — Spacing between tiles (default 12pt).
- `.autoplay` — Advances tiles automatically every `interval` seconds.

## PhoneFrame

```swift
PhoneFrame(content:)
```

**Modifiers**

- `.notch` — Camera cutout style: island / notch / none (default island).
- `.bezel` — Bezel color family — the 900 ladder step frames the device (default neutral).

## PriceAlertCard

```swift
PriceAlertCard(title, isOn:)
```

**Modifiers**

- `.subtitle`
- `.icon`
- `.price`
- `.trend`
- `.accent`
- `.surface`
- `.cornerRadius`
- `.elevation` — Surface elevation (default `.none` — the original hairline-bordered look).

## PromoBanner

```swift
init(_ title: String, action: (() -> Void)? = nil)

// usage: PromoBanner("title")
```

**Modifiers**

- `.subtitle` — Secondary line under the title.
- `.icon` — Leading SF Symbol visual.
- `.ctaTitle` — Trailing call-to-action button title (renders only when paired with the init `action`).
- `.accent` — Banner tint treatment: blue / dark / turquoise (R4 token-bound).
- `.color` — Banner tint treatment: blue / dark / turquoise.

## RatingSummary

```swift
init(score: Double)

// usage: RatingSummary(score: 1)
```

**Modifiers**

- `.label` — Qualitative label shown next to the score badge (e.g.
- `.reviews` — Review-count link and its tap handler (link is disabled without a handler).

## ResultView

Ant-style "Result" template: a full-page status view for the outcome of an operation (success / info / warning / error) or an exception page (404 / 403 / 500), with up to two actions.

```swift
init(_ status: ResultStatus, title: String)

// usage: ResultView(<ResultStatus>, title: "title")
```

**Modifiers**

- `.message` — Supporting text under the title.
- `.subtitle` — Alias for ``message(_:)`` — mirrors Ant's `subTitle`.
- `.icon` — Replace the status emblem with a custom icon / illustration (Ant `icon`).
- `.content` — Arbitrary body content between the subtitle and the actions (Ant children).
- `.extra` — A custom actions area, replacing the primary/secondary buttons (Ant `extra`).
- `.primaryAction` — Primary (status-tinted) action button — renders when both title and action are set.
- `.secondaryAction` — Secondary (outline) action button — renders when both title and action are set.

## ReviewCard

A token-bound single review card.

```swift
ReviewCard(author:, score:, text:)
```

**Modifiers**

- `.surface` — Surface fill (background token key, default `.bgBase`).
- `.cornerRadius` — Container corner radius role (default `.box`).
- `.elevation` — Surface elevation (default `.none` — the original hairline-bordered look).
- `.date` — The review date, shown under the author.
- `.title` — A bold one-line summary above the body.
- `.verified` — Shows a verified-stay seal next to the author.
- `.photos` — A horizontal strip of review photos.
- `.stars` — Shows a star rating (derived from the 0–10 score) instead of the ScoreBadge.
- `.expandable` — Truncates long text to 3 lines with a "Read more" toggle.
- `.onPhotoTap` — Called with the photo index when a photo is tapped (enables the lightbox).

## RoomCard

```swift
RoomCard(name:)
```

**Modifiers**

- `.image`
- `.board`
- `.occupancy`
- `.features`
- `.price`
- `.original`
- `.unit`
- `.discountBadge`
- `.badge`
- `.selection` — Radio selection binding (mutually exclusive with ``onSelect(_:action:)``).
- `.onSelect` — A trailing Select button.
- `.accent`
- `.cornerRadius`
- `.elevation`
- `.surface`

## SegmentedTabBar

Tab bar with a selection binding and an animated underline.

```swift
init(_ items: [TabItem], selection: Binding<Int>, onClose: ((Int) -> Void)? = nil, onAdd: (() -> Void)? = nil)

// usage: SegmentedTabBar(<[TabItem]>, selection: $selection)
```

**Modifiers**

- `.scrollable` — Let the bar scroll horizontally instead of distributing tabs evenly.
- `.tabStyle` — Visual treatment: underline / card / pill (boxed track, filled active tab).
- `.size` — Tab-bar density (Ant Tabs `size`): small / medium (default) / large — scales the label type, icon glyph and pill/card padding together.
- `.scrollAlign` — Where a scrollable bar parks the selected tab on selection change (HeroUI Tabs `scrollAlign`; default `.center`).
- `.dividers` — Draw a hairline in the border token between adjacent tabs (HeroUI Tabs.Separator).
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`).

## RadioCard

Organisms.

```swift
init(_ title: String, isSelected: Bool, action: @escaping () -> Void)

// usage: RadioCard("title", isSelected: true, action: { })
```

**Modifiers**

- `.description` — Secondary description line under the title.

## CheckboxCard

```swift
init(_ title: String, isChecked: Bool, action: @escaping () -> Void)

// usage: CheckboxCard("title", isChecked: true, action: { })
```

**Modifiers**

- `.description` — Secondary description line under the title.

## SheetHeader

```swift
SheetHeader(title)
```

**Modifiers**

- `.subtitle`
- `.onBack` — Adds a leading back (‹) button.
- `.onClose` — Adds a trailing close (✕) button.
- `.progress` — A bottom progress line (0…1) for a multi-step flow (replaces the divider).
- `.showsDivider` — Draw the bottom hairline divider (default on; ignored when a progress bar is shown).
- `.accent`
- `.surface` — Surface fill (background token key).

## Sidebar

```swift
init(sections: [Sidebar.Section], selection: Binding<String?>)

// usage: Sidebar(sections: <[Sidebar.Section]>, selection: $selection)
```

**Modifiers**

- `.header` — A custom view pinned above the navigation list (brand mark, profile…).
- `.footer` — A custom view pinned to the bottom of the sidebar (settings, sign-out…).
- `.width` — Fixed sidebar width (defaults to flexible / parent-driven).
- `.a11yID` — Stable accessibility identifier for the sidebar container.

## ThemePicker

A grid of `ThemePreset` preview cards.

```swift
init(selection: Binding<String?>, themes: [ThemePreset] = ThemePreset.all, onSelect: ((ThemePreset) -> Void)? = nil)

// usage: ThemePicker(selection: $selection)
```

**Modifiers**

- `.columns` — Fix the grid to `count` equal columns; `nil` (default) keeps the adaptive 160–240pt sizing.
- `.spacing` — Gap between cards, both axes (default 12).

## TicketStub

A token-bound ticket / boarding-pass surface.

```swift
TicketStub(content:)
```

**Modifiers**

- `.perforation` — Draw the dashed perforation across the tear line (default on).
- `.notchRadius` — Radius of the side notches (default 10).
- `.cornerRadius` — Outer corner radius (radius role token, default `.box`).
- `.elevation` — Surface elevation: none / soft / elevated.
- `.surface` — Surface fill (background token key, default `.bgBase`).
- `.dashColor` — Perforation dash colour (border token key, default `.borderPrimary`).
- `.contentPadding` — Inner content padding (spacing token key, default `.md`).

## Timeline

```swift
init(_ items: [Timeline.Item])

// usage: Timeline(<[Timeline.Item]>)
```

**Modifiers**

- `.axis` — Rail orientation: vertical (default) or horizontal.
- `.mode` — Content placement around the rail: left / right / alternate (vertical only).
- `.reversed` — Flip the item order.
- `.pending` — Trailing loading ("pending") node with its label.

## Upload

```swift
init(prompt: String = String(themeKit: "Add a photo from your device or take one with the camera."), files: [UploadFile] = [], onPick: @escaping () -> Void = {}, onRemove: @escaping (UploadFile) -> Void = { _ in }, onRetry: ((UploadFile) -> Void)? = nil)

// usage: Upload()
```

**Modifiers**

- `.buttonTitle` — Title of the file-picker button.
- `.maxCount` — Cap the number of files; once reached the picker is disabled and a count is shown.
- `.onPreview` — Make each file's thumbnail a tappable preview (Ant `onPreview`) — e.g.
- `.onDownload` — Show a download icon on completed files and fire this when tapped (Ant `onDownload` / `showDownloadIcon`).
- `.showsRemoveIcon` — Show the per-file remove (trash) icon (Ant `showRemoveIcon`; default on).
- `.showsList` — Render the file list (Ant `showUploadList`; default on).
- `.listType` — Presentation of the file list (Ant `listType`): `.list` rows (default) or a `.pictureCard` thumbnail grid whose trailing add tile is the picker.

## UploadList

`Upload` wired to an `UploadController` — renders its files with remove + retry.

```swift
init(controller: UploadController, onPick: @escaping () -> Void = {})

// usage: UploadList(controller: <UploadController>)
```

**Modifiers**

- `.prompt` — Prompt text shown above the picker button.
- `.buttonTitle` — Title of the file-picker button.

## VideoPlayerView

Inline video on AVKit (reference `InlineVideoPlayerView`): autoplay, loop, mute, aspect-fill, and active-gating (only the visible item plays).

```swift
init(_ url: URL?, progress: Binding<Double>? = nil, isMuted: Binding<Bool>? = nil, onTap: (() -> Void)? = nil, isActive: Binding<Bool> = .constant(true))

// usage: VideoPlayerView(<URL>)
```

**Modifiers**

- `.autoplay` — Whether the video starts playing on appear (default true).
- `.loop` — Whether playback loops back to the start (default true).
- `.muted` — Whether the audio starts muted (default true — required for iOS inline autoplay).
- `.muteToggle` — Shows a mute/unmute toggle button overlay.
- `.tapToToggle` — Whether tapping the video toggles play/pause.

## WindowFrame

```swift
WindowFrame(title, content:)
```

**Modifiers**

- `.elevation` — Surface elevation: none / soft / elevated (default soft).
- `.accent` — Tint the title bar with a semantic color; `nil` (default) uses neutral chrome.

## AirportPicker

Airport search & select.

```swift
AirportPicker(selection:, suggestions:)
```

**Modifiers**

- `.onQueryChange` — Debounced query callback — the caller performs its lookup and updates `suggestions`.
- `.debounce` — Debounce interval for the query callback (default 0.25s, clamped ≥ 0).
- `.recent` — Recent airports shown before typing; the optional action drives the section header's Clear button.
- `.popular` — Curated popular airports shown before typing.
- `.nearby` — Airports near the user shown before typing (the caller resolves location).
- `.loading` — Skeleton rows while the caller's lookup is in flight.
- `.placeholder` — Placeholder for the search field / sheet trigger (default "City or airport").
- `.presentation` — `.inline` (default) embeds the picker; `.sheet`, `.popover` and `.fullScreenCover` render a field-shaped trigger that opens the search UI in the matching container (`.fullScreenCover` degrades to a sheet on macOS).
- `.rowContent` — Replaces the built-in suggestion row with caller content, built per `(airport, isSelected)`.
- `.sectionTitles` — Overrides the pre-typing section headers; `nil` keeps the stock English-generic titles ("Nearby" / "Recent" / "Popular").
- `.chipVariant` — Fill style of the IATA code chip: `.soft` (default), `.solid`, `.outline` or `.ghost` — all resolved from the accent's semantic ladder.
- `.detents` — Detents for the `.sheet` presentation (default `[.large]`).
- `.triggerIcon` — SF Symbol on the field-shaped trigger (default `"airplane"`).
- `.density` — Row density: `.regular` (default) or `.compact`.
- `.surface` — Surface fill behind the search field and sections (background token key); unset keeps the transparent default — the picker rides its screen's background.
- `.accent` — Semantic tint for the code chips, selection checkmark and Clear action; `nil` (default) keeps the hero/neutral tokens.
- `.a11yID` — Sets the accessibility-identifier namespace for this component (its sub-elements get `"<id>.<element>"`, e.g.

## AncillaryCard

```swift
AncillaryCard(title)
```

**Modifiers**

- `.icon`
- `.image`
- `.subtitle`
- `.price`
- `.badge`
- `.quantity` — A quantity stepper bound to `binding` (controlled — mutually exclusive with ``added(_:title:addedTitle:)``).
- `.added` — An add/remove toggle bound to `binding` (controlled; English defaults, overridable).
- `.accent`
- `.elevation` — Shell elevation, fed to the active `CardStyle` (default `.none` — today's flat, hairline-only chrome).
- `.surface`
- `.controlSurface` — Surface token for the quantity stepper's capsule track (default `.bgSecondary`) — distinct from ``surface(_:)``, which fills the card shell.
- `.cornerRadius`

## BoardingPass

```swift
BoardingPass(passenger:, from:, to:)
```

**Modifiers**

- `.airline`
- `.flightNo`
- `.cabin`
- `.cities`
- `.times`
- `.date`
- `.details` — The labelled detail cells (gate / seat / boarding / terminal…), in order.
- `.gate` — Convenience for the common gate / seat / boarding trio.
- `.bookingRef`
- `.passengerLabel` — Localise the "Passenger" caption (English default).
- `.barcode` — A Code-128 barcode in the stub.
- `.qr` — A QR code in the stub (instead of a barcode).
- `.accent`
- `.surface`
- `.elevation`
- `.codeSize` — Footprint of the stub's QR / barcode (default `.medium` — the classic sizes).
- `.detailsLayout` — Detail-cell arrangement: one `.row` (default) or a two-column `.grid` — honoured by `.classic`.
- `.cornerRadius` — Outer corner radius (radius role token, default `.box`) — forwarded to the active style.
- `.perforation` — Draw the dashed perforation across the tear line (default on) — tear presets only.
- `.dashColor` — Perforation dash colour (border token key, default `.borderPrimary`) — tear presets only.

## CheckInFlow

A check-in journey scaffold — `Steps` header + the current page + a Back / Continue dock.

```swift
CheckInFlow(steps:, selection:, page:)
```

**Modifiers**

- `.nextTitle` — Title of the advancing dock button (default "Continue"); on the last step the button shows ``doneTitle(_:)`` instead.
- `.backTitle` — Title of the back dock button (default "Back").
- `.doneTitle` — Title of the advancing button on the last step (default "Done") — the tap calls ``onComplete(_:)`` instead of advancing.
- `.canAdvance` — Gate advancing (e.g.
- `.onComplete` — Called when the advancing button is tapped on the last step.
- `.showsStepper` — Show or hide the progress chrome — whichever ``CheckInFlowStyle`` is active (`Steps` header, bar or dot pager) — for compact hosts that provide their own.
- `.accent` — Semantic tint for the done/active step markers; `nil` (default) keeps the stock theme-hero markers.
- `.dockLayout` — Built-in dock alignment: `.trailing` (default, packed buttons) or `.stretch` (full-width buttons).
- `.buttonSize` — Control size of the built-in dock buttons (default `.medium`).
- `.stepsTappable` — Lets a tap on a *done* marker jump back to that step (markers gain the button trait).
- `.pageTransition` — Page-change motion: `.slide` (default, RTL-mirrored), `.fade`, or `.none` — all applied through the `MicroMotion` / Reduce-Motion gate.
- `.stepperSize` — Marker/label size of the `Steps` header (default `.medium`).
- `.stepperPlacement` — Progress-chrome placement: `.top` (default) or `.leading` — a vertical `Steps` rail beside the page.
- `.progressStyle` — Progress chrome: `.steps` markers or `.bar` — superseded by the style axis: prefer `.checkInFlowStyle(.steps/.bar/.paged)`, settable once per screen via the environment.

## FareFamilyCard

A token-bound fare-family option card.

```swift
FareFamilyCard(name, price:)
```

**Modifiers**

- `.surface` — Surface fill (background token key).
- `.currency` — Currency code for the price.
- `.accent` — The tier accent colour — brands the name badge and CTA (green / orange / purple…).
- `.features` — The feature & rule lines.
- `.selected` — Selected state (for a CTA card without a binding).
- `.selection` — Bind selection — presets render a price + radio row instead of a CTA button.
- `.onSelect` — Called when the card's CTA is tapped.
- `.ctaTitle` — A custom CTA title (e.g.
- `.badgeVariant` — Fill treatment of the tier name chip (default `.solid`).
- `.elevation` — Shell elevation, fed to the active `CardStyle` (default `.none` — today's flat, hairline-only chrome).
- `.expanded` — Drives `.accordion`'s expansion from outside — e.g.
- `.layout` — Layout archetype — superseded by the style axis: prefer `.fareFamilyCardStyle(.stacked/.column/.row/.accordion)`, settable once per screen via the environment.

## FareSummary

A token-bound fare breakdown.

```swift
FareSummary(lines, currencyCode:)
```

**Modifiers**

- `.onInfo` — Called when a line's info button is tapped (only lines created with `info:` show one).
- `.expandable` — Makes the breakdown collapsible behind the total row, bound to the caller's expansion flag (controlled).
- `.totalSize` — Size of the total `PriceTag` (default `.large`).
- `.totalEmphasis` — Emphasis of the total `PriceTag` (default `.hero`).
- `.showsDivider` — Draw the divider above the total row (default on).
- `.currency` — Currency code for every line.

## FilterBar

```swift
FilterBar(chips, selection:)
```

**Modifiers**

- `.onFilter` — Adds the pinned leading Filter button (collapses to icon-only on scroll).
- `.onSort` — Adds the pinned leading Sort button (collapses to icon-only on scroll).
- `.collapsible` — Whether the leading buttons collapse to icons on scroll (default on).
- `.size` — Overall size (heights + typography): small / medium (default) / large.
- `.chipStyle` — Chip selection look — `.solid` (accent fill) or `.outlined` (the design-system light-blue + hero-border pill).
- `.leadingShape` — Leading Filter/Sort button shape — `.adaptive` (collapsing text) or `.circle` (a fixed accent circle, icon-only).
- `.accent` — Token-fed accent for the leading buttons and selected chips (default hero).
- `.chipSurface` — Surface token for the unselected chip fill (default `.bgWhite`).
- `.spacing` — Gap between controls (default 8).
- `.selectionMode` — `.multiple` (default) toggles chips independently; `.single` keeps at most one chip on — tapping another chip replaces the selection.
- `.onClearAll` — Appends a trailing ghost "Clear" chip to the scroller, shown only while the selection is non-empty.
- `.overflowFade` — Fades the scroller's trailing edge with a gradient mask as an overflow hint (RTL-safe — `UnitPoint.leading/.trailing` mirror with the layout).

## FlightCard

A token-bound flight card — one segment, or a multi-leg itinerary.

```swift
FlightCard(airline:, from:, to:, departure:, arrival:)
```

**Modifiers**

- `.surface` — Surface fill (background token key).
- `.accent` — A semantic accent for the brand chrome — the airline icon, the route-path planes and the Select button.
- `.stops` — Number of stops (0 = nonstop, shown in green).
- `.price` — The fare, rendered as a hero `PriceTag` in the footer.
- `.airlineIcon` — A leading airline SF Symbol (default `airplane.circle.fill`).
- `.badge` — A success badge in the header, e.g.
- `.airlineLogo` — A remote airline logo in the header (overrides the SF Symbol) — parity with ``FlightResultRow/airlineLogo(_:)``.
- `.elevation` — Shell elevation, fed to the active `CardStyle` (default `.none` — today's flat, hairline-only chrome).
- `.selected` — Selected state, fed to the active `CardStyle` (the default style draws a hero border).
- `.onSelect` — Adds a "Select" button to the footer.
- `.favorite` — A heart toggle in the header bound to a favourite flag (controlled — the caller owns persistence).
- `.scarcity` — Shows a "N seats left" scarcity line (urgent colour).
- `.fareBrand` — A fare-brand chip next to the airline, e.g.

## FlightListItem

```swift
FlightListItem(legs:)
```

**Modifiers**

- `.surface` — Surface fill the style draws behind the item.
- `.sliceLabels` — Per-slice captions for multi-leg styles, e.g.
- `.flightNo`
- `.cabin`
- `.airlineIcon` — SF Symbol used when no custom logo slot is provided.
- `.price` — The headline price.
- `.original` — A compare-at price (typical/undiscounted) — deal-aware styles strike it through.
- `.fares` — Fare-family options (`.fareBoard` renders one chip per fare).
- `.departures` — Departure times for schedule-grouping styles (`.timetable`), plus an optional cadence note like "Nonstop · 1h 05m · every ~2h".
- `.deal` — A price-judgment signal ("23% below typical") with its semantic tone.
- `.trend` — Recent price history (normalized or raw) — styles may draw it as a sparkline.
- `.badge` — Ranking badge ("Best", "Cheapest").
- `.amenities` — SF Symbols for onboard amenities (Wi-Fi, power, …) — rich styles show them.
- `.baggage` — Baggage allowances shown in meta rows — carry-on ("8kg") and checked bag.
- `.onDetails` — Secondary "open details" action; styles with a details affordance show it.
- `.selected` — Marks the item as the current selection (styles accent it).
- `.onSelect` — Primary action; expandable styles pin it in the expanded footer.
- `.expanded` — Drives expandable styles (`.journey`) from outside — e.g.
- `.favorite` — Self-managed favourite heart (uncontrolled): every built-in style renders the heart in its identity/price corner and the item owns the flag.
- `.accent` — Selection accent — tints the selected border, fare/time chips and other emphasis colours the styles otherwise take from the theme's hero tokens.
- `.radius` — Corner-radius role of the card shell (default `.box`).
- `.meta` — Generic icon + text meta pairs, e.g.
- `.selectedFare` — Drives fare-chip selection (`.fareBoard`) from outside — e.g.
- `.selectedDeparture` — Drives departure-chip selection (`.timetable`) from outside — mirrors ``selectedFare(_:)``.

## FlightResultRow

```swift
FlightResultRow(airline:, from:, to:, departure:, arrival:)
```

**Modifiers**

- `.surface` — Surface fill (background token key) — feeds the active style's shell.
- `.accent` — A semantic accent for the brand chrome — the airline fallback glyph, the active bookmark and the Select button.
- `.flightNo` — Flight number, e.g.
- `.cabin` — Cabin class caption, e.g.
- `.stops` — Number of stops on the outbound leg (0 = direct, in green).
- `.returnLeg` — Adds a return leg (round-trip) — stacked under the outbound route.
- `.addLeg` — Adds an arbitrary extra leg (multi-city) — stacked in order.
- `.price` — The fare.
- `.airlineIcon` — A leading airline SF Symbol (default `airplane.circle.fill`).
- `.airlineLogo` — A remote airline logo (overrides the SF Symbol).
- `.baggage` — A baggage chip, e.g.
- `.badge` — A success badge, e.g.
- `.selected` — Selected state, fed to the active `CardStyle` (the default style draws a hero border).
- `.elevation` — Shell elevation, fed to the active `CardStyle` (default `.none` — today's flat, hairline-only chrome).
- `.priceFractionDigits` — Fraction digits for the fare `PriceTag` (default 2).
- `.favorite` — A heart toggle bound to a favourite flag (controlled — the caller owns persistence).
- `.bookmark` — A bookmark (save) toggle bound to a flag (controlled).
- `.totalPrice` — A secondary total-price line under the fare, e.g.
- `.urgency` — An urgency note in the meta row, shown in error red (e.g.
- `.onSelect` — Adds a Select button (with an optional custom title).
- `.onDetails` — Adds a "Details" link in the meta row.

## FlightTicketCard

```swift
FlightTicketCard(from:, to:)
```

**Modifiers**

- `.cities`
- `.times`
- `.duration`
- `.stops`
- `.airline`
- `.airlineLogo`
- `.price`
- `.original` — Pre-discount price shown struck through next to the price (via `PriceTag.original(_:)`); `nil` (the default) hides it.
- `.favorite` — A heart toggle in the stub bound to a favourite flag (controlled — the caller owns persistence).
- `.accent`
- `.elevation`
- `.surface`
- `.cornerRadius` — Outer corner radius (radius role token, default `.box`).
- `.perforation` — Draw the dashed perforation across the tear line (default on) — tear presets only.
- `.dashColor` — Perforation dash colour (border token key, default `.borderPrimary`).
- `.priceEmphasis` — Emphasis of the stub's `PriceTag` (default `.standard`).

## FlightTracker

The live flight status board — badge, route + progress, schedule vs estimate, gate/terminal/belt facts and a phase timeline, on a `Card` shell.

```swift
FlightTracker(info)
```

**Modifiers**

- `.progress` — En-route progress 0…1 drawn along the route path (clamped; `nil` hides it).
- `.updated` — "Updated 2 minutes ago" caption — formatted with the environment locale.
- `.details` — Extra fact rows appended to the facts grid, e.g.
- `.showsTimeline` — Show the Check-in → Boarding → Departed → Arrived phase timeline (default on).
- `.accent` — Semantic tint for the progress treatment and estimate emphasis; `nil` (default) derives from the status (`FlightStatus.semantic`).
- `.surface` — Surface fill for the card shell (background token key).
- `.elevation` — Card shell elevation: none / soft (default) / elevated.
- `.variant`
- `.showsFacts` — Show the gate/terminal/desk/belt facts grid (default on; `.board`/`.timeline`).
- `.showsEstimates` — Show the schedule-vs-estimate rows (and the `.compact`/`.banner` estimate time) when estimates differ meaningfully from the schedule (default on).
- `.phaseTitles` — Overrides the phase-timeline titles; `nil` keeps the stock English-generic titles ("Check-in" / "Boarding" / "Departed" / "Arrived").
- `.contentPadding` — Inner padding of the card shell as a spacing token (default `.md`) — forwarded to the composed `Card`.
- `.progressContent` — Replaces the built-in route progress track, built per clamped 0…1 fraction.
- `.timelineSize` — Marker/label size of the phase timeline (default `.small`).

## PassengerForm

The editable traveler form for booking flows.

```swift
PassengerForm(title, draft:)
```

**Modifiers**

- `.fields` — Which fields render, in order (default: all).
- `.nationalities` — Nationality options as ISO 3166-1 region codes (default: all ISO regions).
- `.documentRequired` — Renders document number + expiry as required — asterisks on both, and (only when no `validator(_:)` is wired) the rule pack runs field-locally: `.required() + .documentNumber` on the number, `.required()` plus a future-only picker window on the expiry.
- `.birthDateRange` — Selectable date-of-birth window (default: 120 years back … today).
- `.validator` — Wires every rendered field into the given validator (ADR-F6): messages, focus and live re-validation flow through it, keyed by `PassengerFormField`.
- `.accent` — Accent tint for the interactive chrome (date pickers, menu checkmarks).
- `.label` — Overrides one field's built-in title (e.g.
- `.sectionTitles` — Overrides the section titles.
- `.layout` — Section chrome: `.stacked` (two `Fieldset`s, default), `.flat` (bare fields + plain titles, no fieldset chrome), or `.grouped` (everything in one `Fieldset`).
- `.genders` — The gender selector's options (default: all ``PassengerGender`` cases) — e.g.
- `.columns` — `2` renders given/family side-by-side (via `AdaptiveFit`, so narrow widths still stack); accessibility type sizes always fall back to stacked.

## PaymentMethodSelector

A payment-method chooser — radio-semantic rows (or tiles) over ``PaymentMethodOption`` values, with an optional inline instalment picker under the selected card option.

```swift
PaymentMethodSelector(options, selection:)
```

**Modifiers**

- `.variant` — Layout archetype — superseded by the style axis: prefer `.paymentMethodSelectorStyle(.list/.grid/.carousel/.compactList)`, settable once per screen via the environment.
- `.indicator` — Selected glyph: `.radio` (row-shaped presets' default), `.checkmark` (tile-shaped presets' default), or `.none` — the selected chrome alone signals the choice.
- `.columns` — Grid column count, clamped 1…4 (default 2).
- `.optionContent` — Replaces the built-in row/tile anatomy with caller content, built per `(option, isSelected)` in every style.
- `.badgeStyle` — Style of the per-option badges (default `.info`) — applies wherever the active style draws the `Badge` itself (tiles, carousel, compact rows); the `.list`/`.sectioned` row's badge is drawn by `ListRow`.
- `.radius` — Corner role for tile-shaped presets (default `.field`).
- `.emphasis` — Selected-tile stroke strength: `.subtle` (default, base step) or `.strong` (the 700 "strong" step at 2pt).
- `.installments` — Instalment plans shown inline under the selected `.card` option.
- `.badge` — Per-option badge, e.g.
- `.disabledMethods` — Options rendered disabled and excluded from selection.
- `.accent` — Semantic tint for the radio / selected chrome / instalment rows; `nil` (default) uses the primary triad.
- `.surface` — Surface token for the *unselected* tile-shaped presets' fill (default `.bgBase`); the selected tile keeps the accent tint and stroke.

## SavedCardsList

A stored-cards chooser — radio-semantic rows over ``SavedCard`` values with optional delete and add-new affordances.

```swift
SavedCardsList(cards, selection:)
```

**Modifiers**

- `.onDelete` — Enables the delete affordances — a trailing remove button on every row plus a destructive context-menu entry.
- `.onAddNew` — Appends an "Add new card" row (and wires the empty state's primary action) that invokes `action`.
- `.flagsExpired` — Expired cards (per `SavedCard.isExpired`) carry an "Expired" badge and auto-disable (default on); pass `false` to keep them selectable.
- `.accent` — Semantic tint for the radio / brand glyph / add-new chrome; `nil` (default) uses the primary triad.
- `.variant` — Layout archetype — superseded by the style axis: prefer `.savedCardsListStyle(.list/.wallet/.stack/.grid)`, settable once per screen via the environment.
- `.brandLogo` — Replaces the stock brand symbol with caller content, built per ``CardBrand`` — e.g.
- `.expiredBadge` — Overrides the expired flag's badge.
- `.showsDividers` — Show the hairline dividers between list rows (default on).
- `.surface` — Surface token: the `.list` style's backing fill, or the tile-shaped styles' card-face fill (default `.bgWhite` there).
- `.deleteStyle` — Which delete affordances render once ``onDelete(_:)`` is wired: `.button` (trailing trash), `.contextMenu`, or `.both` (default).
- `.rowContent` — Replaces the built-in row/tile anatomy with caller content, built per `(card, isSelected)`.

## SeatMap

A generic, token-bound seat map.

```swift
SeatMap(sections:, selection:)
```

**Modifiers**

- `.maxSelection` — Max seats a user can pick at once (default unlimited).
- `.seatSize` — Seat square size in points (default 44 — the HIG minimum touch target).
- `.showsLabels` — Shows a column-letter header and a row-number gutter derived from the seat ids.
- `.legend` — Appends a fare-tier legend (only the tiers actually present are shown).
- `.fuselage` — Frames the cabin in an aircraft fuselage (nose, tapered body, exit-door bands).
- `.showsSeatInfo` — Shows a live detail + running-total bar for the last-tapped seat.
- `.recommended` — Highlights recommended seats with a star.
- `.currency` — Currency code for per-seat and total pricing.
- `.seatEnabled` — A custom availability predicate — return false to block a seat (e.g.
- `.passengers` — Assigns seats to specific travellers: tapping a seat gives it to the active passenger (shown by their initials) and advances to the next unassigned one.
- `.zoomable` — Enables pinch-to-zoom (1×–2.5×) on the seat grid.
- `.seatDisplay` — How seats are labelled: `.icon` · `.number` · `.initials` · `.initialsAndNumber`.
- `.aisleWidth` — Width of a `.space` (gap) cell.
- `.tierColors` — Override fare-tier accent colours with semantic tokens — brand the tiers with your own palette.
- `.accent` — Accent for the passenger rail's and deck selector's **active** pill — the token's `.solid` shade fills the pill and `.onSolid` colours its text.
- `.seatShape` — The silhouette every seat is drawn with (`.rounded` default · `.circle` · `.seatback`).
- `.sectionHeader` — Replaces the built-in cabin-section header — receives the section title.
- `.summaryBar` — Replaces the built-in seat-summary bar — receives a live ``SeatSummary`` (focused seat, selection count, running total).
- `.legendPlacement` — Where the legend renders relative to the cabin: `.top` · `.bottom` (default) · `.hidden` (suppresses a `legend()` set upstream).
- `.fuselageSurface` — Surface fill of the fuselage frame (default `.bgSecondaryLight`).
- `.surface` — Explicit surface fill for a ``SeatMapStyle`` preset that draws its own chrome around the units (e.g.
- `.deckLabel` — Custom deck-pill titles for multi-deck cabins, e.g.

## StickyBookingBar

```swift
StickyBookingBar(ctaTitle, action:)
```

**Modifiers**

- `.price`
- `.original`
- `.note`
- `.discountBadge`
- `.ctaIcon`
- `.enabled`
- `.accent`
- `.surface` — Surface fill (background token key).
- `.showsShadow` — Show the bar's shadow (default on).
- `.secondaryAction` — An outline secondary action beside the primary CTA (e.g.
- `.onPriceTap` — Makes the price block tappable (adds a disclosure chevron) — open a fare-breakdown sheet from the bar.
- `.loading` — Show the CTA's loading spinner and block taps while `on` (forwarded to `ThemeButton.loading(_:)`).

## TransportCrossSellCard

A cross-sell for an alternative transport mode — "No flights? Take the bus/train" — with a mode glyph, route endpoints, a lead-in price and a CTA.

```swift
TransportCrossSellCard(mode, from:, to:)
```

**Modifiers**

- `.price` — Lead-in price; the currency code resolves via the §10 environment chain (`formatDefaults.currencyCode` → locale currency → "USD").
- `.duration` — Journey duration, e.g.
- `.departures` — Frequency/terminal note, e.g.
- `.badge` — A short accent-tinted flag, e.g.
- `.onSelect` — The call to action.
- `.variant` — Layout archetype — superseded by the style axis: prefer `.transportCrossSellCardStyle(.ribbon/.inline/.tile)`, settable once per list via the environment (and joined by the new `.banner` full-bleed strip).
- `.size` — Size ramp: `.medium` (default) or `.small` — scales the mode glyph, the `PriceTag` and the paddings together.
- `.tearStyle` — Ribbon tear-line chrome: `.notched` (default — the TicketStub cut + dashed perforation) or `.plain` (an uncut rounded strip).
- `.badgeVariant` — Fill variant of the badge (`.soft` default, `.solid`, `.outline`, `.ghost`); its color keeps following the accent→style mapping.
- `.shadow` — Shadow token under a preset's drawn surface (default `.soft`).
- `.accent` — Overrides the mode-tinted accent (bus `.warning`, train `.info`, ferry `.turquoise`, car `.neutral`); `nil` restores the default.
- `.surface` — Surface token for `.ribbon`/`.tile`'s drawn fill (default `.bgBase`); the ribbon's notch cut and dashed perforation are unaffected.

## TripSearchCard

```swift
TripSearchCard(draft:, onSearch:)
```

**Modifiers**

- `.airports` — Data for the embedded ``AirportPicker`` sheets (same caller-owned model as §9.4): the live `suggestions` for the typed query, plus optional `recent` / `popular` sections shown before typing.
- `.onAirportQuery` — Debounced query callback, plumbed into both embedded pickers — the caller runs its lookup and updates `suggestions`.
- `.dateRange` — Selectable date window (past dates excluded by default).
- `.showsCabinPicker` — Show the inline ``CabinClassSelector`` (default true).
- `.showsTripType` — Show the ``TripTypeToggle`` row (default true).
- `.ctaTitle` — CTA title (default "Search flights").
- `.variant` — Maps 1:1 onto the ``TripSearchCardStyle`` presets and, when called, wins over the environment style (source-behavior stability during migration — ADR-0004 §5).
- `.surface` — Surface fill by background token, threaded into the active ``CardStyle``'s configuration (e.g.
- `.elevation` — Card elevation.
- `.accent` — Semantic tint threaded through the composed pieces (trip-type pill, airport-picker chips, cabin selector, the `.pill` search disc).
- `.density` — Editor density: `.regular` (default) or `.compact` — tighter stacks resolved from spacing tokens.
- `.fieldIcons` — Overrides the field icons (SF Symbol names); `nil` keeps each field's stock symbol (origin/destination "airplane", departure "calendar", passengers "person.2").
- `.showsSwap` — Show the origin/destination swap affordance (default on).
- `.passengerSheetDetents` — Detents for the passengers bottom sheet (default `[.medium]`).
