ferst-core 0.3.0 → 0.4.1

package/components/BlockRenderer.astro

@@ -42,6 +42,8 @@ import MapEmbed from './recipes/MapEmbed.astro';
 import Table from './recipes/Table.astro';
 import Notice from './recipes/Notice.astro';
 import MediaCards from './recipes/MediaCards.astro';
+import ContactCard from './recipes/ContactCard.astro';
+import Locations from './recipes/Locations.astro';
 
 interface Props {
   blocks: Block[];
@@ -86,6 +88,8 @@ const registry: Record<BlockType, any> = {
   table: Table,
   notice: Notice,
   mediaCards: MediaCards,
+  contactCard: ContactCard,
+  locations: Locations,
 };
 ---
 

package/components/CalendarEmbed.astro

@@ -84,13 +84,24 @@ const safe = isSafeEmbedUrl(finalEmbedUrl);
 
   const embeds = document.querySelectorAll<HTMLElement>('.b-calendar__embed');
 
+  // Google Calendar embeds render light-only — `bgcolor` recolours just the
+  // surround, never the grid, so matching it to a dark surface still left a white
+  // calendar sitting in the dark page. Instead we force a deterministic WHITE
+  // surround here (independent of the theme at load) and, in dark mode, invert the
+  // whole frame in CSS (below). The invert is keyed on the site's [data-theme], so
+  // it also flips live when the visitor toggles the theme.
+  function calendarUrl(url: string): string {
+    if (!/google\.com\/calendar|calendar\.google\.com/.test(url)) return url;
+    return url + (url.includes('?') ? '&' : '?') + 'bgcolor=%23ffffff';
+  }
+
   function load(el: HTMLElement) {
     if (el.dataset.loaded === 'true') return;
     const url = el.dataset.embedUrl;
     const frameSlot = el.querySelector<HTMLElement>('.b-calendar__frame');
     if (!url || !frameSlot) return;
     const frame = document.createElement('iframe');
-    frame.src = url;
+    frame.src = calendarUrl(url);
     frame.title = el.dataset.title || 'Calendar';
     frame.loading = 'lazy';
     frame.style.width = '100%';
@@ -135,7 +146,13 @@ const safe = isSafeEmbedUrl(finalEmbedUrl);
     display: block;
     border: var(--card-border);
     border-radius: var(--radius);
-    background: var(--bg-surface);
+    background: #fff;
+  }
+  /* Google Calendar is light-only; in dark mode invert the frame so it reads as a
+     dark calendar (hue-rotate keeps event colours roughly true). Keyed on the
+     site's [data-theme] so it also flips live on a theme toggle. */
+  :global([data-theme='dark']) .b-calendar__frame :global(iframe) {
+    filter: invert(1) hue-rotate(180deg);
   }
   /* Consent card stands in for the calendar until the visitor opts in. */
   .b-calendar__consent {

package/components/CookieBanner.astro

@@ -48,6 +48,16 @@ const { policyHref = '/cookie-policy/' } = Astro.props;
 </script>
 
 <style is:global>
+  /* `display: flex` below is an author rule and would beat the UA `[hidden] {
+     display: none }`, so the banner would stay in the layout while dismissed (or
+     for returning visitors, where it starts hidden) — an invisible opacity:0
+     fixed bar that still INTERCEPTS pointer events over whatever sits at the
+     viewport bottom (e.g. the footer's later links). This explicit rule makes
+     `hidden` truly remove it. Must come before `.cookie-banner` so specificity,
+     not order, decides — (0,1,1) beats (0,1,0). */
+  .cookie-banner[hidden] {
+    display: none;
+  }
   .cookie-banner {
     position: fixed;
     left: 20px;

package/components/PostCard.astro

@@ -12,8 +12,14 @@ interface Props {
   heroImage?: string;
   /** Optional tag labels shown as a small eyebrow. */
   tagLabels?: string[];
+  /** Open the link in a new tab (e.g. a post that's just an attached PDF). */
+  newTab?: boolean;
+  /** The call-to-action label (default "Read more"). */
+  moreLabel?: string;
 }
-const { href, title, date, summary, heroImage, tagLabels = [] } = Astro.props;
+const { href, title, date, summary, heroImage, tagLabels = [], newTab = false, moreLabel = 'Read more' } = Astro.props;
+const linkRel = newTab ? 'noopener' : undefined;
+const linkTarget = newTab ? '_blank' : undefined;
 const d = date instanceof Date ? date : new Date(date);
 const iso = Number.isNaN(d.valueOf()) ? undefined : d.toISOString().slice(0, 10);
 const display = Number.isNaN(d.valueOf())
@@ -23,7 +29,7 @@ const display = Number.isNaN(d.valueOf())
 
 <article class="b-post-card">
   {heroImage && (
-    <a class="b-post-card__media" href={href} tabindex="-1" aria-hidden="true">
+    <a class="b-post-card__media" href={href} target={linkTarget} rel={linkRel} tabindex="-1" aria-hidden="true">
       <img src={heroImage} alt="" loading="lazy" />
     </a>
   )}
@@ -33,10 +39,10 @@ const display = Number.isNaN(d.valueOf())
       {display && <time datetime={iso}>{display}</time>}
     </div>
     <h3 class="b-post-card__title">
-      <a href={href}>{title}</a>
+      <a href={href} target={linkTarget} rel={linkRel}>{title}</a>
     </h3>
     {summary && <p class="b-post-card__summary">{summary}</p>}
-    <span class="b-post-card__more" aria-hidden="true">Read more</span>
+    <span class="b-post-card__more" aria-hidden="true">{moreLabel}</span>
   </div>
 </article>
 

package/components/SiteFooter.astro

@@ -190,11 +190,17 @@ const year = new Date().getFullYear();
     text-align: center;
     gap: 0.6rem 1.5rem;
   }
+  /* Tight gap: each link carries its own inline padding (below), so the visible
+     hit target is a clear region *centred on its label* — no wide dead gap between
+     labels where a hover lands on nothing (and the browser keeps showing the
+     previous link's URL, which reads as an off-by-one). The negative inline margin
+     cancels the first/last item's padding so the row still edge-aligns. */
   .site-footer .footer-nav {
     display: flex;
     flex-wrap: wrap;
     justify-content: center;
-    gap: 0.3rem 1rem;
+    gap: 0.15rem 0.15rem;
+    margin-inline: -0.55rem;
   }
   .site-footer .footer-nav a,
   .site-footer .footer-nav button {
@@ -208,13 +214,32 @@ const year = new Date().getFullYear();
     color: var(--accent);
     background: none;
     border: none;
-    padding: 0;
+    border-radius: var(--radius-sm, 6px);
+    padding: 0 0.55rem;
     cursor: pointer;
+    text-decoration: none;
+    transition: background 0.15s ease, color 0.15s ease;
+  }
+  /* Visible hover/focus affordance: makes each link's boundary unmistakable, so
+     it's always clear which one you're on. */
+  .site-footer .footer-nav a:hover,
+  .site-footer .footer-nav button:hover,
+  .site-footer .footer-nav a:focus-visible,
+  .site-footer .footer-nav button:focus-visible {
+    background: color-mix(in srgb, var(--accent) 12%, transparent);
+    text-decoration: underline;
+    text-underline-offset: 3px;
   }
   [data-theme="dark"] .site-footer .footer-nav a,
   [data-theme="dark"] .site-footer .footer-nav button {
     color: var(--gold);
   }
+  [data-theme="dark"] .site-footer .footer-nav a:hover,
+  [data-theme="dark"] .site-footer .footer-nav button:hover,
+  [data-theme="dark"] .site-footer .footer-nav a:focus-visible,
+  [data-theme="dark"] .site-footer .footer-nav button:focus-visible {
+    background: color-mix(in srgb, var(--gold) 16%, transparent);
+  }
   .site-footer .footer-copy {
     margin: 0;
     font-family: var(--font-body);

package/components/recipes/ContactCard.astro

@@ -0,0 +1,170 @@
+---
+/**
+ * ContactCard — a Level-2 recipe: a rich, branded "get in touch" band. A display-
+ * type title + subtitle on the left, the contact channels as tappable tiles on the
+ * right, and a closing note across the bottom. For a contact or find-us page — the
+ * polished alternative to a plain notice box.
+ *
+ * Fully THEME-ADAPTIVE (composes in light AND dark): the panel is `--bg-section`
+ * with a soft `--gold` corner wash for brand presence, text is `--fg`/`--accent`/
+ * `--muted`, tiles are `--bg-surface` recesses, icons + hovers use `--gold`. Every
+ * one of those tokens flips per theme, so the band re-composes correctly in each
+ * mode (never the old always-dark band) and a CMS colour change recolours it.
+ * Contrast-safe: brand gold is used only decoratively (wash, rule, icons, hovers),
+ * never as body/label text — those use the ink/text tokens that meet AA on the
+ * panel in both themes. Whole tile links when `href` is set.
+ */
+import Icon from '../Icon.astro';
+import { isIconKey } from '../../lib/icons';
+
+interface Item {
+  icon?: string;
+  value: string;
+  href?: string;
+}
+interface Props {
+  eyebrow?: string;
+  title: string;
+  subtitle?: string;
+  note?: string;
+  items?: Item[];
+}
+const { eyebrow, title, subtitle, note, items = [] } = Astro.props;
+const rel = (href?: string) => (href && /^https?:\/\//.test(href) ? 'noopener' : undefined);
+const target = (href?: string) => (href && /^https?:\/\//.test(href) ? '_blank' : undefined);
+---
+
+<section class="b-contact">
+  <div class="b-contact__panel">
+    <div class="b-contact__head">
+      {eyebrow && <p class="b-contact__eyebrow">{eyebrow}</p>}
+      <h2 class="b-contact__title">{title}</h2>
+      {subtitle && <p class="b-contact__subtitle">{subtitle}</p>}
+    </div>
+
+    {items.length > 0 && (
+      <ul class="b-contact__items">
+        {items.map((item) => {
+          const inner = (
+            <>
+              {item.icon && isIconKey(item.icon) && (
+                <span class="b-contact__icon" aria-hidden="true"><Icon name={item.icon} size={18} /></span>
+              )}
+              <span class="b-contact__value">{item.value}</span>
+            </>
+          );
+          return (
+            <li>
+              {item.href ? (
+                <a class="b-contact__item" href={item.href} target={target(item.href)} rel={rel(item.href)}>{inner}</a>
+              ) : (
+                <div class="b-contact__item">{inner}</div>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    )}
+
+    {note && <p class="b-contact__note">{note}</p>}
+  </div>
+</section>
+
+<style>
+  .b-contact {
+    max-width: 72rem;
+    margin-inline: auto;
+    padding-inline: 1rem;
+  }
+  /* Adaptive panel: a section surface that flips light↔dark with the theme, lifted
+     off the page by a border + shadow, with a soft brand-gold wash for presence. */
+  .b-contact__panel {
+    position: relative;
+    isolation: isolate;
+    overflow: hidden;
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 1.5rem 2.5rem;
+    padding: clamp(1.75rem, 4vw, 3rem);
+    border-radius: var(--radius);
+    background: var(--bg-section);
+    color: var(--fg);
+    border: 1px solid var(--border);
+    box-shadow: var(--shadow-md);
+  }
+  /* Brand wash — a gold glow in the top-right, behind the content (z-index below the
+     panel's own children via isolation). Adds brand presence in both themes without
+     tinting the text ground, so contrast is never at risk. */
+  .b-contact__panel::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    background: radial-gradient(115% 130% at 100% 0%, color-mix(in srgb, var(--gold) 20%, transparent), transparent 62%);
+    pointer-events: none;
+  }
+  @media (min-width: 48rem) {
+    .b-contact__panel { grid-template-columns: 1.2fr 1fr; align-items: center; }
+  }
+  .b-contact__head { display: flex; flex-direction: column; gap: 0.5rem; }
+  .b-contact__eyebrow {
+    margin: 0;
+    display: inline-flex; align-items: center; gap: 0.6rem;
+    font-family: var(--font-heading);
+    font-size: 0.75rem; font-weight: 700; letter-spacing: 0.14em; text-transform: uppercase;
+    color: var(--accent);
+  }
+  /* Short gold rule carries the brand into the eyebrow without colouring the text. */
+  .b-contact__eyebrow::before {
+    content: ''; flex: 0 0 auto; width: 1.5rem; height: 2px; border-radius: 2px;
+    background: var(--gold);
+  }
+  .b-contact__title {
+    margin: 0;
+    font-family: var(--font-display, var(--font-heading));
+    font-size: clamp(1.9rem, 4vw, 2.8rem);
+    line-height: 1.05;
+    text-wrap: balance;
+    color: var(--fg);
+  }
+  .b-contact__subtitle {
+    margin: 0.15rem 0 0;
+    font-family: var(--font-heading);
+    font-weight: 600;
+    color: var(--accent);
+  }
+  .b-contact__items {
+    list-style: none;
+    margin: 0; padding: 0;
+    display: flex; flex-direction: column; gap: 0.6rem;
+  }
+  .b-contact__item {
+    display: flex; align-items: center; gap: 0.75rem;
+    padding: 0.7rem 1rem;
+    border-radius: var(--radius-sm);
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    color: var(--fg);
+    font-family: var(--font-heading);
+    font-weight: 600;
+    font-size: 0.95rem;
+    text-decoration: none;
+    transition: border-color 0.15s ease, background 0.15s ease;
+  }
+  a.b-contact__item:hover {
+    border-color: var(--gold);
+    background: color-mix(in srgb, var(--gold) 8%, var(--bg-surface));
+  }
+  a.b-contact__item:focus-visible { outline: 2px solid var(--gold); outline-offset: 2px; }
+  .b-contact__icon { display: inline-flex; color: var(--gold); flex: 0 0 auto; }
+  .b-contact__value { min-width: 0; overflow-wrap: anywhere; }
+  .b-contact__note {
+    grid-column: 1 / -1;
+    margin: 0;
+    padding-top: 1.25rem;
+    border-top: 1px solid var(--border);
+    color: var(--muted);
+    font-size: 0.9rem;
+    line-height: 1.6;
+  }
+</style>

package/components/recipes/LatestPosts.astro

@@ -11,7 +11,7 @@ import PostCard from '../PostCard.astro';
 import Heading from '../blocks/Heading.astro';
 import Button from '../Button.astro';
 import { getIndexPosts, getPostsByTag } from '../../lib/posts';
-import { isRecent } from '../../content/posts';
+import { isRecent, postLink } from '../../content/posts';
 
 interface Props {
   title?: string;
@@ -68,12 +68,12 @@ const isNew = (date: Date | string) => isRecent(date, newWithinDays, nowMs);
     <ul class="b-latest-posts__list">
       {posts.map((p, i) => {
         const { iso, label } = fmt(p.data.date);
-        const href = `/posts/${p.slug}`;
+        const { href, newTab } = postLink(p);
         const cats = (p.data.tags ?? []).slice(0, 2);
         return (
           <li class="b-post-row">
             {p.data.heroImage && (
-              <a class="b-post-row__media" href={href} tabindex="-1" aria-hidden="true">
+              <a class="b-post-row__media" href={href} target={newTab ? '_blank' : undefined} rel={newTab ? 'noopener' : undefined} tabindex="-1" aria-hidden="true">
                 <img src={p.data.heroImage} alt="" loading="lazy" />
               </a>
             )}
@@ -81,7 +81,7 @@ const isNew = (date: Date | string) => isRecent(date, newWithinDays, nowMs);
               {cats.length > 0 && (
                 <span class="b-post-row__cat">{cats.join(' · ')}</span>
               )}
-              <h3 class="b-post-row__title"><a href={href}>{p.data.title}</a></h3>
+              <h3 class="b-post-row__title"><a href={href} target={newTab ? '_blank' : undefined} rel={newTab ? 'noopener' : undefined}>{p.data.title}</a></h3>
             </div>
             <div class="b-post-row__aside">
               {i === 0 && isNew(p.data.date) && <span class="b-post-row__new">New</span>}
@@ -94,16 +94,21 @@ const isNew = (date: Date | string) => isRecent(date, newWithinDays, nowMs);
     </ul>
   ) : (
     <div class="b-latest-posts__grid">
-      {posts.map((p) => (
-        <PostCard
-          href={`/posts/${p.slug}`}
-          title={p.data.title}
-          date={p.data.date}
-          summary={p.data.summary}
-          heroImage={p.data.heroImage}
-          tagLabels={p.data.tags}
-        />
-      ))}
+      {posts.map((p) => {
+        const { href, newTab } = postLink(p);
+        return (
+          <PostCard
+            href={href}
+            newTab={newTab}
+            moreLabel={newTab ? 'Open PDF' : undefined}
+            title={p.data.title}
+            date={p.data.date}
+            summary={p.data.summary}
+            heroImage={p.data.heroImage}
+            tagLabels={p.data.tags}
+          />
+        );
+      })}
     </div>
   )}
 

package/components/recipes/Locations.astro

@@ -0,0 +1,150 @@
+---
+/**
+ * Locations ("Where to find us") — a Level-2 recipe: one or more places, each a
+ * neat tile with a consent-gated map on top and its name / address / directions
+ * below. Replaces stacking bare map embeds. The map loads once the visitor accepts
+ * the site cookie banner (shared consent — no per-tile gate for anyone who
+ * accepted); the per-tile "Show map" button is a fallback that grants the same
+ * consent. Token-driven, equal-height tiles. https embed URLs only.
+ */
+import Icon from '../Icon.astro';
+import Heading from '../blocks/Heading.astro';
+import { isSafeEmbedUrl } from '../../content/calendar';
+
+interface Item {
+  name: string;
+  address?: string;
+  embedUrl: string;
+  directionsUrl?: string;
+}
+interface Props {
+  title?: string;
+  intro?: string;
+  columns?: 1 | 2;
+  provider?: string;
+  items?: Item[];
+}
+const { title, intro, columns = 2, provider = 'Google Maps', items = [] } = Astro.props;
+---
+
+<section class="b-locations">
+  {(title || intro) && (
+    <div class="b-locations__head">
+      {title && <Heading text={title} level={2} />}
+      {intro && <p class="b-locations__intro">{intro}</p>}
+    </div>
+  )}
+  <div class="b-locations__grid" data-cols={columns}>
+    {items.map((item) => (
+      <article class="b-locations__card">
+        <div class="b-locations__map">
+          {isSafeEmbedUrl(item.embedUrl) ? (
+            <div class="b-loc-map" data-embed-url={item.embedUrl} data-title={`Map — ${item.name}`}>
+              <div class="b-loc-map__consent">
+                <p class="b-loc-map__text">This map is provided by {provider}.</p>
+                <button type="button" class="b-loc-map__load">Show map</button>
+              </div>
+              <div class="b-loc-map__frame"></div>
+            </div>
+          ) : (
+            <div class="b-loc-map__fallback" aria-hidden="true"><Icon name="map-pin" size={30} /></div>
+          )}
+        </div>
+        <div class="b-locations__body">
+          <h3 class="b-locations__name">{item.name}</h3>
+          {item.address && <p class="b-locations__address">{item.address}</p>}
+          {item.directionsUrl && (
+            <a class="b-locations__dir" href={item.directionsUrl} target="_blank" rel="noopener">
+              Get directions <span aria-hidden="true">→</span>
+            </a>
+          )}
+        </div>
+      </article>
+    ))}
+  </div>
+</section>
+
+<script>
+  // Shared site consent: accepting the cookie banner auto-loads every map here.
+  import { hasConsent, setConsent, onConsentChange } from '../../lib/consent-client';
+
+  const maps = document.querySelectorAll<HTMLElement>('.b-loc-map');
+  function load(el: HTMLElement) {
+    if (el.dataset.loaded === 'true') return;
+    const url = el.dataset.embedUrl;
+    const slot = el.querySelector<HTMLElement>('.b-loc-map__frame');
+    if (!url || !slot) return;
+    const frame = document.createElement('iframe');
+    frame.src = url;
+    frame.title = el.dataset.title || 'Map';
+    frame.loading = 'lazy';
+    frame.referrerPolicy = 'no-referrer-when-downgrade';
+    frame.style.width = '100%';
+    frame.style.height = '100%';
+    frame.style.border = '0';
+    slot.replaceChildren(frame);
+    el.dataset.loaded = 'true';
+    const consent = el.querySelector<HTMLElement>('.b-loc-map__consent');
+    if (consent) consent.hidden = true;
+  }
+  const loadAll = () => maps.forEach(load);
+
+  if (hasConsent()) loadAll();
+  onConsentChange((allowed) => { if (allowed) loadAll(); });
+  maps.forEach((el) => {
+    el.querySelector<HTMLButtonElement>('.b-loc-map__load')?.addEventListener('click', () => setConsent(true));
+  });
+</script>
+
+<style>
+  .b-locations {
+    display: flex;
+    flex-direction: column;
+    gap: 1.75rem;
+    max-width: 72rem;
+    margin-inline: auto;
+    padding-inline: 1rem;
+  }
+  .b-locations__head { display: flex; flex-direction: column; gap: 0.6rem; }
+  .b-locations__intro { margin: 0; color: var(--muted); max-width: var(--max); }
+  .b-locations__grid { display: grid; grid-template-columns: 1fr; gap: 1.5rem; }
+  @media (min-width: 44em) {
+    .b-locations__grid[data-cols='2'] { grid-template-columns: repeat(2, 1fr); }
+  }
+  .b-locations__card {
+    display: flex;
+    flex-direction: column;
+    background: var(--bg-surface);
+    border: var(--card-border);
+    border-radius: var(--radius);
+    box-shadow: var(--shadow-sm);
+    overflow: hidden;
+  }
+  /* Map region — uniform ratio; the consent card fills it until the iframe loads. */
+  .b-locations__map { position: relative; aspect-ratio: 4 / 3; background: var(--bg-section); }
+  .b-loc-map, .b-loc-map__frame, .b-loc-map__consent, .b-loc-map__fallback { position: absolute; inset: 0; }
+  .b-loc-map__frame :global(iframe) { display: block; }
+  .b-loc-map__consent {
+    display: flex; flex-direction: column; align-items: center; justify-content: center;
+    gap: 0.75rem; padding: 1.5rem; text-align: center;
+  }
+  .b-loc-map__consent[hidden] { display: none; }
+  .b-loc-map__text { margin: 0; color: var(--muted); font-size: 0.9rem; max-width: 32ch; }
+  .b-loc-map__load {
+    font: inherit; font-family: var(--font-heading); font-weight: 600; font-size: 0.9rem;
+    padding: 0.5rem 1.1rem; border: none; border-radius: var(--radius-sm);
+    background: var(--gold); color: var(--text-light); cursor: pointer;
+    transition: filter 0.15s ease;
+  }
+  .b-loc-map__load:hover { filter: brightness(0.94); }
+  .b-loc-map__load:focus-visible { outline: 2px solid var(--gold); outline-offset: 2px; }
+  .b-loc-map__fallback { display: flex; align-items: center; justify-content: center; color: var(--muted); }
+  .b-locations__body { display: flex; flex-direction: column; gap: 0.4rem; padding: 1.1rem 1.2rem 1.3rem; }
+  .b-locations__name { margin: 0; font-size: 1.15rem; }
+  .b-locations__address { margin: 0; color: var(--muted); line-height: 1.55; white-space: pre-line; }
+  .b-locations__dir {
+    margin-top: 0.35rem;
+    font-family: var(--font-heading); font-weight: 600; font-size: 0.9rem;
+    color: var(--gold);
+  }
+</style>

package/components/recipes/Stats.astro

@@ -1,6 +1,13 @@
 ---
 /** Stats — a Level-2 recipe: a band of headline numbers over an optional
- *  heading/intro. Composes the Heading primitive; numbers use the brand accent. */
+ *  heading/intro. Composes the Heading primitive; numbers use the brand accent.
+ *
+ *  Self-composing: the grid never reserves more columns than there are stats, so
+ *  a single item centres as a feature instead of stranding an empty half-band
+ *  (the "£10 pinned to one side" bug); each stat is a token-driven tile (radius/
+ *  surface/stroke/shadow knobs, like every Card), so it reads as a designed unit
+ *  at any count and in either theme. Labels are width-capped so a long caption
+ *  wraps to a tidy block rather than a full-width line. */
 import Heading from '../blocks/Heading.astro';
 
 interface Item { value: string; label: string; description?: string }
@@ -12,6 +19,9 @@ interface Props {
   items?: Item[];
 }
 const { title, intro, background = 'muted', columns = 3, items = [] } = Astro.props;
+// Cap the column count at the item count — one stat should never sit in a
+// two-column grid (half empty). Falls back to 1 for an empty list.
+const cols = Math.min(columns, Math.max(items.length, 1)) as 1 | 2 | 3 | 4;
 ---
 
 <section class="b-stats" data-bg={background}>
@@ -22,11 +32,11 @@ const { title, intro, background = 'muted', columns = 3, items = [] } = Astro.pr
         {intro && <p class="b-stats__intro">{intro}</p>}
       </div>
     )}
-    <div class="b-stats__grid" data-cols={columns}>
+    <div class="b-stats__grid" data-cols={cols}>
       {items.map((item) => (
         <div class="b-stats__item">
           <span class="b-stats__value">{item.value}</span>
-          <span class="b-stats__label">{item.label}</span>
+          {item.label && <span class="b-stats__label">{item.label}</span>}
           {item.description && <span class="b-stats__desc">{item.description}</span>}
         </div>
       ))}
@@ -58,21 +68,35 @@ const { title, intro, background = 'muted', columns = 3, items = [] } = Astro.pr
   .b-stats__grid {
     display: grid;
     grid-template-columns: 1fr;
-    gap: 1.5rem 2rem;
+    gap: 1.25rem;
+    width: 100%;
+    margin-inline: auto;
   }
   @media (min-width: 40em) {
-    .b-stats__grid { grid-template-columns: repeat(2, 1fr); }
+    .b-stats__grid[data-cols='2'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .b-stats__grid[data-cols='3'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+    .b-stats__grid[data-cols='4'] { grid-template-columns: repeat(2, minmax(0, 1fr)); }
   }
   @media (min-width: 60em) {
-    .b-stats__grid[data-cols='3'] { grid-template-columns: repeat(3, 1fr); }
-    .b-stats__grid[data-cols='4'] { grid-template-columns: repeat(4, 1fr); }
+    .b-stats__grid[data-cols='3'] { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+    .b-stats__grid[data-cols='4'] { grid-template-columns: repeat(4, minmax(0, 1fr)); }
   }
+  /* A lone stat is a centred feature, not a full-width slab. */
+  .b-stats__grid[data-cols='1'] { max-width: 30rem; }
+  /* Token-driven tile: the same radius / surface / stroke / shadow knobs as every
+     Card, so it stays consistent and theme-correct. On the muted band the tile's
+     --bg-surface sits a step above --bg-section, giving depth in both themes. */
   .b-stats__item {
     display: flex;
     flex-direction: column;
     align-items: center;
     text-align: center;
-    gap: 0.35rem;
+    gap: 0.5rem;
+    padding: clamp(1.5rem, 3vw, 2.25rem) clamp(1.25rem, 3vw, 1.75rem);
+    border-radius: var(--radius);
+    background: var(--bg-surface);
+    border: var(--card-border);
+    box-shadow: var(--shadow-md);
   }
   .b-stats__value {
     font-family: var(--font-heading);
@@ -81,8 +105,8 @@ const { title, intro, background = 'muted', columns = 3, items = [] } = Astro.pr
     line-height: 1;
     color: var(--gold);
   }
-  .b-stats__label { font-weight: 600; color: var(--fg); }
-  .b-stats__desc { font-size: 0.875rem; color: var(--muted); line-height: 1.5; }
+  .b-stats__label { font-weight: 600; color: var(--fg); line-height: 1.4; max-width: 30ch; }
+  .b-stats__desc { font-size: 0.875rem; color: var(--muted); line-height: 1.5; max-width: 32ch; }
 </style>
 
 <script>

package/content/blocks.ts

@@ -480,6 +480,47 @@ export const mediaCardsBlock = z.object({
     .default([]),
 });
 
+/** ContactCard — a branded "get in touch" band: display title + subtitle on the
+ *  left, contact channels as tappable pills on the right, a note across the bottom. */
+export const contactCardBlock = z.object({
+  type: z.literal('contactCard'),
+  enabled: z.boolean().default(true),
+  eyebrow: z.string().optional(),
+  title: z.string(),
+  subtitle: z.string().optional(),
+  note: z.string().optional(),
+  items: z
+    .array(
+      z.object({
+        icon: z.string().optional(),
+        value: z.string(),
+        href: z.string().optional(),
+      })
+    )
+    .default([]),
+});
+
+/** Locations ("Where to find us") — location tiles, each a consent-gated map over
+ *  a name / address / directions. https embed URLs only (isSafeEmbedUrl). */
+export const locationsBlock = z.object({
+  type: z.literal('locations'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  columns: z.union([z.literal(1), z.literal(2)]).default(2),
+  provider: z.string().default('Google Maps'),
+  items: z
+    .array(
+      z.object({
+        name: z.string(),
+        address: z.string().optional(),
+        embedUrl: z.string(),
+        directionsUrl: z.string().optional(),
+      })
+    )
+    .default([]),
+});
+
 export type RecipeBlock =
   | z.infer<typeof heroBlock>
   | z.infer<typeof featureCardsBlock>
@@ -503,7 +544,9 @@ export type RecipeBlock =
   | z.infer<typeof mapEmbedBlock>
   | z.infer<typeof tableBlock>
   | z.infer<typeof noticeBlock>
-  | z.infer<typeof mediaCardsBlock>;
+  | z.infer<typeof mediaCardsBlock>
+  | z.infer<typeof contactCardBlock>
+  | z.infer<typeof locationsBlock>;
 
 /* ── Level-1 layout / container primitives ─────────────────────────────────
  * These hold child blocks, so the schema is **recursive** (a container's
@@ -612,6 +655,8 @@ export const blockSchema = z.discriminatedUnion('type', [
   tableBlock,
   noticeBlock,
   mediaCardsBlock,
+  contactCardBlock,
+  locationsBlock,
   sectionBlock,
   gridBlock,
   stackBlock,

package/content/posts.ts

@@ -88,6 +88,23 @@ export function tagCounts(posts: Array<{ data: { tags?: string[] } }>): Record<s
   return counts;
 }
 
+/**
+ * Where a post card/row should link. Normally the post's own page — but a post
+ * that is just an attached file with no body (e.g. a newsletter that's only a PDF)
+ * links straight to the file, opened in a new tab, so there's no empty post page
+ * in between. Pure; the caller passes the entry's `body` (raw markdown) so
+ * "has text" is decided here.
+ */
+export function postLink(
+  post: { slug: string; body?: string | null; data: { attachment?: string } },
+  base = '/posts',
+): { href: string; newTab: boolean } {
+  const attachment = post.data.attachment;
+  const hasBody = !!post.body && post.body.trim() !== '';
+  if (attachment && !hasBody) return { href: attachment, newTab: true };
+  return { href: `${base}/${post.slug}`, newTab: false };
+}
+
 /**
  * Whether a post date is within the last `days` of `now` — used to flag a "New"
  * badge in the compact latest-posts list. `days <= 0` disables it; a future or

package/content/schemas.ts

@@ -126,6 +126,22 @@ export const themeSettingsSchema = z.object({
   stroke: z.enum(['on', 'off']).default('on'),
   /** Input treatment — a single site-wide choice (a `data-field` attr on <html>). */
   fields: z.enum(['boxed', 'filled', 'underline']).default('boxed'),
+  /** Dark-mode formula knobs (root-derivation model). `darkDepth` = how light the
+   *  dark page background sits (OKLCH L); `darkChroma` = the cap on how much colour
+   *  the dark ground may carry. Both feed the AUTOMATIC dark roots. */
+  darkDepth: z.number().min(0.12).max(0.4).default(0.21),
+  darkChroma: z.number().min(0).max(0.15).default(0.05),
+  /** Explicit overrides for the three dark ROOTS. Each blank ⇒ the root is derived
+   *  from its light source by the formula; set ⇒ every dark token in that role
+   *  re-derives from this colour. Roots only (ground / text / accent) — never a
+   *  lone downstream token — so the palette can never fall out of sync. */
+  darkOverrides: z
+    .object({
+      ground: z.string().default(''),
+      text: z.string().default(''),
+      accent: z.string().default(''),
+    })
+    .default({}),
   /** Raw per-token overrides, layered last. Rarely needed. */
   advanced: z
     .object({

package/lib/posts.ts

@@ -24,6 +24,10 @@ import {
   type PostsSettings,
 } from '../content/posts';
 
+// Re-export the pure link helper so clients can import it alongside the data
+// helpers (e.g. a custom NewsList) from one place.
+export { postLink } from '../content/posts';
+
 export type PostEntry = CollectionEntry<'posts'>;
 
 /** A tag resolved for display: its slug + label/description + how many posts use it. */

package/lib/themeTokens.ts

@@ -66,29 +66,84 @@ const LIGHT_DERIVATION = [
   '--news-card-meta:color-mix(in srgb, var(--ink) 72%, var(--surface))',
 ].join(';');
 
-/** Dark-mode derivations — the OKLCH translation of the same three source vars. */
-const DARK_DERIVATION = [
-  '--fg:oklch(from var(--ink) 0.94 calc(c * 0.3) h)',
-  '--muted:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
-  '--accent:oklch(from var(--ink) 0.86 calc(c * 0.3) h)',
-  '--brown:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
-  '--bg:oklch(from var(--brand) 0.16 0.015 h)',
-  '--bg-surface:oklch(from var(--brand) 0.21 0.02 h)',
-  '--bg-section:oklch(from var(--brand) 0.19 0.018 h)',
-  '--bg-tag:oklch(from var(--brand) 0.14 0.015 h)',
-  '--dark-bg:oklch(from var(--brand) 0.12 0.015 h)',
-  '--border:oklch(from var(--brand) 0.32 0.02 h)',
-  '--gold:oklch(from var(--brand) 0.78 calc(c * 0.9) h)',
-  '--gold-light:oklch(from var(--brand) 0.30 calc(c * 0.55) h)',
-  '--accent-2:oklch(from var(--brand) 0.70 calc(c * 0.9) calc(h + 26))',
-  '--text-footer:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
-  '--text-footer-link:oklch(from var(--brand) 0.78 calc(c * 0.9) h)',
-  '--text-copyright:oklch(from var(--ink) 0.55 calc(c * 0.3) h)',
-  '--text-subtle:oklch(from var(--ink) 0.55 calc(c * 0.3) h)',
-  '--divider-dark:oklch(from var(--brand) 0.32 0.02 h)',
-  '--news-card-meta:oklch(from var(--ink) 0.74 calc(c * 0.3) h)',
+/**
+ * Dark mode uses a ROOT-DERIVATION model that mirrors light's three sources, so an
+ * editor can only ever change coherent roots — never a lone downstream token that
+ * would then clash with the rest.
+ *
+ * Three dark ROOTS, one per role:
+ *   --dark-ground  (surfaces)  ← surface, chroma BOOSTED as it darkens so a pale
+ *                                tint survives instead of collapsing to grey/black;
+ *                                lightness = --dark-bg-l (the depth knob).
+ *   --dark-text    (text)      ← ink, lightened for a dark ground.
+ *   --dark-accent  (accents)   ← brand, brightened for a dark ground.
+ * Each defaults to this formula but can be OVERRIDDEN with an explicit colour (see
+ * buildThemeStyle); either way EVERY dark token below derives from the three roots,
+ * so the palette stays internally consistent whether automatic or hand-set.
+ */
+const DARK_ROOTS_AUTO = [
+  '--dark-ground:oklch(from var(--surface) var(--dark-bg-l) clamp(0, calc(c * 3.5), var(--dark-chroma-cap)) h)',
+  '--dark-text:oklch(from var(--ink) 0.94 calc(c * 0.3) h)',
+  '--dark-accent:oklch(from var(--brand) 0.78 calc(c * 0.9) h)',
 ].join(';');
 
+/** Every working dark token, derived from the three roots (offsets in OKLCH L). */
+const DARK_DOWNSTREAM = [
+  // Grounds ← --dark-ground
+  '--bg:var(--dark-ground)',
+  '--bg-surface:oklch(from var(--dark-ground) calc(l + 0.05) c h)',
+  '--bg-section:oklch(from var(--dark-ground) calc(l + 0.025) c h)',
+  '--bg-tag:oklch(from var(--dark-ground) calc(l - 0.03) c h)',
+  '--dark-bg:oklch(from var(--dark-ground) calc(l - 0.05) c h)',
+  '--border:oklch(from var(--dark-ground) calc(l + 0.19) c h)',
+  '--divider-dark:oklch(from var(--dark-ground) calc(l + 0.19) c h)',
+  // Text ← --dark-text
+  '--fg:var(--dark-text)',
+  '--muted:oklch(from var(--dark-text) calc(l - 0.20) c h)',
+  '--accent:oklch(from var(--dark-text) calc(l - 0.08) c h)',
+  '--brown:oklch(from var(--dark-text) calc(l - 0.20) c h)',
+  '--text-footer:oklch(from var(--dark-text) calc(l - 0.20) c h)',
+  '--text-copyright:oklch(from var(--dark-text) calc(l - 0.39) c h)',
+  '--text-subtle:oklch(from var(--dark-text) calc(l - 0.39) c h)',
+  '--news-card-meta:oklch(from var(--dark-text) calc(l - 0.20) c h)',
+  // Accents ← --dark-accent
+  '--gold:var(--dark-accent)',
+  '--gold-light:oklch(from var(--dark-accent) calc(l - 0.46) calc(c * 0.6) h)',
+  '--accent-2:oklch(from var(--dark-accent) calc(l - 0.08) c calc(h + 26))',
+  '--text-footer-link:var(--dark-accent)',
+].join(';');
+
+/** Defaults for the dark-formula knobs (also the CMS/schema defaults). */
+export const DARK_DEFAULTS = { depth: 0.21, chroma: 0.05 } as const;
+
+/** Clamp a numeric knob to a range, falling back to `fallback` when absent/NaN. */
+function clampNum(v: unknown, min: number, max: number, fallback: number): number {
+  const n = typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+  return Math.min(max, Math.max(min, n));
+}
+
+/**
+ * Compose the dark block: the depth/chroma knobs, the three auto roots, any
+ * explicit root overrides (which win over the auto value), then the downstream
+ * derivations that read whichever root value ended up winning.
+ */
+function darkDeclarations(theme: ThemeSettings): string {
+  const depth = clampNum(theme.darkDepth, 0.12, 0.4, DARK_DEFAULTS.depth);
+  const chroma = clampNum(theme.darkChroma, 0, 0.15, DARK_DEFAULTS.chroma);
+  const ov = theme.darkOverrides ?? {};
+  const overrides: string[] = [];
+  if (clean(ov.ground)) overrides.push(`--dark-ground:${clean(ov.ground)}`);
+  if (clean(ov.text)) overrides.push(`--dark-text:${clean(ov.text)}`);
+  if (clean(ov.accent)) overrides.push(`--dark-accent:${clean(ov.accent)}`);
+  return [
+    `--dark-bg-l:${depth}`,
+    `--dark-chroma-cap:${chroma}`,
+    DARK_ROOTS_AUTO,
+    ...overrides,
+    DARK_DOWNSTREAM,
+  ].join(';');
+}
+
 /** Drop a value that could break out of a CSS declaration. The source is trusted
  *  repo JSON, but this keeps a stray value honest (defence in depth). */
 function clean(v: unknown): string {
@@ -151,7 +206,7 @@ export function buildThemeStyle(theme: ThemeSettings): ThemeStyle {
   const css = [
     rootDecls.length ? `:root:root{${rootDecls.join(';')}}` : '',
     themed ? `:root:root:not([data-theme="dark"]){${LIGHT_DERIVATION}}` : '',
-    themed ? `:root:root[data-theme="dark"]{${DARK_DERIVATION}}` : '',
+    themed ? `:root:root[data-theme="dark"]{${darkDeclarations(theme)}}` : '',
     rawBlock(':root:root', theme.advanced?.light),
     rawBlock(':root:root[data-theme="dark"]', theme.advanced?.dark),
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ferst-core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Ferst Core — the shared, brand-agnostic client-site system: Astro components, layouts, content schemas, the layered config resolver, and a neutral styling architecture that every client overrides.",
   "license": "BUSL-1.1",