@dloizides/marketing-astro-kit 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.2.0
+
+- New `DemoFrame.astro` — a themeable, **client-side "try it" demo** shell for
+  static marketing sites (no backend): an eyebrow/title/intro, a row of clickable
+  example chips, a per-example result panel (bespoke product body injected via a
+  named slot `result-<example.id>`), a clearly-visible "sample data" disclaimer,
+  and a primary CTA (reuses `PrimaryCta`). Tiny inline vanilla JS toggles which
+  result shows on chip click (+ arrow-key roving tablist); the first example is
+  visible without JS (progressive enhancement). New `DemoExample` / `DemoFrameData`
+  types in `schema.ts`.
+- New `GuideCard.astro` — a themeable card for a **guides / SEO content-hub**
+  listing, rendering one guide's tags, title, description and date. New
+  `GuideCardData` type.
+- New `guideFrontmatterSchema` (Zod, built on `astro/zod`) + `GuideFrontmatter`
+  type in `schema.ts` — plug straight into an Astro content collection
+  (`defineCollection({ loader: glob(...), schema: guideFrontmatterSchema })`) so
+  every product's guides validate the same shape (title, description, slug?,
+  publishDate, updatedDate?, tags, ogImage?, canonical?, draft?). The article
+  page + routes + JSON-LD stay product-owned.
+- `schema.ts` now imports `z` from `astro/zod` (Astro is already a peer dep) —
+  the ONE runtime import; every other export stays plain types.
+
 ## 1.1.0
 
 - New `PrimaryCta.astro` — a themeable primary call-to-action (link OR spam-safe

package/README.md

@@ -1,13 +1,15 @@
 # @dloizides/marketing-astro-kit
 
-Two reusable, **themeable** Astro marketing sections for product sites — the
-credibility markers an executive scans for before they trust a SaaS:
+Reusable, **themeable** Astro marketing sections for product sites — the
+credibility + conversion markers an executive scans for before they trust a SaaS:
 
 | Component | What it is |
 |---|---|
 | `PricingComparison.astro` | A clean **Free-vs-Pro(-vs-Business…) comparison table** — tier columns with price + CTA header, grouped feature rows (check / cross / short value), an optional footnote and an optional one-time "callout" card (e.g. a concierge/service tier). |
 | `TrustSection.astro` | A **trust / credibility** block — security & compliance cards with inline icons, a customer-logo row (real + clearly-labeled **placeholders**), testimonial cards (clearly-labeled **placeholders**), an optional **founding-partner** panel, an honest **founder** line, a **sample-deliverable** showcase, and a discreet **built-by** line. |
 | `PrimaryCta.astro` | A themeable **primary call-to-action** (link OR spam-safe contact) with an optional secondary CTA. Pair with `buildPrimaryCta` so ONE `SIGNUP_URL` constant drives whether it's a real signup link or lead-capture. |
+| `DemoFrame.astro` | A themeable, **client-side "try it" demo** shell for static sites (no backend): eyebrow/title/intro, a row of clickable example chips, a per-example result panel (bespoke product body via a named `result-<id>` slot), a "sample data" disclaimer, and a primary CTA. Tiny inline vanilla JS toggles which result shows; first example visible without JS. |
+| `GuideCard.astro` | A themeable **card for a guides / SEO content-hub** listing — one guide's tags, title, description and date. Pair with `guideFrontmatterSchema` on an Astro content collection. |
 
 ## Config-driven primary CTA (`PrimaryCta` + `buildPrimaryCta`)
 
@@ -72,6 +74,93 @@ hooks → Lighthouse-light.
 Extracted from `kefi-marketing` as the 2nd genuine use (per the "extract on the
 second use" rule); the Astro marketing sites otherwise share no code.
 
+## Client-side "try it" demo (`DemoFrame`)
+
+Static marketing sites (nginx, no backend) can still offer an interactive demo —
+`DemoFrame` renders the shared chrome around **curated, clearly-labelled sample
+data** that runs entirely in the browser. The frame owns the eyebrow/title/intro,
+the clickable example chips, a "sample data" disclaimer and the primary CTA; each
+product injects its own bespoke **result body per example** through a named slot
+(`result-<example.id>`), because that markup mirrors the product's real output:
+
+```ts
+// src/data/marketing.ts
+import type { DemoFrameData } from '@marketing-kit/schema';
+export const demo: DemoFrameData = {
+  eyebrow: 'See it in action',
+  title: 'Screen a wallet — watch the verdict',
+  examples: [
+    { id: 'flagged', label: '0x…illustrative', sublabel: 'Sanctioned' },
+    { id: 'clean',   label: 'Clean wallet',     sublabel: 'No matches' },
+  ],
+  disclaimer: 'Sample results on example wallets. Create a free account to screen any address.',
+  cta: primaryCta, // a MarketingCta driving to signup
+};
+```
+
+```astro
+---
+import DemoFrame from '@marketing-kit/DemoFrame.astro';
+import { demo } from '../data/marketing';
+---
+<DemoFrame data={demo} id="demo">
+  <!-- One panel per example, keyed by data-demo-result (matching an example id).
+       Mark the FIRST panel data-active so it shows without JS. -->
+  <div data-demo-result="flagged" data-active
+       id="demo-panel-flagged" role="tabpanel" aria-labelledby="demo-chip-flagged">
+    <!-- bespoke high-risk result mock -->
+  </div>
+  <div data-demo-result="clean"
+       id="demo-panel-clean" role="tabpanel" aria-labelledby="demo-chip-clean">
+    <!-- bespoke low-risk result mock -->
+  </div>
+</DemoFrame>
+```
+
+Astro forbids a dynamic `slot[name]`, so panels are routed through the default
+slot and keyed by a `data-demo-result` attribute (matching an example `id`)
+rather than named slots. The frame's chip ids are `<id>-chip-<exampleId>` and it
+wires `aria-controls` to `<id>-panel-<exampleId>`, so give each host panel
+`id="<id>-panel-<exampleId>"` + `aria-labelledby="<id>-chip-<exampleId>"`. The
+**first panel (`data-active`) is visible without JS** — the inline script only
+moves the active panel on chip click (and arrow-key roving for the tablist). Keep
+the result copy honest: real, public example data or an obviously-illustrative
+placeholder, never a fabricated claim.
+
+## SEO guides / content hub (`GuideCard` + `guideFrontmatterSchema`)
+
+A shared pattern for a product's guides flywheel: the kit supplies the **Zod
+frontmatter schema** (plug into an Astro content collection) and the **card** for
+the hub; the routes, article layout and JSON-LD stay product-owned.
+
+```ts
+// src/content.config.ts
+import { defineCollection } from 'astro:content';
+import { glob } from 'astro/loaders';
+import { guideFrontmatterSchema } from '@marketing-kit/schema';
+
+const guides = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './src/content/guides' }),
+  schema: guideFrontmatterSchema,
+});
+export const collections = { guides };
+```
+
+```astro
+---
+// src/pages/guides/index.astro
+import { getCollection } from 'astro:content';
+import GuideCard from '@marketing-kit/GuideCard.astro';
+const guides = (await getCollection('guides', ({ data }) => !data.draft))
+  .sort((a, b) => +b.data.publishDate - +a.data.publishDate);
+---
+{guides.map((g) => <GuideCard data={{ ...g.data, href: `/guides/${g.id}/` }} />)}
+```
+
+`guideFrontmatterSchema` fields: `title`, `description`, `slug?`, `publishDate`,
+`updatedDate?`, `tags`, `ogImage?`, `canonical?`, `draft?`. It is built on
+`astro/zod`, so it is the same zod instance Astro's content layer uses.
+
 ## Theming contract
 
 The components read these CSS vars off the host `:root` (each has a sensible

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@dloizides/marketing-astro-kit",
-  "version": "1.1.0",
-  "description": "Reusable, themeable Astro marketing sections for product sites — a Free-vs-Pro pricing comparison table and a trust / credibility section (security cards, customer-logo + testimonial placeholders, discreet built-by). Data-driven via a shared TypeScript schema; themed entirely through the host site's CSS custom properties.",
+  "version": "1.2.0",
+  "description": "Reusable, themeable Astro marketing sections for product sites — a Free-vs-Pro pricing comparison table, a trust / credibility section (security cards, customer-logo + testimonial placeholders, discreet built-by), a client-side \"try it\" demo shell, and an SEO guides/content-hub card + frontmatter schema. Data-driven via a shared TypeScript schema; themed entirely through the host site's CSS custom properties.",
   "keywords": [
     "astro",
     "marketing",
     "pricing",
     "comparison-table",
     "trust",
+    "demo",
+    "guides",
+    "content-hub",
+    "seo",
     "landing-page",
     "saas"
   ],
@@ -27,6 +31,8 @@
     "./PricingComparison.astro": "./src/PricingComparison.astro",
     "./TrustSection.astro": "./src/TrustSection.astro",
     "./PrimaryCta.astro": "./src/PrimaryCta.astro",
+    "./DemoFrame.astro": "./src/DemoFrame.astro",
+    "./GuideCard.astro": "./src/GuideCard.astro",
     "./schema": "./src/schema.ts",
     "./icons": "./src/icons.ts"
   },

package/src/DemoFrame.astro

@@ -0,0 +1,264 @@
+---
+// Reusable interactive "try it" demo shell for product marketing sites — a
+// themeable chrome around client-side, curated example data. The marketing
+// sites are static (nginx, no backend), so the demo runs ENTIRELY in the
+// browser over honest, clearly-labelled sample data. This component owns the
+// shared parts:
+//
+//   • eyebrow / title / intro
+//   • a row of clickable example "chips"
+//   • a result-panel area — the host supplies one bespoke, product-owned panel
+//     per example in the default slot, each tagged `data-demo-result="<id>"`
+//     (matching an example id) and the FIRST one also `data-active`
+//   • a clearly-visible "sample data" disclaimer line
+//   • a primary CTA (reuses PrimaryCta) driving to signup
+//
+//   <DemoFrame data={demo}>
+//     <div data-demo-result="flagged" data-active
+//          id="demo-panel-flagged" role="tabpanel" aria-labelledby="demo-chip-flagged">
+//       …your bespoke high-risk result markup…
+//     </div>
+//     <div data-demo-result="clean"
+//          id="demo-panel-clean" role="tabpanel" aria-labelledby="demo-chip-clean">…</div>
+//   </DemoFrame>
+//
+// The per-example RESULT markup is inherently product-specific (it mirrors the
+// product's real output), so it comes in via the default slot (Astro forbids a
+// dynamic `slot[name]`, so panels are keyed by a `data-demo-result` attribute
+// instead) while the frame stays shared. The frame's chip ids are
+// `<id>-chip-<exampleId>` and it wires `aria-controls` to `<id>-panel-<exampleId>`,
+// so a host panel should use `id="<id>-panel-<exampleId>"` +
+// `aria-labelledby="<id>-chip-<exampleId>"`. Minimal inline vanilla JS toggles
+// which panel shows on chip click — no framework. Progressive enhancement: the
+// FIRST panel (`data-active`) is visible without JS; the script just moves it.
+import type { DemoFrameData } from './schema';
+import PrimaryCta from './PrimaryCta.astro';
+
+interface Props {
+  data: DemoFrameData;
+  id?: string;
+}
+
+const { data, id = 'demo' } = Astro.props as Props;
+const { examples } = data;
+---
+
+<section class="dmk-demo" id={id} aria-labelledby={`${id}-title`} data-demo-frame>
+  <div class="dmk-container">
+    <p class="dmk-eyebrow" data-reveal>{data.eyebrow}</p>
+    <h2 class="dmk-title" id={`${id}-title`} data-reveal>{data.title}</h2>
+    {data.intro && <p class="dmk-intro" data-reveal>{data.intro}</p>}
+
+    <div class="dmk-panel" data-reveal>
+      <div class="dmk-chips" role="tablist" aria-label="Example inputs">
+        {examples.map((ex, i) => (
+          <button
+            type="button"
+            class="dmk-chip"
+            role="tab"
+            id={`${id}-chip-${ex.id}`}
+            aria-controls={`${id}-panel-${ex.id}`}
+            aria-selected={i === 0 ? 'true' : 'false'}
+            tabindex={i === 0 ? '0' : '-1'}
+            data-demo-chip={ex.id}
+            data-active={i === 0 ? '' : undefined}
+            data-umami-event={ex.analyticsEvent}
+          >
+            <span class="dmk-chip__label">{ex.label}</span>
+            {ex.sublabel && <span class="dmk-chip__sub">{ex.sublabel}</span>}
+          </button>
+        ))}
+      </div>
+
+      <div class="dmk-results">
+        <slot />
+      </div>
+
+      <p class="dmk-disclaimer" data-reveal>
+        <span class="dmk-disclaimer__dot" aria-hidden="true"></span>
+        {data.disclaimer}
+      </p>
+
+      <div class="dmk-cta" data-reveal>
+        <PrimaryCta cta={data.cta} secondary={data.secondaryCta} size="md" />
+      </div>
+    </div>
+  </div>
+</section>
+
+<script>
+  // Chip → result toggle for every DemoFrame on the page. Progressive
+  // enhancement: without JS the CSS already shows the first ([data-active])
+  // result; this just moves `data-active` on click (and arrow-key roving so the
+  // tablist is keyboard-navigable).
+  document.querySelectorAll('[data-demo-frame]').forEach((frame) => {
+    const chips = Array.from(frame.querySelectorAll('[data-demo-chip]'));
+    const results = Array.from(frame.querySelectorAll('[data-demo-result]'));
+
+    const activate = (key) => {
+      chips.forEach((chip) => {
+        const on = chip.getAttribute('data-demo-chip') === key;
+        chip.toggleAttribute('data-active', on);
+        chip.setAttribute('aria-selected', on ? 'true' : 'false');
+        chip.setAttribute('tabindex', on ? '0' : '-1');
+      });
+      results.forEach((result) => {
+        result.toggleAttribute('data-active', result.getAttribute('data-demo-result') === key);
+      });
+    };
+
+    chips.forEach((chip, index) => {
+      chip.addEventListener('click', () => activate(chip.getAttribute('data-demo-chip')));
+      chip.addEventListener('keydown', (event) => {
+        const delta = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0;
+        if (!delta) return;
+        event.preventDefault();
+        const next = chips[(index + delta + chips.length) % chips.length];
+        activate(next.getAttribute('data-demo-chip'));
+        next.focus();
+      });
+    });
+  });
+</script>
+
+<style>
+  .dmk-demo {
+    --_brand: var(--brand, #d8332a);
+    --_brand-deep: var(--brand-deep, #a8231c);
+    --_accent: var(--accent, #f5a300);
+    --_ink: var(--ink, #0a0a1f);
+    --_paper: var(--paper, #fff);
+    --_bg: var(--bg, #fbf9f4);
+    --_bg-tint: var(--bg-tint, #f1ede1);
+    --_muted: var(--muted, rgba(10, 10, 31, 0.62));
+    --_hairline: var(--hairline, rgba(10, 10, 31, 0.1));
+    --_r-md: var(--radius-md, 14px);
+    --_r-lg: var(--radius-lg, 24px);
+    --_shadow: var(--shadow, 0 30px 60px -30px rgba(10, 10, 31, 0.4));
+    padding: 96px 0;
+    background: var(--_paper);
+    border-top: 1px solid var(--_hairline);
+    border-bottom: 1px solid var(--_hairline);
+  }
+  .dmk-container {
+    width: min(1200px, 100% - 48px);
+    margin-inline: auto;
+  }
+  .dmk-eyebrow {
+    font-family: 'Oswald', sans-serif;
+    font-size: 12px;
+    font-weight: 600;
+    letter-spacing: 0.22em;
+    text-transform: uppercase;
+    color: var(--_brand);
+    margin: 0;
+  }
+  .dmk-title {
+    font-family: 'Oswald', 'Inter', sans-serif;
+    font-size: clamp(30px, 3.8vw, 46px);
+    font-weight: 700;
+    line-height: 1.08;
+    letter-spacing: -0.01em;
+    margin: 12px 0 14px;
+    max-width: 24ch;
+    color: var(--_ink);
+  }
+  .dmk-intro {
+    color: var(--_muted);
+    max-width: 62ch;
+    margin: 0 0 36px;
+  }
+
+  /* Panel --------------------------------------------------------------- */
+  .dmk-panel {
+    padding: 26px;
+    border-radius: var(--_r-lg);
+    background: var(--_bg);
+    border: 1px solid var(--_hairline);
+  }
+  @media (max-width: 560px) {
+    .dmk-panel { padding: 18px; }
+    .dmk-demo { padding: 64px 0; }
+  }
+
+  /* Chips (tablist) ----------------------------------------------------- */
+  .dmk-chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 10px;
+    margin-bottom: 22px;
+  }
+  .dmk-chip {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 2px;
+    padding: 11px 16px;
+    border-radius: var(--_r-md);
+    background: var(--_paper);
+    border: 1px solid var(--_hairline);
+    cursor: pointer;
+    text-align: left;
+    font-family: inherit;
+    transition: border-color 0.14s ease, box-shadow 0.14s ease, transform 0.14s ease,
+      background 0.14s ease;
+  }
+  .dmk-chip:hover { transform: translateY(-1px); border-color: color-mix(in srgb, var(--_brand) 40%, var(--_hairline)); }
+  .dmk-chip:focus-visible { outline: 2px solid var(--_brand); outline-offset: 2px; }
+  .dmk-chip[data-active] {
+    border-color: var(--_brand);
+    background: color-mix(in srgb, var(--_brand) 8%, var(--_paper));
+    box-shadow: 0 8px 22px -14px color-mix(in srgb, var(--_brand) 80%, transparent);
+  }
+  .dmk-chip__label {
+    font-family: 'Oswald', 'Inter', sans-serif;
+    font-weight: 600;
+    font-size: 14px;
+    letter-spacing: 0.01em;
+    color: var(--_ink);
+  }
+  .dmk-chip__sub {
+    font-size: 11.5px;
+    color: var(--_muted);
+  }
+
+  /* Results ------------------------------------------------------------- */
+  /* The panels are host-supplied slot content, so the show/hide toggle is
+     :global (keyed by data attributes) to reach across the slot boundary; it
+     stays scoped under .dmk-results so it can't leak to the wider page. */
+  .dmk-results { min-height: 10px; }
+  .dmk-results :global([data-demo-result]) { display: none; }
+  .dmk-results :global([data-demo-result][data-active]) {
+    display: block;
+    animation: dmk-fade 0.28s cubic-bezier(0.2, 0.7, 0.2, 1);
+  }
+  @keyframes dmk-fade {
+    from { opacity: 0; transform: translateY(6px); }
+    to { opacity: 1; transform: none; }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .dmk-results :global([data-demo-result][data-active]) { animation: none; }
+  }
+
+  /* Disclaimer ---------------------------------------------------------- */
+  .dmk-disclaimer {
+    display: flex;
+    align-items: baseline;
+    gap: 9px;
+    margin: 22px 0 0;
+    font-size: 12.5px;
+    line-height: 1.5;
+    color: var(--_muted);
+    font-style: italic;
+  }
+  .dmk-disclaimer__dot {
+    flex-shrink: 0;
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: var(--_accent);
+    transform: translateY(1px);
+  }
+
+  .dmk-cta { margin-top: 22px; }
+</style>

package/src/GuideCard.astro

@@ -0,0 +1,132 @@
+---
+// Reusable card for a guides / content-hub listing on a product marketing site.
+// Renders ONE guide's title, description, tags and date as a themeable link
+// card. Data-driven (schema.ts → GuideCardData); themed via host CSS vars.
+// Framework-free, no images → Lighthouse-light.
+//
+//   {guides.map((g) => <GuideCard data={{ ...g.data, href: `/guides/${g.id}/` }} />)}
+//
+// Pair with `guideFrontmatterSchema` (schema.ts) on the host's Astro content
+// collection so every product's hub validates + renders alike; the article
+// page + routes stay product-owned.
+import type { GuideCardData } from './schema';
+
+interface Props {
+  data: GuideCardData;
+}
+
+const { data } = Astro.props as Props;
+
+// Accept a Date (from the content collection) or a preformatted string. When a
+// Date, format it to a stable, locale-neutral "14 Jul 2026" and emit a machine
+// <time datetime> for the ISO value (good for SEO + a11y).
+const toDate = (value: Date | string): Date | null => {
+  const d = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(d.getTime()) ? null : d;
+};
+const published = toDate(data.publishDate);
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const dateLabel = published
+  ? `${published.getUTCDate()} ${MONTHS[published.getUTCMonth()]} ${published.getUTCFullYear()}`
+  : typeof data.publishDate === 'string'
+    ? data.publishDate
+    : '';
+const dateIso = published ? published.toISOString().slice(0, 10) : undefined;
+const tags = data.tags ?? [];
+---
+
+<a class="gmk-card" href={data.href}>
+  {tags.length > 0 && (
+    <div class="gmk-tags">
+      {tags.slice(0, 3).map((tag) => <span class="gmk-tag">{tag}</span>)}
+    </div>
+  )}
+  <h3 class="gmk-card-t">{data.title}</h3>
+  <p class="gmk-card-d">{data.description}</p>
+  <div class="gmk-card-foot">
+    {dateLabel && <time class="gmk-date" datetime={dateIso}>{dateLabel}</time>}
+    <span class="gmk-go" aria-hidden="true">Read →</span>
+  </div>
+</a>
+
+<style>
+  .gmk-card {
+    --_brand: var(--brand, #d8332a);
+    --_brand-deep: var(--brand-deep, #a8231c);
+    --_ink: var(--ink, #0a0a1f);
+    --_paper: var(--paper, #fff);
+    --_bg: var(--bg, #fbf9f4);
+    --_bg-tint: var(--bg-tint, #f1ede1);
+    --_muted: var(--muted, rgba(10, 10, 31, 0.62));
+    --_hairline: var(--hairline, rgba(10, 10, 31, 0.1));
+    --_r-md: var(--radius-md, 14px);
+    --_shadow: var(--shadow, 0 30px 60px -30px rgba(10, 10, 31, 0.4));
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    gap: 10px;
+    padding: 24px 22px;
+    border-radius: var(--_r-md);
+    background: var(--_paper);
+    border: 1px solid var(--_hairline);
+    text-decoration: none;
+    color: inherit;
+    transition: transform 0.18s ease, box-shadow 0.18s ease, border-color 0.18s ease;
+  }
+  .gmk-card:hover {
+    transform: translateY(-4px);
+    box-shadow: var(--_shadow);
+    border-color: transparent;
+  }
+  .gmk-tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+  }
+  .gmk-tag {
+    font-family: 'Oswald', sans-serif;
+    font-size: 10.5px;
+    font-weight: 600;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--_brand-deep);
+    background: color-mix(in srgb, var(--_brand) 10%, transparent);
+    padding: 4px 9px;
+    border-radius: 999px;
+  }
+  .gmk-card-t {
+    font-family: 'Oswald', 'Inter', sans-serif;
+    font-size: 19px;
+    font-weight: 600;
+    line-height: 1.2;
+    margin: 2px 0 0;
+    color: var(--_ink);
+  }
+  .gmk-card-d {
+    color: var(--_muted);
+    font-size: 14.5px;
+    line-height: 1.5;
+    margin: 0;
+    flex-grow: 1;
+  }
+  .gmk-card-foot {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    margin-top: 6px;
+    padding-top: 12px;
+    border-top: 1px solid var(--_hairline);
+  }
+  .gmk-date {
+    font-size: 12.5px;
+    color: var(--_muted);
+  }
+  .gmk-go {
+    font-family: 'Oswald', sans-serif;
+    font-size: 13px;
+    font-weight: 600;
+    color: var(--_brand-deep);
+  }
+  .gmk-card:hover .gmk-go { color: var(--_brand); }
+</style>

package/src/schema.ts

@@ -1,13 +1,21 @@
 // Data schema for the marketing "pricing comparison" + "trust / credibility"
-// Astro sections. Framework-agnostic types — a product supplies its own typed
-// data object (see kefi-marketing/src/data/marketing.ts) and the two .astro
-// components render it. No product-specific values live here.
+// + "try-it demo" + "guides/content-hub" Astro sections. Framework-agnostic
+// types — a product supplies its own typed data object (see
+// kefi-marketing/src/data/marketing.ts) and the .astro components render it.
+// No product-specific values live here.
 //
 // Themeing is done entirely through CSS custom properties on the host site's
 // `:root` (--brand, --accent, --ink, --paper, --muted, --hairline, radii,
 // --shadow, and the Oswald/Inter font families). The components reference
 // those vars with sensible fallbacks, so a site drops them in and they inherit
 // its palette automatically.
+//
+// The `guideFrontmatterSchema` (bottom of file) is the ONE Zod import — built
+// on Astro's own bundled zod (`astro/zod`, an `astro` peer-dep subpath), so the
+// content collection a host site defines validates guide frontmatter with the
+// SAME zod instance Astro's content layer uses. Everything else is plain types.
+
+import { z } from 'astro/zod';
 
 // ── Pricing comparison ─────────────────────────────────────────────────────
 
@@ -231,3 +239,91 @@ export interface TrustSectionData {
   /** Optional "the actual report you get" showcase (image or named slot). */
   sampleDeliverable?: SampleDeliverable;
 }
+
+// ── Interactive "try it" demo (DemoFrame.astro) ─────────────────────────────
+// The marketing sites are static (nginx, no backend), so the demo is entirely
+// CLIENT-SIDE over curated example data — honest, and clearly labelled "sample".
+// DemoFrame renders the SHARED chrome (eyebrow/title/intro, a row of clickable
+// example chips, a result panel, a "sample data" disclaimer, a primary CTA);
+// each product injects its own bespoke RESULT body per example through a named
+// slot (`slot="result-<example.id>"`) so the result markup stays product-owned
+// while the shell is reused. Tiny inline vanilla JS toggles which result shows;
+// the first example is visible without JS (progressive enhancement).
+
+/** One selectable example in a {@link DemoFrameData}. `id` wires the chip to its
+ *  result body: the host passes `<Fragment slot="result-<id>">…</Fragment>`. */
+export interface DemoExample {
+  /** Stable id — must match the named slot `result-<id>` the host supplies, and
+   *  is used for the chip↔result toggle + analytics. No spaces. */
+  id: string;
+  /** Chip label (e.g. a masked sample wallet or "Clean wallet"). */
+  label: string;
+  /** Optional muted sub-label under the chip (e.g. an expected-verdict hint). */
+  sublabel?: string;
+  /** Optional Umami custom-event name fired when this chip is picked. */
+  analyticsEvent?: string;
+}
+
+export interface DemoFrameData {
+  eyebrow: string;
+  title: string;
+  /** Optional intro paragraph under the title. */
+  intro?: string;
+  /** The clickable examples, in display order. The first is shown by default
+   *  (and is the one visible when JS is off). */
+  examples: DemoExample[];
+  /** The clearly-visible "these are sample results" disclaimer line. */
+  disclaimer: string;
+  /** Primary CTA driving to signup (reuses the shared MarketingCta wiring). */
+  cta: MarketingCta;
+  /** Optional secondary CTA rendered beside the primary. */
+  secondaryCta?: MarketingCta;
+}
+
+// ── SEO guides / content-hub (GuideCard.astro + guideFrontmatterSchema) ──────
+// A shared pattern for a product's guides/content flywheel: the Zod frontmatter
+// schema a host site plugs into an Astro content collection, plus a themeable
+// card that renders one guide in a hub listing. The article page + collection
+// wiring stay product-owned (routes, layout, JSON-LD) — the kit supplies the
+// validated shape + the card so every product's hub looks and validates alike.
+
+/** Zod schema for a guide's frontmatter — plug straight into an Astro content
+ *  collection: `defineCollection({ loader: glob(...), schema: guideFrontmatterSchema })`.
+ *  Built on `astro/zod` so it is the same zod instance Astro's content layer
+ *  uses. `publishDate`/`updatedDate` are coerced from ISO strings to `Date`. */
+export const guideFrontmatterSchema = z.object({
+  /** Headline — also the <title>/OG title. */
+  title: z.string(),
+  /** Meta description + card blurb (~120–160 chars). */
+  description: z.string(),
+  /** Optional route slug override; when omitted the host uses the file id. */
+  slug: z.string().optional(),
+  /** Publication date (ISO string in frontmatter → Date). */
+  publishDate: z.coerce.date(),
+  /** Optional last-updated date. */
+  updatedDate: z.coerce.date().optional(),
+  /** Topic tags for the card + on-page chips. */
+  tags: z.array(z.string()).default([]),
+  /** Optional per-guide OG image URL (falls back to the site default). */
+  ogImage: z.string().optional(),
+  /** Optional canonical override (defaults to the guide's own URL). */
+  canonical: z.string().optional(),
+  /** Draft guides are excluded from the hub + routes. */
+  draft: z.boolean().default(false),
+});
+
+/** The inferred frontmatter type (a guide entry's `data`). */
+export type GuideFrontmatter = z.infer<typeof guideFrontmatterSchema>;
+
+/** Props for {@link GuideCard}: one guide's card fields + its resolved href.
+ *  A superset-compatible subset of {@link GuideFrontmatter} plus `href` so the
+ *  host maps `entry.data` + the route in one place. */
+export interface GuideCardData {
+  title: string;
+  description: string;
+  href: string;
+  tags?: string[];
+  /** Accepts a `Date` (from the collection) or a preformatted string. */
+  publishDate: Date | string;
+  updatedDate?: Date | string;
+}