lion-make 0.2.0 → 0.3.1

package/guidelines/content-types/general/rtb-dynamic.md

@@ -0,0 +1,55 @@
+# RTB - Dynamic
+
+**Zone:** General — Primary Column, Outro only. Not valid in Sideburn.
+
+## Description
+
+RTB (Reasons To Buy) variant that renders a responsive grid of benefit cards from a structured data source. Use when the number of items is variable or content-managed at runtime. Supports optional icons and horizontal rule separators.
+
+Compare with:
+- `RTBDescriptive` — text-heavy, explanatory body per item
+- `RTBHighlight` — large stat/number callouts
+- `RTBs` — illustration + short text list
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `items` | `RTBDynamicItem[]` | Yes | Array of benefit cards |
+| `heading` | `string` | No | Section heading |
+| `columns` | `2 \| 3 \| 4` | No | Number of grid columns (default: `3`) |
+| `showDividers` | `boolean` | No | Horizontal rules between rows (default: `false`) |
+| `className` | `string` | No | Additional CSS class |
+
+### RTBDynamicItem
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `heading` | `string` | Yes | Card title |
+| `body` | `string` | No | Supporting copy (1–2 sentences) |
+| `iconSrc` | `string` | No | Icon URL |
+| `iconAlt` | `string` | No | Icon alt text |
+
+## Usage
+
+```tsx
+import { RTBDynamic } from 'lion-make'
+
+<RTBDynamic
+  heading="What's included"
+  columns={3}
+  items={[
+    { iconSrc: '/icons/shield.svg', iconAlt: '', heading: 'Death benefit', body: 'Tax-free lump sum paid to your beneficiary.' },
+    { iconSrc: '/icons/calendar.svg', iconAlt: '', heading: 'Flexible terms', body: '10, 20, or 30-year term options.' },
+    { iconSrc: '/icons/dollar.svg', iconAlt: '', heading: 'Level premiums', body: 'Locked-in rate for the life of your policy.' },
+  ]}
+/>
+```
+
+## Design Tokens
+
+- Grid gap: `var(--Grid-gutter-size)`
+- Card border: `var(--border-width-thin)` solid `var(--color-line)`
+- Card border-radius: `var(--border-radius-base)`
+- Heading: `var(--h4-font-size)`, `var(--font-weight-600)`
+- Body: `var(--body-font-size)`, `var(--font-weight-400)`

package/guidelines/content-types/general/rtb-highlight.md

@@ -0,0 +1,50 @@
+# RTB - Highlight
+
+**Zone:** General — Primary Column, Sideburn, Outro.
+
+## Description
+
+RTB (Reasons To Buy) variant using large stat/metric callouts as the primary visual hook. Each item leads with a bold number or short phrase, followed by a brief label. Use when data communicates trust more effectively than prose.
+
+Compare with:
+- `RTBDescriptive` — text-heavy, explanatory body per item
+- `RTBDynamic` — multi-column grid driven by a data source
+- `RTBs` — illustration + short text list
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `items` | `RTBHighlightItem[]` | Yes | Array of stat items (3–5 recommended) |
+| `heading` | `string` | No | Optional section heading |
+| `layout` | `'row' \| 'column'` | No | Arrangement direction (default: `'row'`) |
+| `className` | `string` | No | Additional CSS class |
+
+### RTBHighlightItem
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `stat` | `string` | Yes | The headline number or short phrase (e.g., "100+ years", "A+ rating") |
+| `label` | `string` | Yes | Brief description of what the stat represents |
+
+## Usage
+
+```tsx
+import { RTBHighlight } from 'lion-make'
+
+<RTBHighlight
+  heading="Trusted by families since 1909"
+  items={[
+    { stat: '100+', label: 'Years in business' },
+    { stat: 'A+', label: 'AM Best financial strength rating' },
+    { stat: '$2.4B', label: 'Claims paid in 2023' },
+    { stat: '4M+', label: 'Customers nationwide' },
+  ]}
+/>
+```
+
+## Design Tokens
+
+- Stat text: `var(--h1-font-size)`, `var(--font-weight-700)`, `var(--color-brand)`
+- Label text: `var(--h5-font-size)`, `var(--font-weight-400)`, `var(--color-gray-dark)`
+- Dividers between items: `var(--border-width-thin)` solid `var(--color-line)`

