@affinda/wc 0.1.0 → 0.2.0

package/dist/types/components.d.ts

@@ -5,11 +5,15 @@
  * It contains typing information for all components that exist in this project.
  */
 import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
+import { Gap, HeadingSize, Padding, Theme } from "./types";
+import { HeroTopPad, HeroVariant } from "./components/af-hero/af-hero";
 import { IconName } from "@affinda/icons";
 import { NumberBadgeNumber, NumberBadgeVariant } from "./components/af-number-badge/af-number-badge";
 import { TabShape } from "./components/af-tab/af-tab";
 import { TabBarBreakpoint, TabBarShape } from "./components/af-tab-bar/af-tab-bar";
 import { TagSize, TagVariant } from "./components/af-tag/af-tag";
+export { Gap, HeadingSize, Padding, Theme } from "./types";
+export { HeroTopPad, HeroVariant } from "./components/af-hero/af-hero";
 export { IconName } from "@affinda/icons";
 export { NumberBadgeNumber, NumberBadgeVariant } from "./components/af-number-badge/af-number-badge";
 export { TabShape } from "./components/af-tab/af-tab";
@@ -130,7 +134,7 @@ export namespace Components {
           * Theme - sets background color and provides theme context to children. Defaults to 'mist-green' if not specified.
           * @default 'mist-green'
          */
-        "theme"?: 'white' | 'white-ivory' | 'inkwell' | 'mist-green' | 'soft-clay';
+        "theme"?: Theme;
     }
     /**
      * Center layout component for quickly centering content.
@@ -345,7 +349,7 @@ export namespace Components {
           * Theme variant - sets background color and provides theme context. Only applies to 'standard' layout mode. Defaults to 'mist-green'.
           * @default 'mist-green'
          */
-        "theme"?: 'white' | 'white-ivory' | 'inkwell' | 'mist-green' | 'soft-clay';
+        "theme"?: Theme;
     }
     /**
      * Feature Grid component - CSS Grid container for feature cards.
@@ -544,6 +548,87 @@ export namespace Components {
          */
         "level": 'xl' | '1' | '2' | '3' | '4' | '5';
     }
+    /**
+     * Unified top-of-page hero — replaces the 7+ hand-rolled hero implementations
+     * the Affinda marketing site (and sibling apps) currently ship. Covers five
+     * canonical patterns via the `variant` prop:
+     * - `inkwell-photo` — inkwell background, blob-masked photo on the right.
+     *   Use for: listing / archive pages (blog, case-studies, whitepapers,
+     *   value-creation, about-us) and industry landing pages that carry a
+     *   photograph instead of an illustration.
+     * - `inkwell-illustration` — inkwell background, illustration on the right.
+     *   Use for: industry landing pages, /industries, /integrations, /platform
+     *   with bespoke art.
+     * - `inkwell-centered` — inkwell background, centred typography lockup.
+     *   Slot `<af-paperclip-decoration />` into the `paperclip` slot for the
+     *   watermark treatment. Use for: `/`, `/au`, `/platform`.
+     * - `soft-clay-illustration` — soft-clay background, illustration on the
+     *   right. Use for: /news, /industries overview, /security, /compare.
+     * - `mist-green-illustration` — same layout as soft-clay-illustration but on
+     *   the mist-green theme. Reserved for future pages.
+     * ## Slots
+     * - default — heading content (use when richer markup than the `heading`
+     *   prop can express is needed; e.g. coloured spans or line breaks).
+     * - `description` — supporting copy under the heading.
+     * - `badge` — optional pre-heading label (pill, version tag).
+     * - `buttons` — hero CTAs (usually an `<af-button-group>`).
+     * - `image` — the photograph for the `inkwell-photo` variant. Wrapped in
+     *   the blob mask automatically.
+     * - `illustration` — the illustration SVG for `-illustration` variants.
+     * - `paperclip` — watermark for `inkwell-centered`. Consumers typically
+     *   slot `<af-paperclip-decoration />` here.
+     * - `logos-below` — overlap row at the bottom gutter (logo carousel etc.).
+     *   Painted with the theme's background so it cleanly overlaps the image's
+     *   lower edge on the photo variant.
+     * ## Float-navbar handling
+     * When `floatNavbar` is true (the default for the inkwell variants) the
+     * component sets `data-af-hero-float-navbar="true"` on `<body>` via a
+     * lifecycle hook, and a companion rule in `@affinda/css/base.css` applies
+     * the `body > header { position: absolute }` / `main { padding-top: 0 }`
+     * / navbar-spacer-transparent treatment. Consumers already import
+     * `@affinda/css` so no extra import is required. The rule deactivates
+     * when the hero is removed from the DOM.
+     * ## Image lift
+     * The `inkwell-photo` variant renders the photo column with
+     * `margin-top: var(--af-hero-image-lift, -260px)`. Override per-page by
+     * setting `--af-hero-image-lift` on the `<af-hero>` element.
+     */
+    interface AfHero {
+        /**
+          * Description text (use the `description` slot for richer markup).
+          * @default ''
+         */
+        "description": string;
+        /**
+          * Float the site header over the hero and paint the navbar-spacer transparent so the hero background flows to the top of the viewport. Defaults to true for the three inkwell variants, false for the soft-clay / mist-green illustration variants (whose consumers don't always want a full-bleed crown).
+         */
+        "floatNavbar"?: boolean;
+        /**
+          * Heading text (use the default slot for richer markup).
+          * @default ''
+         */
+        "heading": string;
+        /**
+          * Whether to apply the blob mask to the slotted `image`. Defaults to `true` for `inkwell-photo`. Set `false` if you want to slot in a pre-masked raster or a custom wrapper.
+          * @default true
+         */
+        "maskImage": boolean;
+        /**
+          * Typography lockup max-width (px). Defaults to 620, matching the live site.
+          * @default 620
+         */
+        "maxWidth": number;
+        /**
+          * Top padding preset. `default` = 124px (matches IndustryHero / IllustrationHero). `loose` = 164px (matches ListingHero — gives the image a touch more breathing room above the lockup on archive pages).
+          * @default 'default'
+         */
+        "topPad": HeroTopPad;
+        /**
+          * Layout / theme preset. See variant docs in the component header.
+          * @default 'inkwell-photo'
+         */
+        "variant": HeroVariant;
+    }
     /**
      * Icon component that displays SVG icons from the Affinda icon library.
      * Icons inherit color from their parent via currentColor.
@@ -676,7 +761,7 @@ export namespace Components {
           * Theme variant - sets background color and provides theme context. Defaults to 'mist-green'.
           * @default 'mist-green'
          */
