@contentrain/astro-kit 0.21.0 → 0.22.0

package/catalog.json

@@ -276,7 +276,7 @@
           "max": 3,
           "default": 2,
           "content": false,
-          "description": "Level of the section heading; card titles are one below."
+          "description": "Level of the section heading; card titles are one below, or at this level when there is no title."
         }
       },
       "slots": {},
@@ -507,7 +507,7 @@
     {
       "id": "contact-form",
       "name": "Contact form",
-      "description": "The contact section: heading, introduction, contact details (email, phone, address) and a Contentrain Studio form — fields, spam protection and notifications set in Studio, submissions reviewed there. Replaces form plugins; renders the details alone until the site is bound to a Studio project. When the owner chose another home at migration (site.config.ts `features.forms`) the form posts to their form service, or the section shows an address to write to or a link to the form on WordPress.",
+      "description": "The contact section: heading, introduction, contact details (email, phone, address) and a Contentrain Studio form — fields, spam protection and notifications set in Studio, submissions reviewed there. Replaces form plugins; renders the details alone until the site is bound to a Studio project (a section left with only its heading is not drawn: the heading would title a form that is not there). When the owner chose another home at migration (site.config.ts `features.forms`) the form posts to their form service, or the section shows an address to write to or a link to the form on WordPress.",
       "category": "section",
       "uses": [],
       "shared": [
@@ -612,9 +612,10 @@
           "classic/ninja-forms"
         ]
       },
-      "a11y": "Contact details are a description list when every one has a label, a plain list otherwise; links say what they open. The form's labels, errors and focus handling are Studio's form runtime (FormMount). The section is labelled by its heading.",
+      "a11y": "Contact details are a description list when every one has a label, a plain list otherwise; links say what they open. The form's labels, errors and focus handling are Studio's form runtime (FormMount). The section is labelled by its heading. Without a form to show and with no introduction or details, the section is not drawn at all.",
       "files": [
-        "ContactForm.astro"
+        "ContactForm.astro",
+        "contact-form.ts"
       ],
       "contentFields": {
         "heading": "heading",
@@ -1098,7 +1099,7 @@
           "divi/et_pb_blurb"
         ]
       },
-      "a11y": "A list; icons are decorative (aria-hidden), the title and text carry the meaning. The section is labelled by its heading.",
+      "a11y": "A list; icons are decorative (aria-hidden), the title and text carry the meaning. Each title is an <h3> under the section's <h2>, or an <h2> when the section has no heading (the list style's are plain text). The section is labelled by its heading.",
       "pattern": {
         "summary": "repeated icon + short title + line of text",
         "signals": [
@@ -1672,6 +1673,14 @@
           ],
           "default": "full",
           "description": "Layout cover only. full: the image runs the full window width. content: the cover sits in the reading column, as a WordPress cover block that is not alignfull does under the page title."
+        },
+        "headingScale": {
+          "options": [
+            "default",
+            "theme"
+          ],
+          "default": "default",
+          "description": "default: the layout's own type scale. theme: the heading takes the site's size for its level (`--text-heading-1` for the page-opening hero, `-2` otherwise), as the source's own h1 does under a block theme."
         }
       },
       "props": {
@@ -1770,6 +1779,13 @@
           "type": "string",
           "content": false,
           "description": "Anchor id of the section; the heading gets `<id>-title`."
+        },
+        "minHeight": {
+          "type": "integer",
+          "content": false,
+          "min": 100,
+          "max": 2000,
+          "description": "Layout cover only: the cover's own height in pixels, as the source sets it (520); absent, the layout's default."
         }
       },
       "slots": {},
@@ -1790,7 +1806,8 @@
       },
       "a11y": "A labelled region (aria-labelledby the heading). One h1 by default; `level: 2` inside pages that already have one. The cover image is decorative when its alt is empty; text sits on an ink scrim for contrast.",
       "files": [
-        "Hero.astro"
+        "Hero.astro",
+        "hero.ts"
       ],
       "contentFields": {
         "heading": "heading",
@@ -2510,7 +2527,7 @@
           "divi/et_pb_pricing_tables"
         ]
       },