package/guidelines/content-types/general/side-menu-explorer.md

@@ -0,0 +1,62 @@
+# Side Menu Explorer
+
+**Zone:** General — Primary Column only. Not valid in Sideburn or Outro.
+
+## Description
+
+A vertically-stacked tabbed navigation that controls which content panel is visible. Renders as a left-side menu with a persistent panel to the right. Typically used on product and category pages to let users explore coverage options without navigating away.
+
+This component is structural (contains panels), so it must not be nested inside another Container.
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `items` | `SideMenuExplorerItem[]` | Yes | Tabs and their associated panels |
+| `defaultActiveIndex` | `number` | No | Index of the tab to show on load (default: `0`) |
+| `heading` | `string` | No | Accessible heading above the menu |
+| `className` | `string` | No | Additional CSS class |
+
+### SideMenuExplorerItem
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | Yes | Tab button label |
+| `panelContent` | `React.ReactNode` | Yes | Content rendered when this tab is active |
+| `id` | `string` | No | Unique ID (used for `aria-controls`; auto-generated if omitted) |
+
+## Usage
+
+```tsx
+import { SideMenuExplorer } from 'lion-make'
+
+<SideMenuExplorer
+  heading="Explore our life insurance options"
+  items={[
+    {
+      label: 'Term Life',
+      panelContent: <TermLifePanel />,
+    },
+    {
+      label: 'Whole Life',
+      panelContent: <WholeLifePanel />,
+    },
+    {
+      label: 'Universal Life',
+      panelContent: <UniversalLifePanel />,
+    },
+  ]}
+/>
+```
+
+## Accessibility
+
+- Menu uses `role="tablist"`, each tab `role="tab"`, each panel `role="tabpanel"`.
+- Active tab has `aria-selected="true"`.
+- Panel linked via `aria-labelledby`.
+
+## Design Tokens
+
+- Menu background: `var(--color-gray-lightest)`
+- Active tab: left border `var(--border-width-thick)` solid `var(--color-brand)`, text `var(--color-brand)`, `var(--font-weight-600)`
+- Inactive tab: `var(--color-gray-dark)`, `var(--font-weight-400)`

package/guidelines/content-types/general/simple-cta-block.md

@@ -0,0 +1,44 @@
+# Simple CTA Block
+
+**Zone:** General — Primary Column, Sideburn, Outro.
+
+## Description
+
+A lightweight call-to-action block with a headline, optional subtext, and a single primary button. Distinct from `CTA` (the inline CTA element) — `SimpleCTABlock` is a standalone section block with its own container and background treatment.
+
+Use for mid-page conversion nudges that don't need the full weight of a Hero.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `heading` | `string` | Yes | — | Block headline |
+| `subtext` | `string` | No | — | Supporting copy, displayed below the heading |
+| `ctaLabel` | `string` | Yes | — | Button text |
+| `ctaHref` | `string` | Yes | — | Button destination |
+| `ctaVariant` | `'primary' \| 'secondary'` | No | `'primary'` | Button style |
+| `background` | `'white' \| 'gray' \| 'brand'` | No | `'white'` | Block background color |
+| `alignment` | `'left' \| 'center'` | No | `'center'` | Text alignment |
+| `className` | `string` | No | — | Additional CSS class |
+
+## Usage
+
+```tsx
+import { SimpleCTABlock } from 'lion-make'
+
+<SimpleCTABlock
+  heading="Ready to protect your family?"
+  subtext="Takes less than 5 minutes. No medical exam required."
+  ctaLabel="Get a free quote"
+  ctaHref="/quote"
+  background="gray"
+/>
+```
+
+## Design Tokens
+
+- Background `gray`: `var(--color-gray-lightest)`
+- Background `brand`: `var(--color-brand)`, text `var(--color-white)`
+- Heading: `var(--h2-font-size)`, `var(--font-weight-700)`
+- Subtext: `var(--body-font-size)`, `var(--font-weight-400)`
+- Padding: `var(--padding-large-v)` vertical