-        "theme"?: 'white' | 'white-ivory' | 'inkwell' | 'mist-green' | 'soft-clay';
+        "theme"?: Theme;
     }
     /**
      * A styled image container with rounded corners and a subtle inset border.
@@ -769,7 +854,7 @@ export namespace Components {
           * Theme - sets the banner background color and typography colors
           * @default 'mist-green'
          */
-        "theme": BannerTheme;
+        "theme": Theme;
     }
     /**
      * Inline layout component for horizontal inline-flex layouts with gap and optional wrapping.
@@ -1102,7 +1187,7 @@ export namespace Components {
         /**
           * Theme for the spacer background - should match the section below the navbar
          */
-        "theme"?: 'white' | 'inkwell' | 'mist-green' | 'soft-clay';
+        "theme"?: Theme;
     }
     /**
      * NumberBadge displays numbers 1-10 in either a filled circle or text-only style.
@@ -1129,6 +1214,52 @@ export namespace Components {
          */
         "variant": NumberBadgeVariant;
     }
+    /**
+     * Numbered stepper — filled soft-clay circle badges (1/2/3) paired with a
+     * heading + body description per step. Sibling to `af-stepper` (which uses
+     * outlined badges on a single spine connector); the numbered variant uses
+     * filled badges with per-step connector segments, matching the Webflow
+     * "How it works" marketing pattern.
+     * Renders children `af-numbered-stepper-item` elements horizontally on
+     * desktop (auto-stacks on mobile) or vertically when `orientation="vertical"`.
+     * The parent auto-assigns badge numbers based on DOM order, so consumers
+     * don't hand-number the steps.
+     * Headings use the shared `heading-size="card"` scale from
+     * `af-typography-lockup` (22/20px) — no bespoke font-size tokens.
+     * @example ```html
+     * <af-numbered-stepper>
+     *   <af-numbered-stepper-item>
+     *     <h3 slot="heading">Connect your ATS</h3>
+     *     <p slot="body">OAuth-based hook into the tools you already use.</p>
+     *   </af-numbered-stepper-item>
+     *   <af-numbered-stepper-item>...</af-numbered-stepper-item>
+     *   <af-numbered-stepper-item>...</af-numbered-stepper-item>
+     * </af-numbered-stepper>
+     * ```
+     */
+    interface AfNumberedStepper {
+        /**
+          * Layout orientation. Horizontal auto-stacks to vertical on mobile.
+          * @default 'horizontal'
+         */
+        "orientation": 'horizontal' | 'vertical';
+    }
+    /**
+     * A single step within an `af-numbered-stepper`. Renders a filled soft-clay
+     * circle badge (via `af-number-badge`) alongside a heading + body lockup.
+     * The parent `af-numbered-stepper` auto-assigns the `index` prop based on
+     * DOM order. Pass `index` explicitly to override.
+     * Heading scale is the shared `card` variant from `af-typography-lockup`
+     * (22/20px) — the same ladder step used by diff-card, related-card, and
+     * other card-title uses across the design system.
+     */
+    interface AfNumberedStepperItem {
+        /**
+          * Step number shown in the badge. Auto-assigned by the parent stepper if not explicitly set.
+          * @default 1
+         */
+        "index": number;
+    }
     /**
      * Decorative paperclip vector graphic. Renders the left-half paperclip
      * silhouette (viewBox `0 0 655 754`) that the marketing site bleeds off
@@ -1228,12 +1359,12 @@ export namespace Components {
           * Padding variant
           * @default 'default'
          */
-        "padding": 'none' | 'tight' | 'default' | 'loose';
+        "padding": Padding;
         /**
           * Theme - sets background color and provides theme context to children
           * @default 'white'
          */
-        "theme": 'white' | 'inkwell' | 'mist-green' | 'soft-clay' | 'white-ivory';
+        "theme": Theme;
     }
     /**
      * Show component for responsive visibility control.
@@ -1316,7 +1447,7 @@ export namespace Components {
           * Padding variant
           * @default 'default'
          */
-        "padding": 'none' | 'tight' | 'default' | 'loose';
+        "padding": Padding;
         /**
           * Theme for the top half of the section
           * @default 'mist-green'
@@ -1354,6 +1485,35 @@ export namespace Components {
          */
         "wrap": boolean;
     }