-      "a11y": "Plans are a <ul>; each name is an <h3>. A featured plan is marked by a text badge and a ring, not colour alone. Buttons are links with their own label.",
+      "a11y": "Plans are a <ul>; each name is an <h3> under the section's <h2>, or an <h2> when the section has no heading. A featured plan is marked by a text badge and a ring, not colour alone. Buttons are links with their own label.",
       "pattern": {
         "summary": "repeated plan units: name + price + feature list + button",
         "signals": [
@@ -3180,7 +3197,7 @@
           "divi/et_pb_blurb"
         ]
       },
-      "a11y": "Steps are an <ol>, so their order and count are announced; the visible numbers are CSS counters, not text. Each title is an <h3>. The section is labelled by its heading when it has one.",
+      "a11y": "Steps are an <ol>, so their order and count are announced; the visible numbers are CSS counters, not text. Each title is an <h3> under the section's <h2>, or an <h2> when the section has no heading. The section is labelled by its heading when it has one.",
       "pattern": {
         "summary": "ordered sequence: numbered title + short text units",
         "signals": [
@@ -3291,7 +3308,7 @@
           "classic/tabs"
         ]
       },
-      "a11y": "Zag.js tabs: role=tablist/tab/tabpanel with aria-selected, aria-controls and aria-labelledby; arrow keys (per orientation), Home and End move between tabs. Before the script runs every panel is visible with its own h3 title; after, the titles become screen-reader-only and the tabs label the panels.",
+      "a11y": "Zag.js tabs: role=tablist/tab/tabpanel with aria-selected, aria-controls and aria-labelledby; arrow keys (per orientation), Home and End move between tabs. Before the script runs every panel is visible with its own title (an h3 under the section's h2, an h2 when there is no heading); after, the titles become screen-reader-only and the tabs label the panels.",
       "files": [
         "Tabs.astro"
       ]
@@ -3408,7 +3425,7 @@
           "divi/et_pb_team_member"
         ]
       },