package/guidelines/content-types/general/spacing-block.md

@@ -0,0 +1,40 @@
+# Spacing Block
+
+**Zone:** General — Primary Column, Sideburn, Outro.
+
+## Description
+
+An invisible structural block that inserts vertical whitespace between other content types. Use to control rhythm and breathing room without wrapping content in a full Container.
+
+Renders as an empty `<div>` with a configurable height — no visible output.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | No | `'md'` | Vertical height of the space |
+| `className` | `string` | No | — | Additional CSS class |
+
+## Size Reference
+
+| Size | Rendered height |
+|---|---|
+| `xs` | `var(--spacing-xs)` — 0.8rem |
+| `sm` | `var(--spacing-sm)` — 1.6rem |
+| `md` | `var(--spacing-md)` — 3.2rem |
+| `lg` | `var(--spacing-lg)` — 6.4rem |
+| `xl` | `var(--spacing-xl)` — 9.6rem |
+
+## Usage
+
+```tsx
+import { SpacingBlock } from 'lion-make'
+
+<SpacingBlock size="lg" />
+```
+
+## When to use vs Container padding
+
+- Use `SpacingBlock` between two sibling content types that each render in their own Container.
+- Use Container `padding` props when you need to control space inside a single Container's top/bottom.
+- Do not use `SpacingBlock` inside a Container — that creates double-spacing artifacts.

package/guidelines/content-types/general/speed-bump.md

@@ -0,0 +1,45 @@
+# Speed Bump
+
+**Zone:** General — Primary Column, Outro only. Not valid in Sideburn.
+
+## Description
+
+A full-width interstitial block used to interrupt content flow and redirect user attention before they continue scrolling. Typically presents a single focused question or confirmation step — "Before you go, are you sure you're covered?" — with one or two action paths.
+
+Use sparingly: no more than one Speed Bump per page, and only when the user decision is significant.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `heading` | `string` | Yes | — | Primary question or statement |
+| `subtext` | `string` | No | — | Supporting copy |
+| `primaryCtaLabel` | `string` | Yes | — | Primary action label |
+| `primaryCtaHref` | `string` | Yes | — | Primary action destination |
+| `secondaryCtaLabel` | `string` | No | — | Secondary/dismiss action label |
+| `secondaryCtaHref` | `string` | No | — | Secondary action destination (if omitted, acts as dismiss) |
+| `background` | `'brand' \| 'dark' \| 'light'` | No | `'brand'` | Block background treatment |
+| `className` | `string` | No | — | Additional CSS class |
+
+## Usage
+
+```tsx
+import { SpeedBump } from 'lion-make'
+
+<SpeedBump
+  heading="Not sure which plan is right for you?"
+  subtext="Talk to an agent — no sales pressure, just answers."
+  primaryCtaLabel="Chat with an agent"
+  primaryCtaHref="/contact/chat"
+  secondaryCtaLabel="Continue browsing"
+  background="brand"
+/>
+```
+
+## Design Tokens
+
+- Background `brand`: `var(--color-brand)`, all text `var(--color-white)`
+- Background `dark`: `var(--color-gray-darkest)`, all text `var(--color-white)`
+- Background `light`: `var(--color-gray-lightest)`, text `var(--color-text)`
+- Heading: `var(--h2-font-size)`, `var(--font-weight-700)`
+- Padding: `var(--padding-large-v)` vertical, `var(--edge-padding)` horizontal

package/guidelines/content-types/general/table-block.md

