@contentrain/astro-kit 0.30.0 → 0.32.0

package/components/cta/Cta.astro

@@ -3,13 +3,21 @@
 // across the full section, or as a card inside it.
 import { tv } from 'tailwind-variants'
 import Button from '../_shared/Button.astro'
+import KitImage from '../_shared/KitImage.astro'
 import Section from '../_shared/Section.astro'
-import type { ActionInput } from '../_shared/types'
+import type { ActionInput, ImageInput, MeasuredStyle } from '../_shared/types'
 
 const cta = tv({
   slots: {
     box: 'flex flex-col gap-6',
     copy: 'flex flex-col gap-3',
+    eyebrow: 'text-sm font-semibold tracking-wide uppercase opacity-80',
+    // The text and buttons when a picture stands beside them.
+    text: 'flex min-w-0 flex-1 flex-col gap-6',
+    // The buttons with the small print under them.
+    cta: 'flex flex-col gap-2 md:shrink-0',
+    note: 'text-sm opacity-75',
+    media: 'w-full max-w-sm shrink-0 overflow-hidden rounded-[var(--radius-image,var(--radius-card))] md:w-2/5',
     heading: 'text-2xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-3xl',
     body: 'max-w-2xl text-pretty opacity-85',
     actions: 'flex flex-wrap gap-3',
@@ -21,13 +29,19 @@ const cta = tv({
       // Heading, text and buttons in one column at the start edge, on every width.
       stacked: { box: 'items-start text-start' },
     },
+    // The heading's scale; `lg` also gives the band more room.
+    size: { md: {}, lg: { heading: 'text-3xl md:text-5xl' } },
+    // The text block's alignment (`centered` already sets its own).
+    align: { start: {}, center: { copy: 'items-center text-center', body: 'mx-auto' } },
+    // With a picture: which side it takes on wide screens (text first in the source).
+    mediaSide: { end: {}, start: { media: 'md:order-first' } },
     frame: {
       full: {},
       card: { box: 'rounded-card border border-line p-8 md:p-12' },
     },
     // 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.
     // none: no fill of its own — the page background and text colour show through.
-    tone: { default: {}, muted: {}, inverse: {}, accent: { body: 'opacity-100' }, brand: { body: 'opacity-100' }, none: {} },
+    tone: { default: {}, muted: {}, inverse: {}, accent: { body: 'opacity-100', eyebrow: 'opacity-100', note: 'opacity-100' }, brand: { body: 'opacity-100', eyebrow: 'opacity-100', note: 'opacity-100' }, none: {} },
     // The buttons' own alignment: `start` keeps them at the start edge under centred text (a WordPress buttons block
     // with no justification sits left in a group whose heading and paragraph are centred). The row is the text's
     // column, as WordPress's content width is, not the whole section. Only centred needs it: inline and stacked
@@ -42,35 +56,61 @@ const cta = tv({
     { frame: 'card', tone: 'accent', class: { box: 'border-transparent bg-accent text-accent-ink' } },
     { frame: 'card', tone: 'brand', class: { box: 'border-transparent bg-brand text-brand-ink' } },
     { layout: 'centered', actionsAlign: 'start', class: { actions: 'w-full max-w-2xl justify-start' } },
+    { layout: 'centered', class: { cta: 'items-center' } },
   ],
-  defaultVariants: { layout: 'inline', frame: 'full', tone: 'accent', actionsAlign: 'inherit' },
+  defaultVariants: { layout: 'inline', frame: 'full', size: 'md', align: 'start', mediaSide: 'end', tone: 'accent', actionsAlign: 'inherit' },
 })
 
 interface Props {
   heading: string
+  eyebrow?: string | undefined
   body?: string | undefined
+  /** The small print under the buttons ("No credit card required"). */
+  note?: string | undefined
+  /** A small picture beside the text. A large one is a `split`. */
+  image?: ImageInput | undefined
   actions: ActionInput[]
   layout?: 'inline' | 'centered' | 'stacked' | undefined
   frame?: 'full' | 'card' | undefined
+  size?: 'md' | 'lg' | undefined
+  align?: 'start' | 'center' | undefined
+  mediaSide?: 'start' | 'end' | undefined
   tone?: 'default' | 'muted' | 'inverse' | 'accent' | 'brand' | 'none' | undefined
   /** The buttons' alignment: as the layout sets it, or at the start edge under centred text (layout centered). */
   actionsAlign?: 'inherit' | 'start' | undefined
+  /** A picture behind the band (its address); the text turns light and an overlay keeps it readable. For `frame` full. */
+  bgImage?: string | undefined
+  /** The colour laid over `bgImage` (default: black at 55 %). */
+  bgOverlay?: string | 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
   id?: string | undefined
 }
 
-const { heading, body, actions, layout, frame, tone = 'accent', actionsAlign, id } = Astro.props
-const s = cta({ layout, frame, tone, actionsAlign })
+const { heading, eyebrow, body, note, image, actions, layout, frame, size, align, mediaSide, tone = 'accent', actionsAlign, bgImage, bgOverlay, measured: given, id } = Astro.props
+const s = cta({ layout, frame, size, align, mediaSide, tone, actionsAlign })
+// A background picture is the section's measured background: Section draws the image and its overlay, and the text
+// turns light so it reads on either.
+const measured: MeasuredStyle | undefined = bgImage
+  ? { ...given, tone: 'dark', bg: { ...given?.bg, image: bgImage, overlay: bgOverlay ?? given?.bg?.overlay ?? 'rgba(0, 0, 0, 0.55)' } }
+  : given
 const headingId = id ? `${id}-title` : undefined
 // On the accent background the primary button (accent) would vanish: it is drawn as the secondary style there.
 const onAccent = (action: ActionInput): ActionInput => ({ label: action.label, href: action.href, newTab: action.newTab, style: 'secondary' })
-const shown = actions.map(action => (tone === 'accent' && (action.style ?? 'primary') === 'primary' ? onAccent(action) : action))
+const shown = actions.map(action => (tone === 'accent' && !bgImage && (action.style ?? 'primary') === 'primary' ? onAccent(action) : action))
 ---
-<Section tone={frame === 'card' ? 'default' : tone} spacing="md" id={id} aria-labelledby={headingId}>
-  <div class={s.box()}>
-    <div class={s.copy()}>
-      <h2 id={headingId} class={s.heading()}>{heading}</h2>
-      {body && <p class={s.body()} data-kit-text>{body}</p>}
+<Section measured={measured} tone={frame === 'card' ? 'default' : tone} spacing={size === 'lg' ? 'lg' : 'md'} id={id} aria-labelledby={headingId}>
+  <div class:list={[s.box(), image && 'md:flex-row md:items-center md:justify-between md:gap-12']}>
+    <div class={image ? s.text() : 'contents'}>
+      <div class={s.copy()}>
+        {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
+        <h2 id={headingId} class={s.heading()}>{heading}</h2>
+        {body && <p class={s.body()} data-kit-text>{body}</p>}
+      </div>
+      {note
+        ? <div class={s.cta()}>{shown.length > 0 && <div class={s.actions()}>{shown.map(action => <Button action={action} size="lg" />)}</div>}<p class={s.note()} data-kit-text>{note}</p></div>
+        : shown.length > 0 && <div class={s.actions()}>{shown.map(action => <Button action={action} size="lg" />)}</div>}
     </div>
-    {shown.length > 0 && <div class={s.actions()}>{shown.map(action => <Button action={action} size="lg" />)}</div>}
+    {image && <div class={s.media()}><KitImage image={image} sizes="(min-width: 768px) 30vw, 100vw" class="h-auto w-full object-cover" /></div>}
   </div>
 </Section>

package/components/cta/fixtures.json

@@ -5,5 +5,9 @@
   { "name": "card-muted", "props": { "heading": "Support independent travel writing", "frame": "card", "tone": "muted", "layout": "centered", "actions": [{ "label": "Become a member", "href": "/members/" }] } },
   { "name": "stacked-none", "props": { "heading": "Ready when you are", "body": "Tell us where you want to go and we will send a first plan within a week.", "layout": "stacked", "tone": "none", "actions": [{ "label": "Start planning", "href": "/contact/" }] } },
   { "name": "centered-actions-start", "props": { "heading": "See what is on this week", "body": "New films every Thursday, and a late show on Saturdays.", "layout": "centered", "tone": "inverse", "actionsAlign": "start", "actions": [{ "label": "Programme", "href": "/programme/" }] } },
-  { "name": "centered-brand", "props": { "heading": "Ready when you are", "body": "Two launch slots left this quarter.", "layout": "centered", "tone": "brand", "actions": [{ "label": "Book a launch call", "href": "/contact/" }] } }
+  { "name": "centered-brand", "props": { "heading": "Ready when you are", "body": "Two launch slots left this quarter.", "layout": "centered", "tone": "brand", "actions": [{ "label": "Book a launch call", "href": "/contact/" }] } },
+  { "name": "eyebrow-note-lg", "props": { "eyebrow": "Free trial", "heading": "Start building today", "body": "Ship a first page in an afternoon.", "note": "No credit card required", "actions": [{ "label": "Subscribe", "href": "/subscribe/" }], "size": "lg", "tone": "muted", "align": "center" } },
+  { "name": "media-end", "props": { "heading": "See it in action", "body": "A short tour of the editor.", "actions": [{ "label": "Subscribe", "href": "/subscribe/" }], "image": { "src": "/kit-fixtures/photo-1.svg", "alt": "The editor", "width": 640, "height": 480 }, "tone": "default", "frame": "card" } },
+  { "name": "media-start-centered", "props": { "heading": "Join the newsletter", "body": "One email a month.", "actions": [{ "label": "Subscribe", "href": "/subscribe/" }], "image": { "src": "/kit-fixtures/photo-2.svg", "alt": "", "width": 640, "height": 480 }, "mediaSide": "start", "layout": "centered", "tone": "inverse" } },
+  { "name": "background-image", "props": { "heading": "Planning a trip?", "body": "Start with the guides readers use most.", "actions": [{ "label": "Subscribe", "href": "/subscribe/" }], "layout": "centered", "bgImage": "/kit-fixtures/photo-3.svg", "tone": "inverse", "size": "lg" } }
 ]

package/components/cta/meta.json

@@ -4,17 +4,26 @@
   "description": "A call to action: a short heading, an optional line of text and one or two buttons — across the whole section, or as a card inside it.",
   "category": "section",
   "uses": [],
-  "shared": ["Button.astro", "Section.astro", "types.ts"],
+  "shared": ["Button.astro", "KitImage.astro", "Section.astro", "measured.ts", "types.ts"],
   "variants": {
     "layout": { "options": ["inline", "centered", "stacked"], "default": "inline", "description": "inline: text left, buttons right on wide screens. centered: everything centred. stacked: heading, text and buttons in one column at the start edge on every width." },
     "frame": { "options": ["full", "card"], "default": "full", "description": "full: the tone fills the section. card: a rounded box in a plain section carries the tone." },
     "tone": { "options": ["default", "muted", "inverse", "accent", "brand", "none"], "default": "accent", "description": "Background. On accent, primary buttons are drawn in the secondary style so they stay visible. brand: the site's brand colour role (`--color-brand`, the builder's own colour on a band) with its ink; buttons keep their style. none: no fill of its own; the page background shows through (a source colour the palette does not have)." },
-    "actionsAlign": { "options": ["inherit", "start"], "default": "inherit", "description": "The buttons' alignment. inherit: as the layout sets it. start: at the start edge under centred heading and text (layout centered; a WordPress buttons block with no justification in a centred group). inline and stacked ignore it." }
+    "actionsAlign": { "options": ["inherit", "start"], "default": "inherit", "description": "The buttons' alignment. inherit: as the layout sets it. start: at the start edge under centred heading and text (layout centered; a WordPress buttons block with no justification in a centred group). inline and stacked ignore it." },
+    "size": { "options": ["md", "lg"], "default": "md", "description": "md: the usual band. lg: a larger heading and more room above and below." },
+    "align": { "options": ["start", "center"], "default": "start", "description": "Alignment of the heading and text (the centred layout already centres them)." },
+    "mediaSide": { "options": ["end", "start"], "default": "end", "description": "With a picture: the side it takes on wide screens." }
   },
   "props": {
     "heading": { "type": "string", "label": "Heading", "required": true, "description": "The call's heading (Divi CTA title, Elementor call-to-action title)." },
+    "eyebrow": { "type": "string", "label": "Eyebrow", "description": "A short line above the heading." },
     "body": { "type": "text", "label": "Text", "description": "One or two sentences under the heading." },
+    "note": { "type": "string", "label": "Small print", "description": "A line under the buttons (No credit card required)." },
+    "image": { "type": "image", "label": "Image", "description": "A small picture beside the text; a large one belongs in a split section." },
+    "bgImage": { "type": "image", "label": "Background image", "description": "A picture behind the band; the text turns light and an overlay keeps it readable." },
+    "bgOverlay": { "type": "string", "content": false, "description": "The colour laid over the background image (a hex or rgb colour); default black at 55 %." },
     "actions": { "type": "array", "label": "Buttons", "required": true, "items": { "type": "object", "fields": { "label": { "type": "string", "label": "Label", "required": true, "description": "The button text." }, "href": { "type": "url", "label": "Link", "required": true, "description": "Where the button goes: a page on this site or a full address." }, "newTab": { "type": "boolean", "label": "Open in a new tab", "description": "Open the link in a new tab (an external site the reader should not leave for)." }, "style": { "type": "select", "label": "Style", "options": ["primary", "secondary", "ghost"], "description": "primary for the main action, secondary or ghost for the ones beside it." } } }, "description": "Buttons, in order; usually one." },
+    "measured": { "type": "object", "content": false, "description": "The source section's measured style (MeasuredStyle): frame width, padding, fill, image, columns per width, gap, text tone, radius, minimum height — all in pixels. Absent, the site's tokens; present, it wins over tone and columns. Values that are not a number, a colour or a known keyword are dropped.", "fields": { "containerPx": { "type": "integer", "min": 0, "max": 2560, "description": "The frame's content width." }, "padY": { "type": "integer", "min": 0, "max": 400, "description": "Top and bottom padding." }, "padX": { "type": "integer", "min": 0, "max": 200, "description": "The frame's side padding (gutter)." }, "bg": { "type": "object", "description": "The section's background.", "fields": { "color": { "type": "string", "description": "Fill colour: hex, rgb(a) or hsl(a)." }, "image": { "type": "string", "description": "Background image address (http(s) or root-relative), drawn behind the content." }, "overlay": { "type": "string", "description": "Colour or linear/radial gradient laid over the image or the fill." }, "size": { "type": "string", "description": "cover, contain or auto; anything else draws as cover." }, "position": { "type": "string", "description": "One or two of center/top/bottom/left/right or percentages." } } }, "columns": { "type": "object", "description": "Item columns at 390 (base), 768 (md) and 1280 (lg) px; a missing width follows the narrower one.", "fields": { "390": { "type": "integer", "min": 1, "max": 6, "description": "Phone." }, "768": { "type": "integer", "min": 1, "max": 6, "description": "Tablet." }, "1280": { "type": "integer", "min": 1, "max": 6, "description": "Desktop." } } }, "gap": { "type": "integer", "min": 0, "max": 200, "description": "Gap between items." }, "tone": { "type": "select", "options": ["light", "dark"], "description": "What the text is set for: dark = light text on a dark band. Without it, a fill's own lightness decides." }, "align": { "type": "select", "options": ["start", "center", "end"], "description": "Where the heading and lead sit; read by a component whose own align is not set." }, "radius": { "type": "integer", "min": 0, "max": 200, "description": "Card and item corner radius." }, "minHeight": { "type": "integer", "min": 0, "max": 2000, "description": "The section's minimum height." } } },
     "id": { "type": "string", "content": false, "description": "Anchor id of the section; the heading gets `<id>-title`." }
   },
   "slots": {},

package/components/faq/Faq.astro

@@ -5,6 +5,8 @@
 // and AI answers.
 import { tv } from 'tailwind-variants'
 import Section from '../_shared/Section.astro'
+import { measuredColumns } from '../_shared/measured'
+import type { MeasuredStyle } from '../_shared/types'
 
 export interface FaqItem {
   question: string
@@ -14,14 +16,28 @@ export interface FaqItem {
 
 const faq = tv({
   slots: {
-    heading: 'mb-8 text-2xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-3xl',
+    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',
     list: 'flex flex-col',
     item: 'group',
+    question: '',
     summary: 'flex cursor-pointer list-none items-center justify-between gap-4 py-4 text-lg [font-weight:var(--font-weight-heading,600)] [&::-webkit-details-marker]:hidden focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent',
-    marker: 'size-5 shrink-0 transition-transform duration-200 group-open:rotate-45',
+    marker: 'size-5 shrink-0 transition-transform duration-200 motion-reduce:transition-none',
     answer: 'prose-site prose max-w-none pb-5 text-current',
   },
   variants: {
+    // single: heading above, one column. split: the heading and intro stay in a left column (sticky) beside the list.
+    layout: {
+      single: {},
+      split: { root: 'grid gap-10 lg:grid-cols-[minmax(0,1fr)_minmax(0,2fr)] lg:gap-16', head: 'mb-0 lg:sticky lg:top-8 lg:self-start' },
+    },
+    // Two balanced columns of questions on wide screens.
+    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: {} },
     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' },
@@ -36,13 +52,23 @@ const faq = tv({
   },
   compoundVariants: [
     { style: 'cards', tone: 'muted', class: { item: 'border-transparent' } },
+    { icon: 'plus', class: { marker: 'group-open:rotate-45' } },
+    // A rule between items does not cross columns: each item carries its own, and the list's are dropped.
+    { columns: '2', style: 'lines', class: { list: 'lg:divide-y-0 lg:border-y-0', item: 'lg:border-b lg:border-line' } },
+    { columns: '2', style: 'cards', class: { item: 'lg:mb-3' } },
   ],
-  defaultVariants: { style: 'lines', tone: 'default', questionStyle: 'heading' },
+  defaultVariants: { layout: 'single', columns: '1', icon: 'plus', numbered: false, style: 'lines', tone: 'default', questionStyle: 'heading' },
 })
 
 interface Props {
   items: FaqItem[]
   heading?: string | undefined
+  intro?: string | undefined
+  layout?: 'single' | 'split' | undefined
+  columns?: '1' | '2' | undefined
+  icon?: 'plus' | 'chevron' | undefined
+  /** Count the questions with a leading number (drawn by CSS, not part of the text). */
+  numbered?: boolean | undefined
   style?: 'lines' | 'cards' | 'plain' | undefined
   /** How the questions read; `plain` sets its own and ignores this. */
   questionStyle?: 'heading' | 'bold' | undefined
@@ -53,11 +79,19 @@ interface Props {
   /** Add FAQPage structured data (JSON-LD). Once per page. */
   schema?: boolean | undefined
   tone?: 'default' | 'muted' | 'inverse' | 'accent' | 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
   id?: string | undefined
 }
 
-const { items, heading, style, questionStyle, exclusive = false, openFirst = false, schema = false, tone, id = 'faq' } = Astro.props
-const s = faq({ style, questionStyle: style === 'plain' ? 'heading' : questionStyle, tone })
+const { items, heading, intro, layout, columns, icon, numbered = false, style, questionStyle, exclusive = false, openFirst = false, schema = false, tone, measured, id = 'faq' } = Astro.props
+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)
+const wide = layout === 'split' || columns === '2' || measuredCols !== undefined
+// Measured columns win over `columns`. A rule between items does not cross columns, so each item carries its own.
+const listClass = measuredCols && (style === 'cards' || style === 'plain' ? measuredCols : `${measuredCols} divide-y-0 border-b-0`)
+const itemClass = measuredCols ? (style === 'cards' ? 'break-inside-avoid mb-3' : style === 'plain' ? 'break-inside-avoid' : 'break-inside-avoid border-b border-line') : undefined
 const headingId = heading ? `${id}-title` : undefined
 const plain = (html: string) => html.replace(/<[^>]*>/g, ' ').replace(/&nbsp;/g, ' ').replace(/\s+/g, ' ').trim()
 const structured = schema && items.length > 0
@@ -69,18 +103,27 @@ const structured = schema && items.length > 0
   : null
 ---
 {items.length > 0 && (
-  <Section tone={tone} spacing="md" width="prose" id={id} aria-labelledby={headingId}>
-    {heading && <h2 id={headingId} class={s.heading()}>{heading}</h2>}
-    <div class={s.list()}>
-      {items.map((item, i) => (
-        <details class={s.item()} name={exclusive ? id : undefined} open={openFirst && i === 0}>
-          <summary class={s.summary()}>
-            <span>{item.question}</span>
-            <svg class={s.marker()} viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.75" aria-hidden="true"><path d="M10 4v12M4 10h12" /></svg>
-          </summary>
-          <div class={s.answer()} set:html={item.answer} />
-        </details>
-      ))}
+  <Section 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()}>
+          {heading && <h2 id={headingId} class={s.heading()}>{heading}</h2>}
+          {intro && <p class={s.intro()} data-kit-text>{intro}</p>}
+        </header>
+      )}
+      <div class={s.list({ class: listClass })}>
+        {items.map((item, i) => (
+          <details class={s.item({ class: itemClass })} name={exclusive ? id : undefined} open={openFirst && i === 0}>
+            <summary class={s.summary()}>
+              <span class={s.question()}>{item.question}</span>
+              {icon === 'chevron'
+                ? <svg class={s.marker()} viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5 8 5 5 5-5" /></svg>
+                : <svg class={s.marker()} viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.75" aria-hidden="true"><path d="M10 4v12M4 10h12" /></svg>}
+            </summary>
+            <div class={s.answer()} set:html={item.answer} />
+          </details>
+        ))}
+      </div>
     </div>
     {structured && <script type="application/ld+json" set:html={structured} />}
   </Section>

package/components/faq/fixtures.json

@@ -40,5 +40,80 @@
   {
     "name": "lines-bold",
     "props": { "heading": "Questions", "questionStyle": "bold", "id": "faq-bold", "items": [{ "question": "Do you ship printed guides abroad?", "answer": "<p>Yes, to every country in the EU and the UK.</p>" }, { "question": "Can I change my route later?", "answer": "<p>Any time before the trip starts.</p>" }] }
+  },
+  {
+    "name": "split-chevron",
+    "props": {
+      "layout": "split",
+      "icon": "chevron",
+      "heading": "Questions",
+      "intro": "Everything you need before you start.",
+      "id": "faq-split",
+      "items": [
+        { "question": "Do you accept guest essays?", "answer": "<p>Yes — we publish reader essays every season. Send a <a href=\"/pitch/\">short pitch</a> first.</p>" },
+        { "question": "Can I reuse your photographs?", "answer": "<p>Only with written permission. Most are licensed from the photographers, not owned by us.</p>" },
+        { "question": "How often do you publish?", "answer": "<p>Two or three pieces a month, plus the seasonal issue.</p><ul><li>Guides: monthly</li><li>Essays: seasonal</li></ul>" }
+      ]
+    }
+  },
+  {
+    "name": "two-columns-numbered",
+    "props": {
+      "columns": "2",
+      "numbered": true,
+      "icon": "chevron",
+      "id": "faq-cols",
+      "items": [
+        { "question": "Do you accept guest essays?", "answer": "<p>Yes — we publish reader essays every season. Send a <a href=\"/pitch/\">short pitch</a> first.</p>" },
+        { "question": "Can I reuse your photographs?", "answer": "<p>Only with written permission. Most are licensed from the photographers, not owned by us.</p>" },
+        { "question": "How often do you publish?", "answer": "<p>Two or three pieces a month, plus the seasonal issue.</p><ul><li>Guides: monthly</li><li>Essays: seasonal</li></ul>" },
+        { "question": "Do you accept guest essays?", "answer": "<p>Yes — we publish reader essays every season. Send a <a href=\"/pitch/\">short pitch</a> first.</p>" },
+        { "question": "Can I reuse your photographs?", "answer": "<p>Only with written permission. Most are licensed from the photographers, not owned by us.</p>" },
+        { "question": "How often do you publish?", "answer": "<p>Two or three pieces a month, plus the seasonal issue.</p><ul><li>Guides: monthly</li><li>Essays: seasonal</li></ul>" }
+      ],
+      "heading": "Common questions"
+    }
+  },
+  {
+    "name": "split-two-cards-plus",
+    "props": {
+      "layout": "split",
+      "columns": "2",
+      "style": "cards",
+      "icon": "plus",
+      "id": "faq-split-cols",
+      "heading": "Help",
+      "intro": "Short answers.",
+      "items": [
+        { "question": "Do you accept guest essays?", "answer": "<p>Yes — we publish reader essays every season. Send a <a href=\"/pitch/\">short pitch</a> first.</p>" },
+        { "question": "Can I reuse your photographs?", "answer": "<p>Only with written permission. Most are licensed from the photographers, not owned by us.</p>" },
+        { "question": "How often do you publish?", "answer": "<p>Two or three pieces a month, plus the seasonal issue.</p><ul><li>Guides: monthly</li><li>Essays: seasonal</li></ul>" },
+        { "question": "Do you accept guest essays?", "answer": "<p>Yes — we publish reader essays every season. Send a <a href=\"/pitch/\">short pitch</a> first.</p>" },
+        { "question": "Can I reuse your photographs?", "answer": "<p>Only with written permission. Most are licensed from the photographers, not owned by us.</p>" },
+        { "question": "How often do you publish?", "answer": "<p>Two or three pieces a month, plus the seasonal issue.</p><ul><li>Guides: monthly</li><li>Essays: seasonal</li></ul>" }
+      ]
+    }
+  },
+  {
+    "name": "measured-frame",
+    "props": {
+      "heading": "Frequently asked questions",
+      "exclusive": true,
+      "openFirst": true,
+      "schema": true,
+      "items": [
+        { "question": "Do you accept guest essays?", "answer": "<p>Yes — we publish reader essays every season. Send a <a href=\"/pitch/\">short pitch</a> first.</p>" },
+        { "question": "Can I reuse your photographs?", "answer": "<p>Only with written permission. Most are licensed from the photographers, not owned by us.</p>" },
+        { "question": "How often do you publish?", "answer": "<p>Two or three pieces a month, plus the seasonal issue.</p><ul><li>Guides: monthly</li><li>Essays: seasonal</li></ul>" }
+      ],
+      "measured": {
+        "containerPx": 720,
+        "padY": 64,
+        "bg": {
+          "color": "#111827"
+        },
+        "tone": "dark"
+      }
+    }
   }
 ]

package/components/faq/meta.json

@@ -4,8 +4,11 @@
   "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"],
+  "shared": ["Section.astro", "measured.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." },
+    "icon": { "options": ["plus", "chevron"], "default": "plus", "description": "The marker in each question's row: a plus that turns into a cross, or a chevron that turns over." },
     "style": { "options": ["lines", "cards", "plain"], "default": "lines", "description": "lines: rows divided by rules. cards: each question in a rounded box. plain: the browser's own disclosure triangle without rules or boxes, questions at the body size (WordPress's details block)." },
     "tone": { "options": ["default", "muted", "inverse", "accent"], "default": "default", "description": "Section background." },
     "questionStyle": { "options": ["heading", "bold"], "default": "heading", "description": "How the questions read. heading: a small heading (lg, heading weight). bold: body size in bold, as accordion and toggle titles often are. The plain style sets its own and ignores this." }
@@ -13,10 +16,13 @@
   "props": {
     "items": { "type": "array", "label": "Questions", "required": true, "items": { "type": "object", "fields": { "question": { "type": "string", "label": "Question", "required": true, "description": "The question, as the visitor would ask it." }, "answer": { "type": "richtext", "label": "Answer", "required": true, "description": "The answer; links and lists allowed." } } }, "description": "The questions in order (core/details summary + content, Elementor accordion/toggle tabs, Divi accordion/toggle items)." },
     "heading": { "type": "string", "label": "Heading", "description": "Section heading." },
+    "intro": { "type": "text", "label": "Introduction", "description": "A sentence under the heading." },
     "exclusive": { "type": "boolean", "default": false, "content": false, "description": "One answer open at a time (Elementor accordion, Divi accordion). Off for toggles." },
     "openFirst": { "type": "boolean", "default": false, "content": false, "description": "The first answer starts open (Divi open_toggle, Elementor active item 1)." },
     "schema": { "type": "boolean", "default": false, "content": false, "description": "Emit FAQPage JSON-LD built from these items. Use on at most one FAQ per page, and only when the page is really a FAQ." },
-    "id": { "type": "string", "content": false, "description": "Section id; also the exclusive group's name." }
+    "measured": { "type": "object", "content": false, "description": "The source section's measured style (MeasuredStyle): frame width, padding, fill, image, columns per width, gap, text tone, radius, minimum height — all in pixels. Absent, the site's tokens; present, it wins over tone and columns. Values that are not a number, a colour or a known keyword are dropped.", "fields": { "containerPx": { "type": "integer", "min": 0, "max": 2560, "description": "The frame's content width." }, "padY": { "type": "integer", "min": 0, "max": 400, "description": "Top and bottom padding." }, "padX": { "type": "integer", "min": 0, "max": 200, "description": "The frame's side padding (gutter)." }, "bg": { "type": "object", "description": "The section's background.", "fields": { "color": { "type": "string", "description": "Fill colour: hex, rgb(a) or hsl(a)." }, "image": { "type": "string", "description": "Background image address (http(s) or root-relative), drawn behind the content." }, "overlay": { "type": "string", "description": "Colour or linear/radial gradient laid over the image or the fill." }, "size": { "type": "string", "description": "cover, contain or auto; anything else draws as cover." }, "position": { "type": "string", "description": "One or two of center/top/bottom/left/right or percentages." } } }, "columns": { "type": "object", "description": "Item columns at 390 (base), 768 (md) and 1280 (lg) px; a missing width follows the narrower one.", "fields": { "390": { "type": "integer", "min": 1, "max": 6, "description": "Phone." }, "768": { "type": "integer", "min": 1, "max": 6, "description": "Tablet." }, "1280": { "type": "integer", "min": 1, "max": 6, "description": "Desktop." } } }, "gap": { "type": "integer", "min": 0, "max": 200, "description": "Gap between items." }, "tone": { "type": "select", "options": ["light", "dark"], "description": "What the text is set for: dark = light text on a dark band. Without it, a fill's own lightness decides." }, "align": { "type": "select", "options": ["start", "center", "end"], "description": "Where the heading and lead sit; read by a component whose own align is not set." }, "radius": { "type": "integer", "min": 0, "max": 200, "description": "Card and item corner radius." }, "minHeight": { "type": "integer", "min": 0, "max": 2000, "description": "The section's minimum height." } } },
+    "id": { "type": "string", "content": false, "description": "Section id; also the exclusive group's name." },
+    "numbered": { "type": "boolean", "default": false, "content": false, "description": "Count the questions with a leading number, drawn by the page's style rather than written into the text." }
   },
   "slots": {},
   "js": "none",

package/components/feature-list/FeatureList.astro

@@ -3,6 +3,8 @@
 // the feature's icon or a shared check, under an optional heading and intro.
 import { tv } from 'tailwind-variants'
 import Section, { type Tone } from '../_shared/Section.astro'
+import { measuredGrid } from '../_shared/measured'
+import type { MeasuredStyle } from '../_shared/types'
 
 const list = tv({
   slots: {
@@ -26,8 +28,10 @@ const list = tv({
     },
     // On accent the mark takes the ink colour, and text is never dimmed.
     tone: { default: {}, muted: {}, inverse: {}, accent: { mark: 'text-current', text: 'opacity-100' } },
+    // 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: {} },
   },
-  defaultVariants: { columns: '3', style: 'icon', tone: 'default' },
+  defaultVariants: { columns: '3', style: 'icon', tone: 'default', bare: false },
 })
 
 // 24×24 stroke paths (Lucide-style); unknown names fall back to check.
@@ -57,24 +61,47 @@ interface Props {
   columns?: '2' | '3' | '4' | undefined
   style?: 'icon' | 'check' | 'list' | undefined
   tone?: Tone | undefined
+  /** Only the list, with no section of its own, for use inside another section's column. */
+  bare?: boolean | undefined
+  /** The level of the item titles when `bare` (the section's heading level plus one). */
+  titleLevel?: 3 | 4 | 5 | undefined
   id?: string | 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, intro, items, columns, style = 'icon', tone, id } = Astro.props
-const s = list({ columns, style, tone })
+const { heading, intro, items, columns, style = 'icon', tone, bare = false, titleLevel = 3, id, measured } = Astro.props
+const s = list({ columns, style, tone, bare })
 const headingId = heading && id ? `${id}-title` : undefined
 const pathOf = (item: Item) => (style !== 'check' && item.icon && icons[item.icon]) || icons.check
 // 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'
+const Title = style === 'list' ? 'span' : bare ? `h${titleLevel}` as 'h3' : heading ? 'h3' : 'h2'
 ---
-<Section tone={tone} id={id} aria-labelledby={headingId}>
+{bare
+  ? (
+    <ul class={s.grid({ class: measuredGrid(measured) })}>
+      {items.map(item => (
+        <li class={s.item()}>
+          <span class={s.mark()} aria-hidden="true">
+            <svg viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d={pathOf(item)} /></svg>
+          </span>
+          <div>
+            <Title class={s.title()}>{item.title}</Title>
+            {item.text && <p class={s.text()} data-kit-text>{item.text}</p>}
+          </div>
+        </li>
+      ))}
+    </ul>
+  )
+  : (
+<Section 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>}
     </header>
   )}
-  <ul class={s.grid()}>
+  <ul class={s.grid({ class: measuredGrid(measured) })}>
     {items.map(item => (
       <li class={s.item()}>
         <span class={s.mark()} aria-hidden="true">
@@ -88,3 +115,4 @@ const Title = style === 'list' ? 'span' : heading ? 'h3' : 'h2'
     ))}
   </ul>
 </Section>
+  )}

package/components/feature-list/fixtures.json

@@ -150,5 +150,6 @@
       ],
       "style": "list"
     }
-  }
+  },
+  {"name": "measured-gap", "props": {"heading": "Why us", "measured": {"columns": {"390": 1, "768": 2, "1280": 3}, "gap": 16}, "items": [{"title": "Fast", "text": "Static HTML."}, {"title": "Kept", "text": "Every address survives."}, {"title": "Editable", "text": "Content in Studio."}]}}
 ]