+    /**
+     * Individual stat — a large value (e.g. "1B+") paired with a descriptive label.
+     * Intended as a slotted child of `af-stats-row`, but renders standalone too.
+     * Colour is inherited from the ancestor theme context (`af-section` /
+     * `af-card` / `af-theme-override`) via the `--af-typography-*` tokens that
+     * `af-heading` and `af-text` already consume — no theme prop needed here.
+     */
+    interface AfStat {
+        /**
+          * Description / caption rendered beneath the value.
+         */
+        "label": string;
+        /**
+          * The statistic headline value (e.g. "1B+", "95%", "10+").
+         */
+        "value": string;
+    }
+    /**
+     * Layout container for a horizontal row of `af-stat` children.
+     * Flex row that wraps to a grid on narrow viewports. Uses `scoped: true`
+     * so slotted `<af-stat>` children stay in the light DOM and inherit the
+     * ancestor theme (`af-section`) via the cascaded `.theme-*` class.
+     * Intentionally has **no `theme` prop** — a stats row is always flush
+     * against its section background, so a local theme would fight the
+     * ancestor. If you need a different background for the row, wrap it in
+     * its own `af-section` or `af-theme-override`.
+     */
+    interface AfStatsRow {
+    }
     /**
      * Stepper composite for "Sign up / Upload / See results"-style marketing
      * flows. Renders children `af-stepper-step` elements in a horizontal row
@@ -1723,7 +1883,7 @@ export namespace Components {
           * The theme to apply to child components. Overrides any inherited theme from parent containers.
           * @default 'white'
          */
-        "theme": 'white' | 'inkwell' | 'mist-green' | 'soft-clay' | 'white-ivory';
+        "theme": Theme;
     }
     /**
      * Marketing-style composition of heading + description + buttons with
@@ -1785,7 +1945,7 @@ export namespace Components {
           * The heading size (1-5, or "card"; 1 is largest). Controls visual scale only — pair with a matching <h1>-<h5> slotted element for correct document outline (see component docblock). The `card` variant sits between 4 and 5 at 22/20px and is meant for card titles.
           * @default 2
          */
-        "headingSize": 1 | 2 | 3 | 4 | 5 | 'card';
+        "headingSize": HeadingSize;
         /**
           * Maximum width for the copy section (in pixels)
          */
@@ -2200,6 +2360,57 @@ declare global {
         prototype: HTMLAfHeadingElement;
         new (): HTMLAfHeadingElement;
     };
