@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/components/header/header.css.js

@@ -1,57 +1,134 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   :host {
     display: block;
-    background: white;
-    --bd-accesibility-focus: var(--color-blue-500);
-    padding-top: 32px;
-    padding-bottom: 32px;
-  }
-
-  a:focus-visible {
-    outline: var(--spacing-2) solid var(--bd-accesibility-focus);
-    outline-offset: var(--spacing-2);
-    border-radius: var(--space-2xs);
-  }
-  a {
-    color: #000000 !important;
-  }
-  ::slotted(a),
-  ::slotted(*) a {
-    color: #000000 !important;
-  }
-
-  ::slotted([slot="disclaimer-bottom"]) a {
-    color: #000000 !important;
-  }
-
-  ::slotted([slot="header-image"]) {
+    /* --color-surface-default, the role, not --color-neutral-0, the primitive
+       it resolves to. Same value; the category is the point, and CLAUDE.md's
+       "same primitive value is not same semantic meaning" section exists for
+       exactly this. Found by check:color-coverage once the background shorthand came into
+       its scope -- it had been invisible because the check counted
+       background-color: and this package almost never writes that. */
+    background: var(--color-surface-default);
+    /* --spacing-16, and the number changed as well as the spelling. It was a
+       bare 32px on no scale; Header / v2's chosen configuration pads the hero
+       row 16 top and bottom. That 8px per side is not cosmetic -- it is the
+       line of headroom the height study bought to get the header under 600,
+       and the findings note says so outright: "drop the frame padding 24 -> 16,
+       which lands 562px and leaves 38px". The text column takes its own 24
+       back below (.bd-header-left), so the copy still breathes; what got
+       thinner is the band around the media panel, which needed nothing. */
+    padding-top: var(--spacing-16);
+    padding-bottom: var(--spacing-16);
+  }
+
+  /* ::slotted, not a bare element selector. This header renders no anchor of its own -- every
+     link arrives through a slot -- so a descendant selector never reached one,
+     and slotted links fell back to the browser's own ring. The colour rule two
+     rules down already had this right. ::slotted only reaches a directly
+     slotted anchor, which is what the disclaimer link is; an anchor nested
+     inside a slotted wrapper is the consuming page's to style.
+
+     The pseudo-class goes INSIDE the parentheses. ::slotted() takes a compound
+     selector as its argument, so "::slotted(a):focus-visible" is not a valid
+     selector -- the parser drops the whole rule silently, which is the same
+     failure mode as the bare descendant selector this replaced. */
+  ::slotted(a:focus-visible) {
+    /* the one focus ring — see Foundations/Focus */
+    outline: none;
+    box-shadow: var(--focus-outline-primary);
+    border-radius: var(--focus-outline-radius);
+  }
+  /* ::slotted(a) only. A bare element rule stood beside this one and matched
+     nothing: this header renders no anchor of its own, which is the same
+     reason its focus rule had to move to ::slotted in P5G.1. ::slotted(*) a
+     went too -- ::slotted() must be the last compound in a selector, so a
+     descendant after it never matches either. An anchor nested inside a
+     slotted wrapper is the consuming page's to colour. */
+  ::slotted(a) {
+    color: var(--color-text-primary) !important;
+  }
+
+  /* ::slotted([slot="disclaimer-bottom"]) a stood here and could never match.
+     There is no disclaimer-bottom slot: header.js renders
+     disclaimer-bottom-text-start, disclaimer-bottom-link and
+     disclaimer-bottom-text-end. The link is handled by
+     ::slotted([slot="disclaimer-bottom-link"]) at the end of this sheet, which
+     is the rule that actually applies -- and a descendant after ::slotted()
+     never matches anyway, since ::slotted() must be the last compound in a
+     selector, the same reason already recorded for ::slotted(*) a below. */
+
+  /* header-picture, which is the slot header.js renders. This rule was written
+     for [slot="header-image"] and so has never matched anything: the product
+     image was left entirely unsized, rendering at its natural 3500x2338 and
+     cropped to whatever fitted by the wrapper's overflow: hidden. At 375 that
+     showed a 124px-wide vertical slice of a 3500px photograph.
+
+     Four of the five slot names this stylesheet targets do not exist --
+     header-image, right, extra-content and disclaimer-bottom -- against the
+     slots header.js renders: disclaimer-top,
+     disclaimer-bottom-text-start/-link/-text-end and header-picture. Only the
+     one fixed here is load-bearing for layout; the rest are in the report. */
+  /* A REAL COVER FILL, not a zoom. This said height: auto with
+     transform: scale(1.35) translateY(-7%), which is how a wide photograph was
+     made to fill a tall box before the column stretched: blow it up 135%,
+     shove it up 7%, and let the wrapper's overflow: hidden crop whatever
+     misses. Two things are wrong with that. It throws away a third of the
+     image's resolution for nothing -- object-fit: cover already crops, and
+     crops without magnifying -- and the crop it lands on is a magic pair of
+     numbers that moves with the viewport, so which part of the photo a
+     consumer sees was never a decision anyone made.
+     .
+     height: 100% is available because .bd-container stretches both columns to
+     the taller one, so the wrapper has a definite height to fill. Header / v2
+     shows a plain 613-wide media panel filled edge to edge with no transform,
+     which is what this now is.
+     .
+     It also matters to the scrim: the band and the mark are positioned against
+     the WRAPPER, while a transformed image is not where the wrapper is. The
+     mark sat 24px from the wrapper's corner and the image's own corner was
+     somewhere else. */
+  ::slotted([slot="header-picture"]) {
     width: 100%;
-    height: auto;
+    height: 100%;
     object-fit: cover;
-    transform: scale(1.35) translateY(-7%);
     display: block;
-    z-index: 1;
+    z-index: var(--z-base);
     position: relative;
-    border-radius: var(--spacing-20);
+    border-radius: var(--radius-2xl);
   }
 
   .bd-container {
     display: grid;
-    grid-template-columns: 1fr 1fr;
-    align-items: center;
-    gap: 30px;
-    padding: 0 240px;
-    margin: 0 auto;
+    /* minmax(0, 1fr), not 1fr: a bare 1fr floors each column at its own
+       min-content width, which held .bd-header-left at 201px however narrow
+       the screen got and pushed the right-hand column 29px past a 320px
+       viewport. The columns still share the space equally; they are simply
+       allowed to go below their content's natural width, which is what lets
+       the text inside wrap instead of the layout overflowing. */
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    /* --spacing-64, which is the 64px gap between the two 613px columns in
+       Header / v2. It was 30px: on no spacing step at all (28 and 32 are the
+       neighbours) and 34px short of the design. */
+    gap: var(--spacing-64);
+    /* the page column (bd-ensemble), not a 240px gutter: a fixed gutter made the
+       hero the one section whose content width depended on the viewport --
+       960 wide at 1440, 1440 wide at 1920 -- while every other module capped
+       itself */
     align-items: stretch;
   }
 
