lion-make 0.2.0 → 0.3.0

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

@@ -0,0 +1,46 @@
+# Header — Underwriter
+
+**Zone:** Header only.
+
+## Description
+
+Displays the underwriting company attribution — e.g., "Underwritten by United of Omaha Life Insurance Company." Required on product pages where insurance regulatory compliance mandates that the underwriter is disclosed at the page level.
+
+Renders as a small text strip (optionally linked and optionally with a logo). Not the same as the `ComplianceBlock` in the footer — the footer compliance block handles Item Numbers and Material IDs; this is the brand-level underwriter identity.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `text` | `string` | Yes | — | Underwriter attribution text |
+| `logoSrc` | `string` | No | — | Underwriter logo URL |
+| `logoAlt` | `string` | No | `''` | Logo alt text |
+| `href` | `string` | No | — | Optional link (e.g., to underwriter's About page) |
+| `className` | `string` | No | — | Additional CSS class |
+
+## Usage
+
+```tsx
+import { Section, HeaderUnderwriter } from 'lion-make'
+
+<Section zone="header">
+  <HeaderUnderwriter
+    text="Underwritten by United of Omaha Life Insurance Company"
+    logoSrc="/img/logo-united-of-omaha.svg"
+    logoAlt="United of Omaha Life Insurance Company"
+  />
+</Section>
+```
+
+## Placement Rules
+
+- Header zone only.
+- Typically placed inside `CorporateUniversalHeader` (the top thin bar).
+- Required on all product DLPs where a specific underwriting entity applies.
+- Consult legal/compliance for exact required phrasing per product line.
+
+## Design Tokens
+
+- Text: `var(--h6-font-size)`, `var(--font-weight-400)`, `var(--color-white)`
+- Logo height: 24px max within the bar
+- Background inherits from `CorporateUniversalHeader`: `var(--color-blue-dark)`

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

@@ -2,33 +2,79 @@
 
 **Zone rule:** These content types can only be placed in the Header zone. Never use them in Hero, General, or Footer zones.
 
-The Header zone is subdivided into subsections. Each subsection accepts a specific content type.
+The Header zone is composed of two structural bars (`CorporateUniversalHeader` and `GlobalHeaderBar`) that act as containers. The 7 header content types are the individual elements placed inside those bars.
 
-## Header Subsections
+---
 
-| Subsection | Content type | Component |
-|---|---|---|
-| Corporate Universal Header | Corporate Universal Header | `CorporateUniversalHeader` |
-| Global Header Bar | Global Header Bar | `GlobalHeaderBar` |
-| Navigation | Top Nav, Product Nav, Underwriter Nav | *(coming)* |
+## Content Types
+
+| Content type | Component | Required | Typical bar |
+|---|---|---|---|
+| Call to Action | `HeaderCTA` | No | GlobalHeaderBar |
+| Logo | `HeaderLogo` | Yes — one per page | CorporateUniversalHeader or GlobalHeaderBar |
+| Product | `HeaderProduct` | No — product DLPs only | GlobalHeaderBar |
+| Section Navigation | `HeaderSectionNavigation` | No | Below GlobalHeaderBar |
+| Section Title | `HeaderSectionTitle` | No | GlobalHeaderBar |
+| Top Level Navigation | `TopLevelNavigation` | Yes — one per page | GlobalHeaderBar |
+| Underwriter | `HeaderUnderwriter` | Varies — required by compliance on product pages | CorporateUniversalHeader |
+
+---
+
+## Header Structure
+
+```
+Header zone
+├── CorporateUniversalHeader   ← thin top bar
+│   ├── HeaderLogo             (brand logo)
+│   └── HeaderUnderwriter      (underwriter attribution, if required)
+└── GlobalHeaderBar            ← main nav bar
+    ├── HeaderLogo             (or HeaderProduct on product DLPs)
+    ├── TopLevelNavigation     (global nav with optional dropdowns)
+    ├── HeaderSectionTitle     (if applicable)
+    ├── HeaderCTA              (1–2 CTAs, e.g. "Get a quote", "Log in")
+    └── HeaderSectionNavigation (below the bar, on section hubs)
+```
+
+---
 
 ## Placement Example
 
 ```tsx
-import { Section, CorporateUniversalHeader, GlobalHeaderBar } from 'lion-make'
+import {
+  Section,
+  CorporateUniversalHeader,
+  GlobalHeaderBar,
+  HeaderLogo,
+  HeaderUnderwriter,
+  TopLevelNavigation,
+  HeaderCTA,
+} from 'lion-make'
 
 <Section zone="header">
-  <CorporateUniversalHeader logoSrc="/logo.svg" logoAlt="Company" selectedState="NE" />
-  <GlobalHeaderBar
-    logoSrc="/logo-full.svg"
-    logoAlt="Company"
-    underwriterInfo="Underwritten by Mutual of Omaha"
-    ctas={[{ label: 'Get a Quote', href: '/quote', type: 'button' }]}
-  />
+  <CorporateUniversalHeader>
+    <HeaderLogo src="/img/logo.svg" alt="Mutual of Omaha" href="/" />
+    <HeaderUnderwriter text="Underwritten by United of Omaha Life Insurance Company" />
+  </CorporateUniversalHeader>
+  <GlobalHeaderBar>
+    <TopLevelNavigation items={navItems} />
+    <HeaderCTA label="Get a quote" href="/quote" variant="button" />
+    <HeaderCTA label="Log in" href="/login" variant="link" />
+  </GlobalHeaderBar>
 </Section>
 ```
 
+---
+
 ## Files in This Section
 
+- [header-cta.md](./header-cta.md)
+- [header-logo.md](./header-logo.md)
+- [header-product.md](./header-product.md)
+- [header-section-navigation.md](./header-section-navigation.md)
+- [header-section-title.md](./header-section-title.md)
+- [top-level-navigation.md](./top-level-navigation.md)
+- [header-underwriter.md](./header-underwriter.md)
+
+Legacy structural components (bars, not content types):
 - [corporate-universal-header.md](./corporate-universal-header.md)
 - [global-header-bar.md](./global-header-bar.md)

package/guidelines/content-types/header/top-level-navigation.md

@@ -0,0 +1,70 @@
+# Header — Top Level Navigation
+
+**Zone:** Header only.
+
+## Description
+
+The global navigation menu — the primary wayfinding element across all pages. Renders as a horizontal link bar with optional dropdown sub-menus. Every page must include exactly one `TopLevelNavigation`.
+
+Supports one level of dropdown children. Deeper nesting is not supported in Mondrian.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `items` | `TopLevelNavItem[]` | Yes | — | Top-level navigation links |
+| `ariaLabel` | `string` | No | `'Main navigation'` | Accessible label for the `<nav>` element |
+| `className` | `string` | No | — | Additional CSS class |
+
+### TopLevelNavItem
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | Yes | Link text |
+| `href` | `string` | Yes | Destination URL |
+| `isActive` | `boolean` | No | Marks the currently active section |
+| `children` | `TopLevelNavItem[]` | No | Dropdown sub-items (max 8 recommended) |
+
+## Usage
+
+```tsx
+import { Section, TopLevelNavigation } from 'lion-make'
+
+<Section zone="header">
+  <TopLevelNavigation
+    items={[
+      {
+        label: 'Life Insurance',
+        href: '/life',
+        isActive: true,
+        children: [
+          { label: 'Term Life', href: '/life/term' },
+          { label: 'Whole Life', href: '/life/whole' },
+        ],
+      },
+      { label: 'Medicare', href: '/medicare' },
+      { label: 'Supplemental Health', href: '/supplemental' },
+      { label: 'About us', href: '/about' },
+    ]}
+  />
+</Section>
+```
+
+## Placement Rules
+
+- Header zone only. One per page.
+- Sits inside `GlobalHeaderBar`, typically after `HeaderLogo` and before `HeaderCTA`.
+- Dropdown children are shown on hover (desktop) or tap (mobile).
+
+## Accessibility
+
+- `<nav aria-label="Main navigation">` wrapper.
+- Active item gets `aria-current="page"`.
+- Items with children get `aria-haspopup="true"`.
+
+## Design Tokens
+
+- Link: `var(--h5-font-size)`, `var(--font-weight-400)`, `var(--color-white)`
+- Active / hover link: `var(--font-weight-600)`, bottom border `var(--border-width-thick)` solid `var(--color-white)`
+- Dropdown background: `var(--color-white)`
+- Dropdown link: `var(--color-text)`, `var(--font-weight-400)`

package/guidelines/content-types/hero/cta-hero-block.md

@@ -0,0 +1,70 @@
+# CTA Hero Block
+
+**Zone:** Hero only.
+
+## Description
+
+The primary conversion hero. Full-width with a prominent heading, optional subheading and body copy, up to two CTAs, and an optional image or background. This is the default hero for product DLPs and campaign landing pages where driving a conversion action (quote, apply, call) is the primary goal.
+
+Use this when the hero needs to drive a user action. If the hero is purely informational (no CTA), use `HeroBlock` instead.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `heading` | `string` | Yes | — | Page `<h1>` — primary message |
+| `subheading` | `string` | No | — | Secondary message line, lighter weight |
+| `body` | `string` | No | — | Supporting copy (1–2 sentences max) |
+| `ctas` | `CTAHeroBlockCTA[]` | No | `[]` | 1–2 CTAs; first is primary, second is secondary |
+| `imageSrc` | `string` | No | — | Hero image URL |
+| `imageAlt` | `string` | No | `''` | Image alt text |
+| `layout` | `'full-bleed' \| 'split-right' \| 'split-left'` | No | `'split-right'` | Layout treatment |
+| `backgroundSrc` | `string` | No | — | Background image URL (full-bleed only) |
+| `legalText` | `string` | No | — | Small legal/disclaimer line below CTAs |
+| `className` | `string` | No | — | Additional CSS class |
+
+### CTAHeroBlockCTA
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | Yes | Button text |
+| `href` | `string` | Yes | Destination URL |
+| `variant` | `'primary' \| 'secondary'` | No | Button style (default: `'primary'`) |
+
+## Layouts
+
+| Layout | Description |
+|---|---|
+| `split-right` | Content left, image right (8+4 col on desktop) |
+| `split-left` | Image left, content right (4+8 col on desktop) |
+| `full-bleed` | Background image behind content, centered or left-aligned |
+
+## Usage
+
+```tsx
+import { Section, CTAHeroBlock } from 'lion-make'
+
+<Section zone="hero">
+  <CTAHeroBlock
+    heading="Protect your family for less than a coffee a day"
+    subheading="Term life insurance that fits your budget and never raises your rate."
+    ctas={[
+      { label: 'Get a free quote', href: '/quote', variant: 'primary' },
+      { label: 'Learn how it works', href: '/term-life', variant: 'secondary' },
+    ]}
+    imageSrc="/img/hero-family.jpg"
+    imageAlt="Family at home"
+    layout="split-right"
+    legalText="Rates based on a 35-year-old non-smoker in good health."
+  />
+</Section>
+```
+
+## Design Tokens
+
+- Background: `var(--color-brand)` or image
+- Heading: `var(--h1-font-size)`, `var(--font-weight-700)`, `var(--color-white)`
+- Subheading: `var(--h3-font-size)`, `var(--font-weight-300)`, `var(--color-white)`
+- Primary CTA: `var(--color-white)` background, `var(--color-brand)` text
+- Secondary CTA: transparent background, `var(--color-white)` border + text
+- Legal text: `var(--h6-font-size)`, `var(--color-white-opaque)`

package/guidelines/content-types/hero/hero-block.md

@@ -0,0 +1,56 @@
+# Hero Block
+
+**Zone:** Hero only.
+
+## Description
+
+The standard informational hero. Used when the hero zone carries context and orientation rather than a direct conversion action. Supports an eyebrow label, heading, subheading, body copy, and an optional image — but no CTA slots. If a CTA is needed, use `CTAHeroBlock` instead.
+
+Typical use cases: section index pages, About pages, content hub headers, educational/resource pages.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `heading` | `string` | Yes | — | Page `<h1>` |
+| `subheading` | `string` | No | — | Supporting headline, lighter weight |
+| `body` | `string` | No | — | Introductory paragraph |
+| `eyebrow` | `string` | No | — | Small uppercase label above the heading (e.g., product category) |
+| `imageSrc` | `string` | No | — | Hero image URL |
+| `imageAlt` | `string` | No | `''` | Image alt text |
+| `layout` | `'full-bleed' \| 'split-right' \| 'split-left' \| 'minimal'` | No | `'full-bleed'` | Layout treatment |
+| `backgroundSrc` | `string` | No | — | Background image URL (full-bleed only) |
+| `className` | `string` | No | — | Additional CSS class |
+
+## Layouts
+
+| Layout | Description |
+|---|---|
+| `full-bleed` | Background image or color fills the full hero width |
+| `split-right` | Content left, image right |
+| `split-left` | Image left, content right |
+| `minimal` | Text only, no image; centered or left-aligned; typically shorter |
+
+## Usage
+
+```tsx
+import { Section, HeroBlock } from 'lion-make'
+
+<Section zone="hero">
+  <HeroBlock
+    eyebrow="Life Insurance"
+    heading="Coverage built around your life"
+    subheading="Explore options for every stage — from starting a family to planning for retirement."
+    imageSrc="/img/hero-life.jpg"
+    imageAlt="Person reviewing documents"
+    layout="split-right"
+  />
+</Section>
+```
+
+## Design Tokens
+
+- Heading: `var(--h1-font-size)`, `var(--font-weight-700)`, `var(--color-white)` (or `var(--color-text)` on light backgrounds)
+- Eyebrow: `var(--h6-font-size)`, `var(--font-weight-600)`, uppercase, `var(--color-teal)`
+- Subheading: `var(--h3-font-size)`, `var(--font-weight-300)`
+- Body: `var(--body-font-size)`, `var(--font-weight-400)`

package/guidelines/content-types/hero/multi-hero.md

@@ -0,0 +1,78 @@
+# Multi Hero
+
+**Zone:** Hero only.
+
+## Description
+
+A multi-panel hero that rotates or tabs between 2–5 content slides. Each panel is independently authored with its own heading, image, and optional CTA. Use when multiple products or campaigns need to share the hero zone on a hub page (e.g., a home page or insurance category index).
+
+Auto-rotation is optional and disabled by default for accessibility. When enabled, panels must include sufficient contrast and the rotation must be user-pausable.
+
+**Limit to hub/home pages.** On product DLPs, use `CTAHeroBlock` — a single focused message always outperforms a rotating hero for conversion.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `panels` | `MultiHeroPanel[]` | Yes | — | Slide content (min 2, max 5 recommended) |
+| `autoRotate` | `boolean` | No | `false` | Whether panels advance automatically |
+| `rotateIntervalMs` | `number` | No | `5000` | Auto-rotation interval in milliseconds |
+| `defaultActiveIndex` | `number` | No | `0` | Index of the panel shown on load |
+| `showIndicators` | `boolean` | No | `true` | Dot indicators below the hero |
+| `className` | `string` | No | — | Additional CSS class |
+
+### MultiHeroPanel
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `heading` | `string` | Yes | Panel `<h1>` |
+| `subheading` | `string` | No | Supporting headline |
+| `body` | `string` | No | Short paragraph |
+| `imageSrc` | `string` | No | Panel image URL |
+| `imageAlt` | `string` | No | Image alt text |
+| `ctaLabel` | `string` | No | CTA button text |
+| `ctaHref` | `string` | No | CTA destination |
+| `id` | `string` | No | Unique ID for `aria-controls` |
+
+## Usage
+
+```tsx
+import { Section, MultiHero } from 'lion-make'
+
+<Section zone="hero">
+  <MultiHero
+    autoRotate={false}
+    panels={[
+      {
+        heading: 'Life insurance made simple',
+        subheading: 'Affordable coverage, guaranteed rates.',
+        imageSrc: '/img/hero-life.jpg',
+        imageAlt: '',
+        ctaLabel: 'Get a quote',
+        ctaHref: '/life/quote',
+      },
+      {
+        heading: 'Medicare coverage you can count on',
+        subheading: 'Supplement plans to fill the gaps.',
+        imageSrc: '/img/hero-medicare.jpg',
+        imageAlt: '',
+        ctaLabel: 'Explore plans',
+        ctaHref: '/medicare',
+      },
+    ]}
+  />
+</Section>
+```
+
+## Accessibility
+
+- Each panel has `aria-hidden` when not active.
+- Indicators use `role="tab"` + `aria-selected`.
+- If `autoRotate` is `true`, a pause button must be provided (implement in the consuming app).
+
+## Design Tokens
+
+- Active indicator: `var(--color-brand)`
+- Inactive indicator: `var(--color-line)`
+- Panel heading: `var(--h1-font-size)`, `var(--font-weight-700)`, `var(--color-white)`
+- Panel CTA: `var(--color-white)` background, `var(--color-brand)` text

package/guidelines/content-types/hero/not-available-hero-block.md

@@ -0,0 +1,64 @@
+# Not Available Hero Block
+
+**Zone:** Hero only.
+
+## Description
+
+A dedicated hero for pages or products that are not available in the user's state or region. Replaces the standard hero entirely when the product cannot be offered — do not render another hero type alongside this one.
+
+The block communicates clearly that the product is unavailable, names the state if known, offers alternative products or paths, and provides a contact option.
+
+This component should be rendered conditionally based on state-availability data from the product catalog or facet system. Never hardcode unavailability — derive it from the facet targeting layer.
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `stateName` | `string` | No | — | Name of the unavailable state (e.g., `'New York'`). Used in the default heading if `heading` is not provided. |
+| `heading` | `string` | No | `'Not available in [stateName]'` | Override the default heading |
+| `body` | `string` | No | Default message | Override the default body copy |
+| `alternatives` | `NotAvailableAlternative[]` | No | `[]` | Links to related available products |
+| `contactCtaLabel` | `string` | No | — | Contact CTA label (e.g., "Talk to an agent") |
+| `contactCtaHref` | `string` | No | — | Contact CTA destination |
+| `imageSrc` | `string` | No | — | Optional supporting image |
+| `imageAlt` | `string` | No | `''` | Image alt text |
+| `className` | `string` | No | — | Additional CSS class |
+
+### NotAvailableAlternative
+
+| Prop | Type | Description |
+|---|---|---|
+| `label` | `string` | Link text (e.g., "Explore Medicare Supplement plans") |
+| `href` | `string` | Destination URL |
+
+## Usage
+
+```tsx
+import { Section, NotAvailableHeroBlock } from 'lion-make'
+
+// Rendered when facet targeting determines the product is unavailable in the user's state
+<Section zone="hero">
+  <NotAvailableHeroBlock
+    stateName="New York"
+    alternatives={[
+      { label: 'Medicare Supplement plans', href: '/medicare' },
+      { label: 'Supplemental health coverage', href: '/supplemental' },
+    ]}
+    contactCtaLabel="Talk to an agent"
+    contactCtaHref="/contact"
+  />
+</Section>
+```
+
+## Default copy (when props are omitted)
+
+- **Heading:** "Not available in [stateName]" or "Not available in your state"
+- **Body:** "This product is not currently offered in your area. Explore available options below or contact us for help finding coverage."
+
+## Design Tokens
+
+- Background: `var(--color-gray-lightest)`
+- Heading: `var(--h2-font-size)`, `var(--font-weight-700)`, `var(--color-text)`
+- Body: `var(--body-font-size)`, `var(--color-gray-dark)`
+- Alternative links: `var(--color-brand)`, underline
+- Contact CTA: `var(--color-brand)` background, `var(--color-white)` text

package/guidelines/content-types/hero/overview.md

@@ -1,41 +1,76 @@
 # Hero Zone Content Types
 
-**Zone rule:** These content types can only be placed in the Hero zone. Never use them in Header, General, or Footer zones.
+**Zone rule:** These content types can only be placed in the Hero zone. Never use them in Header, General, Anklet, or Footer zones.
 
-The Hero zone is the primary visual area of the page, immediately below the header. It always spans the full width of the page regardless of template.
+The Hero zone sits immediately below the Header and spans full page width regardless of template (Forehead or Sideburn). Every page should have one hero — the type chosen depends on the page's goal.
 
-## Available Content Types
+---
 
-| Content Type | Component | Description |
+## Content Types
+
+| Content type | Component | When to use |
 |---|---|---|
-| Hero | `Hero` | Full-page-width hero with heading, optional image, and CTA |
+| CTA Hero Block | `CTAHeroBlock` | Primary conversion goal — product DLPs, campaign pages |
+| Hero Block | `HeroBlock` | Informational — section hubs, About, resource pages |
+| Multi Hero | `MultiHero` | Multiple products/messages — home page, category hubs |
+| Not Available Hero Block | `NotAvailableHeroBlock` | Product unavailable in user's state (facet-triggered) |
+
+---
+
+## Decision Tree
+
+```
+Does the hero need a CTA?
+  ├── Yes → Does the page feature a single product/campaign?
+  │           ├── Yes → CTAHeroBlock
+  │           └── No (hub page, multiple products) → MultiHero
+  └── No  → Is the product unavailable in the user's state?
+              ├── Yes → NotAvailableHeroBlock
+              └── No  → HeroBlock
+```
+
+---
 
-## Variants
+## Layout Options
 
-| Variant | Description |
+| Layout | Supported by |
 |---|---|
-| `full-bleed` | Background image or gradient fills the entire hero area edge to edge |
-| `split` | Content on the left, image on the right (50/50) |
-| `minimal` | Text-only, no image, centered or left-aligned |
+| `full-bleed` | CTAHeroBlock, HeroBlock |
+| `split-right` | CTAHeroBlock, HeroBlock |
+| `split-left` | CTAHeroBlock, HeroBlock |
+| `minimal` | HeroBlock only |
+| Multi-panel | MultiHero (unique — panels, not a layout prop) |
+
+---
 
 ## Placement Example
 
 ```tsx
-import { Section, Hero } from 'lion-make'
+import { Section, CTAHeroBlock } from 'lion-make'
 
 <Section zone="hero">
-  <Hero
-    variant="full-bleed"
-    heading="Protect what matters most"
-    subheading="Affordable life insurance starting at $0.99."
-    imageSrc="/hero-family.jpg"
+  <CTAHeroBlock
+    heading="Protect your family for less than a coffee a day"
+    subheading="Term life insurance that fits your budget."
+    ctas={[
+      { label: 'Get a free quote', href: '/quote', variant: 'primary' },
+      { label: 'Learn how it works', href: '/term-life', variant: 'secondary' },
+    ]}
+    imageSrc="/img/hero-family.jpg"
     imageAlt="Family at home"
-    ctaLabel="Get a Quote"
-    ctaHref="/quote"
+    layout="split-right"
   />
 </Section>
 ```
 
+---
+
 ## Files in This Section
 
+- [cta-hero-block.md](./cta-hero-block.md)
+- [hero-block.md](./hero-block.md)
+- [multi-hero.md](./multi-hero.md)
+- [not-available-hero-block.md](./not-available-hero-block.md)
+
+Legacy (pre-Mondrian generic stub — kept for backward compatibility):
 - [hero-variants.md](./hero-variants.md)