-      "a11y": "Members are a <ul>; each name is an <h3>, and a linked member's link text is the name. A portrait's text defaults to the name. The section is labelled by its heading when it has one.",
+      "a11y": "Members are a <ul>; each name is an <h3> under the section's <h2> (an <h2> when the section has no heading), and a linked member's link text is the name. A portrait's text defaults to the name. The section is labelled by its heading when it has one.",
       "pattern": {
         "summary": "repeated person units: portrait + name + role",
         "signals": [

package/components/card-grid/CardGrid.astro

@@ -44,7 +44,7 @@ interface Props {
   title?: string | undefined
   intro?: string | undefined
   items: Item[]
-  /** Heading level of the section title; card titles are one level below. */
+  /** Heading level of the section title; card titles are one level below, or at this level when there is no title. */
   headingLevel?: 2 | 3 | undefined
   columns?: '2' | '3' | '4' | undefined
   style?: 'plain' | 'bordered' | 'elevated' | undefined
@@ -57,7 +57,8 @@ const { list, card, media, title: cardTitle, text } = grid({ columns, style, ali
 // Accent backgrounds have the least contrast headroom: text on them is never dimmed.
 const dim = tone === 'accent' ? 'opacity-100' : undefined
 const Heading = `h${headingLevel}` as 'h2' | 'h3'
-const CardHeading = `h${headingLevel + 1}` as 'h3' | 'h4'
+// One level under the section title, or the title's level when there is none.
+const CardHeading = `h${title ? headingLevel + 1 : headingLevel}` as 'h2' | 'h3' | 'h4'
 const headingId = title ? `cards-${title.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : undefined
 ---
 <Section tone={tone} aria-labelledby={headingId}>

package/components/card-grid/meta.json

@@ -107,7 +107,7 @@
       "max": 3,
       "default": 2,
       "content": false,
-      "description": "Level of the section heading; card titles are one below."
+      "description": "Level of the section heading; card titles are one below, or at this level when there is no title."
     }
   },
   "slots": {},

package/components/contact-form/ContactForm.astro

@@ -4,7 +4,8 @@
 // StudioForm): its fields, spam protection and notifications live in Studio,
 // and submissions arrive there for review — no form plugin, no mail server.
 // Until the site is bound to a Studio project the form renders nothing and the
-// contact details still show. When the owner chose another home for forms at
+// contact details still show — and a section left with its heading alone is not
+// drawn (a heading over a form that is not there). When the owner chose another home for forms at
 // migration (site.config.ts `features.forms`), the same place holds a form
 // that posts to their form service, an address to write to, or a link to the
 // form on WordPress.
@@ -12,6 +13,7 @@ import { tv } from 'tailwind-variants'
 import Section from '../_shared/Section.astro'
 import StudioForm from '../../studio/StudioForm.astro'
 import { formHome } from '../../../lib/features'
+import { contactSectionBare } from './contact-form'
 
 export interface ContactDetail {
   /** What the detail is (Phone, Email); a source's icon list often has none. */
@@ -69,6 +71,7 @@ interface Props {
 const { model, heading, intro, formHeading, details = [], layout, align, tone, id = 'contact' } = Astro.props
 // Nothing to render (Studio not bound yet): a split would leave an empty column — the details stand alone.
 const formShown = formHome(model) !== null
+const bare = contactSectionBare({ formShown, intro, details })
 const s = contact({ layout: formShown ? layout : 'stacked', align, tone })
 const headingId = heading ? `${id}-title` : undefined
 // A description list needs a term for every detail; an icon list carried from the source has values only.
@@ -77,6 +80,7 @@ const LINK = 'underline decoration-line underline-offset-4 hover:decoration-curr
 // One level under the section heading, or the section's heading when there is none.
 const FormHeading = heading ? 'h3' : 'h2'
 ---
+{!bare && (
 <Section tone={tone} spacing="md" id={id} aria-labelledby={headingId}>
   <div class={s.grid()}>
     {(heading || intro || details.length > 0) && (
@@ -116,3 +120,4 @@ const FormHeading = heading ? 'h3' : 'h2'
       : <StudioForm model={model} class={s.form()} />)}
   </div>
 </Section>
+)}

package/components/contact-form/contact-form.ts

@@ -0,0 +1,8 @@
+// When the contact section has nothing to show. Its form is drawn only where a home for it exists (Studio bound, the
+// WordPress page known, a service address that is https); until then the section stands on its heading, introduction
+// and details. A section left with a heading ALONE titles a form that is not there — the page would print "Tell us about
+// your project" over empty space — so it is not drawn at all, and appears with its form once the form has a home.
+
+export function contactSectionBare(input: { formShown: boolean, intro?: string | undefined, details?: readonly unknown[] | undefined }): boolean {
+  return !input.formShown && !input.intro && !(input.details?.length ?? 0)
+}

package/components/contact-form/fixtures.json

@@ -12,9 +12,9 @@
       ]
     }
   },
-  { "name": "stacked-muted", "props": { "model": "contact-submissions", "heading": "Write to us", "layout": "stacked", "tone": "muted", "id": "write" } },
+  { "name": "stacked-muted", "props": { "model": "contact-submissions", "heading": "Write to us", "intro": "We read every message and answer within two working days.", "layout": "stacked", "tone": "muted", "id": "write" } },
   { "name": "stacked-start", "props": { "model": "contact-submissions", "intro": "Tell us what you make and when you want to launch.", "details": [{ "value": "Studio 4, Harbour Lane" }], "layout": "stacked", "align": "start", "id": "start" } },
   { "name": "split-inverse", "props": { "model": "contact-submissions", "heading": "Press", "tone": "inverse", "id": "press", "details": [{ "label": "Press office", "value": "press@northwind.example", "href": "mailto:press@northwind.example" }] } },
-  { "name": "stacked-accent", "props": { "model": "newsletter-requests", "heading": "Request a print copy", "layout": "stacked", "tone": "accent", "id": "print" } },
+  { "name": "stacked-accent", "props": { "model": "newsletter-requests", "heading": "Request a print copy", "intro": "Print copies ship in the first week of each quarter.", "layout": "stacked", "tone": "accent", "id": "print" } },
   { "name": "form-heading", "props": { "model": "contact-submissions", "heading": "Contact", "intro": "Tell us where you are and what you need.", "formHeading": "Tell us about your project", "details": [{ "label": "Address", "value": "12 Harbour Street, Leith" }] } }
 ]

package/components/contact-form/meta.json

@@ -1,7 +1,7 @@
 {
   "id": "contact-form",
   "name": "Contact form",
-  "description": "The contact section: heading, introduction, contact details (email, phone, address) and a Contentrain Studio form — fields, spam protection and notifications set in Studio, submissions reviewed there. Replaces form plugins; renders the details alone until the site is bound to a Studio project. When the owner chose another home at migration (site.config.ts `features.forms`) the form posts to their form service, or the section shows an address to write to or a link to the form on WordPress.",
+  "description": "The contact section: heading, introduction, contact details (email, phone, address) and a Contentrain Studio form — fields, spam protection and notifications set in Studio, submissions reviewed there. Replaces form plugins; renders the details alone until the site is bound to a Studio project (a section left with only its heading is not drawn: the heading would title a form that is not there). When the owner chose another home at migration (site.config.ts `features.forms`) the form posts to their form service, or the section shows an address to write to or a link to the form on WordPress.",
   "category": "section",
   "uses": [],
   "shared": ["Section.astro"],
@@ -26,5 +26,5 @@
     "divi": ["divi/et_pb_contact_form"],
     "classic": ["classic/contact-form-7", "classic/wpforms", "classic/gravityforms", "classic/ninja-forms"]
   },
-  "a11y": "Contact details are a description list when every one has a label, a plain list otherwise; links say what they open. The form's labels, errors and focus handling are Studio's form runtime (FormMount). The section is labelled by its heading."
+  "a11y": "Contact details are a description list when every one has a label, a plain list otherwise; links say what they open. The form's labels, errors and focus handling are Studio's form runtime (FormMount). The section is labelled by its heading. Without a form to show and with no introduction or details, the section is not drawn at all."
 }

package/components/feature-list/FeatureList.astro

@@ -64,7 +64,8 @@ const { heading, intro, items, columns, style = 'icon', tone, id } = Astro.props
 const s = list({ columns, style, tone })
 const headingId = heading && id ? `${id}-title` : undefined
 const pathOf = (item: Item) => (style !== 'check' && item.icon && icons[item.icon]) || icons.check
-const Title = style === 'list' ? 'span' : 'h3'
+// A plain list's items are not headings; otherwise one level under the section heading, or the section's when there is none.
+const Title = style === 'list' ? 'span' : heading ? 'h3' : 'h2'
 ---
 <Section tone={tone} id={id} aria-labelledby={headingId}>
   {(heading || intro) && (

package/components/feature-list/meta.json

@@ -106,7 +106,7 @@
       "divi/et_pb_blurb"
     ]
   },
-  "a11y": "A list; icons are decorative (aria-hidden), the title and text carry the meaning. The section is labelled by its heading.",
+  "a11y": "A list; icons are decorative (aria-hidden), the title and text carry the meaning. Each title is an <h3> under the section's <h2>, or an <h2> when the section has no heading (the list style's are plain text). The section is labelled by its heading.",
   "pattern": {
     "summary": "repeated icon + short title + line of text",
     "signals": [

package/components/hero/Hero.astro

@@ -6,6 +6,7 @@ import Button from '../_shared/Button.astro'
 import KitImage from '../_shared/KitImage.astro'
 import Section from '../_shared/Section.astro'
 import type { ActionInput, ImageInput } from '../_shared/types'
+import { coverHeight as heightOf, headingStyle as styleOf } from './hero'
 
 const hero = tv({
   slots: {
@@ -36,6 +37,8 @@ const hero = tv({
     // How wide a cover runs: the full window, or the reading column — a WordPress cover block that is not
     // alignfull sits in the content column, the page title above it.
     width: { full: {}, content: {} },
+    // The heading's size: the layout's own scale, or the site's size for its level (set inline, see ./hero).
+    headingScale: { default: {}, theme: {} },
   },
   compoundVariants: [
     // After the layout's own heights, so a boxed cover keeps WordPress's 430px default.
@@ -45,7 +48,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' },
+  defaultVariants: { layout: 'split', tone: 'default', align: 'center', leadAlign: 'inherit', actionsAlign: 'inherit', width: 'full', headingScale: 'default' },
 })
 
 interface Props {
@@ -67,13 +70,20 @@ interface Props {
   width?: 'full' | 'content' | undefined
   tone?: 'default' | 'muted' | 'inverse' | 'accent' | undefined
   id?: string | undefined
+  /** A cover's own height in pixels, as the source sets it (`520`); absent, the layout's default. Layout cover only. */
+  minHeight?: number | undefined
+  /** `theme`: the heading takes the site's size for its level (the source's own `h1` size), not the layout's scale. */
+  headingScale?: 'default' | 'theme' | undefined
 }
 
-const { heading, level = 1, eyebrow, lead, actions = [], image, layout = 'split', align, leadAlign, actionsAlign, width = 'full', tone, id } = Astro.props
-const s = hero({ layout, align, leadAlign, actionsAlign, width, tone })
+
+const { heading, level = 1, eyebrow, lead, actions = [], image, layout = 'split', align, leadAlign, actionsAlign, width = 'full', tone, id, minHeight, headingScale } = Astro.props
+const s = hero({ layout, align, leadAlign, actionsAlign, width, tone, headingScale })
 const Heading = level === 1 ? 'h1' : 'h2'
 const headingId = id ? `${id}-title` : undefined
 const cover = layout === 'cover' && image
+const coverHeight = cover ? heightOf(minHeight) : undefined
+const headingStyle = styleOf(headingScale, level)
 ---
 {cover && width === 'content'
   ? (
@@ -82,10 +92,10 @@ const cover = layout === 'cover' && image
         <KitImage image={image} priority sizes="(min-width: 768px) 46rem, 100vw" class="absolute inset-0 -z-10 h-full w-full object-cover" />
         <div class="absolute inset-0 -z-10 bg-ink/60" aria-hidden="true" />
         <div class="px-6 py-10 md:px-10">
-          <div class={s.grid()}>
+          <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()}>{heading}</Heading>
+              <Heading id={headingId} class={s.heading()} style={headingStyle}>{heading}</Heading>
               {lead && <p class={s.lead()} data-kit-text>{lead}</p>}
               {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} size="lg" />)}</div>}
             </div>
@@ -100,10 +110,10 @@ const cover = layout === 'cover' && image
       <KitImage image={image} priority sizes="100vw" class="absolute inset-0 -z-10 h-full w-full object-cover" />
       <div class="absolute inset-0 -z-10 bg-ink/60" aria-hidden="true" />
       <div class="container-page py-16 md:py-28">
-        <div class={s.grid()}>
+        <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()}>{heading}</Heading>
+            <Heading id={headingId} class={s.heading()} style={headingStyle}>{heading}</Heading>
             {lead && <p class={s.lead()} data-kit-text>{lead}</p>}
             {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} size="lg" />)}</div>}
           </div>
@@ -117,7 +127,7 @@ const cover = layout === 'cover' && image
       <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()}>{heading}</Heading>
+          <Heading id={headingId} class={s.heading()} style={headingStyle}>{heading}</Heading>
           {lead && <p class={s.lead()} data-kit-text>{lead}</p>}
           {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} size="lg" />)}</div>}
         </div>

package/components/hero/fixtures.json

@@ -167,5 +167,29 @@
       "level": 2,
       "actionsAlign": "start"
     }
+  },
+  {
+    "name": "cover-content-theme-size",
+    "props": {
+      "heading": "Independent cinema, a neighbourhood hall",
+      "lead": "A hundred and twenty seats, fresh popcorn.",
+      "layout": "cover",
+      "actions": [
+        {
+          "label": "This week's programme",
+          "href": "/programme/"
+        }
+      ],
+      "image": {
+        "src": "/kit-fixtures/photo-1.svg",
+        "alt": "",
+        "width": 1600,
+        "height": 900
+      },
+      "width": "content",
+      "level": 2,
+      "minHeight": 520,
+      "headingScale": "theme"
+    }
   }
 ]

package/components/hero/hero.ts

@@ -0,0 +1,9 @@
+// A cover's height reaches the style attribute only as a whole number of pixels: a value from a plan is data, not CSS.
+export const coverHeight = (value: number | undefined): string | undefined => (Number.isInteger(value) && value! >= 100 && value! <= 2000 ? `${value}px` : undefined)
+
+/**
+ * `theme`: the heading's size is the site's for its level, the one the source's own `h1`/`h2` has (`--text-heading-1`,
+ * fluid where the theme's is); the layout's scale is the fallback while the site declares none.
+ */
+export const headingStyle = (scale: 'default' | 'theme' | undefined, level: 1 | 2): string | undefined =>
+  scale === 'theme' ? `font-size: var(--text-heading-${level}, var(--text-5xl)); line-height: var(--leading-heading, 1.2)` : undefined

package/components/hero/meta.json

@@ -61,6 +61,14 @@
       ],
       "default": "full",
       "description": "Layout cover only. full: the image runs the full window width. content: the cover sits in the reading column, as a WordPress cover block that is not alignfull does under the page title."
+    },
+    "headingScale": {
+      "options": [
+        "default",
+        "theme"
+      ],
+      "default": "default",
+      "description": "default: the layout's own type scale. theme: the heading takes the site's size for its level (`--text-heading-1` for the page-opening hero, `-2` otherwise), as the source's own h1 does under a block theme."
     }
   },
   "props": {
@@ -159,6 +167,13 @@
       "type": "string",
       "content": false,
       "description": "Anchor id of the section; the heading gets `<id>-title`."
+    },
+    "minHeight": {
+      "type": "integer",
+      "content": false,
+      "min": 100,
+      "max": 2000,
+      "description": "Layout cover only: the cover's own height in pixels, as the source sets it (520); absent, the layout's default."
     }
   },
   "slots": {},

package/components/pricing/Pricing.astro

@@ -61,6 +61,8 @@ interface Props {
 const { heading, intro, plans, featuredLabel = 'Most popular', columns, tone, id } = Astro.props
 const s = pricing({ columns, tone })
 const headingId = heading && id ? `${id}-title` : undefined
+// One level under the section heading, or the section's heading when there is none.
+const PlanHeading = heading ? 'h3' : 'h2'
 const features = await Promise.all(plans.map(plan => renderMarkdown(plan.features)))
 ---
 {plans.length > 0 && (
@@ -75,7 +77,7 @@ const features = await Promise.all(plans.map(plan => renderMarkdown(plan.feature
       {plans.map((plan, i) => (
         <li class={s.plan({ class: plan.featured ? 'ring-2 ring-accent shadow-lg md:-my-2 md:py-10' : undefined })}>
           {plan.featured && <p class={s.badge()}>{featuredLabel}</p>}
-          <h3 class={s.name()}>{plan.name}</h3>
+          <PlanHeading class={s.name()}>{plan.name}</PlanHeading>
           <p class={s.price()}>
             <span class={s.amount()}>{plan.price}</span>
             {plan.period && <span class={s.period()}>{plan.period}</span>}

package/components/pricing/meta.json

@@ -120,7 +120,7 @@
       "divi/et_pb_pricing_tables"
     ]
   },
-  "a11y": "Plans are a <ul>; each name is an <h3>. A featured plan is marked by a text badge and a ring, not colour alone. Buttons are links with their own label.",
+  "a11y": "Plans are a <ul>; each name is an <h3> under the section's <h2>, or an <h2> when the section has no heading. A featured plan is marked by a text badge and a ring, not colour alone. Buttons are links with their own label.",
   "pattern": {
     "summary": "repeated plan units: name + price + feature list + button",
     "signals": [

package/components/steps/Steps.astro

@@ -60,6 +60,8 @@ interface Props {
 const { heading, intro, items, layout, style, id } = Astro.props
 const s = steps({ layout, style })
 const headingId = heading && id ? `${id}-title` : undefined
+// One level under the section heading, or the section's heading when there is none.
+const StepHeading = heading ? 'h3' : 'h2'
 ---
 {items.length > 0 && (
   <Section id={id} aria-labelledby={headingId}>
@@ -75,7 +77,7 @@ const headingId = heading && id ? `${id}-title` : undefined
           {step.number && <span class={s.badge()} aria-hidden="true">{step.number}</span>}
           <div class={s.body()}>
             {imageOf(step.image, step.imageAlt) && <div class={s.media()}><KitImage image={imageOf(step.image, step.imageAlt)!} sizes="(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw" class="aspect-[3/2] w-full object-cover" /></div>}
-            <h3 class={s.title()}>{step.title}</h3>
+            <StepHeading class={s.title()}>{step.title}</StepHeading>
             <p class={s.text()} data-kit-text>{step.text}</p>
           </div>
         </li>

package/components/steps/meta.json

@@ -97,7 +97,7 @@
       "divi/et_pb_blurb"
     ]
   },
-  "a11y": "Steps are an <ol>, so their order and count are announced; the visible numbers are CSS counters, not text. Each title is an <h3>. The section is labelled by its heading when it has one.",
+  "a11y": "Steps are an <ol>, so their order and count are announced; the visible numbers are CSS counters, not text. Each title is an <h3> under the section's <h2>, or an <h2> when the section has no heading. The section is labelled by its heading when it has one.",
   "pattern": {
     "summary": "ordered sequence: numbered title + short text units",
     "signals": [

package/components/tabs/Tabs.astro

@@ -52,6 +52,8 @@ interface Props {
 const { items, heading, label, style, orientation = 'horizontal', tone, id = 'tabs' } = Astro.props
 const s = tabs({ style, orientation, tone })
 const headingId = heading ? `${id}-title` : undefined
+// One level under the section heading, or the section's heading when there is none.
+const PanelHeading = heading ? 'h3' : 'h2'
 const value = (i: number) => `tab-${i + 1}`
 ---
 {items.length > 0 && (
@@ -63,7 +65,7 @@ const value = (i: number) => `tab-${i + 1}`
       </div>
       {items.map((item, i) => (
         <div data-part="content" data-value={value(i)} class="min-w-0 flex-1">
-          <h3 class={s.title()}>{item.label}</h3>
+          <PanelHeading class={s.title()}>{item.label}</PanelHeading>
           <div class={s.panel()} set:html={item.content} />
         </div>
       ))}

package/components/tabs/meta.json

@@ -24,5 +24,5 @@
     "divi": ["divi/et_pb_tabs"],
     "classic": ["classic/tabs"]
   },
-  "a11y": "Zag.js tabs: role=tablist/tab/tabpanel with aria-selected, aria-controls and aria-labelledby; arrow keys (per orientation), Home and End move between tabs. Before the script runs every panel is visible with its own h3 title; after, the titles become screen-reader-only and the tabs label the panels."
+  "a11y": "Zag.js tabs: role=tablist/tab/tabpanel with aria-selected, aria-controls and aria-labelledby; arrow keys (per orientation), Home and End move between tabs. Before the script runs every panel is visible with its own title (an h3 under the section's h2, an h2 when there is no heading); after, the titles become screen-reader-only and the tabs label the panels."
 }

package/components/team/Team.astro

@@ -57,6 +57,8 @@ interface Props {
 const { heading, intro, items, columns, style, roleStyle, id } = Astro.props
 const s = team({ columns, style, roleStyle })
 const headingId = heading && id ? `${id}-title` : undefined
+// One level under the section heading, or the section's heading when there is none.
+const NameHeading = heading ? 'h3' : 'h2'
 ---
 {items.length > 0 && (
   <Section id={id} aria-labelledby={headingId}>
@@ -71,11 +73,11 @@ const headingId = heading && id ? `${id}-title` : undefined
         <li class={s.member()}>
           {/* The portrait's text defaults to the name: a photo of a named person is not decoration. */}
           {imageOf(member.image, member.imageAlt ?? member.name) && <div class={s.portrait()}><KitImage image={imageOf(member.image, member.imageAlt ?? member.name)!} sizes="(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw" class="aspect-square w-full object-cover" /></div>}
-          <h3 class={s.name()}>
+          <NameHeading class={s.name()}>
             {member.href
               ? <a href={member.href} class="text-current no-underline after:absolute after:inset-0 after:content-[''] hover:text-accent">{member.name}</a>
               : member.name}
-          </h3>
+          </NameHeading>
           {member.role && <p class={s.role()}>{member.role}</p>}
           {member.bio && <p class={s.bio()} data-kit-text>{member.bio}</p>}
         </li>

package/components/team/meta.json

@@ -110,7 +110,7 @@
       "divi/et_pb_team_member"
     ]
   },
-  "a11y": "Members are a <ul>; each name is an <h3>, and a linked member's link text is the name. A portrait's text defaults to the name. The section is labelled by its heading when it has one.",
+  "a11y": "Members are a <ul>; each name is an <h3> under the section's <h2> (an <h2> when the section has no heading), and a linked member's link text is the name. A portrait's text defaults to the name. The section is labelled by its heading when it has one.",
   "pattern": {
     "summary": "repeated person units: portrait + name + role",
     "signals": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/astro-kit",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "license": "MIT",
   "description": "Copy-in Astro components for Contentrain sites (shadcn model): typed props, tailwind-variants, zero JavaScript by default — with a machine-readable catalog",
   "type": "module",
@@ -42,7 +42,7 @@
     "mapping"
   ],
   "dependencies": {
-    "@contentrain/types": "1.39.0"
+    "@contentrain/types": "1.41.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",