lion-make 0.1.0 → 0.3.0

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)

package/guidelines/content-types/overview.md

@@ -8,52 +8,109 @@ Content types are predefined design patterns. Each content type belongs to exact
 2. **What is the purpose of this content?** → determines the specific type within the category.
 
 ```
-Is this for the top of every page (logo, nav)?
-  → Header zone → [header content types](./header/overview.md)
+Is this for the top of every page (logo, nav, CTAs)?
+  → Header zone → [header/overview.md](./header/overview.md)
 
-Is this the primary visual/headline area?
-  → Hero zone → [hero content types](./hero/overview.md)
+Is this the primary visual/headline area of the page?
+  → Hero zone → [hero/overview.md](./hero/overview.md)
 
-Is this informational, promotional, or a form in the body of the page?
-  → General zone → [general content types](./general/overview.md)
+Is this informational, promotional, interactive, or a form in the body of the page?
+  → General zone → [general/overview.md](./general/overview.md)
 
-Is this legal, compliance, or disclosure content?
-  → Footer zone → [footer content types](./footer/overview.md)
+Is this a quick-links bar above the footer?
+  → Anklet zone → Anklet component
+
+Is this legal, compliance, nav, or disclosure content in the bottom of the page?
+  → Footer zone → [footer/overview.md](./footer/overview.md)
 ```
 
+---
+
 ## Content Type Catalog by Zone
 
-### Header Zone (header section only)
+### Header Zone
 
-| Content Type | Component | Description |
-|---|---|---|
-| Corporate Universal Header | `CorporateUniversalHeader` | Blue bar with state selector and logo |
-| Global Header Bar | `GlobalHeaderBar` | White bar with logo, underwriter info, CTAs |
+7 content types — placed inside structural bars (`CorporateUniversalHeader`, `GlobalHeaderBar`).
+
+| Content Type | Component | Typical bar | Required |
+|---|---|---|---|
+| Call to Action | `HeaderCTA` | GlobalHeaderBar | No |
+| Logo | `HeaderLogo` | CorporateUniversalHeader or GlobalHeaderBar | Yes — one per page |
+| Product | `HeaderProduct` | GlobalHeaderBar | No — product DLPs only |
+| Section Navigation | `HeaderSectionNavigation` | Below GlobalHeaderBar | No — section hubs only |
+| Section Title | `HeaderSectionTitle` | GlobalHeaderBar | No |
+| Top Level Navigation | `TopLevelNavigation` | GlobalHeaderBar | Yes — one per page |
+| Underwriter | `HeaderUnderwriter` | CorporateUniversalHeader | Varies — required by compliance on product pages |
+
+→ Full detail: [header/overview.md](./header/overview.md)
 
-### Hero Zone (hero section only)
+---
 
-| Content Type | Component | Variants |
+### Hero Zone
+
+4 content types — one per page. Choose based on page goal.
+
+| Content Type | Component | When to use |
 |---|---|---|
-| Hero | `Hero` | `full-bleed`, `split`, `minimal` |
+| CTA Hero Block | `CTAHeroBlock` | Conversion goal (product DLPs, campaigns) |
+| Hero Block | `HeroBlock` | Informational (section hubs, About, resources) |
+| Multi Hero | `MultiHero` | Multiple products/messages (home, category hubs) |
+| Not Available Hero Block | `NotAvailableHeroBlock` | Product unavailable in user's state |
+
+→ Full detail + decision tree: [hero/overview.md](./hero/overview.md)
+
+---
 
 ### General Zone (Primary Column, Sideburn, Outro)
 
-| Content Type | Component | Allowed zones |
-|---|---|---|
-| CTA | `CTA` | Primary Column, Sideburn, Outro |
-| Call-Out | `CallOut` | Primary Column, Sideburn, Outro |
-| RTBs | `RTBs` | Primary Column, Sideburn, Outro |
-| Confidence Tags | `ConfidenceTags` | Primary Column, Sideburn, Outro |
-| Lead Form | `LeadForm` | Primary Column, Outro only (not Sideburn) |
-| Rich Text | `RichText` | Primary Column, Sideburn, Outro |
+37 content types. Zone availability varies — not all types are valid in Sideburn or Outro. See [general/overview.md](./general/overview.md) for the full zone availability matrix.
+
+| Group | Content Types |
+|---|---|
+| **Forms** | `LeadForm`, `MultiStepLeadForm`, `EmailCalloutBlock`, `OptIn` |
+| **CTAs** | `CTA`, `SimpleCTABlock`, `CallOut` |
+| **Value props (RTBs)** | `RTBs`, `RTBDescriptive`, `RTBHighlight`, `RTBDynamic` |
+| **Trust & social proof** | `ConfidenceTags`, `MultiTestimonial`, `PullQuote`, `WAHFU` |
+| **Media** | `ContentImageBlock`, `FullSizeImageWithHighlightBox`, `EmbeddedVideoBlock` |
+| **Products & content** | `ProductBlock`, `CrossSellCardBlock`, `ResourceSpotlight`, `BasicContentBlock` |
+| **Reference & structure** | `AccordionBlock`, `SideMenuExplorer`, `TableBlock`, `DecorativeListBlock` |
+| **Urgency** | `LastChanceBlock`, `SpeedBump` |
+| **Prose & text** | `BodyTextCopyBlock`, `RichText`, `PullQuote` |
+| **Layout & utility** | `SpacingBlock`, `HorizontalRule`, `BackgroundColorBlock`, `InlineMessage` |
+| **Platform-specific** | `AllBlogsPostBlock` (blog), `RecentBlogPostsBlock` (blog), `HotJobsBlock` (careers) |
 
-### Footer Zone (footer section only)
+→ Full detail + zone matrix: [general/overview.md](./general/overview.md)
 
-| Content Type | Component | Subsection |
+---
+
+### Anklet Zone
+
+Fixed structure — one component, no variants.
+
+| Content Type | Component | Description |
 |---|---|---|
-| Disclaimer | `Disclaimer` | Disclaimer subsection |
-| Disclosure | `Disclosure` | Disclosure subsection |
-| Compliance Block | `ComplianceBlock` | Compliance subsection |
+| Anklet | `Anklet` | Horizontal quick-links bar above the footer |
+
+The `Anklet` component is placed outside any `<Section>` wrapper, between the General Content zone and the Footer zone.
+
+---
+
+### Footer Zone
+
+7 content types with a mandatory render order.
+
+| Order | Content Type | Component | Description |
+|---|---|---|---|
+| 1 | Links & Social | `LinksAndSocial` | Footer nav columns + social icons |
+| 2 | Disclaimers | `Disclaimer` | Static legal copy (always visible) |
+| 3 | Disclosures | `Disclosure` | Toggle starts collapsed |
+| 3 | Disclosure Toggle Open | `DisclosureToggleOpen` | Toggle starts expanded |
+| 4 | Compliance | `ComplianceBlock` | Item Number / Material ID |
+| 5 | Legal Links | `LegalLinks` | Privacy, Terms, Copyright — always last |
+
+→ Full detail + placement example: [footer/overview.md](./footer/overview.md)
+
+---
 
 ## Zone Exclusivity Rule