+    /**
+     * Unified top-of-page hero — replaces the 7+ hand-rolled hero implementations
+     * the Affinda marketing site (and sibling apps) currently ship. Covers five
+     * canonical patterns via the `variant` prop:
+     * - `inkwell-photo` — inkwell background, blob-masked photo on the right.
+     *   Use for: listing / archive pages (blog, case-studies, whitepapers,
+     *   value-creation, about-us) and industry landing pages that carry a
+     *   photograph instead of an illustration.
+     * - `inkwell-illustration` — inkwell background, illustration on the right.
+     *   Use for: industry landing pages, /industries, /integrations, /platform
+     *   with bespoke art.
+     * - `inkwell-centered` — inkwell background, centred typography lockup.
+     *   Slot `<af-paperclip-decoration />` into the `paperclip` slot for the
+     *   watermark treatment. Use for: `/`, `/au`, `/platform`.
+     * - `soft-clay-illustration` — soft-clay background, illustration on the
+     *   right. Use for: /news, /industries overview, /security, /compare.
+     * - `mist-green-illustration` — same layout as soft-clay-illustration but on
+     *   the mist-green theme. Reserved for future pages.
+     * ## Slots
+     * - default — heading content (use when richer markup than the `heading`
+     *   prop can express is needed; e.g. coloured spans or line breaks).
+     * - `description` — supporting copy under the heading.
+     * - `badge` — optional pre-heading label (pill, version tag).
+     * - `buttons` — hero CTAs (usually an `<af-button-group>`).
+     * - `image` — the photograph for the `inkwell-photo` variant. Wrapped in
+     *   the blob mask automatically.
+     * - `illustration` — the illustration SVG for `-illustration` variants.
+     * - `paperclip` — watermark for `inkwell-centered`. Consumers typically
+     *   slot `<af-paperclip-decoration />` here.
+     * - `logos-below` — overlap row at the bottom gutter (logo carousel etc.).
+     *   Painted with the theme's background so it cleanly overlaps the image's
+     *   lower edge on the photo variant.
+     * ## Float-navbar handling
+     * When `floatNavbar` is true (the default for the inkwell variants) the
+     * component sets `data-af-hero-float-navbar="true"` on `<body>` via a
+     * lifecycle hook, and a companion rule in `@affinda/css/base.css` applies
+     * the `body > header { position: absolute }` / `main { padding-top: 0 }`
+     * / navbar-spacer-transparent treatment. Consumers already import
+     * `@affinda/css` so no extra import is required. The rule deactivates
+     * when the hero is removed from the DOM.
+     * ## Image lift
+     * The `inkwell-photo` variant renders the photo column with
+     * `margin-top: var(--af-hero-image-lift, -260px)`. Override per-page by
+     * setting `--af-hero-image-lift` on the `<af-hero>` element.
+     */
+    interface HTMLAfHeroElement extends Components.AfHero, HTMLStencilElement {
+    }
+    var HTMLAfHeroElement: {
+        prototype: HTMLAfHeroElement;
+        new (): HTMLAfHeroElement;
+    };
     /**
      * Icon component that displays SVG icons from the Affinda icon library.
      * Icons inherit color from their parent via currentColor.
@@ -2509,6 +2720,50 @@ declare global {
         prototype: HTMLAfNumberBadgeElement;
         new (): HTMLAfNumberBadgeElement;
     };
+    /**
+     * Numbered stepper — filled soft-clay circle badges (1/2/3) paired with a
+     * heading + body description per step. Sibling to `af-stepper` (which uses
+     * outlined badges on a single spine connector); the numbered variant uses
+     * filled badges with per-step connector segments, matching the Webflow
+     * "How it works" marketing pattern.
+     * Renders children `af-numbered-stepper-item` elements horizontally on
+     * desktop (auto-stacks on mobile) or vertically when `orientation="vertical"`.
+     * The parent auto-assigns badge numbers based on DOM order, so consumers
+     * don't hand-number the steps.
+     * Headings use the shared `heading-size="card"` scale from
+     * `af-typography-lockup` (22/20px) — no bespoke font-size tokens.
+     * @example ```html
+     * <af-numbered-stepper>
+     *   <af-numbered-stepper-item>
+     *     <h3 slot="heading">Connect your ATS</h3>
+     *     <p slot="body">OAuth-based hook into the tools you already use.</p>
+     *   </af-numbered-stepper-item>
+     *   <af-numbered-stepper-item>...</af-numbered-stepper-item>
+     *   <af-numbered-stepper-item>...</af-numbered-stepper-item>
+     * </af-numbered-stepper>
+     * ```
+     */
+    interface HTMLAfNumberedStepperElement extends Components.AfNumberedStepper, HTMLStencilElement {
+    }
+    var HTMLAfNumberedStepperElement: {
+        prototype: HTMLAfNumberedStepperElement;
+        new (): HTMLAfNumberedStepperElement;
+    };
+    /**
+     * A single step within an `af-numbered-stepper`. Renders a filled soft-clay
+     * circle badge (via `af-number-badge`) alongside a heading + body lockup.
+     * The parent `af-numbered-stepper` auto-assigns the `index` prop based on
+     * DOM order. Pass `index` explicitly to override.
+     * Heading scale is the shared `card` variant from `af-typography-lockup`
+     * (22/20px) — the same ladder step used by diff-card, related-card, and
+     * other card-title uses across the design system.
+     */
+    interface HTMLAfNumberedStepperItemElement extends Components.AfNumberedStepperItem, HTMLStencilElement {
+    }
+    var HTMLAfNumberedStepperItemElement: {
+        prototype: HTMLAfNumberedStepperItemElement;
+        new (): HTMLAfNumberedStepperItemElement;
+    };
     /**
      * Decorative paperclip vector graphic. Renders the left-half paperclip
      * silhouette (viewBox `0 0 655 754`) that the marketing site bleeds off
@@ -2636,6 +2891,35 @@ declare global {
         prototype: HTMLAfStackElement;
         new (): HTMLAfStackElement;
     };
+    /**
+     * Individual stat — a large value (e.g. "1B+") paired with a descriptive label.
+     * Intended as a slotted child of `af-stats-row`, but renders standalone too.
+     * Colour is inherited from the ancestor theme context (`af-section` /
+     * `af-card` / `af-theme-override`) via the `--af-typography-*` tokens that
+     * `af-heading` and `af-text` already consume — no theme prop needed here.
+     */
+    interface HTMLAfStatElement extends Components.AfStat, HTMLStencilElement {
+    }
+    var HTMLAfStatElement: {
+        prototype: HTMLAfStatElement;
+        new (): HTMLAfStatElement;
+    };
+    /**
+     * Layout container for a horizontal row of `af-stat` children.
+     * Flex row that wraps to a grid on narrow viewports. Uses `scoped: true`
+     * so slotted `<af-stat>` children stay in the light DOM and inherit the
+     * ancestor theme (`af-section`) via the cascaded `.theme-*` class.
+     * Intentionally has **no `theme` prop** — a stats row is always flush
+     * against its section background, so a local theme would fight the
+     * ancestor. If you need a different background for the row, wrap it in
+     * its own `af-section` or `af-theme-override`.
+     */
+    interface HTMLAfStatsRowElement extends Components.AfStatsRow, HTMLStencilElement {
+    }
+    var HTMLAfStatsRowElement: {
+        prototype: HTMLAfStatsRowElement;
+        new (): HTMLAfStatsRowElement;
+    };
     /**
      * Stepper composite for "Sign up / Upload / See results"-style marketing
      * flows. Renders children `af-stepper-step` elements in a horizontal row
@@ -2964,6 +3248,7 @@ declare global {
         "af-grid": HTMLAfGridElement;
         "af-grid-callout": HTMLAfGridCalloutElement;
         "af-heading": HTMLAfHeadingElement;
+        "af-hero": HTMLAfHeroElement;
         "af-icon": HTMLAfIconElement;
         "af-icon-box": HTMLAfIconBoxElement;
         "af-icon-button": HTMLAfIconButtonElement;
@@ -2983,6 +3268,8 @@ declare global {
         "af-nav-menu-nest": HTMLAfNavMenuNestElement;
         "af-navbar": HTMLAfNavbarElement;
         "af-number-badge": HTMLAfNumberBadgeElement;
+        "af-numbered-stepper": HTMLAfNumberedStepperElement;
+        "af-numbered-stepper-item": HTMLAfNumberedStepperItemElement;
         "af-paperclip-decoration": HTMLAfPaperclipDecorationElement;
         "af-progress-line": HTMLAfProgressLineElement;
         "af-radio": HTMLAfRadioElement;
@@ -2992,6 +3279,8 @@ declare global {
         "af-spacer": HTMLAfSpacerElement;
         "af-split-section": HTMLAfSplitSectionElement;
         "af-stack": HTMLAfStackElement;
+        "af-stat": HTMLAfStatElement;
+        "af-stats-row": HTMLAfStatsRowElement;
         "af-stepper": HTMLAfStepperElement;
         "af-stepper-step": HTMLAfStepperStepElement;
         "af-switch": HTMLAfSwitchElement;
@@ -3130,7 +3419,7 @@ declare namespace LocalJSX {
           * Theme - sets background color and provides theme context to children. Defaults to 'mist-green' if not specified.
           * @default 'mist-green'
          */
