@contentrain/astro-kit 0.40.0 → 0.41.0

package/README.md

@@ -81,6 +81,22 @@ The starter sets it to the accent; a site whose accent does not reach 4.5:1 on i
 surface sets a readable one. A dark section (`tone="inverse"`) reads
 `--color-accent-text-inverse` in its place.
 
+Quieter text (an intro, a caption, a role, a footer link) is a colour role, never
+opacity: dimmed text lays its colour over the band, and on a mid-tone band that falls
+under 4.5:1. It reads `--color-ink-muted` on a light band, `--color-ink-muted-inverse`
+on a dark one (the starter mixes the surface toward the ink; without it, the band's own
+text colour) and the fill's own ink on an accent or brand band. A light surface inside
+a band (a card, a form panel, a menu) is back on `--color-ink-muted`. The classes are
+in `_shared/muted.ts`.
+
+### Section hooks
+
+Every section component renders its root with an `id` and `data-kit-section="<component id>"`
+(`hero`, `card-grid`, `slider`, …), so a site's theme or a design layer can style one
+kind of section, or one section, without touching the component. The id is the one the
+page gives, or the component id counted per page (`hero`, then `hero-2`), the same on
+every build.
+
 A migrated site also carries its theme's type and shape, and components read
 these with a fallback to the kit's own values, so a site without them looks
 unchanged:

package/catalog.json

@@ -23,6 +23,7 @@
     "--radius-control",
     "--radius-image",
     "--spacing-gutter",
+    "--color-ink-muted-inverse",
     "--text-nav",
     "--text-footer",
     "--text-heading-1",
@@ -103,7 +104,9 @@
         "Button.astro",
         "KitImage.astro",
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -457,7 +460,9 @@
         "behaviors.ts",
         "embed-frame.ts",
         "embed-target.ts",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -643,6 +648,11 @@
               "description": "The section's minimum height."
             }
           }
+        },
+        "id": {
+          "type": "string",
+          "content": false,
+          "description": "Anchor id of the section. Without one, `behavior`, `behavior-2`, … in render order, so every section on a page has its own."
         }
       },
       "slots": {},
@@ -742,7 +752,9 @@
         "KitImage.astro",
         "Section.astro",
         "image.ts",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -964,6 +976,11 @@
               "description": "The section's minimum height."
             }
           }
+        },
+        "id": {
+          "type": "string",
+          "content": false,
+          "description": "Anchor id of the section; the title gets `<id>-title`. Without one, `card-grid`, `card-grid-2`, … in render order, so every section on a page has its own."
         }
       },
       "slots": {},
@@ -1087,7 +1104,9 @@
       "uses": [],
       "shared": [
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -1319,7 +1338,9 @@
       "shared": [
         "KitImage.astro",
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -1646,7 +1667,9 @@
         "Button.astro",
         "KitImage.astro",
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -1901,7 +1924,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, `cta`, `cta-2`, … in render order, so every section on a page has its own."
         }
       },
       "slots": {},