@@ -0,0 +1,55 @@
+# Table Block
+
+**Zone:** General — Primary Column, Outro only. Not valid in Sideburn (column too narrow).
+
+## Description
+
+A structured data table for comparing products, coverage levels, or feature matrices. Supports column highlighting, sticky header, and optional footnote row. Renders as a semantic `<table>` with accessible markup.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `headers` | `string[]` | Yes | — | Column header labels |
+| `rows` | `TableRow[]` | Yes | — | Data rows |
+| `caption` | `string` | No | — | Accessible `<caption>` (also used as visible heading if `showCaption` is true) |
+| `showCaption` | `boolean` | No | `false` | Render caption visibly above the table |
+| `highlightColumn` | `number` | No | — | Zero-based index of a column to visually highlight |
+| `stickyHeader` | `boolean` | No | `false` | Fix the header row on scroll |
+| `footnote` | `string` | No | — | Legal or explanatory note below the table |
+| `className` | `string` | No | — | Additional CSS class |
+
+### TableRow
+
+| Prop | Type | Description |
+|---|---|---|
+| `label` | `string` | Row header (first column) |
+| `cells` | `(string \| React.ReactNode)[]` | Values for remaining columns |
+
+## Usage
+
+```tsx
+import { TableBlock } from 'lion-make'
+
+<TableBlock
+  caption="Term life coverage comparison"
+  showCaption
+  headers={['Feature', '10-Year Term', '20-Year Term', '30-Year Term']}
+  highlightColumn={2}
+  rows={[
+    { label: 'Starting premium', cells: ['$12/mo', '$18/mo', '$26/mo'] },
+    { label: 'Coverage amount', cells: ['$250k–$1M', '$250k–$1M', '$250k–$1M'] },
+    { label: 'Premium changes', cells: ['Never', 'Never', 'Never'] },
+    { label: 'Medical exam required', cells: ['No', 'No', 'Varies'] },
+  ]}
+  footnote="Premiums shown are illustrative. Actual rates depend on age, health, and coverage selected."
+/>
+```
+
+## Design Tokens
+
+- Header row: `var(--color-brand)` background, `var(--color-white)` text, `var(--font-weight-600)`
+- Highlighted column header: `var(--color-teal)` background
+- Row border: `var(--border-width-thin)` solid `var(--color-line)`
+- Alternating rows: `var(--color-gray-lightest)` on odd rows
+- Footnote: `var(--h6-font-size)`, `var(--color-gray)`

package/guidelines/content-types/general/wahfu.md

@@ -0,0 +1,66 @@
+# WAHFU (We Are Here For You)
+
+**Zone:** General — Primary Column, Outro only. Not valid in Sideburn.
+
+## Description
+
+An empathy and support block for sensitive pages (claims, bereavement, illness). Acknowledges the user's situation and surfaces human support options (phone, chat, agent finder). The tone is warm and non-transactional.
+
+"WAHFU" is the internal shorthand — do not expose this acronym in UI copy.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `heading` | `string` | No | `'We're here for you'` | Block headline |
+| `body` | `string` | No | — | Empathy statement (1–2 sentences) |
+| `channels` | `WAHFUChannel[]` | Yes | — | List of support contact options |
+| `background` | `'white' \| 'teal' \| 'brand'` | No | `'teal'` | Block background |
+| `className` | `string` | No | — | Additional CSS class |
+
+### WAHFUChannel
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `type` | `'phone' \| 'chat' \| 'agent' \| 'email'` | Yes | Channel category (controls icon) |
+| `label` | `string` | Yes | Display label |
+| `href` | `string` | Yes | Link destination |
+| `detail` | `string` | No | Hours of availability or context (e.g., "Mon–Fri 8am–8pm CT") |
+
+## Usage
+
+```tsx
+import { WAHFU } from 'lion-make'
+
+<WAHFU
+  heading="We're here when you need us most"
+  body="Filing a claim during a difficult time shouldn't add stress. Our team is ready to help."
+  background="teal"
+  channels={[
+    {
+      type: 'phone',
+      label: 'Call us',
+      href: 'tel:18006952654',
+      detail: 'Mon–Fri 7am–7pm CT',
+    },
+    {
+      type: 'chat',
+      label: 'Chat with us',
+      href: '/chat',
+    },
+    {
+      type: 'agent',
+      label: 'Find a local agent',
+      href: '/agent-finder',
+    },
+  ]}
+/>
+```
+
+## Design Tokens
+
+- Background `teal`: `var(--color-teal)`, text `var(--color-white)`
+- Background `brand`: `var(--color-brand)`, text `var(--color-white)`
+- Heading: `var(--h2-font-size)`, `var(--font-weight-700)`
+- Channel label: `var(--h5-font-size)`, `var(--font-weight-600)`
+- Detail: `var(--h6-font-size)`, `var(--font-weight-400)`

