@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/header/header.stories.js

@@ -1,5 +1,15 @@
 import { html } from 'lit';
 import './header.js';
+/* The reference story below composes the same atoms the component does, and
+   borrows the component's OWN stylesheet rather than restating it -- see the
+   note on IntendedDesign for what that buys and what it does not cover. */
+import headerCSS from './header.css.js';
+import { ensembleCSS } from '../shared/ensemble.css.js';
+import '../badge/badge.js';
+import '../button/button.js';
+import '../heading/heading.js';
+import '../icons/brand-signature-icon.js';
+import '../paragraph/paragraph.js';
 
 export default {
   title     : 'Components/Header',
@@ -20,7 +30,7 @@ export default {
   devices="5"
   subscription="1"
 >
-  <img slot="header-picture" src="/assets/product.png" alt="Product" />
+  <img slot="header-picture" src="/images/bd-header-img.jpg" alt="Product" />
   <span slot="disclaimer-top">Protection for 5 devices.</span>
 </bd-header>
 \`\`\`
@@ -34,9 +44,376 @@ export default {
 | \`disclaimer-bottom-link\` | Link in the bottom disclaimer |
 | \`disclaimer-bottom-text-end\` | End of the bottom disclaimer line |
 
+### This is Header / v2's chosen configuration
+
+Everything below was brought across from Figma \`Header / v2\` (node \`340:4\`),
+which is the winning variant of the *Header height study* — variant **I**
+(all type shrunk) at frame padding 16, with the brand signature and scrim. The
+Figma component measures **1290 × 566**, under the 600px target the study was
+run against; every value here was then measured in this Storybook at 1440.
+
+**The type is all roles, and no new token was needed.** That is the headline
+result: the as-built header needed a brand-new \`fontSize-64\` primitive and a
+\`display-hero\` role for its 64px headline — **both since retired, because this
+was their only reason to exist** — and the configuration that actually
+won drops to 48 — where \`heading-h1\` already lives. Measured, in render order:
+
+| | role | measured |
+|---|---|---|
+| product name | \`heading-h4\` role on a \`<p>\` | 24px / 600 / 31.2px, \`rgb(0 89 214)\` |
+| headline | \`bd-h\` at \`visual-level="h1"\`, level from \`heading-level\` | 48px / 700 / 60px |
+| description | \`bd-p variant="regular"\` | 16px / 400 / 24px |
+| struck price | \`bd-p regular\` + \`font-weight="medium"\`, muted | 16px / 500 / 24px, \`rgb(86 94 102)\` |
+| discount | \`bd-badge tone="success" variant="fill" size="lg"\` | 14px / 500, white on \`rgb(14 133 50)\` |
+| final price | \`heading-h2\` | 36px / 700 / 45px |
+| disclaimers | \`bd-p variant="xsmall"\`, muted | 12px / 400 / 17.4px |
+| both CTAs | \`size="lg"\` | 16/32 padding, 18px label, 8px radius |
+
+### The heading structure: one h1, and the eyebrow is not a heading
+
+This changed, and it changes the outline of every page rendering the header, so
+it is worth reading rather than skipping.
+
+**Before:** the product name was \`as="h2"\` and the headline \`as="h4"\`, in
+that DOM order. So the eyebrow was announced as a landmark and the actual
+promise was announced two levels below it — a heading list read *"Bitdefender
+Total Security"* (h2) then *"Complete protection for all your devices"* (h4),
+in the wrong order of importance.
+
+**Now:** the headline is the page's \`<h1>\` and the product name is a \`<p>\`.
+
+- The headline is the main heading of the page. This component is the product
+  hero and there is one per page, which is the condition an \`h1\` needs.
+  \`bd-h\`'s h1 role is 5xl / bold / tight — 48/700/1.25 — which is Header /
+  v2's value-prop exactly, so \`as="h1"\` needs no \`visual-level\` beside it.
+  The outline level and the type role agree here instead of having to be
+  separated.
+- The product name is a **kicker**: a label naming the product, and in Figma a
+  plain text layer called \`product-name\` rather than a heading. A kicker in
+  the outline is worse than no kicker in the outline — it adds a rung nobody
+  navigates by and pushes the real heading down. It resolves through the
+  \`heading-h4\` **role** on a non-heading element, which is the right way
+  round: the role names the type job ("the most prominent label on the
+  section"), and what the element *is* is settled by the tag.
+
+**The alternative, and why not.** The other accessible eyebrow pattern nests
+both inside the heading —
+\`<h1><span>Bitdefender…</span><span>Complete protection…</span></h1>\` —
+giving the heading an accessible name that carries the product as well as the
+promise. Rejected on two counts: every heading list, skip link and screen-reader
+rotor entry would read the whole run, and it would mean hand-rendering the
+\`h1\` here instead of going through \`bd-h\`, which takes one slot. The product
+is already named by the document title, the price block and the CTA; the
+heading does not have to carry it too.
+
+**If your page needs a different level, say so — that is your call, not this
+component's.** \`heading-level\` takes h1–h6 and defaults to \`h1\`:
+
+\`\`\`html
+<bd-header heading-level="h2" subtitle="Complete protection…"></bd-header>
+\`\`\`
+
+Two things about it worth knowing before you use it:
+
+- **It moves the heading in the outline and changes nothing about how it
+  looks.** \`visual-level\` is pinned to \`h1\` in the component, so the hero
+  stays 48 / 700 / 60px at every level. The size is the design's; only the
+  level is the page's. Without the pin, \`bd-h\` follows \`as\` for both and
+  \`heading-level="h3"\` would have rendered the hero at the h3 role instead —
+  measured **32px at 1024 and 24px at 320**, against 48 and 30 — an SEO
+  decision repainting the design.
+- **\`h1\` is the right answer far more often than not.** A hero that is not
+  the page's main heading is usually a sign the hero is in the wrong place, so
+  treat a non-\`h1\` here as something you decided rather than something you
+  reached for. The prop exists because the decision belongs to the page — the
+  dev team and the SEO team own the heading levels on this section — not
+  because the default is in doubt.
+
+It was hardcoded until 2026-09-17, which is the part that was wrong: the rule
+above says the composing page owns \`as=\`, and the component was keeping it.
+
+**The spacing is variant I's 16/8/8.** \`:host\` pads the row 16 (was a bare
+\`32px\`), the content column takes 24 back, the two columns are 64 apart (was
+\`30px\`, on no step and 34 short of the design), and the gaps run
+content 16 → body 16 → copy 8 → actions 8. Tightening copy and actions to 8 is
+where most of the 94px the study saved came from.
+
+**What this retired.** Not only additions — six things that were wrong went:
+
+- a \`font-size: 44px\` on the final price, carrying a recorded \`no token:\`
+  exception because 44 is off the type scale. The design asks for 36, which
+  \`heading-h2\` is exactly, so the exception simply dissolved
+- a hand-rolled discount badge — \`green-100\` behind \`text/success\` at 16px
+  semibold in a \`--radius-xl\` box, with two \`no role:\` markers saying it
+  should be a \`bd-badge\`. It is one now, and not the same one: that tint is
+  the atom's \`shade\`, and the design asks for \`fill\`
+- three off-scale literals (\`30px\`, \`32px\` twice), all three previously
+  baselined in \`lint:tokens\`
+- \`transform: scale(1.35) translateY(-7%)\` on the product image, a crop hack
+  that magnified the photo 135% so a wide image would fill a tall box. A real
+  \`object-fit: cover\` at \`height: 100%\` does that without throwing away a
+  third of the resolution — and it matters to the scrim, which is positioned
+  against the wrapper while a transformed image is somewhere else
+- two dead declarations on each disclaimer. They set \`font-size\` and
+  \`font-weight\` on a \`bd-p\` host, which \`scripts/atom-inert-properties.json\`
+  records as INERT — the atom sets all five type axes on its inner element. So
+  the rendered size was 14 while the rule claimed otherwise; the size now comes
+  from the atom's own \`xsmall\` variant
+- two \`.bd-header-image\` rules disagreeing about \`height\`
+
+**One recorded divergence.** Figma binds \`fontSize\` to a variable on these
+text nodes and leaves \`lineHeight\` and \`letterSpacing\` raw, so its \`-1px\`
+product-name tracking, its \`-2.5%\` headline tracking and its \`150%\` disclaimer
+leading were unbound numbers rather than tokens. CLAUDE.md's rule is to read
+the intent and spell it with the role, so the code takes the roles' values —
+and the Figma component was then set to match, so the two agree on one answer
+rather than on two.
+
+### Responsive: three steps on the breakpoint scale
+
+**There is no mobile frame in Figma.** The height study was run at 1290 only,
+so every width below that was decided here, from the grid arithmetic and then
+by measuring. The page column caps at \`--grid-container-max-*\` with
+\`--grid-padding-*\` either side, so once the design's 64px gap comes out, the
+two-column arithmetic is fixed:
+
+| step | content width | per column |
+|---|---|---|
+| xxl | 1320 − 80 = 1240 | 588 |
+| xl | 1140 − 80 = 1060 | 498 |
+| lg | 960 − 80 = 880 | 408 |
+| md | 720 − 64 = 656 | 296 |
+| sm | 540 − 48 = 492 | 214 |
+
+The CTA row is **446px**. It fits at xl and xxl, wraps at lg, and at md there
+is less room than one button needs. So:
+
+- **\`below('lg')\` — stack.** One column, 32px row gap.
+- **\`below('md')\` — stack the CTA.** Separate from the step above on purpose:
+  at md the column is 656px, where a side-by-side CTA row still fits.
+- **\`below('md')\` — re-proportion the scrim band** (same query, different
+  concern: it is about the media panel, not the copy).
+
+Measured across ten widths afterwards — no horizontal overflow at any of them,
+and the buttons hold 183/246 at every width:
+
+| width | cols | column | headline | description | band | total |
+|---|---|---|---|---|---|---|
+| 1440 | 2 | 588 | 48 × 2 | 16 × 3 | 30% | **566** |
+| 1280 | 2 | 498 | 48 × 2 | 16 × 3 | 30% | 566 |
+| 1100 | 2 | 408 | 48 × 2 | 16 × 4 | 25% | 661 |
+| 1024 | 2 | 408 | 48 × 2 | 16 × 4 | 25% | 661 |
+| 900 | 1 | 656 | 48 × 2 | 16 × 2 | 37% | 1012 |
+| 768 | 1 | 656 | 48 × 2 | 16 × 2 | 37% | 1012 |
+| 600 | 1 | 492 | 48 × 2 | 16 × 3 | 27% | 997 |
+| 375 | 1 | 311 | 48 × 3 | 16 × 5 | 42% | 1002 |
+| 320 | 1 | 256 | 48 × 4 | 16 × 6 | 51% | 1066 |
+
+#### Why lg keeps two columns even though it costs 661px
+
+It is the one arguable step, and it is arguable rather than good. Two columns
+at lg cost the description a fourth line, the CTA row a wrap, and the section
+**661px** against the design's 566. No gap change rescues it: the row needs 445
+and dropping 64 to the lg grid gutter's 40, or to 24, or to 16, gives 420, 428
+and 432. The column is about 40px short however the gutter is spent.
+
+It keeps them because stacking is worse **on the same screen**. Stacked at lg
+the copy gets one 880px column — the headline collapses to one line, which the
+study measured as needing 678 — and then an 880px-wide photograph beneath it at
+its own 1.497 ratio: about 1100px of hero in a window 992–1199 wide. Bounding
+the stacked panel to 16/9 would still land near 978. 661 wins.
+
+#### The scrim band now scales, because it is built from lengths
+
+The band was four percentage stops of a fixed 160px — read straight off Figma,
+which made the invariant arithmetic: the 70% stop landed on the mark's top edge
+only because 0.3 × 160 happens to equal 24 + 24. It is now **length stops
+measured from the bottom**, so the plateau *is* the mark's box by construction
+at any size, and the narrow variant is two smaller numbers rather than a second
+set of percentages. The stops still resolve to Figma's exactly at desktop:
+plateau 0–48, 0.22 at 88, zero at 160.
+
+That mattered because the band was a constant and the panel is not. The panel
+follows the copy beside it when the columns are side by side, and its own
+1.497 ratio once they stack — 311×208 at 375 and 256×171 at 320, which put a
+160px band at **77%** and **94%** of the picture. Below md the inset drops a
+step and the fade drops to 48, giving 40 + 48 = 88: **42%** and **51%**.
+
+One thing that is inherent rather than fixed — a constant band on a variable
+panel is a variable proportion. *Default* has less copy than the design, so its
+panel is 399 tall at 1440 and the band reads 40% there against the design's 30%.
+
+#### What was removed, and one claim corrected
+
+Two of the three old media blocks were largely inert. \`flex-direction: column\`
+on \`.bd-container\` is inert — the container is \`display: grid\`, and the
+identical mistake was already recorded further down the file. \`gap: 2em\` was an
+em literal on no scale and the only live declaration in that block, which is
+why the gap read 32px at exactly 1024 and 64px at 1025. \`width: 100%\` on two
+grid items is redundant, and \`::slotted([slot="right"])\` is one of the four
+slot names this stylesheet targets that \`header.js\` never renders.
+
+So the header's real stacking point was \`below('md')\`, and measured at 768 that
+was far too late: two 312px columns, the headline at three lines, the
+description at five, the buttons crushed from 183/246 to **150/146** with both
+labels broken over three lines inside a box padded for one, and the section
+**737px** tall — against a design that exists to hold it under 600. Flex items
+shrink by default, so "nowrap" never meant "stays on one line"; it meant
+"squashes". \`.bd-cta\` now wraps, which happens at whatever width runs out
+rather than at a breakpoint somebody picks.
+
+**A correction.** The \`(max-width: 480px)\` block set \`max-width: 90%\` and
+\`max-height: 200px\` on \`.bd-header-image\` — a class \`header.js\` does not
+render. For the component it was **dead**: measured at 375 and 320, the slotted
+image computes \`max-width: none\`, \`max-height: none\` and sits flush with the
+wrapper on every edge. It was live only in *Intended design*, which draws a
+real \`<img class="bd-header-image">\`, and that is where a 90%-wide centred
+image left the scrim and the mark — both positioned against the **wrapper** —
+hanging past the photo on each side.
+
+#### Three things only the render showed
+
+The ten-width table above was all measured, and it missed all three of these.
+Numbers answer "does it fit"; they do not answer "does it look deliberate".
+
+1. **The price row was not centred** while everything around it was.
+   \`text-align\` centres a block's *inline content*, and
+   \`.bd-price-zone-top\` is \`display: flex\` — so the property reached its
+   children's text and moved the row itself not at all. The struck price and
+   the badge sat hard left while the final price, a block span, centred
+   underneath. It was patched with \`justify-content: center\`, and then the
+   patch became the argument for dropping the centring altogether — see below.
+   Both are gone.
+2. **The stacked CTAs were ragged** — 183 above 246, both centred. The first
+   attempt made it *worse*: \`align-items: stretch\` took the hosts full width,
+   but each anchor is \`inline-flex\` and hugs its label, so both buttons ended
+   up hard against the left edge of a centred layout. The atom's own answer is
+   its \`fullwidth\` attribute, which a media query cannot set, so the host's
+   display does it instead: a lone child of a single-column grid fills its
+   track. Measured, hosts 492 and anchors 183/246 → 492/492.
+3. **The mark dominated the panel at 320** — 182px on a 256px panel is **71%**,
+   against 30% in the design, so a corner signature became a caption laid
+   across the picture. The numbers said it fitted, and it did fit; fitting was
+   not the question. It steps to the \`sm\` icon step below md — 121px, 47% of
+   that panel — and \`--bd-header-mark-height\` steps with it so the scrim's
+   plateau still ends exactly on the mark's top edge.
+
+Re-verified after, with the mark hidden and the composited backdrop sampled at
+six widths: the plateau covers the mark at **every** width (48px desktop, 32px
+narrow) and the worst contrast is **4.84:1** at 320, with 0% of the mark's area
+under 4.5:1.
+
+#### And one silent defect, which is why the lint gained a rule
+
+An earlier edit in this pass dropped a single \`}\` from the \`below('md')\`
+block. That is valid JavaScript: the module parsed, the import succeeded,
+\`lint:tokens\` stayed clean, all fifteen \`check:ds\` gates passed and so did
+all five browser gates. At runtime every rule after it folded into the media
+query, so at desktop the product name silently collapsed from two lines to one
+and the section lost 63px. **It was caught by looking at a screenshot.**
+
+\`lint:tokens\` now carries \`unbalanced-css-braces\` beside the
+\`declaration-inside-comment\` rule it is modelled on — counting braces per
+\`css\`\`\` template after stripping comments, \`\${…}\` interpolations (every
+one ends in a brace) and strings (\`content: "}"\` is legal CSS). Seven
+selftest cases, and it was proved on the real defect: removing that brace again
+makes it the only new finding, restoring it returns the lint to clean.
+
+#### Two things deliberately left alone
+
+- **The headline does not step down.** \`bd-h\`'s type lives on its inner element
+  inside its shadow root, so a \`font-size\` from here is inert, and no atom in
+  this package changes its type with the viewport. Measured, 48px runs two
+  lines to 500px, three at 375 and four at 320 — and at 320 that is one word
+  per line, which is the most visibly wrong thing left on this page.
+
+  Note the icon and the button above were both reachable because each atom's
+  rule is on \`:host\`, where an outer-tree rule wins. \`bd-h\` puts its type on
+  the **inner** element, so there is no CSS route at all — only two real ones:
+  give \`bd-h\` responsive roles, which is a foundation decision touching every
+  consumer and would be this package's first responsive type; or switch
+  \`visual-level\` from JS the way \`bd-footer\`'s \`_isMobile\` already reads the
+  viewport through \`matchesBelow()\`. Neither is free: the step to move to is
+  \`heading-h2\`, 36/bold, which is **also the final price's role**, so at 36 the
+  headline and the price become the same size and the hierarchy the semibold
+  kicker was added to sharpen flattens. 375 — the common phone width — is three
+  lines and reads fine; 320 is the edge. A design decision, not a CSS one.
+- **Nothing else.** The stacked-CTA raggedness that was listed here is fixed
+  above.
+
+#### The content is left-aligned at every width
+
+It used to centre below \`md\`. It no longer does, and the reasoning is worth
+keeping because the centring looked harmless:
+
+- **The design never asked for it.** \`Header / v2\` is left-aligned and there is
+  no mobile frame in the file that centres. Changing the axis at a breakpoint was
+  a decision nobody recorded making.
+- **The content is the wrong shape for it.** Six stacked blocks of very different
+  widths — a two-line kicker, a two-line headline, a five-line description, a
+  price pair, two CTAs, a two-line disclaimer — share no edge when centred, so the
+  eye gets no vertical line to return to down a five-line paragraph at 288px.
+  Centring suits a poster: a headline and one button. This is a specification.
+- **It needed a patch to stop looking broken, and that is the argument.** The price
+  row had to be given \`justify-content: center\` because \`text-align\` cannot
+  move a flex row. A treatment that needs a correction to look deliberate usually
+  is not the right treatment — and dropping the centring removed the patch with it.
+
+The full-width stacked CTAs stay: equal tap targets that do not vary with the copy
+hold either way.
+
+### The brand signature over the image
+
+When \`header-picture\` is filled, the header lays two things over it — a
+\`--color-blue-950\` scrim band across the bottom, and
+\`<bd-brand-signature-icon>\` 24px in from the bottom-right corner (measured:
+24 and 24). Both come from \`Header / v2\`, whose media-panel stacks
+\`media → scrim → brand-signature\` in that order.
+
+Neither is a slot and neither is a prop. The signature is the brand's, not the
+page's, so there is nothing for a consumer to decide; the scrim exists so the
+white mark is legible over an image the design system has never seen, so
+turning it off would be turning off the only thing making that true. What the
+consumer controls is the image.
+
+They appear **only** when something is actually slotted. A blue band and a
+white mark over an empty column would be a wash of colour and an invisible
+mark, so \`_hasPicture\` is tracked from the slot's own \`slotchange\` and the
+pair is not rendered at all otherwise — see *No Product Image* below, which is
+a documented state rather than an accident.
+
+**What replaced what.** This used to be the words "Trusted. Always." at 32px
+bold, 16px from the corner. That was type doing a mark's job, it was English
+hardcoded next to a stylesheet, and it clipped: measured at 320px the 133px run
+sat inside a 96px column with \`overflow: hidden\` and read "rusted. lways.".
+The mark is the same words as artwork, so nothing needs translating and the
+width is fixed at 182.
+
+### The prices are empty in Storybook
+
+The struck price, the discount and the final price are store-driven —
+\`data-store-render\` with \`data-store-price\` / \`data-store-discount\` — and
+there is no store in Storybook, so all three render empty. The discount badge
+therefore shows as a small green pill with no text. That is the harness, not
+the design: on a real page \`data-store-hide\` removes the whole row when the
+option is not discounted.
+
 ### Notes
 - Pricing zones use \`data-store-render\` and \`data-store-price\` attributes for store integration
-- \`shadow\` prop reflects as an attribute and defaults to \`true\`
+- \`shadow\` reflects as an attribute and defaults to \`true\`, and it is **not a
+  styling flag** despite the name. It is how
+  \`@repobit/dex-store-elements\` discovers that this component's shadow root
+  should be walked for \`[data-store-render]\` and \`[data-store-hide]\` nodes
+  (its \`SHADOW_HOST_SELECTOR\` is \`'[shadow], [data-bd-watch-shadow]'\`). Every
+  price zone in this component is inside that shadow root, so dropping the
+  attribute silently stops the prices rendering on a real page
+- **\`fullPrice\`, \`discount\` and \`finalPrice\` have been removed.** Nothing read
+  them -- not the template, not the stylesheet, not the store, which computes
+  prices from \`product-id\` + \`devices\` + \`subscription\` and never looks at a
+  host property. They were listed in the component manifest as if they worked,
+  which is the worse half of the defect: that file is the contract a page
+  generator is handed. Wiring them instead would have given one value two
+  sources that can disagree, with no answer to which wins
         `
       }
     }