-        "theme"?: 'white' | 'white-ivory' | 'inkwell' | 'mist-green' | 'soft-clay';
+        "theme"?: Theme;
     }
     /**
      * Center layout component for quickly centering content.
@@ -3349,7 +3638,7 @@ declare namespace LocalJSX {
           * Theme variant - sets background color and provides theme context. Only applies to 'standard' layout mode. Defaults to 'mist-green'.
           * @default 'mist-green'
          */
-        "theme"?: 'white' | 'white-ivory' | 'inkwell' | 'mist-green' | 'soft-clay';
+        "theme"?: Theme;
     }
     /**
      * Feature Grid component - CSS Grid container for feature cards.
@@ -3548,6 +3837,87 @@ declare namespace LocalJSX {
          */
         "level"?: 'xl' | '1' | '2' | '3' | '4' | '5';
     }
+    /**
+     * Unified top-of-page hero — replaces the 7+ hand-rolled hero implementations
+     * the Affinda marketing site (and sibling apps) currently ship. Covers five
+     * canonical patterns via the `variant` prop:
+     * - `inkwell-photo` — inkwell background, blob-masked photo on the right.
+     *   Use for: listing / archive pages (blog, case-studies, whitepapers,
+     *   value-creation, about-us) and industry landing pages that carry a
+     *   photograph instead of an illustration.
+     * - `inkwell-illustration` — inkwell background, illustration on the right.
+     *   Use for: industry landing pages, /industries, /integrations, /platform
+     *   with bespoke art.
+     * - `inkwell-centered` — inkwell background, centred typography lockup.
+     *   Slot `<af-paperclip-decoration />` into the `paperclip` slot for the
+     *   watermark treatment. Use for: `/`, `/au`, `/platform`.
+     * - `soft-clay-illustration` — soft-clay background, illustration on the
+     *   right. Use for: /news, /industries overview, /security, /compare.
+     * - `mist-green-illustration` — same layout as soft-clay-illustration but on
+     *   the mist-green theme. Reserved for future pages.
+     * ## Slots
+     * - default — heading content (use when richer markup than the `heading`
+     *   prop can express is needed; e.g. coloured spans or line breaks).
+     * - `description` — supporting copy under the heading.
+     * - `badge` — optional pre-heading label (pill, version tag).
+     * - `buttons` — hero CTAs (usually an `<af-button-group>`).
+     * - `image` — the photograph for the `inkwell-photo` variant. Wrapped in
+     *   the blob mask automatically.
+     * - `illustration` — the illustration SVG for `-illustration` variants.
+     * - `paperclip` — watermark for `inkwell-centered`. Consumers typically
+     *   slot `<af-paperclip-decoration />` here.
+     * - `logos-below` — overlap row at the bottom gutter (logo carousel etc.).
+     *   Painted with the theme's background so it cleanly overlaps the image's
+     *   lower edge on the photo variant.
+     * ## Float-navbar handling
+     * When `floatNavbar` is true (the default for the inkwell variants) the
+     * component sets `data-af-hero-float-navbar="true"` on `<body>` via a
+     * lifecycle hook, and a companion rule in `@affinda/css/base.css` applies
+     * the `body > header { position: absolute }` / `main { padding-top: 0 }`
+     * / navbar-spacer-transparent treatment. Consumers already import
+     * `@affinda/css` so no extra import is required. The rule deactivates
+     * when the hero is removed from the DOM.
+     * ## Image lift
+     * The `inkwell-photo` variant renders the photo column with
+     * `margin-top: var(--af-hero-image-lift, -260px)`. Override per-page by
+     * setting `--af-hero-image-lift` on the `<af-hero>` element.
+     */
+    interface AfHero {
+        /**
+          * Description text (use the `description` slot for richer markup).
+          * @default ''
+         */
+        "description"?: string;
+        /**
+          * Float the site header over the hero and paint the navbar-spacer transparent so the hero background flows to the top of the viewport. Defaults to true for the three inkwell variants, false for the soft-clay / mist-green illustration variants (whose consumers don't always want a full-bleed crown).
+         */
+        "floatNavbar"?: boolean;
+        /**
+          * Heading text (use the default slot for richer markup).
+          * @default ''
+         */
+        "heading"?: string;
+        /**
+          * Whether to apply the blob mask to the slotted `image`. Defaults to `true` for `inkwell-photo`. Set `false` if you want to slot in a pre-masked raster or a custom wrapper.
+          * @default true
+         */
+        "maskImage"?: boolean;
+        /**
+          * Typography lockup max-width (px). Defaults to 620, matching the live site.
+          * @default 620
+         */
+        "maxWidth"?: number;
+        /**
+          * Top padding preset. `default` = 124px (matches IndustryHero / IllustrationHero). `loose` = 164px (matches ListingHero — gives the image a touch more breathing room above the lockup on archive pages).
+          * @default 'default'
+         */
+        "topPad"?: HeroTopPad;
+        /**
+          * Layout / theme preset. See variant docs in the component header.
+          * @default 'inkwell-photo'
+         */
+        "variant"?: HeroVariant;
+    }
     /**
      * Icon component that displays SVG icons from the Affinda icon library.
      * Icons inherit color from their parent via currentColor.
@@ -3680,7 +4050,7 @@ declare namespace LocalJSX {
           * Theme variant - sets background color and provides theme context. Defaults to 'mist-green'.
           * @default 'mist-green'
          */