@@ -1947,7 +1970,9 @@
       "shared": [
         "Button.astro",
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -2338,7 +2363,9 @@
       "uses": [],
       "shared": [
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -2611,7 +2638,9 @@
       "shared": [
         "KitImage.astro",
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -2823,7 +2852,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": {},
@@ -2871,6 +2900,7 @@
       "category": "chrome",
       "uses": [],
       "shared": [
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -3093,7 +3123,9 @@
         "KitImage.astro",
         "Section.astro",
         "image.ts",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -3389,6 +3421,8 @@
       "shared": [
         "Button.astro",
         "KitImage.astro",
+        "instance-id.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -3619,7 +3653,9 @@
         "Button.astro",
         "KitImage.astro",
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -3809,7 +3845,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",
@@ -3976,6 +4012,7 @@
       "category": "chrome",
       "uses": [],
       "shared": [
+        "muted.ts",
         "safe-url.ts"
       ],
       "variants": {
@@ -4057,7 +4094,9 @@
         "KitImage.astro",
         "Section.astro",
         "image.ts",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -4266,7 +4305,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, `logo-cloud`, `logo-cloud-2`, … in render order, so every section on a page has its own."
         }
       },
       "slots": {},
@@ -4312,6 +4351,8 @@
       "category": "chrome",
       "uses": [],
       "shared": [
+        "instance-id.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -4437,7 +4478,9 @@
       "uses": [],
       "shared": [
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -4927,7 +4970,9 @@
       ],
       "shared": [
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -5247,7 +5292,9 @@
       "shared": [
         "Button.astro",
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -5385,7 +5432,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, `pricing`, `pricing-2`, … in render order, so every section on a page has its own."
         },
         "compact": {
           "type": "boolean",
@@ -5660,6 +5707,7 @@
       "category": "chrome",
       "uses": [],
       "shared": [
+        "instance-id.ts",
         "safe-url.ts"
       ],
       "variants": {
@@ -5747,7 +5795,9 @@
         "embed-frame.ts",
         "embed-target.ts",
         "image.ts",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -6102,8 +6152,9 @@
       "category": "chrome",
       "uses": [],
       "shared": [
-        "social.ts",
-        "safe-url.ts"
+        "muted.ts",
+        "safe-url.ts",
+        "social.ts"
       ],
       "variants": {
         "display": {
@@ -6205,7 +6256,9 @@
         "Button.astro",
         "KitImage.astro",
         "Section.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -6533,7 +6586,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, `split`, `split-2`, … in render order, so every section on a page has its own."
         },
         "sticky": {
           "type": "boolean",
@@ -6605,7 +6658,9 @@
         "embed-frame.ts",
         "embed-target.ts",
         "image.ts",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -6854,7 +6909,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, `stats`, `stats-2`, … in render order, so every section on a page has its own."
         }
       },
       "slots": {},
@@ -6905,7 +6960,9 @@
         "KitImage.astro",
         "Section.astro",
         "image.ts",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -7016,7 +7073,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, `steps`, `steps-2`, … in render order, so every section on a page has its own."
         },
         "currentLabel": {
           "type": "string",
@@ -7185,7 +7242,9 @@
         "Button.astro",
         "Section.astro",
         "SectionHeader.astro",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -7441,9 +7500,11 @@
         "KitImage.astro",
         "Section.astro",
         "image.ts",
+        "instance-id.ts",
         "measured.ts",
-        "social.ts",
+        "muted.ts",
         "safe-url.ts",
+        "social.ts",
         "types.ts"
       ],
       "variants": {
@@ -7564,7 +7625,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, `team`, `team-2`, … in render order, so every section on a page has its own."
         },
         "bioClamp": {
           "type": "integer",
@@ -7748,7 +7809,9 @@
         "KitImage.astro",
         "Section.astro",
         "image.ts",
+        "instance-id.ts",
         "measured.ts",
+        "muted.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -7990,7 +8053,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, `testimonial`, `testimonial-2`, … in render order, so every section on a page has its own."
         },
         "ratingLabel": {
           "type": "string",

package/components/_shared/Section.astro

@@ -4,6 +4,7 @@
 // their order.
 import { tv } from 'tailwind-variants'
 import { measuredFrame } from './measured'
+import { mutedAccent, mutedBrand, mutedInverse, mutedReset } from './muted'
 import { safeSrc } from './safe-url'
 import type { MeasuredStyle } from './types'
 
@@ -11,13 +12,14 @@ const section = tv({
   base: '',
   variants: {
     tone: {
-      default: 'bg-surface text-ink',
-      muted: 'bg-surface-muted text-ink',
-      // A dark band reads the accent's text colour made for it (`--color-accent-text-inverse`).
-      inverse: 'bg-ink text-surface [--color-accent-text:var(--color-accent-text-inverse)]',
-      accent: 'bg-accent text-accent-ink',
+      default: `bg-surface text-ink ${mutedReset}`,
+      muted: `bg-surface-muted text-ink ${mutedReset}`,
+      // A dark band reads the accent's text colour made for it (`--color-accent-text-inverse`), and its quieter text
+      // the muted role made for it (`muted.ts`).
+      inverse: `bg-ink text-surface [--color-accent-text:var(--color-accent-text-inverse)] ${mutedInverse}`,
+      accent: `bg-accent text-accent-ink ${mutedAccent}`,
       // The site's brand colour where it is not the accent (a band the source paints in the builder's own colour).
-      brand: 'bg-brand text-brand-ink',
+      brand: `bg-brand text-brand-ink ${mutedBrand}`,
       // No fill of its own: the page's background and text colour show through.
       none: '',
     },
@@ -42,15 +44,17 @@ interface Props {
   id?: string | undefined
   class?: string | undefined
   'aria-labelledby'?: string | undefined
+  /** The component this section is (`hero`, `card-grid`): `data-kit-section`'s value, the hook a theme or a design layer styles one kind of section by. */
+  kit?: string | undefined
   /** The source section's measured style (`MeasuredStyle`): frame width, padding, fill, image, columns, gap. Wins over `tone`. */
   measured?: MeasuredStyle | undefined
 }
 
-const { tone: given, spacing, width = 'page', as: Tag = 'section', id, class: className, 'aria-labelledby': labelledBy, measured } = Astro.props
+const { tone: given, spacing, width = 'page', as: Tag = 'section', id, class: className, 'aria-labelledby': labelledBy, kit, measured } = Astro.props
 const m = measuredFrame(measured)
 // A measured fill is the section's own colour, its text set by the measured tone; a tone alone picks the kit's band.
 const tone = m.color ? 'none' : m.tone === 'dark' ? 'inverse' : m.tone === 'light' ? 'default' : given
-const text = m.color ? (m.tone === 'dark' ? 'text-surface [--color-accent-text:var(--color-accent-text-inverse)]' : 'text-ink') : undefined
+const text = m.color ? (m.tone === 'dark' ? `text-surface [--color-accent-text:var(--color-accent-text-inverse)] ${mutedInverse}` : `text-ink ${mutedReset}`) : undefined
 const layered = m.image || m.overlay ? 'relative isolate overflow-hidden' : undefined
 const style = [m.color && `background-color: ${m.color}`, m.style].filter(Boolean).join('; ') || undefined
 // The reading column reads its own width token.
@@ -58,7 +62,7 @@ const frameStyle = width === 'prose' ? m.frameStyle?.replace('--container-page:'
 const backdrop = safeSrc(m.image?.src)
 const dataTone = m.color ? (m.tone === 'dark' ? 'inverse' : 'default') : tone ?? 'default'
 ---
-<Tag id={id} aria-labelledby={labelledBy} class={section({ tone, spacing, class: [text, layered, className].filter(Boolean).join(' ') || undefined })} style={style} data-tone={dataTone} data-kit-section data-kit-spacing={spacing ?? 'md'} data-kit-measured={measured ? '' : undefined}>
+<Tag id={id} aria-labelledby={labelledBy} class={section({ tone, spacing, class: [text, layered, className].filter(Boolean).join(' ') || undefined })} style={style} data-tone={dataTone} data-kit-section={kit ?? ''} data-kit-spacing={spacing ?? 'md'} data-kit-measured={measured ? '' : undefined}>
   {m.image && backdrop && <img src={backdrop} alt="" loading="lazy" decoding="async" class="absolute inset-0 -z-10 h-full w-full" style={`object-fit: ${m.image.fit}${m.image.position ? `; object-position: ${m.image.position}` : ''}`} />}
   {m.overlay && <div class="absolute inset-0 -z-10" style={`background: ${m.overlay}`} aria-hidden="true" />}
   {width === 'none' ? <slot /> : <div class={width === 'prose' ? 'container-prose' : 'container-page'} style={frameStyle}><slot /></div>}

package/components/_shared/SectionHeader.astro

@@ -3,6 +3,7 @@
 // section components that have no header of their own use it; with none of the four given it draws nothing.
 import Button from './Button.astro'
 import type { ActionInput } from './types'
+import { muted } from './muted'
 
 interface Props {
   heading?: string | undefined
@@ -19,9 +20,9 @@ const Heading = `h${headingLevel}` as 'h2' | 'h3'
 ---
 {(heading || intro || eyebrow || actions.length > 0) && (
   <header class="mb-10 flex max-w-2xl flex-col gap-3">
-    {eyebrow && <p class="text-sm font-semibold tracking-wide uppercase opacity-80">{eyebrow}</p>}
+    {eyebrow && <p class:list={['text-sm font-semibold tracking-wide uppercase', muted]}>{eyebrow}</p>}
     {heading && <Heading id={headingId} class="text-3xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-4xl">{heading}</Heading>}
-    {intro && <p class="text-lg opacity-80" data-kit-text>{intro}</p>}
+    {intro && <p class:list={['text-lg', muted]} data-kit-text>{intro}</p>}
     {actions.length > 0 && <div class="mt-2 flex flex-wrap gap-3">{actions.map(action => <Button action={action} />)}</div>}
   </header>
 )}

package/components/_shared/instance-id.ts

@@ -0,0 +1,24 @@
+// A component's id when the page gives none. Its tabs, lightboxes, labels and buttons point at elements by id
+// (`aria-controls`, `popovertarget`, `for`), so two instances on one page that both took the same default (two galleries,
+// two FAQs, two newsletters) would point into each other: a click in the second opened the first one's image. Each
+// default is taken once per page instead: `gallery`, then `gallery-2`, `gallery-3`, in the order the page renders
+// them, the same on every build. An id the page gives is kept as it is, and a default steps around it.
+
+const taken = new WeakMap<object, Set<string>>()
+
+/** `given` when set, else `base`, `base-2`, … — the first one not yet used on this page (`page` = `Astro.locals`). */
+export function instanceId(page: object, given: string | undefined, base: string): string {
+  let ids = taken.get(page)
+  if (!ids) {
+    ids = new Set()
+    taken.set(page, ids)
+  }
+  if (given) {
+    ids.add(given)
+    return given
+  }
+  let id = base
+  for (let n = 2; ids.has(id); n++) id = `${base}-${n}`
+  ids.add(id)
+  return id
+}

package/components/_shared/muted.ts

@@ -0,0 +1,19 @@
+// Quieter text (an intro, a caption, a role, a footer link) in a colour role, never a dimmed ink: opacity lays the
+// text over whatever is behind it, and on a mid-tone band that falls under 4.5:1. The role is the one made for the
+// band the text sits on. A band sets `--kit-muted` (dark: `--color-ink-muted-inverse`, a fill: its own ink), a light
+// surface inside it (a card, a form panel, a drawer) clears it again, and without either it is `--color-ink-muted`.
+
+/** Quieter text: the band's muted role. */
+export const muted = 'text-[color:var(--kit-muted,var(--color-ink-muted))]'
+
+/** On a dark band: the muted role made for it, or the band's own text where the site's theme has none. */
+export const mutedInverse = '[--kit-muted:var(--color-ink-muted-inverse,var(--color-surface))]'
+
+/** On the accent fill: no muted role is made for it, so quieter text there is the fill's own ink. */
+export const mutedAccent = '[--kit-muted:var(--color-accent-ink)]'
+
+/** On the brand fill: the fill's own ink, as on the accent. */
+export const mutedBrand = '[--kit-muted:var(--color-brand-ink)]'
+
+/** A light surface inside a band (a card, a form panel, a drawer): back to the page's muted role. */
+export const mutedReset = '[--kit-muted:initial]'

package/components/band/Band.astro

@@ -9,6 +9,8 @@ import Section, { type Tone } from '../_shared/Section.astro'
 import { measuredGrid } from '../_shared/measured'
 import type { ActionInput, ImageInput, MeasuredStyle } from '../_shared/types'
 import { safeHref } from '../_shared/safe-url'
+import { instanceId } from '../_shared/instance-id'
+import { muted } from '../_shared/muted'
 
 const band = tv({
   slots: {
@@ -16,16 +18,16 @@ const band = tv({
     copy: 'flex max-w-3xl flex-col gap-4',
     eyebrow: 'text-sm font-semibold tracking-wide text-accent-text uppercase',
     heading: 'text-3xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-4xl',
-    lead: 'text-lg text-pretty opacity-85',
+    lead: `text-lg text-pretty ${muted}`,
     media: 'overflow-hidden rounded-[var(--radius-image,var(--radius-card))]',
     list: 'grid items-start gap-6 md:gap-8',
     item: 'relative flex flex-col gap-3 rounded-[var(--radius-card)]',
     itemMedia: 'overflow-hidden rounded-[var(--radius-image,var(--radius-card))]',
     itemTitle: 'text-lg leading-snug [font-weight:var(--font-weight-heading,600)] text-balance',
     itemValue: 'text-4xl [font-weight:var(--font-weight-heading,700)] tracking-tight',
-    itemMeta: 'text-sm opacity-75',
-    itemText: 'opacity-80',
-    itemPoints: 'flex list-disc flex-col gap-1 ps-5 opacity-80',
+    itemMeta: `text-sm ${muted}`,
+    itemText: muted,
+    itemPoints: `flex list-disc flex-col gap-1 ps-5 ${muted}`,
     actions: 'flex flex-wrap gap-3',
   },
   variants: {
@@ -42,7 +44,7 @@ const band = tv({
       center: { copy: 'mx-auto items-center text-center', actions: 'justify-center', item: 'items-center text-center' },
     },
     // Accent backgrounds have the least contrast headroom: text on them is never dimmed.
-    tone: { default: {}, muted: {}, inverse: {}, accent: { lead: 'opacity-100', itemText: 'opacity-100', itemMeta: 'opacity-100', itemPoints: 'opacity-100', eyebrow: 'text-current' } },
+    tone: { default: {}, muted: {}, inverse: {}, accent: { eyebrow: 'text-current' } },
   },
   defaultVariants: { layout: 'stack', columns: '3', align: 'start', tone: 'default' },
 })
@@ -89,10 +91,11 @@ const aligned = align ?? (measured?.align === 'center' ? 'center' : undefined)
 const s = band({ layout: media ? layout : 'stack', columns, align: aligned, tone })
 const Heading = `h${headingLevel}` as 'h2' | 'h3'
 const ItemHeading = `h${heading ? headingLevel + 1 : headingLevel}` as 'h2' | 'h3' | 'h4'
-const headingId = heading ? (id ? `${id}-title` : `band-${heading.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`) : undefined
+// Two bands with the same heading on one page get two ids (`band-<heading>`, then `band-<heading>-2`).
+const headingId = heading ? (id ? `${id}-title` : instanceId(Astro.locals, undefined, `band-${heading.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`)) : undefined
 const hasCopy = Boolean(heading || eyebrow || lead || actions.length)
 ---
-<Section tone={tone} id={id} aria-labelledby={headingId} measured={measured}>
+<Section kit="band" tone={tone} id={id} aria-labelledby={headingId} measured={measured}>
   <div class="flex flex-col gap-10">
     {(hasCopy || media) && (
       <div class={s.grid()}>

package/components/band/meta.json

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

package/components/behavior/Behavior.astro

@@ -9,6 +9,7 @@
 // nothing hidden. Only a page that has an island loads the module (Astro bundles a component's script once, for the
 // pages that use it).
 import Section from '../_shared/Section.astro'
+import { instanceId } from '../_shared/instance-id'
 import type { MeasuredStyle } from '../_shared/types'
 
 interface Props {
@@ -29,9 +30,13 @@ interface Props {
   tone?: 'default' | 'muted' | 'inverse' | 'accent' | undefined
   /** The source section's measured style (`MeasuredStyle`). */
   measured?: MeasuredStyle | undefined
+  /** Section id, unique per page; without one `behavior`, `behavior-2`, … in render order. */
+  id?: string | undefined
 }
 
-const { kind, html, items, title, panel, fact, previousLabel, nextLabel, closeLabel, tone, measured } = Astro.props
+const { kind, html, items, title, panel, fact, previousLabel, nextLabel, closeLabel, tone, measured, id: givenId } = Astro.props
+// Every section has an id, so a theme or a design layer can address this one: the page's, or `behavior`, `behavior-2`, … in render order.
+const id = instanceId(Astro.locals, givenId, 'behavior')
 // Selectors and ids go into attributes only, never into markup or a script; an empty one is left out.
 const attr = (value: string | undefined): string | undefined => (value && value.length <= 300 ? value : undefined)
 const factId = fact && /^[\w:.-]{1,120}$/.test(fact) ? fact : undefined
@@ -39,7 +44,7 @@ const factId = fact && /^[\w:.-]{1,120}$/.test(fact) ? fact : undefined
 const NOSCRIPT = '<style>.cr-behavior dialog:not([open]){display:block;position:static;margin:0;max-width:none}</style>'
 ---
 {html && (
-  <Section tone={tone} measured={measured}>
+  <Section kit="behavior" tone={tone} id={id} measured={measured}>
     <div
       class="cr-behavior"
       data-cr-behavior={kind}

package/components/behavior/fixtures.json

@@ -39,7 +39,7 @@
       "kind": "disclosure",
       "fact": "interactive:fx3",
       "tone": "inverse",
-      "html": "<h2><button aria-expanded=\"false\" aria-controls=\"cr-fx3-a\">Do you ship abroad?</button></h2><div id=\"cr-fx3-a\"><p>Yes, to the whole of Europe.</p></div><details><summary>Can I return an order?</summary><p>Within 30 days.</p></details>"
+      "html": "<h2><button aria-expanded=\"false\" aria-controls=\"cr-fx5-a\">Do you ship abroad?</button></h2><div id=\"cr-fx5-a\"><p>Yes, to the whole of Europe.</p></div><details><summary>Can I return an order?</summary><p>Within 30 days.</p></details>"
     }
   },
   {
@@ -48,7 +48,7 @@
       "kind": "disclosure",
       "fact": "interactive:fx3",
       "tone": "accent",
-      "html": "<h2><button aria-expanded=\"false\" aria-controls=\"cr-fx3-a\">Do you ship abroad?</button></h2><div id=\"cr-fx3-a\"><p>Yes, to the whole of Europe.</p></div><details><summary>Can I return an order?</summary><p>Within 30 days.</p></details>"
+      "html": "<h2><button aria-expanded=\"false\" aria-controls=\"cr-fx6-a\">Do you ship abroad?</button></h2><div id=\"cr-fx6-a\"><p>Yes, to the whole of Europe.</p></div><details><summary>Can I return an order?</summary><p>Within 30 days.</p></details>"
     }
   },
   {"name": "video-link", "props": {"kind": "anchor", "fact": "interactive:fx5", "html": "<h2>Studio tour</h2><p>A walk through the workshop.</p><a href=\"https://www.youtube.com/watch?v=aqz-KE-bpKQ\" target=\"_blank\" rel=\"noopener noreferrer\" data-cr-video=\"youtube:aqz-KE-bpKQ\"><img src=\"/kit-fixtures/photo-2.svg\" alt=\"\" loading=\"lazy\" width=\"1200\" height=\"800\"><span>Studio tour</span></a>"}},