package/guidelines/content-types/header/header-cta.md

@@ -0,0 +1,41 @@
+# Header — Call to Action
+
+**Zone:** Header only.
+
+## Description
+
+A CTA element placed within the header bar — typically "Get a Quote", "Log In", or "Chat with us". Distinct from the general zone `CTA` and `SimpleCTABlock` components, which live in the page body.
+
+The header CTA renders as a styled anchor. Use `variant="button"` for primary conversion actions and `variant="link"` for secondary utility links (e.g., log in).
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `label` | `string` | Yes | — | Button or link text |
+| `href` | `string` | Yes | — | Destination URL |
+| `variant` | `'button' \| 'link' \| 'phone'` | No | `'button'` | Visual treatment |
+| `className` | `string` | No | — | Additional CSS class |
+
+## Usage
+
+```tsx
+import { Section, HeaderCTA } from 'lion-make'
+
+<Section zone="header">
+  <HeaderCTA label="Get a quote" href="/quote" variant="button" />
+  <HeaderCTA label="Log in" href="/login" variant="link" />
+</Section>
+```
+
+## Placement Rules
+
+- Header zone only. Never place in Hero, General, or Footer zones.
+- Typically placed inside a `GlobalHeaderBar` alongside `TopLevelNavigation`.
+- Limit to 1–2 CTAs per header to avoid visual clutter.
+
+## Design Tokens
+
+- Button variant: `var(--color-brand)` background, `var(--color-white)` text
+- Link variant: `var(--color-white)` text, underline on hover
+- Font: `var(--h5-font-size)`, `var(--font-weight-600)`

package/guidelines/content-types/header/header-logo.md

@@ -0,0 +1,45 @@
+# Header — Logo
+
+**Zone:** Header only.
+
+## Description
+
+The brand or product logo displayed in the header bar. Renders as a linked image that navigates to the homepage (or a specified destination). Every page must have exactly one `HeaderLogo`.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `src` | `string` | Yes | — | Image URL |
+| `alt` | `string` | Yes | — | Alt text (use the brand name, e.g., "Mutual of Omaha") |
+| `href` | `string` | No | `'/'` | Link destination |
+| `width` | `number` | No | — | Explicit image width (px) |
+| `height` | `number` | No | — | Explicit image height (px) |
+| `className` | `string` | No | — | Additional CSS class |
+
+## Usage
+
+```tsx
+import { Section, HeaderLogo } from 'lion-make'
+
+<Section zone="header">
+  <HeaderLogo
+    src="/img/logo-mutual.svg"
+    alt="Mutual of Omaha"
+    href="/"
+    width={180}
+    height={40}
+  />
+</Section>
+```
+
+## Placement Rules
+
+- Header zone only.
+- One per page — do not render multiple `HeaderLogo` instances.
+- Typically the leftmost element inside `CorporateUniversalHeader` or `GlobalHeaderBar`.
+
+## Design Tokens
+
+- No background — logo file must include sufficient padding or transparent background.
+- Wrapper link outline: `var(--color-brand)` on focus (keyboard navigation).

package/guidelines/content-types/header/header-product.md

@@ -0,0 +1,45 @@
+# Header — Product
+
+**Zone:** Header only.
+
+## Description
+
+Displays the name (and optionally the logo and tagline) of the specific product line being featured on the page. Used on product DLPs (detail landing pages) where the header needs to identify which product the user is exploring.
+
+Distinct from `HeaderLogo` (which is always the master brand) — `HeaderProduct` is the product-level identity layer within the same header.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | `string` | Yes | — | Product name (e.g., "Term Life Insurance") |
+| `logoSrc` | `string` | No | — | Product-specific logo or lockup |
+| `logoAlt` | `string` | No | `''` | Logo alt text |
+| `href` | `string` | No | — | Link destination (e.g., product overview page) |
+| `tagline` | `string` | No | — | Short descriptor below the product name |
+| `className` | `string` | No | — | Additional CSS class |
+
+## Usage
+
+```tsx
+import { Section, HeaderProduct } from 'lion-make'
+
+<Section zone="header">
+  <HeaderProduct
+    name="Term Life Insurance"
+    tagline="Affordable coverage, guaranteed premiums"
+    href="/term-life"
+  />
+</Section>
+```
+
+## Placement Rules
+
+- Header zone only.
+- Use on product DLPs. Not required on general marketing or homepage.
+- Appears inside `GlobalHeaderBar`, typically between `HeaderLogo` and `TopLevelNavigation`.
+
+## Design Tokens
+
+- Name: `var(--h4-font-size)`, `var(--font-weight-700)`, `var(--color-white)`
+- Tagline: `var(--h6-font-size)`, `var(--font-weight-400)`, `var(--color-white-opaque)`