-        "theme"?: 'white' | 'white-ivory' | 'inkwell' | 'mist-green' | 'soft-clay';
+        "theme"?: Theme;
     }
     /**
      * A styled image container with rounded corners and a subtle inset border.
@@ -3773,7 +4143,7 @@ declare namespace LocalJSX {
           * Theme - sets the banner background color and typography colors
           * @default 'mist-green'
          */
-        "theme"?: BannerTheme;
+        "theme"?: Theme;
     }
     /**
      * Inline layout component for horizontal inline-flex layouts with gap and optional wrapping.
@@ -4130,7 +4500,7 @@ declare namespace LocalJSX {
         /**
           * Theme for the spacer background - should match the section below the navbar
          */
-        "theme"?: 'white' | 'inkwell' | 'mist-green' | 'soft-clay';
+        "theme"?: Theme;
     }
     /**
      * NumberBadge displays numbers 1-10 in either a filled circle or text-only style.
@@ -4157,6 +4527,52 @@ declare namespace LocalJSX {
          */
         "variant"?: NumberBadgeVariant;
     }
+    /**
+     * Numbered stepper — filled soft-clay circle badges (1/2/3) paired with a
+     * heading + body description per step. Sibling to `af-stepper` (which uses
+     * outlined badges on a single spine connector); the numbered variant uses
+     * filled badges with per-step connector segments, matching the Webflow
+     * "How it works" marketing pattern.
+     * Renders children `af-numbered-stepper-item` elements horizontally on
+     * desktop (auto-stacks on mobile) or vertically when `orientation="vertical"`.
+     * The parent auto-assigns badge numbers based on DOM order, so consumers
+     * don't hand-number the steps.
+     * Headings use the shared `heading-size="card"` scale from
+     * `af-typography-lockup` (22/20px) — no bespoke font-size tokens.
+     * @example ```html
+     * <af-numbered-stepper>
+     *   <af-numbered-stepper-item>
+     *     <h3 slot="heading">Connect your ATS</h3>
+     *     <p slot="body">OAuth-based hook into the tools you already use.</p>
+     *   </af-numbered-stepper-item>
+     *   <af-numbered-stepper-item>...</af-numbered-stepper-item>
+     *   <af-numbered-stepper-item>...</af-numbered-stepper-item>
+     * </af-numbered-stepper>
+     * ```
+     */
+    interface AfNumberedStepper {
+        /**
+          * Layout orientation. Horizontal auto-stacks to vertical on mobile.
+          * @default 'horizontal'
+         */
+        "orientation"?: 'horizontal' | 'vertical';
+    }
+    /**
+     * A single step within an `af-numbered-stepper`. Renders a filled soft-clay
+     * circle badge (via `af-number-badge`) alongside a heading + body lockup.
+     * The parent `af-numbered-stepper` auto-assigns the `index` prop based on
+     * DOM order. Pass `index` explicitly to override.
+     * Heading scale is the shared `card` variant from `af-typography-lockup`
+     * (22/20px) — the same ladder step used by diff-card, related-card, and
+     * other card-title uses across the design system.
+     */
+    interface AfNumberedStepperItem {
+        /**
+          * Step number shown in the badge. Auto-assigned by the parent stepper if not explicitly set.
+          * @default 1
+         */
+        "index"?: number;
+    }
     /**
      * Decorative paperclip vector graphic. Renders the left-half paperclip
      * silhouette (viewBox `0 0 655 754`) that the marketing site bleeds off
@@ -4260,12 +4676,12 @@ declare namespace LocalJSX {
           * Padding variant
           * @default 'default'
          */
-        "padding"?: 'none' | 'tight' | 'default' | 'loose';
+        "padding"?: Padding;
         /**
           * Theme - sets background color and provides theme context to children
           * @default 'white'
          */
-        "theme"?: 'white' | 'inkwell' | 'mist-green' | 'soft-clay' | 'white-ivory';
+        "theme"?: Theme;
     }
     /**
      * Show component for responsive visibility control.
@@ -4348,7 +4764,7 @@ declare namespace LocalJSX {
           * Padding variant
           * @default 'default'
          */
-        "padding"?: 'none' | 'tight' | 'default' | 'loose';
+        "padding"?: Padding;
         /**
           * Theme for the top half of the section
           * @default 'mist-green'
@@ -4386,6 +4802,35 @@ declare namespace LocalJSX {
          */
         "wrap"?: boolean;
     }
