feat(website): the social card shows the product, and the brand gets a real mark (#1047)

* docs(website): design for the framed social card kit

One card kit on the site's own light surface, showing the approval beat
inside the site's browser frame. Records two constraints found while
prototyping: Satori kills the render worker on WebP, so card art must be
generated PNG; and Inter and the mono face are fetched from Google Fonts on
every render, so they should be bundled like Garamond already is.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(website): the social card shows the product, and the brand gets a real mark

The card was dark, centred, and built from a seam and a glow that exist
nowhere else, so the light page it opened looked like a different product.
It now renders on the site's own ground through a shared kit: the rail rule
and mono eyebrow, the BrowserFrame with its traffic lights, the pills, the
wordmark. Inside the frame, three beats drawn rather than screenshotted —
an ask, a proposal, and an Approve/Decline pair — so the card shows the
human-in-the-loop claim the copy makes.

The blog card moves onto the same kit, which retires the near-black blue it
alone used.

The airplane emoji is replaced by a drawn paper plane, shared by the nav and
footer wordmark, the card, src/app/icon.svg as the favicon, a regenerated
favicon.ico, and a square logo that finally lets the Organization structured
data assert a logo.

Two constraints found while prototyping and recorded in the spec: Satori kills
the render worker on WebP, which rules out every screenshot we own; and Inter
and the mono face were fetched from Google Fonts on every render, failing
silently when unreachable. All four faces are now bundled, instanced and
subset by scripts/build-card-fonts.py, and together are smaller than the one
unsubsetted Garamond they replace.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: blove

apps/website/e2e/website.spec.ts

@@ -27,6 +27,18 @@ test('landing page renders hero headline', async ({ page }) => {
   await expect(page.locator('.hero-eyebrow')).toContainText('Angular');
 });
 
+test('the default social card renders as a PNG', async ({ request }) => {
+  // The default card is rendered at request time, so a Satori rejection — a
+  // div with two children and no explicit `display`, a font it cannot parse —
+  // is a 500 on the live route rather than a build failure. The blog's cards
+  // are prerendered and already fail the build, so only this one needs a
+  // runtime check.
+  const res = await request.get('/opengraph-image');
+  expect(res.status()).toBe(200);
+  expect(res.headers()['content-type']).toContain('image/png');
+  expect((await res.body()).byteLength).toBeGreaterThan(10_000);
+});
+
 test('landing page renders the dark proof band', async ({ page }) => {
   await page.goto('/');
   await expect(page.locator('#proof-heading')).toBeVisible();

apps/website/public/brand/logo-180.png

@@ -0,0 +1,108 @@
+"""
+Generate the static, subsetted TTFs the social cards render with.
+
+Why this script exists
+----------------------
+Satori (the engine behind Next.js ImageResponse) cannot decode woff2, which is
+the only format Google Fonts serves, and it crashes on variable-weight TTFs
+with "Cannot read properties of undefined (reading '256')". So every face a
+card uses has to be instanced to a single weight, stripped of its variable
+tables, and committed.
+
+Until now only Garamond was bundled (see instance-garamond.py, which this
+script supersedes). Inter and JetBrains Mono were scraped from the Google
+Fonts CSS API on every card render. That is a network round trip inside an
+image render, and when it fails there is no error — the card silently falls
+back to whatever loaded, which is how a card whose eyebrow and pills are
+specified in mono came out set in serif. Bundling removes the dependency.
+
+The fonts are subsetted to Latin plus the punctuation the site actually uses,
+which is what keeps four faces under 150KB total rather than well over 1MB.
+Blog post titles are the only unbounded text on a card; anything outside this
+range falls back to Satori's bundled Noto Sans rather than failing.
+
+Usage:
+    pip install --user fonttools brotli
+    python3 apps/website/scripts/build-card-fonts.py
+
+Re-run if an upstream font is updated, and commit the result.
+"""
+
+import os
+import tempfile
+import urllib.request
+
+from fontTools import subset
+from fontTools.ttLib import TTFont
+from fontTools.varLib.instancer import instantiateVariableFont
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+OUT_DIR = os.path.join(os.path.dirname(HERE), "src", "app", "card", "fonts")
+
+# Basic Latin, Latin-1 Supplement, and the General Punctuation the site uses
+# (typographic quotes, en/em dashes, ellipsis, the middot separator).
+UNICODES = "U+0020-007E,U+00A0-00FF,U+2010-2015,U+2018-201A,U+201C-201E,U+2022,U+2026,U+2030,U+2039,U+203A,U+20AC,U+00B7"
+
+FACES = [
+    {
+        "name": "EBGaramond-Bold.ttf",
+        "url": "https://github.com/google/fonts/raw/main/ofl/ebgaramond/EBGaramond%5Bwght%5D.ttf",
+        "weight": 700,
+    },
+    {
+        "name": "Inter-Regular.ttf",
+        "url": "https://github.com/google/fonts/raw/main/ofl/inter/Inter%5Bopsz,wght%5D.ttf",
+        "weight": 400,
+    },
+    {
+        "name": "Inter-SemiBold.ttf",
+        "url": "https://github.com/google/fonts/raw/main/ofl/inter/Inter%5Bopsz,wght%5D.ttf",
+        "weight": 600,
+    },
+    {
+        "name": "JetBrainsMono-Bold.ttf",
+        "url": "https://github.com/google/fonts/raw/main/ofl/jetbrainsmono/JetBrainsMono%5Bwght%5D.ttf",
+        "weight": 700,
+    },
+]
+
+
+def build(face: dict) -> None:
+    with tempfile.NamedTemporaryFile(suffix=".ttf", delete=False) as tmp:
+        print(f"  downloading {face['url']}")
+        with urllib.request.urlopen(face["url"]) as res:
+            tmp.write(res.read())
+        raw = tmp.name
+
+    font = TTFont(raw)
+    axes = {"wght": face["weight"]}
+    # Inter carries an optical-size axis as well; pin it to its text setting so
+    # instancing leaves no variable tables behind for Satori to trip over.
+    if "fvar" in font and any(a.axisTag == "opsz" for a in font["fvar"].axes):
+        axes["opsz"] = 14
+    font = instantiateVariableFont(font, axes, updateFontNames=False, inplace=True)
+    for table in ("fvar", "STAT", "MVAR", "HVAR", "VVAR", "gvar", "cvar", "avar"):
+        if table in font:
+            del font[table]
+
+    options = subset.Options()
+    options.set(layout_features=["*"], name_IDs=["*"], notdef_outline=True)
+    subsetter = subset.Subsetter(options=options)
+    subsetter.populate(unicodes=subset.parse_unicodes(UNICODES))
+    subsetter.subset(font)
+
+    out = os.path.join(OUT_DIR, face["name"])
+    font.save(out)
+    os.unlink(raw)
+    print(f"  wrote {face['name']} ({os.path.getsize(out) // 1024}KB)")
+
+
+def main() -> None:
+    os.makedirs(OUT_DIR, exist_ok=True)
+    for face in FACES:
+        print(f"{face['name']} @ {face['weight']}")
+        build(face)
+
+
+if __name__ == "__main__":
+    main()

apps/website/public/brand/logo-512.png

@@ -2,6 +2,8 @@ import { ImageResponse } from 'next/og';
 import { getAllPosts, getPostBySlug } from '../../../lib/blog';
 import { getAuthor } from '../../../lib/blog-authors';
 import { loadCardFonts } from '../../og-font';
+import { CARD } from '../../card/tokens';
+import { Rail, Wordmark } from '../../card/chrome';
 
 export const runtime = 'nodejs';
 export const alt = 'Threadplane blog post';
@@ -43,8 +45,8 @@ export default async function og({ params }: Params) {
             display: 'flex',
             alignItems: 'center',
             justifyContent: 'center',
-            background: '#0b0d12',
-            color: '#ffffff',
+            background: CARD.ground,
+            color: CARD.ink,
             fontSize: 64,
           }}
         >
@@ -55,7 +57,7 @@ export default async function og({ params }: Params) {
     );
   }
 
-  const fonts = await loadCardFonts();
+  const fonts = await loadCardFonts({ mono: true });
   const author = getAuthor(post.frontmatter.author);
 
   return new ImageResponse(
@@ -68,42 +70,37 @@ export default async function og({ params }: Params) {
           flexDirection: 'column',
           justifyContent: 'space-between',
           padding: 64,
-          background: '#0b0d12',
-          color: '#ffffff',
+          background: CARD.ground,
+          color: CARD.ink,
           fontFamily: 'Inter, sans-serif',
         }}
       >
-        <div
-          style={{
-            fontSize: 24,
-            textTransform: 'uppercase',
-            letterSpacing: '0.12em',
-            opacity: 0.6,
-          }}
-        >
-          Threadplane Blog
-        </div>
+        <Rail text="THREADPLANE BLOG" />
         <div
           style={{
             fontFamily: 'EB Garamond, Georgia, serif',
             fontSize: 64,
             fontWeight: 700,
             lineHeight: 1.1,
             letterSpacing: '-0.02em',
-            maxWidth: '90%',
+            color: CARD.ink,
+            maxWidth: '92%',
           }}
         >
           {post.frontmatter.title}
         </div>
         {/*
           Satori requires an explicit `display` on any div with more than one
-          child node, and throws otherwise. This byline has three (name,
-          separator, date), so the `display: flex` is load-bearing — its
-          absence is what 500ed every post's card. The two divs above have a
-          single child each and need no `display`.
+          child node, and throws otherwise. This row has two (the byline and
+          the wordmark), and the byline itself has three (name, separator,
+          date), so both `display: flex` are load-bearing — their absence is
+          what 500ed every post's card.
         */}
-        <div style={{ display: 'flex', fontSize: 24, opacity: 0.7 }}>
-          {author.name} · {post.frontmatter.date}
+        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+          <div style={{ display: 'flex', fontSize: 24, color: CARD.inkMuted }}>
+            {author.name} · {post.frontmatter.date}
+          </div>
+          <Wordmark size={30} />
         </div>
       </div>
     ),

