@contentrain/astro-kit 0.40.0 → 0.42.0

package/components/dialog/Dialog.astro

@@ -19,6 +19,8 @@ import Button from '../_shared/Button.astro'
 import Section from '../_shared/Section.astro'
 import type { ActionInput, MeasuredStyle } from '../_shared/types'
 import Prose from '../prose/Prose.astro'
+import { instanceId } from '../_shared/instance-id'
+import { mutedReset } from '../_shared/muted'
 
 const dialog = tv({
   slots: {
@@ -28,7 +30,7 @@ const dialog = tv({
     // modal (the `open` preview prop) it is a block in the flow under the button, not a box over it. The inner box
     // scrolls, not the dialog: a click on the scrollbar then never lands on the dialog itself (the backdrop test). The
     // display is set only when open (`open:flex`): an author `display` would override the UA's `display: none` when closed.
-    box: 'm-auto w-[min(92vw,var(--dialog-width))] max-h-[85dvh] flex-col open:flex rounded-card border border-line bg-surface p-0 text-ink shadow-xl backdrop:bg-ink/50 [&[open]:not(:modal)]:relative [&[open]:not(:modal)]:m-0 [&[open]:not(:modal)]:basis-full',
+    box: `m-auto w-[min(92vw,var(--dialog-width))] max-h-[85dvh] flex-col open:flex rounded-card border border-line bg-surface p-0 text-ink shadow-xl backdrop:bg-ink/50 [&[open]:not(:modal)]:relative [&[open]:not(:modal)]:m-0 [&[open]:not(:modal)]:basis-full ${mutedReset}`,
     inner: 'flex min-h-0 flex-col gap-4 overflow-y-auto p-6 md:p-8',
     heading: 'pe-10 text-xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-2xl',
     actions: 'flex flex-wrap gap-3',
@@ -78,10 +80,11 @@ interface Props {
   fact?: string | undefined
 }
 
-const { id: givenId = 'dialog', triggerLabel, heading, html, actions = [], closeLabel = 'Close', triggerStyle, size, align: given, tone, measured, open = false, trigger, fact } = Astro.props
+const { id: givenId, triggerLabel, heading, html, actions = [], closeLabel = 'Close', triggerStyle, size, align: given, tone, measured, open = false, trigger, fact } = Astro.props
 const factId = fact && /^[\w:.-]{1,120}$/.test(fact) ? fact : undefined
 // The id goes into attributes and into the scripting-off style sheet, so it is a plain token or the default.
-const id = /^[A-Za-z][\w-]*$/.test(givenId) ? givenId : 'dialog'
+// Two dialogs without one of their own never share it (each opener would open the first).
+const id = instanceId(Astro.locals, givenId && /^[A-Za-z][\w-]*$/.test(givenId) ? givenId : undefined, 'dialog')
 const align = given ?? measured?.align
 // On the accent band the primary button (accent) would vanish: drawn as the secondary style there, as in Cta. The
 // dialog's own actions sit on the dialog's surface, not the band, so they keep their styles.

package/components/dialog/meta.json

@@ -9,7 +9,9 @@
   "shared": [
     "Button.astro",
     "Section.astro",
+    "instance-id.ts",
     "measured.ts",
+    "muted.ts",
     "safe-url.ts",
     "types.ts"
   ],

package/components/faq/Faq.astro

@@ -7,6 +7,8 @@ import { tv } from 'tailwind-variants'
 import Section from '../_shared/Section.astro'
 import { measuredColumns } from '../_shared/measured'
 import type { MeasuredStyle } from '../_shared/types'
+import { instanceId } from '../_shared/instance-id'
+import { muted } from '../_shared/muted'
 
 export interface FaqItem {
   question: string
@@ -19,7 +21,7 @@ const faq = tv({
     root: '',
     head: 'mb-8 flex flex-col gap-3',
     heading: 'text-2xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-3xl',
-    intro: 'max-w-2xl text-lg opacity-80',
+    intro: `max-w-2xl text-lg ${muted}`,
     list: 'flex flex-col',
     item: 'group',
     question: '',
@@ -37,7 +39,7 @@ const faq = tv({
     columns: { '1': {}, '2': { list: 'lg:block lg:columns-2 lg:gap-x-12', item: 'break-inside-avoid' } },
     // The marker in each question's row: a plus that turns into a cross, or a chevron that turns over.
     icon: { plus: {}, chevron: { marker: 'group-open:rotate-180' } },
-    numbered: { true: { list: '[counter-reset:faq]', item: '[counter-increment:faq]', question: 'before:me-4 before:tabular-nums before:opacity-60 before:content-[counter(faq,decimal-leading-zero)]' }, false: {} },
+    numbered: { true: { list: '[counter-reset:faq]', item: '[counter-increment:faq]', question: 'before:me-4 before:tabular-nums before:text-[color:var(--kit-muted,var(--color-ink-muted))] before:content-[counter(faq,decimal-leading-zero)]' }, false: {} },
     style: {
       lines: { list: 'divide-y divide-line border-y border-line' },
       cards: { list: 'gap-3', item: 'rounded-card border border-line px-5', summary: 'py-5' },
@@ -84,7 +86,9 @@ interface Props {
   id?: string | undefined
 }
 
-const { items, heading, intro, layout, columns, icon, numbered = false, style, questionStyle, exclusive = false, openFirst = false, schema = false, tone, measured, id = 'faq' } = Astro.props
+const { items, heading, intro, layout, columns, icon, numbered = false, style, questionStyle, exclusive = false, openFirst = false, schema = false, tone, measured, id: givenId } = Astro.props
+// Two on one page never share an id: their labels and controls would point into each other.
+const id = instanceId(Astro.locals, givenId, 'faq')
 const s = faq({ layout, columns, icon, numbered, style, questionStyle: style === 'plain' ? 'heading' : questionStyle, tone })
 // Two columns and the split layout need the page's width; one column reads in the narrow one.
 const measuredCols = measuredColumns(measured)
@@ -103,7 +107,7 @@ const structured = schema && items.length > 0
   : null
 ---
 {items.length > 0 && (
-  <Section measured={measured} tone={tone} spacing="md" width={wide ? 'page' : 'prose'} id={id} aria-labelledby={headingId}>
+  <Section kit="faq" measured={measured} tone={tone} spacing="md" width={wide ? 'page' : 'prose'} id={id} aria-labelledby={headingId}>
     <div class={s.root()}>
       {(heading || intro) && (
         <header class={s.head()}>

package/components/faq/meta.json

@@ -4,7 +4,7 @@
   "description": "Questions and answers as native <details> disclosures (no script), in lines or cards; optionally one open at a time, and optionally with FAQPage structured data for search engines and AI answers.",
   "category": "section",
   "uses": [],
-  "shared": ["Section.astro", "measured.ts", "safe-url.ts", "types.ts"],
+  "shared": ["Section.astro", "instance-id.ts", "measured.ts", "muted.ts", "safe-url.ts", "types.ts"],
   "variants": {
     "layout": { "options": ["single", "split"], "default": "single", "description": "single: the heading above one column. split: the heading and introduction stay in a left column beside the list; stacks on a phone." },
     "columns": { "options": ["1", "2"], "default": "1", "description": "Columns of questions on wide screens." },

package/components/feature-list/FeatureList.astro

@@ -4,8 +4,10 @@
 import { tv } from 'tailwind-variants'
 import KitImage from '../_shared/KitImage.astro'
 import Section, { type Tone } from '../_shared/Section.astro'
+import { instanceId } from '../_shared/instance-id'
 import { measuredGrid } from '../_shared/measured'
 import type { MeasuredStyle } from '../_shared/types'
+import { muted } from '../_shared/muted'
 
 const list = tv({
   slots: {
@@ -13,7 +15,7 @@ const list = tv({
     item: 'flex gap-4',
     mark: 'flex size-6 shrink-0 items-center justify-center text-accent-text',
     title: 'text-lg leading-snug [font-weight:var(--font-weight-heading,600)] text-balance',
-    text: 'mt-1 opacity-80',
+    text: `mt-1 ${muted}`,
   },
   variants: {
     columns: {
@@ -28,7 +30,7 @@ const list = tv({
       list: { grid: 'flex flex-col gap-3', item: 'items-center gap-3', mark: 'size-5', title: 'text-[length:var(--text-body,1rem)] leading-normal [font-weight:inherit] text-pretty', text: 'mt-0' },
     },
     // On accent the mark takes the ink colour, and text is never dimmed.
-    tone: { default: {}, muted: {}, inverse: {}, accent: { mark: 'text-current', text: 'opacity-100' } },
+    tone: { default: {}, muted: {}, inverse: {}, accent: { mark: 'text-current' } },
     // A list inside another section's column: one column, tighter, no section around it.
     bare: { true: { grid: 'sm:grid-cols-1 gap-y-5' }, false: {} },
   },
@@ -73,9 +75,11 @@ interface Props {
   measured?: MeasuredStyle | undefined
 }
 
-const { heading, intro, items, columns, style = 'icon', tone, bare = false, titleLevel = 3, id, measured } = Astro.props
+const { heading, intro, items, columns, style = 'icon', tone, bare = false, titleLevel = 3, id: givenId, measured } = Astro.props
+// Every section has an id, so a theme or a design layer can address this one: the page's, or `feature-list`, `feature-list-2`, … in render order.
+const id = instanceId(Astro.locals, givenId, 'feature-list')
 const s = list({ columns, style, tone, bare })
-const headingId = heading && id ? `${id}-title` : undefined
+const headingId = heading ? `${id}-title` : undefined
 const pathOf = (item: Item) => (style !== 'check' && item.icon && icons[item.icon]) || icons.check
 // The feature's own image icon, where the style shows each feature's own mark.
 const imageOf = (item: Item) => (style !== 'check' && item.iconImage) || undefined
@@ -101,11 +105,11 @@ const Title = style === 'list' ? 'span' : bare ? `h${titleLevel}` as 'h3' : head
     </ul>
   )
   : (
-<Section measured={measured} tone={tone} id={id} aria-labelledby={headingId}>
+<Section kit="feature-list" measured={measured} tone={tone} id={id} aria-labelledby={headingId}>
   {(heading || intro) && (
     <header class="mb-10 flex max-w-2xl flex-col gap-3">
       {heading && <h2 id={headingId} class="text-3xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-4xl">{heading}</h2>}
-      {intro && <p class:list={['text-lg', tone === 'accent' ? undefined : 'opacity-80']} data-kit-text>{intro}</p>}
+      {intro && <p class:list={['text-lg', muted]} data-kit-text>{intro}</p>}
     </header>
   )}
   <ul class={s.grid({ class: measuredGrid(measured) })}>

package/components/feature-list/meta.json

@@ -7,7 +7,9 @@
   "shared": [
     "KitImage.astro",
     "Section.astro",
+    "instance-id.ts",
     "measured.ts",
+    "muted.ts",
     "safe-url.ts",
     "types.ts"
   ],
@@ -219,7 +221,7 @@
     "id": {
       "type": "string",
       "content": false,
-      "description": "Anchor id of the section; the heading gets `<id>-title`."
+      "description": "Anchor id of the section; the heading gets `<id>-title`. Without one, `feature-list`, `feature-list-2`, … in render order, so every section on a page has its own."
     }
   },
   "slots": {},

package/components/footer/Footer.astro

@@ -5,13 +5,14 @@ import { tv } from 'tailwind-variants'
 import type { LinkInput } from '../_shared/types'
 import { contactKeys, footerLinkSizeClasses, footerVars, type ContactInput } from './footer'
 import { safeHref } from '../_shared/safe-url'
+import { muted as quiet, mutedInverse } from '../_shared/muted'
 
 const footer = tv({
   slots: {
     root: 'mt-auto',
     inner: 'container-page py-10 text-sm',
-    muted: 'opacity-75',
-    link: 'text-current no-underline opacity-75 hover:opacity-100 hover:underline',
+    muted: quiet,
+    link: `no-underline ${quiet} hover:text-current hover:underline`,
   },
   variants: {
     layout: {
@@ -21,7 +22,7 @@ const footer = tv({
     tone: {
       default: { root: 'bg-surface text-ink' },
       muted: { root: 'bg-surface-muted text-ink' },
-      inverse: { root: 'bg-ink text-surface' },
+      inverse: { root: `bg-ink text-surface ${mutedInverse}` },
     },
     // The border on the footer's top side: the default tone's own unless `border` says otherwise.
     border: { on: { root: 'border-t border-line' }, off: {} },

package/components/footer/meta.json

@@ -5,6 +5,7 @@
   "category": "chrome",
   "uses": [],
   "shared": [
+    "muted.ts",
     "safe-url.ts",
     "types.ts"
   ],

package/components/gallery/Gallery.astro

@@ -12,6 +12,8 @@ import type { MeasuredStyle } from '../_shared/types'
 import { imageOf, type ImageSource } from '../_shared/image'
 import { type ImageInput } from '../_shared/types'
 import { safeHref } from '../_shared/safe-url'
+import { instanceId } from '../_shared/instance-id'
+import { muted } from '../_shared/muted'
 
 export interface GalleryItem {
   /** The image's address (or, until 0.7, an `ImageInput`). */
@@ -29,7 +31,7 @@ const gallery = tv({
     item: 'm-0',
     frame: 'group relative block w-full cursor-zoom-in overflow-hidden rounded-[var(--radius-image,var(--radius-card))] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent',
     thumb: 'h-full w-full object-cover transition-transform duration-300 hover:scale-[1.02]',
-    caption: 'mt-2 text-sm opacity-75',
+    caption: `mt-2 text-sm ${muted}`,
     viewer: 'm-auto max-h-[92vh] max-w-[92vw] bg-transparent p-0 backdrop:bg-ink/85',
   },
   variants: {
@@ -85,14 +87,16 @@ interface Props {
   id?: string | undefined
 }
 
-const { items: given, heading, layout, columns, aspect, gap, captionStyle, hoverEffect, enlargeLabel = 'Enlarge', regionLabel = 'Images', open = 'popover', closeLabel = 'Close', tone, measured, id = 'gallery' } = Astro.props
+const { items: given, heading, layout, columns, aspect, gap, captionStyle, hoverEffect, enlargeLabel = 'Enlarge', regionLabel = 'Images', open = 'popover', closeLabel = 'Close', tone, measured, id: givenId } = Astro.props
+// Two on one page never share an id: their labels and controls would point into each other.
+const id = instanceId(Astro.locals, givenId, 'gallery')
 const items = given.flatMap(item => { const image = imageOf(item.image, item.imageAlt); return image ? [{ ...item, image, full: imageOf(item.full, item.imageAlt) }] : [] }) satisfies Array<{ image: ImageInput, caption?: string | undefined }>
 const s = gallery({ layout, columns, open, aspect, gap, captionStyle, hoverEffect })
 const headingId = heading ? `${id}-title` : undefined
 const sizes = columns === '2' ? '50vw' : columns === '4' ? '(min-width: 768px) 25vw, 50vw' : '(min-width: 768px) 33vw, 50vw'
 ---
 {items.length > 0 && (
-  <Section measured={measured} tone={tone} spacing="md" id={id} aria-labelledby={headingId}>
+  <Section kit="gallery" measured={measured} tone={tone} spacing="md" id={id} aria-labelledby={headingId}>
     {heading && <h2 id={headingId} class={s.heading()}>{heading}</h2>}
     {/* A scrolling strip is a labelled, focusable region so the keyboard can scroll it. */}
     <div tabindex={layout === 'row' ? 0 : undefined} role={layout === 'row' ? 'region' : undefined} aria-label={layout === 'row' ? heading ?? regionLabel : undefined}>
@@ -107,7 +111,7 @@ const sizes = columns === '2' ? '50vw' : columns === '4' ? '(min-width: 768px) 2
                 : open === 'link'
                   ? <a href={safeHref(item.image.src)} class={s.frame()}><KitImage image={item.image} sizes={sizes} class={s.thumb()} /></a>
                   : <div class={s.frame()}><KitImage image={item.image} sizes={sizes} class={s.thumb()} /></div>}
-              {item.caption && <figcaption class={s.caption({ class: tone === 'accent' ? 'opacity-100' : undefined })}>{item.caption}</figcaption>}
+              {item.caption && <figcaption class={s.caption()}>{item.caption}</figcaption>}
             </figure>
             {open === 'popover' && (
               <div id={viewer} popover class={s.viewer()}>

package/components/gallery/meta.json

@@ -8,7 +8,9 @@
     "KitImage.astro",
     "Section.astro",
     "image.ts",
+    "instance-id.ts",
     "measured.ts",
+    "muted.ts",
     "safe-url.ts",
     "types.ts"
   ],

package/components/header/Header.astro

@@ -7,8 +7,10 @@ import KitImage from '../_shared/KitImage.astro'
 import type { ActionInput, ImageInput, NavItem } from '../_shared/types'
 import Nav from '../nav/Nav.astro'
 import SearchBox from '../search-box/SearchBox.astro'
+import { instanceId } from '../_shared/instance-id'
 import { safeHref } from '../_shared/safe-url'
 import { brandColorValue } from './header'
+import { muted, mutedInverse } from '../_shared/muted'
 
 const header = tv({
   slots: {
@@ -24,8 +26,8 @@ const header = tv({
     },
     tone: {
       default: { root: 'bg-surface text-ink' },
-      inverse: { root: 'bg-ink text-surface' },
-      transparent: { root: 'absolute inset-x-0 top-0 bg-transparent text-surface' },
+      inverse: { root: `bg-ink text-surface ${mutedInverse}` },
+      transparent: { root: `absolute inset-x-0 top-0 bg-transparent text-surface ${mutedInverse}` },
     },
     position: { static: {}, sticky: { root: 'sticky top-0' } },
     bordered: { true: {}, false: {} },
@@ -76,6 +78,8 @@ interface Props {
 
 const { siteName, tagline, brandSize, brandWeight, brandTracking, bordered, offsetTop, padTop, padBottom, linkNav, brandColor, logo, showName = true, homeHref = '/', items, action, search, navLabel, menuLabel, closeLabel, layout, tone, position, menu } = Astro.props
 const { root, inner, brand } = header({ layout, tone, position, bordered })
+// The header's search field: `header-search` on a page, a second header's its own (its label points at its own input).
+const searchId = search ? instanceId(Astro.locals, undefined, 'header-search') : undefined
 const rootStyle = offsetTop ? `margin-top: ${offsetTop}` : undefined
 const innerStyle = [padTop && `padding-top: ${padTop}`, padBottom && `padding-bottom: ${padBottom}`].filter(Boolean).join('; ') || undefined
 const brandColour = brandColorValue(brandColor)
@@ -93,7 +97,7 @@ const wrap = search ? 'flex-wrap lg:flex-nowrap' : tagline ? 'flex-wrap md:flex-
             {logo && <KitImage image={logo} priority class="h-8 w-auto" sizes="160px" />}
             {showName && <span>{siteName}</span>}
           </a>
-          <p class="opacity-75" data-kit-tagline>{tagline}</p>
+          <p class={muted} data-kit-tagline>{tagline}</p>
         </div>
       )
       : (
@@ -104,7 +108,7 @@ const wrap = search ? 'flex-wrap lg:flex-nowrap' : tagline ? 'flex-wrap md:flex-
       )}
     {search && (
       <div class="order-last basis-full lg:order-none lg:ms-auto lg:basis-auto">
-        <SearchBox action={search.action} label={search.label} placeholder={search.placeholder} submitLabel={search.submitLabel} size="sm" id="header-search" />
+        <SearchBox action={search.action} label={search.label} placeholder={search.placeholder} submitLabel={search.submitLabel} size="sm" id={searchId} />
       </div>
     )}
     <div class:list={['flex items-center gap-4', layout === 'centered' ? 'justify-center' : 'ms-auto']}>

package/components/header/meta.json

@@ -4,7 +4,7 @@
   "description": "Site header: brand (logo and/or name), navigation and an optional call-to-action button.",
   "category": "chrome",
   "uses": ["nav", "search-box"],
-  "shared": ["Button.astro", "KitImage.astro", "safe-url.ts", "types.ts"],
+  "shared": ["Button.astro", "KitImage.astro", "instance-id.ts", "muted.ts", "safe-url.ts", "types.ts"],
   "variants": {
     "layout": { "options": ["split", "centered", "brand-left"], "default": "split", "description": "split: brand left, navigation right. centered: brand above centred navigation. brand-left: navigation right after the brand." },
     "tone": { "options": ["default", "inverse", "transparent"], "default": "default", "description": "Surface with a bottom border, dark (ink) background, or transparent over the hero that follows." },

package/components/hero/Hero.astro

@@ -5,17 +5,21 @@ import { tv } from 'tailwind-variants'
 import Button from '../_shared/Button.astro'
 import KitImage from '../_shared/KitImage.astro'
 import Section from '../_shared/Section.astro'
+import Lines from '../_shared/Lines.astro'
+import { instanceId } from '../_shared/instance-id'
 import type { ActionInput, ImageInput, MeasuredStyle } from '../_shared/types'
 import { measuredFrame } from '../_shared/measured'
 import { coverHeight as heightOf, headingStyle as styleOf } from './hero'
+import { muted, mutedInverse } from '../_shared/muted'
+import { BLEED } from '../_shared/bleed'
 
 const hero = tv({
   slots: {
     grid: 'grid items-center gap-10',
     copy: 'flex flex-col gap-5',
-    eyebrow: 'text-sm font-semibold tracking-wide uppercase opacity-80',
+    eyebrow: `text-sm font-semibold tracking-wide uppercase ${muted}`,
     heading: 'text-4xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-5xl lg:text-6xl',
-    lead: 'max-w-2xl text-lg text-pretty opacity-85 md:text-xl',
+    lead: `max-w-2xl text-lg text-pretty ${muted} md:text-xl`,
     // A hero's short promise list ("Fast, easy and painless"), each with its icon when it has one.
     points: 'flex flex-wrap gap-x-6 gap-y-2 text-base font-medium md:text-lg',
     point: 'flex items-center gap-2',
@@ -29,7 +33,7 @@ const hero = tv({
       cover: { grid: 'relative z-10 min-h-[28rem] md:min-h-[36rem]', copy: 'max-w-3xl' },
     },
     // accent/accent-ink is only ~5:1 — dimming text on it drops body copy under 4.5:1 (WCAG 1.4.3), so accent keeps it at full strength.
-    tone: { default: {}, muted: {}, inverse: {}, accent: { eyebrow: 'opacity-100', lead: 'opacity-100' } },
+    tone: { default: {}, muted: {}, inverse: {}, accent: {} },
     // Where a cover sets its text over the image. WordPress covers centre it unless told otherwise.
     align: { start: {}, center: {} },
     // The lead's own alignment: `start` keeps it at the start edge, across the column, under a centred heading
@@ -45,6 +49,18 @@ const hero = tv({
     headingScale: { default: {}, theme: {} },
     // The level whose site size the heading takes when it is not the level it is written at (set inline, see ./hero).
     headingSize: { own: {}, h1: {}, h2: {} },
+    // The heading as the author broke it: `lines` prints each `\n`-separated line as its own block (`data-kit-line`),
+    // `flow` (the default) as one run of text.
+    headingLines: { flow: {}, lines: {} },
+    // Split and centered (a cover ignores both): the image before the text, on phones and on the start side (split),
+    // or above the heading (centered).
+    stackOrder: { 'text-first': {}, 'media-first': { media: 'order-first' } },
+    // edge: the image runs on to the window's edge on its side (wide screens), or across the whole width when centered.
+    // overlap: it also crosses the section's bottom edge by `--hero-overlap` (3rem), drawn over the next section's top
+    // padding: set at the grid's bottom and moved past the hero's own bottom padding (`spacing="lg"`: 4rem, 7rem from md),
+    // not laid out there, so the next section stays where it was. Only an image that comes last can cross the bottom: one
+    // that comes first (`media-first`) would be moved down over the text, so there overlap draws as edge.
+    imageBleed: { none: {}, edge: { media: 'rounded-none' }, overlap: { media: 'relative z-10 self-end translate-y-[calc(4rem+var(--hero-overlap,3rem))] rounded-none md:translate-y-[calc(7rem+var(--hero-overlap,3rem))]' } },
   },
   compoundVariants: [
     // After the layout's own heights, so a boxed cover keeps WordPress's 430px default.
@@ -54,7 +70,7 @@ const hero = tv({
     { leadAlign: 'start', class: { lead: 'mx-0 max-w-none self-stretch text-start' } },
     { actionsAlign: 'start', class: { actions: 'justify-start self-stretch' } },
   ],
-  defaultVariants: { layout: 'split', tone: 'default', align: 'center', leadAlign: 'inherit', actionsAlign: 'inherit', width: 'full', headingScale: 'default', headingSize: 'own' },
+  defaultVariants: { layout: 'split', tone: 'default', align: 'center', leadAlign: 'inherit', actionsAlign: 'inherit', width: 'full', headingScale: 'default', headingSize: 'own', headingLines: 'flow', stackOrder: 'text-first', imageBleed: 'none' },
 })
 
 interface Props {
@@ -84,33 +100,46 @@ interface Props {
   headingScale?: 'default' | 'theme' | undefined
   /** The level whose site size the heading takes, when it is not the level it is written at (`h1` size on an `h2`: a page keeps one `h1`). `own` (absent): the heading's own level under `theme`, as before. */
   headingSize?: 'own' | 'h1' | 'h2' | undefined
+  /** `lines`: each line of the heading (split at `\n`) is a block of its own, `data-kit-line="<n>"`, for a theme to set per line. `flow` (absent): one run of text, as before. */
+  headingLines?: 'flow' | 'lines' | undefined
+  /** Split and centered: `media-first` puts the image before the text (phones and the start side in split, above the heading in centered). `text-first` (absent): as before. */
+  stackOrder?: 'text-first' | 'media-first' | undefined
+  /** Split and centered: `edge` runs the image on to the window's edge on its side (both sides when centered); `overlap` also lets it cross the section's bottom edge by `--hero-overlap` (3rem), when the image comes last (with `media-first` it draws as `edge`). `none` (absent): as before. */
+  imageBleed?: 'none' | 'edge' | 'overlap' | undefined
   /** The source section's measured style (`MeasuredStyle`): frame, padding, fill, background image, columns per width, gap. Absent, the site's tokens; present, it wins over tone and columns. */
   measured?: MeasuredStyle | undefined
 }
 
 
-const { heading, level = 1, eyebrow, lead, items = [], actions = [], image, layout = 'split', align, leadAlign, actionsAlign, width = 'full', tone, id, minHeight, headingScale, headingSize, measured } = Astro.props
-const s = hero({ layout, align, leadAlign, actionsAlign, width, tone, headingScale, headingSize })
+const { heading, level = 1, eyebrow, lead, items = [], actions = [], image, layout = 'split', align, leadAlign, actionsAlign, width = 'full', tone, id: givenId, minHeight, headingScale, headingSize, headingLines, stackOrder, imageBleed, measured } = Astro.props
+// Every section has an id, so a theme or a design layer can address this one: the page's, or `hero`, `hero-2`, … in render order.
+const id = instanceId(Astro.locals, givenId, 'hero')
+// Overlap moves the image down past the section's bottom, so only an image that comes last may: first, it is edge.
+const bleedAs = imageBleed === 'overlap' && stackOrder === 'media-first' ? 'edge' : imageBleed
+const s = hero({ layout, align, leadAlign, actionsAlign, width, tone, headingScale, headingSize, headingLines, stackOrder, imageBleed: bleedAs })
 const Heading = level === 1 ? 'h1' : 'h2'
-const headingId = id ? `${id}-title` : undefined
+const headingId = `${id}-title`
 const cover = layout === 'cover' && image
 const coverHeight = cover ? heightOf(minHeight) : undefined
 const headingStyle = styleOf(headingScale, level, headingSize)
 // A cover draws its own image: the measured background image is that image, and the measured overlay is its scrim.
 const sectionMeasured = cover && measured ? { ...measured, bg: measured.bg ? { ...measured.bg, image: undefined, overlay: undefined } : undefined } : measured
 const scrim = cover ? measuredFrame(measured).overlay : undefined
+// The window's edge for a bleeding image: its own side in split (the start side when it comes first), both when centered.
+const bleeds = !cover && image && imageBleed !== undefined && imageBleed !== 'none'
+const bleed = bleeds ? (layout === 'centered' ? `max-w-none md:w-auto ${BLEED.start} ${BLEED.end}` : BLEED[stackOrder === 'media-first' ? 'start' : 'end']) : undefined
 ---
 {cover && width === 'content'
   ? (
-    <Section measured={sectionMeasured} tone="none" spacing="sm" width="prose" id={id} aria-labelledby={headingId}>
-      <div class="relative isolate overflow-hidden bg-ink text-surface">
+    <Section kit="hero" measured={sectionMeasured} tone="none" spacing="sm" width="prose" id={id} aria-labelledby={headingId}>
+      <div class={`relative isolate overflow-hidden bg-ink text-surface ${mutedInverse}`}>
         <KitImage image={image} priority sizes="(min-width: 768px) 46rem, 100vw" class="absolute inset-0 -z-10 h-full w-full object-cover" />
         <div class:list={['absolute inset-0 -z-10', !scrim && 'bg-ink/60']} style={scrim ? `background: ${scrim}` : undefined} aria-hidden="true" />
         <div class="px-6 py-10 md:px-10">
           <div class={s.grid()} style={coverHeight ? `min-height: ${coverHeight}` : undefined}>
             <div class={s.copy()}>
               {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
-              <Heading id={headingId} class={s.heading()} style={headingStyle}>{heading}</Heading>
+              <Heading id={headingId} class={s.heading()} style={headingStyle}>{headingLines === 'lines' ? <Lines text={heading} /> : heading}</Heading>
               {lead && <p class={s.lead()} data-kit-text>{lead}</p>}
               {items.length > 0 && <ul class={s.points()}>{items.map(item => <li class={s.point()}>{item.icon && <KitImage image={{ src: item.icon, alt: '' }} class="h-6 w-6 shrink-0 object-contain" />}<span>{item.title}</span></li>)}</ul>}
               {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} size="lg" />)}</div>}
@@ -122,14 +151,14 @@ const scrim = cover ? measuredFrame(measured).overlay : undefined
   )
   : cover
   ? (
-    <Section measured={sectionMeasured} tone="inverse" spacing="none" width="none" id={id} aria-labelledby={headingId} class="relative isolate overflow-hidden">
+    <Section kit="hero" measured={sectionMeasured} tone="inverse" spacing="none" width="none" id={id} aria-labelledby={headingId} class="relative isolate overflow-hidden">
       <KitImage image={image} priority sizes="100vw" class="absolute inset-0 -z-10 h-full w-full object-cover" />
       <div class:list={['absolute inset-0 -z-10', !scrim && 'bg-ink/60']} style={scrim ? `background: ${scrim}` : undefined} aria-hidden="true" />
       <div class:list={['container-page', measured?.padY === undefined && 'py-16 md:py-28']}>
         <div class={s.grid()} style={coverHeight ? `min-height: ${coverHeight}` : undefined}>
           <div class={s.copy()}>
             {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
-            <Heading id={headingId} class={s.heading()} style={headingStyle}>{heading}</Heading>
+            <Heading id={headingId} class={s.heading()} style={headingStyle}>{headingLines === 'lines' ? <Lines text={heading} /> : heading}</Heading>
             {lead && <p class={s.lead()} data-kit-text>{lead}</p>}
               {items.length > 0 && <ul class={s.points()}>{items.map(item => <li class={s.point()}>{item.icon && <KitImage image={{ src: item.icon, alt: '' }} class="h-6 w-6 shrink-0 object-contain" />}<span>{item.title}</span></li>)}</ul>}
             {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} size="lg" />)}</div>}
@@ -139,18 +168,18 @@ const scrim = cover ? measuredFrame(measured).overlay : undefined
     </Section>
   )
   : (
-    <Section measured={sectionMeasured} tone={tone} spacing="lg" id={id} aria-labelledby={headingId}>
+    <Section kit="hero" measured={sectionMeasured} tone={tone} spacing="lg" id={id} aria-labelledby={headingId} class={bleeds ? 'overflow-x-clip' : undefined}>
       {/* Without an image a split has nothing beside the text: the text takes the whole row, not half of it. */}
       <div class={s.grid({ class: image ? undefined : 'md:grid-cols-1' })}>
         <div class={s.copy()}>
           {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
-          <Heading id={headingId} class={s.heading()} style={headingStyle}>{heading}</Heading>
+          <Heading id={headingId} class={s.heading()} style={headingStyle}>{headingLines === 'lines' ? <Lines text={heading} /> : heading}</Heading>
           {lead && <p class={s.lead()} data-kit-text>{lead}</p>}
               {items.length > 0 && <ul class={s.points()}>{items.map(item => <li class={s.point()}>{item.icon && <KitImage image={{ src: item.icon, alt: '' }} class="h-6 w-6 shrink-0 object-contain" />}<span>{item.title}</span></li>)}</ul>}
           {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} size="lg" />)}</div>}
         </div>
         {image && (
-          <div class={s.media()}>
+          <div class:list={[s.media(), bleed]}>
             <KitImage image={image} priority sizes={layout === 'split' ? '(min-width: 768px) 50vw, 100vw' : '(min-width: 1024px) 56rem, 100vw'} class="h-auto w-full object-cover" />
           </div>
         )}

package/components/hero/fixtures.json

@@ -241,5 +241,11 @@
     }
   },
   {"name": "cover-measured-overlay", "props": {"heading": "Fresh eggs, every morning", "lead": "A family farm since 1962.", "layout": "cover", "image": {"src": "/kit-fixtures/photo-4.svg", "alt": "", "width": 1600, "height": 900}, "actions": [{"label": "Visit us", "href": "/visit/"}], "measured": {"padY": 140, "minHeight": 560, "tone": "dark", "bg": {"image": "/kit-fixtures/photo-4.svg", "overlay": "rgba(20, 40, 10, 0.45)"}}}},
-  {"name": "points", "props": {"heading": "Private Sigorta'ya Hoşgeldiniz!", "items": [{"icon": "/kit-fixtures/logo.svg", "title": "Hızlı, Kolay & Sorunsuz"}, {"title": "En Uygun Fiyatlar"}], "actions": [{"label": "Ürünlerimiz", "href": "/urunlerimiz/"}], "image": {"src": "/kit-fixtures/photo-1.svg", "alt": "", "width": 1200, "height": 800}}}
+  {"name": "points", "props": {"heading": "Private Sigorta'ya Hoşgeldiniz!", "items": [{"icon": "/kit-fixtures/logo.svg", "title": "Hızlı, Kolay & Sorunsuz"}, {"title": "En Uygun Fiyatlar"}], "actions": [{"label": "Ürünlerimiz", "href": "/urunlerimiz/"}], "image": {"src": "/kit-fixtures/photo-1.svg", "alt": "", "width": 1200, "height": 800}}},
+  {"name": "heading-lines", "props": {"layout": "centered", "tone": "accent", "headingLines": "lines", "eyebrow": "Northwind Journal", "heading": "Slow travel.\nGood coffee.\nTwelve years on the road.", "lead": "Essays, guides and photographs, now in one place.", "actions": [{"label": "Start reading", "href": "/journal/"}]}},
+  {"name": "split-media-first", "props": {"heading": "Your site, moved and checked", "lead": "Every page, address and form carried over.", "stackOrder": "media-first", "image": {"src": "/kit-fixtures/photo-1.svg", "alt": "A desk by a window", "width": 1200, "height": 800}, "actions": [{"label": "Start", "href": "/start/"}]}},
+  {"name": "centered-media-first-edge", "props": {"layout": "centered", "heading": "Your site, moved and checked", "lead": "Every page, address and form carried over.", "stackOrder": "media-first", "imageBleed": "edge", "image": {"src": "/kit-fixtures/photo-1.svg", "alt": "A desk by a window", "width": 1200, "height": 800}}},
+  {"name": "split-overlap", "props": {"heading": "Your site, moved and checked", "lead": "Every page, address and form carried over.", "imageBleed": "overlap", "tone": "muted", "image": {"src": "/kit-fixtures/photo-1.svg", "alt": "A desk by a window", "width": 1200, "height": 800}}},
+  {"name": "centered-media-first-overlap", "props": {"layout": "centered", "heading": "Your site, moved and checked", "lead": "Every page, address and form carried over.", "stackOrder": "media-first", "imageBleed": "overlap", "tone": "muted", "image": {"src": "/kit-fixtures/photo-1.svg", "alt": "A desk by a window", "width": 1200, "height": 800}}},
+  {"name": "split-media-first-overlap", "props": {"heading": "Your site, moved and checked", "lead": "Every page, address and form carried over.", "stackOrder": "media-first", "imageBleed": "overlap", "tone": "muted", "image": {"src": "/kit-fixtures/photo-1.svg", "alt": "A desk by a window", "width": 1200, "height": 800}}}
 ]

package/components/hero/meta.json

@@ -7,8 +7,12 @@
   "shared": [
     "Button.astro",
     "KitImage.astro",
+    "Lines.astro",
     "Section.astro",
+    "bleed.ts",
+    "instance-id.ts",
     "measured.ts",
+    "muted.ts",
     "safe-url.ts",
     "types.ts"
   ],
@@ -80,6 +84,31 @@
       ],
       "default": "own",
       "description": "The level whose site size the heading takes when it is not the level it is written at: h1 on an h2 heading keeps a source's second h1 at the h1 size under a page that keeps one h1. own: the heading's own level under headingScale theme, nothing otherwise. Any other value than own sets the size by itself."
+    },
+    "headingLines": {
+      "options": [
+        "flow",
+        "lines"
+      ],
+      "default": "flow",
+      "description": "flow: the heading is one run of text. lines: each line the author broke it into (a line break, \\n, in the heading) is a block of its own, data-kit-line=\"1\", \"2\", …, so a theme or a design layer can give a line its own ink, indent or size. Still one heading, read as one sentence."
+    },
+    "stackOrder": {
+      "options": [
+        "text-first",
+        "media-first"
+      ],
+      "default": "text-first",
+      "description": "Split and centered: the image before the text, on phones and on the start side (split), or above the heading (centered). A cover ignores it."
+    },
+    "imageBleed": {
+      "options": [
+        "none",
+        "edge",
+        "overlap"
+      ],
+      "default": "none",
+      "description": "Split and centered: edge runs the image on to the window's edge on its side (both sides when centered); overlap also lets it cross the section's bottom edge by --hero-overlap (3rem), over the next section's top padding, when the image comes last: with stackOrder media-first it draws as edge, so it never covers the text. A cover ignores it."
     }
   },
   "props": {
@@ -198,7 +227,7 @@
     "id": {
       "type": "string",
       "content": false,
-      "description": "Anchor id of the section; the heading gets `<id>-title`."
+      "description": "Anchor id of the section; the heading gets `<id>-title`. Without one, `hero`, `hero-2`, … in render order, so every section on a page has its own."
     },
     "minHeight": {
       "type": "integer",

package/components/language-switcher/LanguageSwitcher.astro

@@ -5,13 +5,14 @@
 // equivalent in each language); a link without one is not drawn.
 import { tv } from 'tailwind-variants'
 import { safeHref } from '../_shared/safe-url'
+import { muted, mutedReset } from '../_shared/muted'
 
 const switcher = tv({
   slots: {
     list: 'flex flex-wrap items-center gap-x-4 gap-y-1',
-    link: 'text-current no-underline opacity-80 hover:opacity-100 hover:underline aria-[current=true]:font-semibold aria-[current=true]:opacity-100',
+    link: `no-underline ${muted} hover:text-current hover:underline aria-[current=true]:font-semibold aria-[current=true]:text-current`,
     summary: 'inline-flex cursor-pointer list-none items-center gap-2 rounded-md px-3 py-2 text-sm font-medium hover:bg-current/10 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent [&::-webkit-details-marker]:hidden',
-    panel: 'absolute z-30 mt-1 flex min-w-40 flex-col gap-1 rounded-lg border border-line bg-surface p-2 text-ink shadow-lg',
+    panel: `absolute z-30 mt-1 flex min-w-40 flex-col gap-1 rounded-lg border border-line bg-surface p-2 text-ink shadow-lg ${mutedReset}`,
   },
   variants: {
     layout: { list: {}, menu: {} },

package/components/language-switcher/meta.json

@@ -4,7 +4,7 @@
   "description": "Links to the same page in the site's other languages, each with hreflang and its own lang; the current one is marked aria-current. A plain list or a native <details> menu; no JavaScript. The addresses are the page's equivalents in each language, supplied by the caller.",
   "category": "chrome",
   "uses": [],
-  "shared": ["safe-url.ts"],
+  "shared": ["muted.ts", "safe-url.ts"],
   "variants": {
     "layout": {
       "options": [