+    /**
+     * Individual stat — a large value (e.g. "1B+") paired with a descriptive label.
+     * Intended as a slotted child of `af-stats-row`, but renders standalone too.
+     * Colour is inherited from the ancestor theme context (`af-section` /
+     * `af-card` / `af-theme-override`) via the `--af-typography-*` tokens that
+     * `af-heading` and `af-text` already consume — no theme prop needed here.
+     */
+    interface AfStat {
+        /**
+          * Description / caption rendered beneath the value.
+         */
+        "label": string;
+        /**
+          * The statistic headline value (e.g. "1B+", "95%", "10+").
+         */
+        "value": string;
+    }
+    /**
+     * Layout container for a horizontal row of `af-stat` children.
+     * Flex row that wraps to a grid on narrow viewports. Uses `scoped: true`
+     * so slotted `<af-stat>` children stay in the light DOM and inherit the
+     * ancestor theme (`af-section`) via the cascaded `.theme-*` class.
+     * Intentionally has **no `theme` prop** — a stats row is always flush
+     * against its section background, so a local theme would fight the
+     * ancestor. If you need a different background for the row, wrap it in
+     * its own `af-section` or `af-theme-override`.
+     */
+    interface AfStatsRow {
+    }
     /**
      * Stepper composite for "Sign up / Upload / See results"-style marketing
      * flows. Renders children `af-stepper-step` elements in a horizontal row
@@ -4787,7 +5232,7 @@ declare namespace LocalJSX {
           * The theme to apply to child components. Overrides any inherited theme from parent containers.
           * @default 'white'
          */
-        "theme"?: 'white' | 'inkwell' | 'mist-green' | 'soft-clay' | 'white-ivory';
+        "theme"?: Theme;
     }
     /**
      * Marketing-style composition of heading + description + buttons with
@@ -4849,7 +5294,7 @@ declare namespace LocalJSX {
           * The heading size (1-5, or "card"; 1 is largest). Controls visual scale only — pair with a matching <h1>-<h5> slotted element for correct document outline (see component docblock). The `card` variant sits between 4 and 5 at 22/20px and is meant for card titles.
           * @default 2
          */
-        "headingSize"?: 1 | 2 | 3 | 4 | 5 | 'card';
+        "headingSize"?: HeadingSize;
         /**
           * Maximum width for the copy section (in pixels)
          */