package/guidelines/content-types/header/header-section-navigation.md

@@ -0,0 +1,55 @@
+# Header — Section Navigation
+
+**Zone:** Header only.
+
+## Description
+
+A secondary navigation bar that lists the sub-sections of the current page or product area. Renders as a horizontal link list with an active state indicator for the current page. Used on section hubs and multi-page product areas to give users a persistent orientation layer.
+
+Distinct from `TopLevelNavigation` (global, across all products) — Section Navigation is scoped to the current section or product.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `items` | `SectionNavItem[]` | Yes | — | Navigation links |
+| `ariaLabel` | `string` | No | `'Section navigation'` | Accessible label for the `<nav>` element |
+| `className` | `string` | No | — | Additional CSS class |
+
+### SectionNavItem
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | Yes | Link text |
+| `href` | `string` | Yes | Destination URL |
+| `isActive` | `boolean` | No | Marks the current page link |
+
+## Usage
+
+```tsx
+import { Section, HeaderSectionNavigation } from 'lion-make'
+
+<Section zone="header">
+  <HeaderSectionNavigation
+    ariaLabel="Life insurance navigation"
+    items={[
+      { label: 'Term Life', href: '/life/term', isActive: true },
+      { label: 'Whole Life', href: '/life/whole' },
+      { label: 'Universal Life', href: '/life/universal' },
+      { label: 'Compare plans', href: '/life/compare' },
+    ]}
+  />
+</Section>
+```
+
+## Placement Rules
+
+- Header zone only. Renders below `GlobalHeaderBar` when used.
+- Optional — only include when the page belongs to a multi-page section.
+- Active link should match the current page URL exactly.
+
+## Design Tokens
+
+- Background: `var(--color-gray-lightest)` or transparent over header background
+- Link: `var(--h5-font-size)`, `var(--font-weight-400)`, `var(--color-text)`
+- Active link: `var(--font-weight-600)`, bottom border `var(--border-width-thick)` solid `var(--color-brand)`

package/guidelines/content-types/header/header-section-title.md

@@ -0,0 +1,43 @@
+# Header — Section Title
+
+**Zone:** Header only.
+
+## Description
+
+Displays the title of the current section or page within the header area. Used on section index pages or campaign pages where the header itself needs to carry a clear identity heading (separate from the Hero).
+
+Not a substitute for a `Hero` — `HeaderSectionTitle` is a compact, inline header element; the Hero is the full-width content zone below the header.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `title` | `string` | Yes | — | Section or page title |
+| `subtitle` | `string` | No | — | Short supporting line |
+| `as` | `'h1' \| 'h2' \| 'p'` | No | `'h1'` | Semantic heading level |
+| `className` | `string` | No | — | Additional CSS class |
+
+## Usage
+
+```tsx
+import { Section, HeaderSectionTitle } from 'lion-make'
+
+<Section zone="header">
+  <HeaderSectionTitle
+    title="Life Insurance"
+    subtitle="Coverage that protects what matters most"
+    as="h1"
+  />
+</Section>
+```
+
+## Placement Rules
+
+- Header zone only.
+- Use `as="h1"` when no other `<h1>` exists on the page (no Hero with an `<h1>`).
+- If a Hero is present and carries the `<h1>`, use `as="h2"` or `as="p"` here.
+
+## Design Tokens
+
+- Title: `var(--h3-font-size)`, `var(--font-weight-700)`, `var(--color-white)`
+- Subtitle: `var(--h5-font-size)`, `var(--font-weight-400)`, `var(--color-white-opaque)`