@@ -44,19 +421,58 @@ export default {
   argTypes: {
     title: {
       control    : 'text',
-      description: 'Product name rendered as `<bd-h as="h2">`',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
+      description: 'The product name — the kicker above the headline. Rendered as a '
+        + '`<p class="bd-product-name">` resolving through the `heading-h4` role, '
+        + 'NOT as a heading: a kicker in the document outline adds a rung nobody '
+        + 'navigates by. (This used to say `<bd-h as="h2">`, which is what it was '
+        + 'before the heading structure was fixed.)',
+      table: { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
     },
     subtitle: {
       control    : 'text',
-      description: 'Value proposition rendered as `<bd-h as="h4">`',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
+      description: 'The value proposition — the actual heading of the section, rendered '
+        + 'as `<bd-h as="h1" visual-level="h1">`. Its level is the `headingLevel` prop; '
+        + 'its size is fixed. (This used to say `<bd-h as="h4">`, from before the fix.)',
+      table: { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
     },
     description: {
       control    : 'text',
-      description: 'Description paragraph rendered as `<bd-p kind="regular">`',
+      description: 'Description paragraph rendered as `<bd-p variant="regular">`',
       table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
     },
+    ctaLabel: {
+      control    : 'text',
+      description: 'Visible label on the primary CTA. Defaults to `Buy now`, the string this '
+        + 'component has always rendered; the design reads **Get Protection**. Its '
+        + 'destination is not a prop \u2014 the primary carries `buyLink`, so the store '
+        + 'injects the buy URL at runtime.',
+      table: { type: { summary: 'string' }, defaultValue: { summary: 'Buy now' }, category: 'CTA' }
+    },
+    ctaSecondaryLabel: {
+      control    : 'text',
+      description: 'Visible label on the secondary CTA. Defaults to `View more plans`; the '
+        + 'design reads **Start your 30-day trial**.',
+      table: { type: { summary: 'string' }, defaultValue: { summary: 'View more plans' }, category: 'CTA' }
+    },
+    ctaSecondaryHref: {
+      control    : 'text',
+      description: '**Set this.** Destination for the secondary CTA, with no default \u2014 and '
+        + 'until a page gives it one the control is dead: `bd-button-link` drops the `href` '
+        + 'attribute when it is empty, so the anchor is not focusable, is not a link to a '
+        + 'screen reader, and does nothing on click. It has rendered that way since the '
+        + 'component was written.',
+      table: { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'CTA' }
+    },
+    headingLevel: {
+      control    : { type: 'select' },
+      options    : ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+      description: 'Where the headline sits in the **document outline**. Defaults to '
+        + '`h1`, which is what a product hero is on the page it leads. Changing it '
+        + 'does not change how the headline looks — `visual-level` is pinned to `h1`, '
+        + 'so the hero stays 48/700/1.25 at every level. Off-list values fall back to '
+        + '`h2` in `bd-h`: still a heading, never the page\'s.',
+      table: { type: { summary: "'h1'|'h2'|'h3'|'h4'|'h5'|'h6'" }, defaultValue: { summary: 'h1' }, category: 'Content' }
+    },
     productId: {
       control    : 'text',
       description: 'Product ID passed to `<bd-product>` for store price lookup',
@@ -74,8 +490,11 @@ export default {
     },
     shadow: {
       control    : 'boolean',
-      description: 'Reflected attribute for shadow styling',
-      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'true' }, category: 'Appearance' }
+      description: 'NOT styling. It is how @repobit/dex-store-elements finds this '
+        + "component's shadow root -- its SHADOW_HOST_SELECTOR is "
+        + '\'[shadow], [data-bd-watch-shadow]\' -- so every [data-store-render] price '
+        + 'zone inside the shadow tree depends on it. Load-bearing; leave it set.',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'true' }, category: 'Appearance' }
     },
     dataLayerEvent: {
       control    : 'text',
@@ -90,13 +509,17 @@ const render = (args) => html`
     title="${args.title}"
     subtitle="${args.subtitle}"
     description="${args.description}"
+    heading-level="${args.headingLevel}"
+    cta-label="${args.ctaLabel}"
+    cta-secondary-label="${args.ctaSecondaryLabel}"
+    cta-secondary-href="${args.ctaSecondaryHref}"
     product-id="${args.productId}"
     devices="${args.devices}"
     subscription="${args.subscription}"
     ?shadow="${args.shadow}"
     data-layer-event="${args.dataLayerEvent}"
   >
-    <img slot="header-picture" src="/assets/product-header.png" alt="Product screenshot" />
+    <img slot="header-picture" src="/images/bd-header-img.jpg" alt="Product screenshot" />
     <span slot="disclaimer-top">
       Protection for 1 account & ${args.devices} PCs, Macs, tablets, or smartphones.
       Windows® | macOS® | Android™ | iOS®
@@ -105,11 +528,15 @@ const render = (args) => html`
 `;
 
 const defaultArgs = {
-  title         : 'Bitdefender Total Security',
-  subtitle      : 'Complete real-time data protection',
-  description   : 'Award-winning cybersecurity for all your devices. Protection against viruses, malware, ransomware, and more.',
-  productId     : 'ts', devices       : '5', subscription  : '1',
-  shadow        : true, dataLayerEvent: 'info'
+  title            : 'Bitdefender Total Security',
+  subtitle         : 'Complete real-time data protection',
+  description      : 'Award-winning cybersecurity for all your devices. Protection against viruses, malware, ransomware, and more.',
+  headingLevel     : 'h1',
+  ctaLabel         : 'Buy now',
+  ctaSecondaryLabel: 'View more plans',
+  ctaSecondaryHref : '',
+  productId        : 'ts', devices          : '5', subscription     : '1',
+  shadow           : true, dataLayerEvent   : 'info'
 };
 
 // ─── Stories ───────────────────────────────────────────────────────────────
@@ -143,7 +570,7 @@ export const WithDisclaimers = {
       description="Unlimited devices, unlimited VPN, identity theft protection."
       product-id="ps" devices="unlimited" subscription="1"
     >
-      <img slot="header-picture" src="/assets/premium.png" alt="Premium Security" />
+      <img slot="header-picture" src="/images/bd-header-us.jpg" alt="Premium Security" />
       <span slot="disclaimer-top">Protects unlimited devices.</span>
       <span slot="disclaimer-bottom-text-start">By purchasing you agree to our </span>
       <a slot="disclaimer-bottom-link" href="/terms">Terms of Service</a>
@@ -179,5 +606,401 @@ export const Playground = {
   name      : '🛝 Playground',
   args      : { ...defaultArgs },
   render,
-  parameters: { docs: { description: { story: 'Interactive playground. Adjust title, subtitle, description, product-id, devices, and subscription via Controls.' } } }
-};
+  parameters: { docs: { description: { story: 'Interactive playground. Adjust title, subtitle, description, heading-level, product-id, devices, and subscription via Controls.' } } }
+};
+
+export const HeadingLevel = {
+  name      : 'Heading Level (the outline is the page\'s)',
+  parameters: {
+    docs: {
+      description: {
+        story: `Same header twice. The top one takes the default — the headline
+is the page's \`<h1>\`. The bottom one is \`heading-level="h3"\`.
+
+**Look at the type: nothing moved.** Both headlines render 48px / 700 /
+60px, because \`visual-level\` is pinned to \`h1\` inside the component. The
+level is the document outline and the page owns it; the size is the design and
+the component owns it. \`bd-h\` keeps those on separate props for exactly this
+case, and pinning one of them is what stops an outline decision from
+repainting the design — unpinned, this second header would have rendered its
+hero at the h3 role: measured 32px here and 24px at 320, against 48 and 30.
+
+Inspect the shadow roots to see the difference, because that is the only place
+it exists: \`h1.bd-heading.h1\` above, \`h3.bd-heading.h1\` below. The class is
+the type role and stays \`h1\`; the tag is the level and follows the prop.
+
+Measured, both headers, in this story: 48px / 700 / 60px and a section
+**484px** tall at 1024, 30px and **728px** tall at 320 — identical to the
+pixel, differing only in tag name. A level off the h1–h6 list behaves the same
+way on the size and falls back on the level: \`heading-level="zzz"\` renders
+\`h2.bd-heading.h1\` at 48px, which is \`bd-h\`'s own fallback — still a
+heading, never the page's.
+
+**Reach for this deliberately.** A hero that is not the page's main heading is
+usually a sign the hero is in the wrong place. The prop exists because the
+decision belongs to the dev and SEO teams composing the page, not because
+\`h1\` is in doubt.`
+      }
+    }
+  },
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:var(--spacing-64);">
+      <div>
+        <p style="margin:0 0 var(--spacing-8); font: 500 12px/1.4 var(--typography-fontFamily-sans); color: var(--color-text-muted);">
+          default — renders &lt;h1 class="bd-heading h1"&gt;
+        </p>
+        <bd-header
+          title="Bitdefender Total Security"
+          subtitle="Complete real-time data protection"
+          description="Award-winning cybersecurity for all your devices."
+          product-id="ts" devices="5" subscription="1">
+          <img slot="header-picture" src="/images/bd-header-img.jpg" alt="Product screenshot" />
+        </bd-header>
+      </div>
+      <div>
+        <p style="margin:0 0 var(--spacing-8); font: 500 12px/1.4 var(--typography-fontFamily-sans); color: var(--color-text-muted);">
+          heading-level="h3" — renders &lt;h3 class="bd-heading h1"&gt;, same 48px
+        </p>
+        <bd-header
+          heading-level="h3"
+          title="Bitdefender Total Security"
+          subtitle="Complete real-time data protection"
+          description="Award-winning cybersecurity for all your devices."
+          product-id="ts" devices="5" subscription="1">
+          <img slot="header-picture" src="/images/bd-header-img.jpg" alt="Product screenshot" />
+        </bd-header>
+      </div>
+    </div>
+  `
+};
+
+export const CtaCopy = {
+  name      : 'Design copy & a live secondary',
+  parameters: {
+    docs: {
+      description: {
+        story: `Two headers, same component. **Top** is the default: \`Buy now\` /
+\`View more plans\`, and the secondary has no \`href\`. **Bottom** sets the strings
+Header / v2 actually reads and gives the secondary somewhere to go.
+
+Inspect the two secondary buttons and the difference is not the words — the top one
+renders \`<a>\` with **no href attribute at all**, because \`bd-button-link\` drops it
+when the prop is empty. That anchor is not focusable, does not appear in a screen
+reader's list of links, and does nothing when clicked. It has been that way since the
+component was written, and it is what \`cta-secondary-href\` is for.
+
+The primary needs no href either way: it carries \`buyLink\`, so
+\`@repobit/dex-store\` injects the buy URL at runtime — which is also why there is no
+\`cta-href\` prop to match the label one.
+
+**Careful reading this page, though: in Storybook BOTH primaries are inert too**, for
+the same reason the price zones are empty here — there is no store to inject anything.
+Measured on this story: all three hrefless anchors refuse focus and match neither
+\`a[href]\` nor \`:enabled\`, while the one with \`cta-secondary-href\` takes focus
+normally. On a real page the primary gets its href from the store and the secondary
+still does not, unless you set it.
+
+Accessible names come from the visible text now rather than from a \`label\` attribute —
+measured here as "Buy now", "View more plans", "Get Protection" and "Start your 30-day
+trial". Passing both, as this component used to, gave the anchor an \`aria-label\`
+duplicating its own content.`
+      }
+    }
+  },
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:var(--spacing-64)">
+      <div>
+        <p style="margin:0 0 var(--spacing-8); font:500 12px/1.4 var(--typography-fontFamily-sans);
+                  color:var(--color-text-muted)">
+          defaults — and the secondary CTA has no destination
+        </p>
+        <bd-header
+          title="Bitdefender Total Security"
+          subtitle="Complete real-time data protection"
+          description="Award-winning cybersecurity for all your devices."
+          product-id="ts" devices="5" subscription="1">
+          <img slot="header-picture" src="/images/bd-header-img.jpg" alt="Product screenshot" />
+        </bd-header>
+      </div>
+      <div>
+        <p style="margin:0 0 var(--spacing-8); font:500 12px/1.4 var(--typography-fontFamily-sans);
+                  color:var(--color-text-muted)">
+          the design's own copy, and a secondary that navigates
+        </p>
+        <bd-header
+          title="Bitdefender Ultimate Security"
+          subtitle="Complete real-time data protection"
+          description="Award-winning cybersecurity for all your devices."
+          cta-label="Get Protection"
+          cta-secondary-label="Start your 30-day trial"
+          cta-secondary-href="#trial"
+          product-id="ts" devices="5" subscription="1">
+          <img slot="header-picture" src="/images/bd-header-img.jpg" alt="Product screenshot" />
+        </bd-header>
+      </div>
+    </div>
+  `
+};
+
+export const BrandSignature = {
+  name      : 'Brand Signature & Scrim',
+  parameters: {
+    docs: {
+      description: {
+        story: `The two hardest grounds the mark has to survive, side by side.
+
+**Left** is the real product photo. **Right** is a deliberately pale panel
+standing in for a light image — no asset in the package is bright enough to be
+the worst case, and the worst case is the one worth showing, because it is the
+one that decided the colour. A bright brand blue cannot serve here at all:
+white on \`--color-blue-500\` is **4.53:1 solid**, so no partial coverage of it
+can ever reach the minimum. \`--color-blue-950\` at 60% holds white above 4.5:1
+over any image including a white one.
+
+Measured against the photo on the left: worst neighbourhood **8.64:1**, nothing
+under 4.5. With the scrim removed the same crop measured **1.00:1**, with 33.5%
+of the mark's area under the 3:1 WCAG 1.4.11 asks of a non-text graphic — so
+before this the mark was legible by luck of the crop.
+
+The band's geometry is derived rather than tuned: it is 48 + 112 tall
+(measured: 160px), where 48 is the mark's own box — a \`--spacing-24\` inset
+plus the 24px the artwork is drawn at — so the 60% plateau stop at 70% lands
+exactly on the mark's top edge. The arithmetic and the one case it does not
+hold — a root font size *below* 16px — are written out in \`header.css.js\`.
+
+Both headers here are the full chosen configuration, so this story doubles as
+the reference for the type scale and the 16/8/8 rhythm described above.`
+      }
+    }
+  },
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:var(--spacing-64);">
+      <bd-header
+        title="Bitdefender Total Security"
+        subtitle="Complete protection for all your devices"
+        description="Award-winning security for Windows, macOS, Android and iOS."
+        product-id="ts" devices="5" subscription="1"
+      >
+        <img slot="header-picture" src="/images/bd-header-img.jpg" alt="Total Security" />
+      </bd-header>
+
+      <bd-header
+        title="Bitdefender Total Security"
+        subtitle="The same mark on a pale image"
+        description="The stand-in panel on the right is as light as an image can get."
+        product-id="ts" devices="5" subscription="1"
+      >
+        <div
+          slot="header-picture"
+          role="presentation"
+          style="
+            width: 100%;
+            aspect-ratio: 613 / 456;
+            background: linear-gradient(
+              140deg,
+              var(--color-neutral-0),
+              var(--color-blue-100) 55%,
+              var(--color-neutral-0)
+            );
+          "
+        ></div>
+      </bd-header>
+    </div>
+  `
+};
+
+/* ---------------------------------------------------------------------------
+   THE TARGET REFERENCE.
+
+   This is the one story in the file that is NOT bd-header. It is Figma
+   `Header / v2` (node 340:4) drawn with this package's atoms and filled with
+   the file's own dummy content, so a developer can see what the component is
+   meant to become rather than read a description of it.
+
+   IT BORROWS THE COMPONENT'S STYLESHEET. headerCSS is injected verbatim, so
+   every gap, every type role and the scrim geometry come from the same source
+   the component uses and cannot drift from it. Exactly three declarations do
+   not survive the move out of shadow DOM, and they are restated below with
+   that reason attached: :host and two ::slotted() rules. That is also the
+   point the story is making -- the delta between this and bd-header is MARKUP,
+   not styling.
+
+   THE CONTENT IS COPIED, NOT INVENTED. Every string is Figma's, read off the
+   node rather than retyped: "Bitdefender" is the fixed brand line and
+   "Ultimate Security" is the productName property's default, which is why the
+   name is two lines and where the split falls. */
+const FIGMA = {
+  brand      : 'Bitdefender',
+  product    : 'Ultimate Security',
+  valueProp  : 'Your Ultimate Digital Protection',
+  description: 'Award-winning protection against digital threats, including '
+    + 'advanced scams, with unlimited VPN for private browsing, password '
+    + 'manager and digital identity protection.',
+  fullPrice     : '$159.99',
+  discount      : '44% OFF',
+  finalPrice    : '$89.99',
+  ctaPrimary    : 'Get Protection',
+  ctaSecondary  : 'Start your 30-day trial',
+  disclaimerTop : 'Works on: Windows® | macOS® | Android™ | iOS®.',
+  disclaimerNext: 'First year price. Sales tax included. See Terms of Use below.'
+};
+
+export const IntendedDesign = {
+  name      : 'Intended design (Figma reference)',
+  parameters: {
+    controls: { disable: true },
+    docs    : {
+      description: {
+        story: `**This is the target, not the component.** Every other story on
+this page renders \`<bd-header>\`; this one is Figma \`Header / v2\`
+(node \`340:4\`, 1290 × 566) rebuilt from this package's atoms and filled with
+the Figma file's own dummy content. Build against it.
+
+It is **not** a second implementation to copy markup from. It injects
+\`headerCSS\` — the component's real stylesheet — so the spacing, the type
+roles and the scrim all come from the same source \`bd-header\` uses and cannot
+drift from it. Only three declarations do not survive the move out of shadow
+DOM, and the story restates them: \`:host\` (the section's ground and its 16px
+padding) and two \`::slotted()\` rules (the picture's cover fill, the disclaimer
+link's ink). **So the delta below is markup, not styling** — the type scale and
+the 16/8/8 rhythm already match, and were measured doing so.
+
+### What \`bd-header\` still cannot render
+
+| intended | \`bd-header\` today | what it needs |
+|---|---|---|
+| The product name on **two lines** — "Bitdefender" fixed, "Ultimate Security" variable | one \`title\` string, one line | **decided 2026-09-17: nothing, here.** The page builds it. \`title\` stays one string and one line; a page that needs the two-line kicker composes it from the atoms against this story, which is what this story is for. See below |
+| CTA labels "Get Protection" / "Start your 30-day trial" | \`cta-label\` and \`cta-secondary-label\`, defaulting to "Buy now" / "View more plans" | **the page sets them, as of 2026-09-17.** Which words sell a subscription is still funnel copy and still not ours — but it is now a value in markup rather than a literal in this file |
+| \`$159.99\` / \`44% OFF\` / \`$89.99\` visible | store-driven, so empty in Storybook | **nothing.** This is correct behaviour — the reference hardcodes them only so the price block's layout is visible here |
+| the disclaimer as one two-line paragraph | two \`bd-p\` blocks behind three slots | **nothing.** Measured identical: 8px from the CTA row, 0 between the lines |
+
+The Figma component exposes seven properties (\`productName\`, \`subtitle\`,
+\`description\`, \`fullPrice\`, \`finalPrice\`, \`disclaimer\`, and \`media\` as an
+instance swap), and the "Bitdefender" line is deliberately not one of them — it
+is the same word on every product, so the design holds it fixed and lets only
+the rest of the name vary.
+
+### Where each of the two gaps landed
+
+**The two-line product name is the page's, not the component's.** Decided
+2026-09-17. \`bd-header\` keeps one \`title\` string, because the split is
+structural rather than textual — Figma has a fixed brand layer and a variable
+\`productName\`, and no single escaped string reproduces that — and the honest
+place to reproduce structure is markup the page owns. So this story is the
+deliverable, not an interim sketch: it shows the two text nodes in a zero-gap
+vertical stack, with the real \`headerCSS\` behind them, which is what a page
+implementing the two-line kicker builds against. If it later turns out every
+consumer wants it, that is the moment to give \`bd-header\` the second prop —
+not before, because an API change with live consumers should be paid for by
+more than one page.
+
+**The CTA labels are the page's now**, which is as far as this package can
+take them. \`cta-label\` and \`cta-secondary-label\` default to the strings
+this component always rendered, so nothing changes for a consumer who says
+nothing, and the copy owner's answer no longer needs a code change to land.
+Props rather than slots: a label is a plain string with no markup, which is
+what \`title\` and \`subtitle\` already are, and props appear in the manifest a
+page generator reads while slots do not.
+
+**And doing that turned up a dead control.** The secondary CTA has never had a
+destination — \`bd-button-link\` drops the \`href\` attribute when it is empty,
+so it renders an \`<a>\` with no href: not focusable, not a link to a screen
+reader, nothing on click. The primary is fine, because \`buyLink\` has the store
+inject the buy URL. So \`cta-secondary-href\` has no default and wants setting;
+*Design copy & a live secondary* below shows both.
+
+**And the heading level is no longer a gap.** It was a third one, unlisted
+above because it is not visible in a screenshot: the headline's \`as="h1"\` was
+hardcoded, so a page could not place the hero in its own outline. It is the
+\`heading-level\` prop as of 2026-09-17 — see the heading-structure section in
+this component's docs. Same decision as the product name, reached the other
+way: the page owns the outline, so the page gets the say.`
+      }
+    }
+  },
+  render: () => html`
+    <style>
+      ${ensembleCSS.cssText}
+      ${headerCSS.cssText}
+
+      /* (1) stands in for :host, which cannot match in light DOM. The two
+         declarations are headerCSS's own -- the section's ground and the 16px
+         row padding the height study bought. */
+      .bd-header-reference {
+        display: block;
+        background: var(--color-surface-default);
+        padding-block: var(--spacing-16);
+      }
+
+      /* (2) stands in for ::slotted([slot="header-picture"]). Same four
+         declarations; the picture is a real child here rather than slotted,
+         so the shadow pseudo-element never matches it. */
+      .bd-header-reference .bd-header-image {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+      }
+
+      /* (3) stands in for ::slotted([slot="disclaimer-bottom-link"]). */
+      .bd-header-reference .bd-disclaimer-bottom a {
+        color: var(--color-text-primary);
+        text-decoration: underline;
+      }
+
+      /* NOT a stand-in -- the one thing the reference draws that the component
+         has no markup for yet, and the whole reason this story exists. Figma
+         stacks the product name as two text nodes in a zero-gap vertical
+         frame, which is two block lines on the kicker's own 1.3 leading. The
+         type comes from .bd-product-name in headerCSS above; these spans only
+         make the break. */
+      .bd-header-reference .bd-product-name span {
+        display: block;
+      }
+    </style>
+
+    <div class="bd-header-reference">
+      <div class="bd-ensemble bd-container">
+        <div class="bd-header-left">
+          <p class="bd-product-name">
+            <span>${FIGMA.brand}</span><span>${FIGMA.product}</span>
+          </p>
+          <bd-h as="h1" class="bd-value-prop">${FIGMA.valueProp}</bd-h>
+          <bd-p variant="regular" class="bd-description">${FIGMA.description}</bd-p>
+
+          <div class="bd-price-zone-top">
+            <bd-p variant="regular" font-weight="medium" class="original-price">
+              <s>${FIGMA.fullPrice}</s>
+            </bd-p>
+            <bd-badge tone="success" variant="fill" size="lg" class="bd-discount"
+              >${FIGMA.discount}</bd-badge
+            >
+          </div>
+
+          <span class="bd-price-zone-final">${FIGMA.finalPrice}</span>
+
+          <div class="bd-cta">
+            <bd-button-link label=${FIGMA.ctaPrimary} variant="accent" size="lg">
+              ${FIGMA.ctaPrimary}
+            </bd-button-link>
+            <bd-button-link label=${FIGMA.ctaSecondary} variant="tertiary" size="lg">
+              ${FIGMA.ctaSecondary}
+            </bd-button-link>
+          </div>
+
+          <bd-p variant="xsmall" class="bd-disclaimer-top">${FIGMA.disclaimerTop}</bd-p>
+          <bd-p variant="xsmall" class="bd-disclaimer-bottom"
+            >${FIGMA.disclaimerNext}</bd-p
+          >
+        </div>
+
+        <div class="bd-header-right">
+          <div class="bd-header-image-wrapper">
+            <img class="bd-header-image" src="/images/bd-header-img.jpg" alt="" />
+            <div class="bd-header-scrim" aria-hidden="true"></div>
+            <bd-brand-signature-icon class="bd-header-signature"></bd-brand-signature-icon>
+          </div>
+        </div>
+      </div>
+    </div>
+  `
+};