@@ -4934,6 +5379,7 @@ declare namespace LocalJSX {
         "af-grid": AfGrid;
         "af-grid-callout": AfGridCallout;
         "af-heading": AfHeading;
+        "af-hero": AfHero;
         "af-icon": AfIcon;
         "af-icon-box": AfIconBox;
         "af-icon-button": AfIconButton;
@@ -4953,6 +5399,8 @@ declare namespace LocalJSX {
         "af-nav-menu-nest": AfNavMenuNest;
         "af-navbar": AfNavbar;
         "af-number-badge": AfNumberBadge;
+        "af-numbered-stepper": AfNumberedStepper;
+        "af-numbered-stepper-item": AfNumberedStepperItem;
         "af-paperclip-decoration": AfPaperclipDecoration;
         "af-progress-line": AfProgressLine;
         "af-radio": AfRadio;
@@ -4962,6 +5410,8 @@ declare namespace LocalJSX {
         "af-spacer": AfSpacer;
         "af-split-section": AfSplitSection;
         "af-stack": AfStack;
+        "af-stat": AfStat;
+        "af-stats-row": AfStatsRow;
         "af-stepper": AfStepper;
         "af-stepper-step": AfStepperStep;
         "af-switch": AfSwitch;
@@ -5145,6 +5595,52 @@ declare module "@stencil/core" {
              * via CSS custom properties.
              */
             "af-heading": LocalJSX.AfHeading & JSXBase.HTMLAttributes<HTMLAfHeadingElement>;
+            /**
+             * Unified top-of-page hero — replaces the 7+ hand-rolled hero implementations
+             * the Affinda marketing site (and sibling apps) currently ship. Covers five
+             * canonical patterns via the `variant` prop:
+             * - `inkwell-photo` — inkwell background, blob-masked photo on the right.
+             *   Use for: listing / archive pages (blog, case-studies, whitepapers,
+             *   value-creation, about-us) and industry landing pages that carry a
+             *   photograph instead of an illustration.
+             * - `inkwell-illustration` — inkwell background, illustration on the right.
+             *   Use for: industry landing pages, /industries, /integrations, /platform
+             *   with bespoke art.
+             * - `inkwell-centered` — inkwell background, centred typography lockup.
+             *   Slot `<af-paperclip-decoration />` into the `paperclip` slot for the
+             *   watermark treatment. Use for: `/`, `/au`, `/platform`.
+             * - `soft-clay-illustration` — soft-clay background, illustration on the
+             *   right. Use for: /news, /industries overview, /security, /compare.
+             * - `mist-green-illustration` — same layout as soft-clay-illustration but on
+             *   the mist-green theme. Reserved for future pages.
+             * ## Slots
+             * - default — heading content (use when richer markup than the `heading`
+             *   prop can express is needed; e.g. coloured spans or line breaks).
+             * - `description` — supporting copy under the heading.
+             * - `badge` — optional pre-heading label (pill, version tag).
+             * - `buttons` — hero CTAs (usually an `<af-button-group>`).
+             * - `image` — the photograph for the `inkwell-photo` variant. Wrapped in
+             *   the blob mask automatically.
+             * - `illustration` — the illustration SVG for `-illustration` variants.
+             * - `paperclip` — watermark for `inkwell-centered`. Consumers typically
+             *   slot `<af-paperclip-decoration />` here.
+             * - `logos-below` — overlap row at the bottom gutter (logo carousel etc.).
+             *   Painted with the theme's background so it cleanly overlaps the image's
+             *   lower edge on the photo variant.
+             * ## Float-navbar handling
+             * When `floatNavbar` is true (the default for the inkwell variants) the
+             * component sets `data-af-hero-float-navbar="true"` on `<body>` via a
+             * lifecycle hook, and a companion rule in `@affinda/css/base.css` applies
+             * the `body > header { position: absolute }` / `main { padding-top: 0 }`
+             * / navbar-spacer-transparent treatment. Consumers already import
+             * `@affinda/css` so no extra import is required. The rule deactivates
+             * when the hero is removed from the DOM.
+             * ## Image lift
+             * The `inkwell-photo` variant renders the photo column with
+             * `margin-top: var(--af-hero-image-lift, -260px)`. Override per-page by
+             * setting `--af-hero-image-lift` on the `<af-hero>` element.
+             */
+            "af-hero": LocalJSX.AfHero & JSXBase.HTMLAttributes<HTMLAfHeroElement>;
             /**
              * Icon component that displays SVG icons from the Affinda icon library.
              * Icons inherit color from their parent via currentColor.
@@ -5322,6 +5818,40 @@ declare module "@stencil/core" {
              * ```
              */
             "af-number-badge": LocalJSX.AfNumberBadge & JSXBase.HTMLAttributes<HTMLAfNumberBadgeElement>;
+            /**
+             * Numbered stepper — filled soft-clay circle badges (1/2/3) paired with a
+             * heading + body description per step. Sibling to `af-stepper` (which uses
+             * outlined badges on a single spine connector); the numbered variant uses
+             * filled badges with per-step connector segments, matching the Webflow
+             * "How it works" marketing pattern.
+             * Renders children `af-numbered-stepper-item` elements horizontally on
+             * desktop (auto-stacks on mobile) or vertically when `orientation="vertical"`.
+             * The parent auto-assigns badge numbers based on DOM order, so consumers
+             * don't hand-number the steps.
+             * Headings use the shared `heading-size="card"` scale from
+             * `af-typography-lockup` (22/20px) — no bespoke font-size tokens.
+             * @example ```html
+             * <af-numbered-stepper>
+             *   <af-numbered-stepper-item>
+             *     <h3 slot="heading">Connect your ATS</h3>
+             *     <p slot="body">OAuth-based hook into the tools you already use.</p>
+             *   </af-numbered-stepper-item>
+             *   <af-numbered-stepper-item>...</af-numbered-stepper-item>
+             *   <af-numbered-stepper-item>...</af-numbered-stepper-item>
+             * </af-numbered-stepper>
+             * ```
+             */
+            "af-numbered-stepper": LocalJSX.AfNumberedStepper & JSXBase.HTMLAttributes<HTMLAfNumberedStepperElement>;
+            /**
+             * A single step within an `af-numbered-stepper`. Renders a filled soft-clay
+             * circle badge (via `af-number-badge`) alongside a heading + body lockup.
+             * The parent `af-numbered-stepper` auto-assigns the `index` prop based on
+             * DOM order. Pass `index` explicitly to override.
+             * Heading scale is the shared `card` variant from `af-typography-lockup`
+             * (22/20px) — the same ladder step used by diff-card, related-card, and
+             * other card-title uses across the design system.
+             */
+            "af-numbered-stepper-item": LocalJSX.AfNumberedStepperItem & JSXBase.HTMLAttributes<HTMLAfNumberedStepperItemElement>;
             /**
              * Decorative paperclip vector graphic. Renders the left-half paperclip
              * silhouette (viewBox `0 0 655 754`) that the marketing site bleeds off
@@ -5393,6 +5923,25 @@ declare module "@stencil/core" {
              * Uses design tokens for gap values.
              */
             "af-stack": LocalJSX.AfStack & JSXBase.HTMLAttributes<HTMLAfStackElement>;
+            /**
+             * Individual stat — a large value (e.g. "1B+") paired with a descriptive label.
+             * Intended as a slotted child of `af-stats-row`, but renders standalone too.
+             * Colour is inherited from the ancestor theme context (`af-section` /
+             * `af-card` / `af-theme-override`) via the `--af-typography-*` tokens that
+             * `af-heading` and `af-text` already consume — no theme prop needed here.
+             */
+            "af-stat": LocalJSX.AfStat & JSXBase.HTMLAttributes<HTMLAfStatElement>;
+            /**
+             * Layout container for a horizontal row of `af-stat` children.
+             * Flex row that wraps to a grid on narrow viewports. Uses `scoped: true`
+             * so slotted `<af-stat>` children stay in the light DOM and inherit the
+             * ancestor theme (`af-section`) via the cascaded `.theme-*` class.
+             * Intentionally has **no `theme` prop** — a stats row is always flush
+             * against its section background, so a local theme would fight the
+             * ancestor. If you need a different background for the row, wrap it in
+             * its own `af-section` or `af-theme-override`.
+             */
+            "af-stats-row": LocalJSX.AfStatsRow & JSXBase.HTMLAttributes<HTMLAfStatsRowElement>;
             /**
              * Stepper composite for "Sign up / Upload / See results"-style marketing
              * flows. Renders children `af-stepper-step` elements in a horizontal row