-  bd-button {
-    font-size: var(--heading-xxsmall) !important;
-    font-family: var(--typography-fontFamily-sans) !important;
-    font-weight: var(--typography-fontWeight-semibold) !important;
+  /* The content column's own inset, and the second half of the padding change
+     on :host. Header / v2 nests a 24-padded content frame inside a 16-padded
+     row, so the copy sits 40 from the top of the section while the media panel
+     sits 16 -- the image is meant to be the taller of the two. Before this the
+     column had no padding and .bd-product-name carried a 16px top margin
+     instead, which put the title 48 down and the image 32. */
+  .bd-header-left {
+    padding-block: var(--spacing-24);
   }
+
   .bd-header-left,
   .bd-header-right {
     flex: 1;
@@ -65,88 +142,248 @@ export default css`
     position: relative;
   }
 
+  /* .bd-header-image is declared twice in this sheet, and this is the first of
+     the two -- kept for the border-radius, the stacking context and the
+     position, which the second does not set. Its width/height/object-fit/
+     display went, because the second rule sets all four and wins on order, so
+     this copy said height: auto while the rendered image measured 100%. Two
+     rules for one class disagreeing about the same property is worth fixing at
+     the point one of them starts lying. */
   .bd-header-image {
-    width: 100%;
-    height: auto;
-    object-fit: cover;
-    display: block;
-    border-radius: var(--spacing-20);
+    border-radius: var(--radius-2xl);
     position: relative;
-    z-index: 1;
-  }
+    z-index: var(--z-base);
+  }
+  /* ---- the vertical rhythm of the content column --------------------------
+     Header / v2's chosen configuration nests four auto-layout frames, and the
+     gaps below are theirs read top to bottom:
+
+       content  gap 16   product-name -> body
+       body     gap 16   copy -> price -> actions
+       copy     gap  8   headline -> description
+       actions  gap  8   CTA row -> disclaimer
+
+     The 16/8/8 triple is not arbitrary and is not a rhythm anyone chose for
+     its own sake -- it is variant I from the height study, the one
+     configuration that measured the same 578px in all four languages tested.
+     Tightening copy and actions to 8 is where most of the 94px came from.
+
+     These are margins rather than a flex/grid gap because the column is a
+     plain block flow and the atoms carry their own flow margins; a gap would
+     mean also cancelling those. The !important is inherited from the rules
+     these replace, and it earns its keep on exactly one of them: bd-h's inner
+     element keeps the UA heading margins, which are not otherwise reachable
+     from out here. */
+  /* The kicker. It is a <p> rather than a bd-h -- see the note in header.js --
+     so this is the one block of text in this component whose type the
+     stylesheet has to declare, and it declares the ROLE rather than four
+     primitives: heading-h4 is 2xl / semibold / 130 / normal tracking, which is
+     what Header / v2 gives the product name.
+
+     A heading role on a non-heading element is the right way round, not a
+     compromise. CLAUDE.md's rule is to name the job and let the role decide
+     the value, and the job here is "the most prominent label on the section" --
+     there is no 24px label role, and picking body-lead at 20 because it is
+     nearer the body would be choosing by number. What the element is NOT is a
+     heading, and that is settled by the tag, not by the role's name.
+
+     text/brand is declared here rather than passed as bd-h's color="primary"
+     because there is no atom in the way any more, so the declaration lands on
+     the rendered element directly.
+
+     No !important. The two rules this replaces both carried it, inherited from
+     an older version of the file; on a <p> the only thing to beat is the UA
+     margin, which a plain declaration already does. The bd-h below still needs
+     it, because its inner element keeps the UA heading margins and they are
+     not otherwise reachable from out here. */
   .bd-product-name {
-    color: var(--color-blue-500);
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-fontWeight-semibold);
-    font-size: var(--typography-fontSize-3xl);
-    letter-spacing: var(--spacing-0);
-    margin-top: var(--spacing-16) !important;
-    margin-bottom: var(--spacing-8) !important;
+    font-size: var(--typography-heading-h4-fontSize);
+    font-weight: var(--typography-heading-h4-fontWeight);
+    line-height: var(--typography-heading-h4-lineHeight);
+    letter-spacing: var(--typography-heading-h4-letterSpacing);
+    font-family: var(--typography-heading-h4-fontFamily);
+    color: var(--color-text-brand);
+    margin-top: var(--spacing-0);
+    margin-bottom: var(--spacing-16);
   }
 
+  /* The headline's type does NOT step down on narrow viewports, and that is a
+     limit rather than a decision. bd-h's type lives on its inner element
+     inside its shadow root, so a font-size out here is inert
+     (scripts/atom-inert-properties.json), and neither bd-h nor bd-p carries a
+     media query -- no atom in this package changes its type with the viewport.
+     Measured, the 48px headline runs two lines down to 500px, three at 375 and
+     four at 320, where the section reaches 1066px.
+     .
+     Two ways out, both bigger than this change. Give bd-h responsive roles, or
+     switch visual-level from JS the way bd-footer's _isMobile already reads the
+     viewport through matchesBelow(). The second is the package's sanctioned
+     escape hatch and would need a step to move to: heading-h2 is 36/bold, which
+     is also the final price's role, so at 36 the headline and the price would
+     be the same size and the hierarchy the semibold kicker was added to sharpen
+     would flatten. That is a design question, not a CSS one. */
   .bd-value-prop {
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-fontWeight-bold);
-    font-size: var(--heading-xxlarge);
-    color: #000000;
-    letter-spacing: var(--spacing-0);
-    margin: var(--spacing-0) var(--spacing-0) !important;
+    margin: var(--spacing-0) !important;
   }
 
   .bd-description {
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-body-large-fontWeight);
-    font-size: var(--spacing-18);
-    color: #000000;
+    /* LIVE, not inert: scripts/atom-inert-properties.json records colour on a
+       bd-p host as reaching the text, unlike the five type axes. */
+    color: var(--color-text-primary);
     margin-top: var(--spacing-8) !important;
     margin-bottom: var(--spacing-0) !important;
   }
 
   .bd-price-zone-top {
     display: flex;
+    /* 8, which is the price-was frame's gap between the struck price and the
+       discount badge. */
     gap: var(--spacing-8);
     align-items: center;
-    margin-top: var(--spacing-32);
-  }
-
-  .bd-full-price {
-    text-decoration: line-through;
-    color: #000000;
-    font-size: var(--spacing-18);
-    font-family: var(--typography-fontFamily-sans);
+    /* the body frame's gap, 16. It was 32 -- the as-built spacing, twice the
+       chosen one. */
+    margin-top: var(--spacing-16);
   }
 
-  .bd-discount {
-    background: #c3f4d4;
-    color: #0b6a26;
-    padding: var(--spacing-4) var(--spacing-14);
-    border-radius: var(--spacing-14);
-    font-size: var(--spacing-16);
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-fontWeight-semibold);
-  }
+  /* No rule for the struck price. It is now <s> inside <bd-p variant="small">
+     with the class .original-price, matching pricing-card.js and
+     pricing-card-pricing.js, and every declaration this rule carried is dead or
+     redundant against that:
+
+       font-size and font-family -- INERT on a bd-p host, per
+         scripts/atom-inert-properties.json. body-small answers the size.
+       text-decoration -- <s> carries the strike natively, and a host
+         declaration does not cross into the atom's shadow tree anyway: the
+         inner <p> measures text-decoration: none in the pricing cards, which
+         is where the same rule has been dead all along.
+       color -- bd-p's own :host already sets --color-text-primary, the
+         identical token this declared.
+
+     So the struck price now resolves through a role rather than a primitive,
+     and the element finally says what it is. */
+
+  /* The one thing this rule still has to do, and it is not typography. bd-p's
+     inner <p> carries margin-bottom: var(--spacing-16) for paragraph flow, and
+     a bd-p in a flex row is a flex item, so it establishes a block formatting
+     context and that margin cannot collapse through the host -- it is trapped
+     inside the host's box. Measured: the host renders 37px where its text is
+     21px, which grew this zone from 28px to 37px and shifted the struck price
+     6px against the discount badge beside it.
+     .
+     The pricing cards do not show this because both of their siblings are bd-p
+     and the offset cancels; here the badge is a bare span, so it does not.
+     bd-p exposes padding but no margin, so the margin cannot be reached from
+     outside -- this cancels it with the same token it is set from, which keeps
+     the two in step if the token moves. An atom-level way to say "no flow
+     margin" would be better and is not this change's to add. */
+  .original-price {
+    margin-bottom: calc(-1 * var(--spacing-16));
+    /* text/muted, which is what Header / v2 gives the struck price. bd-p's own
+       :host sets text/primary; colour on the host is LIVE (see the note on
+       .bd-description), so this reaches it. A former price is the one number
+       on this card that is deliberately not being offered -- primary ink gave
+       it the same weight in the eye as the price you can actually pay.
+       .
+       The element also moved from variant="small" to "regular": the design
+       reads 16px here, and small is 14. */
+    color: var(--color-text-muted);
+  }
+
+  /* .bd-discount is a bd-badge now, so there is nothing left to declare. The
+     rule that stood here painted --color-green-100 behind --color-text-success
+     at 16px semibold in a --radius-xl box, with two "no role:" markers saying
+     it was a hand-rolled bd-badge tone="success" and that whether it should be
+     one was tracked in plans/foundation-plan.md. It should, it is, and the
+     tracked question is answered.
+     .
+     Worth knowing it was not the same badge: green-100 behind success ink is
+     the atom's shade variant, and Header / v2 asks for fill -- a saturated
+     status/success/fill ground with status/success/on-fill ink. So this was a
+     tint where the design wants a solid, at the wrong size, in the wrong
+     corner radius. The class is kept only as a positioning hook. */
 
   .bd-price-zone-final {
     display: block;
-    font-size: var(--display-large-mobile);
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-fontWeight-bold);
+    /* THE 44px EXCEPTION IS RETIRED. This carried a recorded "no token:" note
+       saying 44 was off the type scale -- 4xl is 36, 5xl is 48 -- and that
+       adding the step would be its own decision. It never needed one: Header /
+       v2 sets the final price at 36 Bold on a 1.25 leading, which is
+       heading-h2 exactly (4xl / bold / tight / normal tracking) on all four
+       axes. The literal was standing in for a size the design does not ask
+       for, left behind when --display-large-mobile was deleted.
+       .
+       The role rather than the four primitives, so the size and the weight
+       cannot drift apart, and so the "no role:" marker that sat below the
+       font-weight -- which only existed because the size could not resolve --
+       goes with it. */
+    font-size: var(--typography-heading-h2-fontSize);
+    font-weight: var(--typography-heading-h2-fontWeight);
+    line-height: var(--typography-heading-h2-lineHeight);
+    letter-spacing: var(--typography-heading-h2-letterSpacing);
+    font-family: var(--typography-heading-h2-fontFamily);
+    /* the body frame's gap to the actions frame below, 16. */
     margin-bottom: var(--spacing-16);
   }
 
   .bd-cta {
     display: flex;
     gap: var(--spacing-16);
-  }
-
+    /* WRAP, because the alternative is not "stays on one line" -- it is
+       "shrinks". Flex items shrink by default, and measured at a 312px column
+       the two buttons went from 183/246 to 150/146 and both labels broke over
+       three lines inside a box padded for one. The height study had already
+       priced the wrap: the row is 446 of the design's 613, so 37% headroom,
+       and wrapping costs about 71px. Paying 71px beats crushing the controls,
+       and it happens on its own at whatever width runs out rather than at a
+       breakpoint somebody picks. */
+    flex-wrap: wrap;
+  }
+
+  /* ---- the two disclaimer lines -------------------------------------------
+     Header / v2 draws these as ONE text node of two lines at 12 Regular on a
+     1.5 leading in text/muted. The code keeps them as two bd-p blocks, because
+     that is the slot API consumers already write against -- disclaimer-top,
+     and the three-part disclaimer-bottom run -- and collapsing them into one
+     would break every page that fills them.
+
+     So the change is the type, and both blocks make the same two moves. The
+     size now comes from the ATOM: variant="xsmall" is bd-p's 12px step, where
+     these were variant="small" (14px) with a font-size and a font-weight
+     declared out here on the host -- both INERT per
+     scripts/atom-inert-properties.json, since bd-p sets all five type axes on
+     its inner element. So the rendered size was 14 and the declarations
+     claiming otherwise did nothing. Two dead declarations and a wrong size, in
+     a rule that looked like it was in control of both.
+
+     One divergence, recorded rather than copied: xsmall's leading is 1.45
+     (body-small's) where the file says 150%. Figma binds fontSize to a
+     variable here and leaves lineHeight raw, so 150% is an unbound number
+     rather than a token -- and CLAUDE.md's rule is to read the intent and
+     spell it with the role, not to borrow the file's value. 17.4px versus 18. */
   .bd-disclaimer-top {
     display: block;
-    margin-top: var(--spacing-16);
-    margin-bottom: var(--spacing-8);
-    font-size: var(--typography-body-small-fontSize);
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-body-large-fontWeight);
-    color: #000000;
+    /* the actions frame's gap, 8 -- down from 16. */
+    margin-top: var(--spacing-8);
+    /* A NEGATIVE 16, not 0. Setting the host's margin to zero was not enough
+       and measuring showed it: the two lines still sat 16px apart. bd-p's
+       inner <p> carries margin-bottom: var(--spacing-16) for paragraph flow,
+       the host has no padding or border to stop it, so it collapses straight
+       through the host's bottom edge -- a zero on the host cancels the host's
+       own margin and leaves the atom's untouched.
+       .
+       Same cancellation, same reason and the same token as .original-price
+       above, which hit this in a flex row where the margin could not collapse
+       at all. bd-p exposes padding but no margin, so there is no way to reach
+       it from outside; using the same token it is set from keeps the two in
+       step if that token moves. An atom-level "no flow margin" would be better
+       and is not this change's to add.
+       .
+       Zero is right because the design has these as two consecutive lines of
+       ONE paragraph -- Header / v2 draws a single 12/1.45 text node of two
+       lines -- rather than two blocks with air between them. Measured after:
+       8px from the CTA row, 0 between the lines. */
+    margin-bottom: calc(-1 * var(--spacing-16));
+    color: var(--color-text-muted);
   }
   .bd-header-image-wrapper {
     position: relative;
@@ -155,123 +392,365 @@ export default css`
     display: flex;
     justify-content: center;
     overflow: hidden;
-    border-radius: 20px;
+    border-radius: var(--radius-2xl);
   }
 
+  /* The same correction as ::slotted([slot="header-picture"]) above, on the
+     internal class. Kept in step deliberately: whichever of the two a page
+     ends up using, the image fills the panel the same way. */
   .bd-header-image {
     display: block;
     width: 100%;
-    height: auto;
+    height: 100%;
     object-fit: cover;
-    transform: scale(1.35) translateY(-7%);
   }
 
-  .bd-header-watermark {
+  /* ---- THE BRAND SIGNATURE AND ITS SCRIM ---------------------------------
+     Figma: Header / v2, media-panel, children bottom-to-top
+     media -> scrim -> brand-signature. Both rules below are that stack.
+
+     WHAT WAS HERE BEFORE. A .bd-header-watermark div holding the words
+     "Trusted. Always." at 32px/700 in text-inverse, 16px from the corner, with
+     a 2px backdrop-blur behind the run. Three things were wrong with it and
+     only one was cosmetic: it was type doing a mark's job (CLAUDE.md's icon
+     rule -- it inherited the text stack, had no viewBox, and changed shape
+     with the font), it was English hardcoded into a stylesheet's neighbour,
+     and it clipped -- measured at 320px the 133px run sat in a 96px column
+     inside an overflow:hidden wrapper and read "rusted. lways.". The mark
+     replaces all three: it is our own artwork, it says nothing that needs
+     translating, and it is 182px wide, which is what the media-panel column
+     has to be able to hold.
+
+     WHY THERE IS A SCRIM AT ALL. The mark is white and the image underneath
+     is the consumer's. Rendered against a real photo with no scrim the worst
+     pixel-neighbourhood under the mark measured 1.00:1, with 33.5% of its area
+     under the 3:1 that WCAG 1.4.11 asks of a non-text graphic -- so the mark
+     was legible by luck of the crop and nothing else.
+
+     WHY blue-950 AND NOT THE BRAND BLUE. A bright brand blue cannot do this
+     job: white on --color-blue-500 is 4.53:1 SOLID, so no partial coverage of
+     it can ever guarantee the minimum. blue-950 at 60% holds white above
+     4.5:1 over any image including a white one, which is the only version of
+     this that is safe for an image nobody has seen. Measured over the test
+     photo: worst 8.64:1, nothing under 4.5.
+
+     THE GEOMETRY IS DERIVED, NOT DRAWN. The band is 48 + 112: 48 is the
+     mark's own box -- a --spacing-24 inset plus the 24px the artwork is drawn
+     at -- and 112 is the fade above it. Because the plateau stop sits at 70%,
+     it lands exactly 48px up from the bottom, which is the mark's top edge, so
+     the mark is inside the flat part of the ramp by construction rather than
+     by a number somebody tuned. That survives a reader enlarging their text:
+     the inset is rem and the artwork is px, so at a 24px root the band is 240
+     with its plateau at 72 and the mark occupies 36-60. It does NOT survive a
+     root SMALLER than 16px -- at 12px the mark's top edge sits about 6px into
+     the ramp, where the scrim is still ~0.52 rather than 0.60. Worth knowing;
+     not worth pinning the inset to px to avoid, since that would stop the
+     corner breathing with the text everywhere else.
+
+     The first stop is the transparent keyword rather than blue-950 at 0%.
+     Gradient interpolation is premultiplied, so that keyword does not fade
+     through grey the way it did before CSS Images 3 -- and color-mix(in srgb,
+     X 0%, transparent) resolves to rgba(0,0,0,0) anyway, which is the thing
+     the old workaround was avoiding. */
+  /* The two lengths everything below is derived from. They live on the
+     wrapper so the scrim and the mark, both its children, read the SAME inset:
+     the mark is positioned by it and the scrim's plateau is sized from it, so
+     they cannot disagree. */
+  .bd-header-image-wrapper {
+    --bd-header-mark-inset: var(--spacing-24);
+    /* the height the artwork is drawn at, and the step the atom defaults to */
+    --bd-header-mark-height: var(--icon-lg-size);
+    --bd-header-scrim-fade: var(--spacing-112);
+    --bd-header-scrim-mid: var(--spacing-40);
+  }
+
+  /* LENGTH STOPS, NOT PERCENTAGES. This was written as percentages of a
+     fixed 160px band -- 0 / 45% / 70% / 100% -- read straight off Figma, and
+     it made the invariant arithmetic rather than structural: the 70% stop
+     landed on the mark's top edge only because 0.3 x 160 happened to equal
+     24 + 24. Measured what that cost at 320px, where the old rules capped the
+     panel at 200px tall: the band was 104% of the panel, so a gradient meant
+     to protect a mark in one corner became a wash over the whole image.
+     .
+     Written as lengths from the bottom the plateau IS the mark's box, by
+     construction, at any size -- so the narrow variant below is two smaller
+     numbers rather than a second set of percentages to re-derive. The stops
+     still resolve to Figma's exactly at desktop: plateau 0-48, 0.22 at 88,
+     zero at 160. */
+  .bd-header-scrim {
+    position: absolute;
+    inset-inline: 0;
+    bottom: 0;
+    height: calc(
+      var(--bd-header-mark-inset) + var(--bd-header-mark-height) +
+        var(--bd-header-scrim-fade)
+    );
+    background: linear-gradient(
+      to top,
+      color-mix(in srgb, var(--color-blue-950) 60%, transparent) 0,
+      color-mix(in srgb, var(--color-blue-950) 60%, transparent)
+        calc(var(--bd-header-mark-inset) + var(--bd-header-mark-height)),
+      color-mix(in srgb, var(--color-blue-950) 22%, transparent)
+        calc(
+          var(--bd-header-mark-inset) + var(--bd-header-mark-height) +
+            var(--bd-header-scrim-mid)
+        ),
+      transparent 100%
+    );
+    z-index: var(--z-raised);
+    pointer-events: none;
+  }
+
+  .bd-header-signature {
     position: absolute;
-    bottom: var(--spacing-16);
-    right: var(--spacing-16);
-    z-index: 2;
-    color: #ffffff;
-    font-size: var(--typography-fontSize-3xl);
-    font-weight: 700;
-    opacity: 1;
-    -webkit-backdrop-filter: blur(2px);
+    /* the same property the scrim sizes its plateau from, so the band cannot
+       stop covering the mark when the inset changes below sm */
+    bottom: var(--bd-header-mark-inset);
+    right: var(--bd-header-mark-inset);
+    z-index: var(--z-raised);
+    color: var(--color-text-inverse);
+    pointer-events: none;
   }
 
-  .bd-header-watermark span {
-    color: #fff;
-    padding: var(--spacing-4) var(--spacing-8);
-    backdrop-filter: blur(2px);
-    -webkit-backdrop-filter: blur(2px);
-    border-radius: var(--spacing-4);
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-fontWeight-bold);
-  }
   .bd-disclaimer-bottom {
     display: block;
-    font-size: var(--typography-body-small-fontSize);
-    font-family: var(--typography-fontFamily-sans);
-    font-weight: var(--typography-body-large-fontWeight);
-    color: #000000;
-    margin-bottom: var(--spacing-16);
-  }
-
-  bd-header a {
-    color: #000000 !important;
-  }
-  ::slotted([slot="right"]) {
-    border-radius: var(--spacing-20);
-    overflow: hidden;
-    max-width: 100%;
-    height: auto;
-  }
-
-  ::slotted([slot="extra-content"]) {
-    margin-top: 1em;
-    display: block;
-  }
-
-  @media (max-width: 1024px) {
+    color: var(--color-text-muted);
+    /* the same cancellation as the rule above, for the same reason -- this is
+       the last block in the column, so the atom's trailing flow margin was
+       adding 16px inside the content frame's own 24px bottom padding. */
+    margin-bottom: calc(-1 * var(--spacing-16));
+  }
+
+  /* A "bd-header a" rule stood here and could never match. It is the bare
+     element rule the ::slotted(a) comment above already describes: this header
+     renders no anchor of its own, and a type selector inside a shadow stylesheet
+     cannot reach the host, let alone the consumer's slotted light DOM. The fix
+     was made once -- ::slotted(a) forty lines up carries the same declaration --
+     and this copy outlived it. Measured before removing: the disclaimer link
+     computes rgb(21,23,25), which is --color-text-primary arriving from the
+     ::slotted rule, so nothing here was load-bearing. */
+  /* ::slotted([slot="right"]) and ::slotted([slot="extra-content"]) are gone.
+     Neither slot exists: header.js renders header-picture, disclaimer-top and
+     the three disclaimer-bottom-* slots, and nothing else. They are two of the
+     four dead slot names the note near the top of this sheet already records,
+     and the copies inside the media queries went when those were rewritten --
+     these were the originals, left behind. extra-content's margin-top: 1em
+     was also the last em literal in the file.
+
+     Recorded rather than silently dropped, so a reader who finds
+     slot="right" in a consumer's markup can learn from this file that it was
+     never supported rather than assume a regression. */
+
+  /* ---- RESPONSIVE ---------------------------------------------------------
+     Three steps, each on the breakpoint scale in shared/token-scales.js, and
+     each one measured rather than guessed. There is no mobile frame in Figma:
+     the height study was run at 1290 only, so every width below that is a
+     decision taken here, and the numbers that drove it are recorded with it.
+
+     WHAT WAS HERE. Three blocks at (max-width: 1024px), below('md') and
+     (max-width: 480px). The first two were mostly inert or wrong:
+
+       flex-direction: column  on .bd-container -- inert. The container is
+         display: grid, and the identical mistake is already recorded forty
+         lines down where below('md') had to fix it with grid-template-columns.
+         So this declaration read as "stacks at 1024" and stacked at nothing.
+       gap: 2em -- an em literal on no scale, and the only live declaration in
+         that block. It was the reason the gap read 32px at exactly 1024 and
+         64px at 1025.
+       width: 100% on two grid items -- redundant; a grid item already fills
+         its track.
+       ::slotted([slot="right"]) -- one of the four slot names this stylesheet
+         targets that header.js does not render. Dead in both blocks.
+
+     So the header's real stacking point was below('md'), and MEASURED at 768
+     that is far too late: two 312px columns, the headline at three lines, the
+     description at five, the buttons crushed to 150/146 with both labels
+     broken over three lines, and the section 737px tall against a design that
+     exists to hold it under 600.
+
+     WHY below('lg') IS THE STACKING POINT. The page column caps at
+     --grid-container-max-* with --grid-padding-* either side, so the content
+     width per step is fixed and so is the two-column arithmetic once the 64px
+     gap comes out of it:
+
+       xxl  1320 - 80 = 1240  ->  588 per column
+       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 wide. It fits at xl and xxl, wraps at lg, and at md
+     there is less room than one button needs. lg is therefore the last step
+     where two columns are even arguable, and it is arguable rather than good --
+     measured, 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 the 64 to the lg grid
+     gutter's 40, or to 24, or to 16, yields 420, 428 and 432. The column is
+     about 40px short however the gutter is spent.
+
+     It keeps two columns anyway, because the alternative is worse on the same
+     screen. Stacked at lg the copy gets one 880px column -- the headline
+     collapses to a single line, which the study measured as needing 678 -- and
+     then an 880px-wide photograph under it at its own 1.497 ratio, so about
+     1100px of hero in a window 992-1199 wide. 661 beats that. Bounding the
+     stacked panel's aspect ratio was tried on paper first: 16/9 at 880 is 495
+     tall, which still lands around 978. Stacking is the answer below lg, not
+     at it. */
+  @media ${unsafeCSS(below('lg'))} {
     .bd-container {
-      flex-direction: column;
-      padding: 0 4em;
-      gap: 2em;
+      /* grid-template-columns, not flex-direction -- see above */
+      grid-template-columns: 1fr;
     }
 
-    .bd-header-left,
-    .bd-header-right {
-      width: 100%;
-    }
-
-    .bd-cta {
-      // flex-direction: column;
-      align-items: flex-start;
-    }
-
-    ::slotted([slot="right"]) {
-      max-width: 100%;
-    }
-  }
-
-  @media (max-width: 768px) {
+    /* row-gap only. The column gap is the design's 64 and there is no second
+       column left to apply it to; 32 is the distance between the copy and the
+       image once they are stacked, and it is a step rather than the 2em that
+       used to arrive here. */
     .bd-container {
-      padding: 0 2em;
-      text-align: center;
-    }
-
-    .bd-product-name,
-    .bd-value-prop,
-    .bd-description,
-    .bd-price-zone-top,
-    .bd-price-zone-final,
-    .bd-disclaimer {
-      text-align: center;
+      row-gap: var(--spacing-32);
     }
+  }
 
+  /* Narrower than md. Separate from the stacking block above on purpose:
+     stacking and the phone treatment are different decisions at different
+     widths, and at md the column is 656px where a side-by-side CTA row still
+     fits.
+
+     THE CONTENT STAYS LEFT-ALIGNED AT EVERY WIDTH. It used to centre here, and
+     three things say it should not:
+
+       The design does not ask for it. Header / v2 is left-aligned, and there
+       is no mobile frame anywhere 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 works for a poster: a headline
+       and one button. This is a specification.
+
+       IT NEEDED A PATCH TO LOOK RIGHT, WHICH IS THE ARGUMENT. 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 left
+       the row itself hard against the left edge while the final price centred
+       underneath it. That needed an extra justify-content: center to correct,
+       and a treatment that needs a patch to stop looking broken is usually
+       the wrong treatment. Removing the centring removes the patch with it:
+       the price row is left-aligned like everything else, and nothing has to
+       be told twice where its axis is.
+
+     The disclaimers were being centred by inheritance rather than by any rule
+     that named them -- the old rule listed .bd-disclaimer, which does not
+     exist in this component. They are left now like the rest. */
+  @media ${unsafeCSS(below('md'))} {
+    /* stretch, not center. The two labels are different lengths, so hugging
+       gave a 183px button above a 246px one -- two different widths on a
+       shared axis, which reads as an accident rather than a pair. It is the
+       Content Switcher's argument in another control: a translation must not
+       be able to make one of two equivalent actions bigger than the other.
+       Full-width they are the same object twice and the tap targets stop
+       varying with the copy, which holds whether the column is centred or
+       left-aligned. */
     .bd-cta {
       flex-direction: column;
-      align-items: center;
+      align-items: stretch;
     }
 
-    .bd-header-right {
-      display: flex;
-      justify-content: center;
+    /* STRETCHING THE COLUMN IS NOT ENOUGH. With align-items: stretch the
+       HOSTS go full width, but the anchor inside each one is inline-flex and
+       hugs its label, so both buttons end up hard against the left edge of
+       their own box. Measured: hosts 492, anchors 183 and 246.
+
+       The atom's own answer is its fullwidth attribute, which adds
+       .max--width -- width: 100%; display: flex -- to that anchor. A media
+       query cannot set an attribute, so this reaches the same computed result
+       through the host's formatting context instead: the host's display is
+       what its shadow child is laid out in, an outer-tree rule beats the
+       atom's :host, and a lone child of a single-column grid fills its track.
+       Measured after: hosts 492, anchors 492 and 492.
+
+       The coupling is worth knowing: this depends on the anchor being the
+       shadow root's only child, which it is (A.button). If the button ever
+       wraps it, prefer fullwidth on the markup and the viewport state it
+       needs. */
+    .bd-cta bd-button-link {
+      display: grid;
     }
+  }
 
-    ::slotted([slot="right"]) {
-      max-width: 100%;
+  /* THE BAND STEPS WITH THE PANEL, and it steps at md rather than sm because
+     that is where the panel stops being landscape. Measured with the band held
+     at its desktop 160 all the way down: 37% of the panel at 768-991, then
+     **49% at 600** -- a 492x329 panel with a 160px band across the bottom half
+     of it. Below md it is 88, which reads 27% at 600 and 30% at 500.
+
+     Two things change and both are about the media panel.
+
+     WHAT WAS AT (max-width: 480px), and a claim worth getting right. The block
+     set max-width: 90% and max-height: 200px on .bd-header-image -- a class
+     header.js does not render. It is the same kind of miss as the four dead
+     slot names recorded at the top of this file, so for the COMPONENT it was
+     dead: measured on Components/Header at 375 and 320, the slotted image
+     computes max-width and max-height of none and sits flush with the wrapper
+     on every edge. It became live only in the Intended design story, 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 it on each side. It is deleted rather than fixed;
+     it existed to tame the scale(1.35) crop this file used to do, and a real
+     cover fill needs no cap.
+
+     WHAT WAS REAL for the component is the band's proportion, because the band
+     was a constant 160 and the panel is not. The panel's height follows the
+     copy beside it when the columns are side by side, and its own 1.497 ratio
+     once they stack -- measured 311x208 at 375 and 256x171 at 320, which put a
+     160px band at 77% and 94% of it. A corner treatment covering 94% of the
+     picture is a wash.
+
+     So the band is re-proportioned rather than capped: the inset drops a step
+     and the fade drops to 48, giving 40 + 48 = 88. Measured after: 42% at 375
+     and 51% at 320. The plateau still covers the mark exactly, because it is
+     derived from the inset rather than from a percentage of the band.
+
+     One thing this does not fix, and it is inherent rather than a defect: a
+     constant band on a variable panel is a variable proportion. Components/
+     Header's own Default story 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%. */
+  @media ${unsafeCSS(below('md'))} {
+    .bd-header-image-wrapper {
+      --bd-header-mark-inset: var(--spacing-16);
+      --bd-header-mark-height: var(--icon-sm-size);
+      --bd-header-scrim-fade: var(--spacing-48);
+      --bd-header-scrim-mid: var(--spacing-16);
     }
-  }
 
-  @media (max-width: 480px) {
-    .bd-header-image {
-      max-width: 90%;
-      max-height: 200px;
+    /* THE MARK STEPS DOWN A SIZE, and this is the other thing only the render
+       showed. At 320 the panel is 256 wide and the mark is 182 of it -- 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.
+       .
+       A height on the host rather than the atom's size attribute, because the
+       size is a viewport question and the attribute is not reachable from a
+       media query. It is not a reach past the API: the atom's own rule is
+       :host { height: var(--bd-icon-size, ...) }, and a consuming rule and a
+       :host rule match the SAME element, where the outer tree wins -- the same
+       mechanism scripts/atom-inert-properties.json records for colour on a
+       bd-p host. --bd-icon-size, which the element sets inline from its size prop, is
+       deliberately not what is overridden here: an inline custom property
+       would beat this rule.
+       .
+       sm on the icon scale is 16px, so the mark renders 121 wide -- 47% of a
+       256px panel. --bd-header-mark-height above is set to the same step, so
+       the scrim's plateau follows it and still ends exactly on the mark's top
+       edge. */
+    .bd-header-signature {
+      height: var(--icon-sm-size);
     }
   }
 
   ::slotted([slot="disclaimer-bottom-link"]) {
-    color: black;
+    color: var(--color-text-primary);
     text-decoration: underline;
   }
 `;