apps/website/public/brand/mark.svg

@@ -0,0 +1,89 @@
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { CARD, MIN_READABLE_PX } from './tokens';
+import { alt } from '../opengraph-image';
+import { HERO_SUBHEAD, PRIMARY_TAGLINE } from '../../lib/positioning';
+
+const REPO_ROOT = join(__dirname, '..', '..', '..', '..', '..');
+const THEME_CSS = join(REPO_ROOT, 'libs', 'design-tokens', 'src', 'lib', 'theme.css');
+
+/** `rgb(28, 28, 28)` → `#1c1c1c`. Values in theme.css use either form. */
+function toHex(value: string): string {
+  const rgb = value.match(/rgb\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)\s*\)/u);
+  if (!rgb) return value.trim().toLowerCase();
+  return `#${[rgb[1], rgb[2], rgb[3]].map((n) => Number(n).toString(16).padStart(2, '0')).join('')}`;
+}
+
+function tokenValue(name: string): string {
+  const css = readFileSync(THEME_CSS, 'utf8');
+  const match = css.match(new RegExp(`--${name}:\\s*([^;]+);`, 'u'));
+  if (!match) throw new Error(`token --${name} not found in theme.css`);
+  return toHex(match[1]);
+}
+
+describe('card tokens', () => {
+  /**
+   * Satori cannot read CSS variables, so the card palette is a hand-copied
+   * snapshot of the light design tokens. A snapshot with nothing checking it
+   * is a snapshot that goes stale silently — the card would keep rendering,
+   * in last season's colours, and only a human comparing a share preview to
+   * the live site would ever notice.
+   */
+  it.each([
+    ['ground', CARD.ground, 'color-surface-tinted'],
+    ['dim', CARD.dim, 'color-surface-dim'],
+    ['ink', CARD.ink, 'color-text-primary'],
+    ['inkSecondary', CARD.inkSecondary, 'color-text-secondary'],
+    ['inkMuted', CARD.inkMuted, 'color-text-muted'],
+    ['border', CARD.border, 'color-border'],
+    ['borderStrong', CARD.borderStrong, 'color-border-strong'],
+    ['accent', CARD.accent, 'color-accent'],
+  ])('%s still matches the design token', (_label, resolved, token) => {
+    expect(resolved.toLowerCase()).toBe(tokenValue(token));
+  });
+});
+
+describe('card fonts', () => {
+  /**
+   * These are read off disk at render time. If one goes missing the card does
+   * not fail — `satoriFonts` drops it and Satori falls back — so a deleted or
+   * unbuilt face is invisible until someone looks at a card and finds the
+   * mono eyebrow set in serif. Assert they exist instead.
+   */
+  it.each([
+    'EBGaramond-Bold.ttf',
+    'Inter-Regular.ttf',
+    'Inter-SemiBold.ttf',
+    'JetBrainsMono-Bold.ttf',
+  ])('%s is bundled', (name) => {
+    const stat = statSync(join(__dirname, 'fonts', name));
+    expect(stat.isFile()).toBe(true);
+    expect(stat.size).toBeGreaterThan(10_000);
+  });
+
+  it('ships static TTFs, not variable ones', () => {
+    // Satori throws "Cannot read properties of undefined (reading '256')" on a
+    // variable font, which would 500 the request-time default card. The build
+    // script strips `fvar`; this asserts the tag is absent from the file.
+    for (const name of ['EBGaramond-Bold.ttf', 'Inter-Regular.ttf', 'JetBrainsMono-Bold.ttf']) {
+      const buf = readFileSync(join(__dirname, 'fonts', name));
+      expect(buf.subarray(0, 2048).includes(Buffer.from('fvar'))).toBe(false);
+    }
+  });
+});
+
+describe('default card alt text', () => {
+  it('describes the picture, and quotes the positioning copy rather than retyping it', () => {
+    expect(alt).toContain(PRIMARY_TAGLINE);
+    expect(alt).toContain(HERO_SUBHEAD);
+    // The card's whole claim is that it shows the product stopping for a
+    // human. Alt text that only names the product would leave a screen-reader
+    // user with the marketing line and none of the evidence.
+    expect(alt).toMatch(/Approve and Decline/u);
+  });
+
+  it('keeps a floor for readable type', () => {
+    expect(MIN_READABLE_PX).toBeGreaterThanOrEqual(18);
+  });
+});