ferst-core 0.3.0 → 0.4.0

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,29 @@ const safe = isSafeEmbedUrl(finalEmbedUrl);
 
   const embeds = document.querySelectorAll<HTMLElement>('.b-calendar__embed');
 
+  // Best-effort theme blend: Google Calendar embeds expose only `bgcolor` (the
+  // surround), not a real dark mode — the grid stays Google's own light. We match
+  // the surround to the current theme surface so the frame doesn't sit as a hard
+  // block. Resolved from --bg-surface at load (a later theme toggle keeps it).
+  function themedCalendarUrl(url: string): string {
+    if (!/google\.com\/calendar|calendar\.google\.com/.test(url)) return url;
+    const probe = document.createElement('span');
+    probe.style.cssText = 'display:none;background:var(--bg-surface)';
+    document.body.appendChild(probe);
+    const m = getComputedStyle(probe).backgroundColor.match(/\d+/g);
+    probe.remove();
+    if (!m) return url;
+    const hex = m.slice(0, 3).map((n) => (+n).toString(16).padStart(2, '0')).join('');
+    return url + (url.includes('?') ? '&' : '?') + 'bgcolor=%23' + hex;
+  }
+
   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 = themedCalendarUrl(url);
     frame.title = el.dataset.title || 'Calendar';
     frame.loading = 'lazy';
     frame.style.width = '100%';

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/recipes/ContactCard.astro

@@ -0,0 +1,145 @@
+---
+/**
+ * ContactCard — a Level-2 recipe: a rich, branded "get in touch" band. A gradient
+ * panel (anchored on --ink so it stays a deep, warm brand tone in BOTH themes)
+ * carries a display-type title + a subtitle on the left, the contact channels as
+ * tappable pills 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.
+ *
+ * Token-driven: the gradient is --ink → brand-tinted, pills are translucent
+ * recesses on it, icons + hovers use --gold, so a CMS colour change recolours the
+ * whole band. Whole pill 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;
+  }
+  /* Anchored on --ink (a source colour that stays dark in both themes) so the band
+     reads as a deep, warm brand panel regardless of light/dark. */
+  .b-contact__panel {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 1.5rem 2.5rem;
+    padding: clamp(1.75rem, 4vw, 3rem);
+    border-radius: var(--radius);
+    background: linear-gradient(135deg, var(--ink), color-mix(in srgb, var(--gold) 26%, var(--ink)));
+    color: var(--text-light);
+    box-shadow: var(--shadow-md);
+  }
+  @media (min-width: 48rem) {
+    .b-contact__panel { grid-template-columns: 1.25fr 1fr; align-items: center; }
+  }
+  .b-contact__head { display: flex; flex-direction: column; gap: 0.5rem; }
+  .b-contact__eyebrow {
+    margin: 0;
+    font-family: var(--font-heading);
+    font-size: 0.75rem; font-weight: 700; letter-spacing: 0.14em; text-transform: uppercase;
+    color: color-mix(in srgb, var(--text-light) 70%, transparent);
+  }
+  .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(--text-light);
+  }
+  .b-contact__subtitle {
+    margin: 0.15rem 0 0;
+    font-family: var(--font-heading);
+    font-weight: 600;
+    color: var(--gold);
+  }
+  .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: color-mix(in srgb, #000 22%, transparent);
+    border: 1px solid color-mix(in srgb, #fff 14%, transparent);
+    color: var(--text-light);
+    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, #000 12%, transparent);
+  }
+  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 color-mix(in srgb, #fff 14%, transparent);
+    color: color-mix(in srgb, var(--text-light) 78%, transparent);
+    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/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.0",
   "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",