Restyle on the Carbon Design System

Adopt Carbon at the design-token level (the component libraries ship JS and
target app UIs; this is a static content site):

- IBM Plex Sans/Mono, self-hosted via @fontsource (no external requests)
- Carbon color tokens + layered White / Gray 100 themes
- 8px spacing scale, productive/expressive type, motion tokens, square
  geometry, 2px focus ring
- UI-shell header, tile grid, Carbon tags, geometric severity meter,
  breadcrumb, colophon crediting Carbon
- Charts themed with IBM Plex + Carbon's data-visualization palette
  (validated colorblind-safe/contrast) on a fixed light canvas so the
  build-time SVG stays legible in both themes

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XPEvmMbac2fCvKXpQcovj8

README.md

@@ -3,21 +3,34 @@
 A catalogue of data-visualization sins — for each one: the chart that misleads,
 why it fools the eye, and the honest version that fixes it.
 
-Built with [Astro](https://astro.build). Charts are authored as
+Built with [Astro](https://astro.build) and styled on the
+[Carbon Design System](https://carbondesignsystem.com). Charts are authored as
 [Vega-Lite](https://vega.github.io/vega-lite/) specs and rendered to **static
 SVG at build time**, so pages ship with zero client-side JavaScript.
 
 ## Tech stack
 
-| Concern    | Choice                                              |
+| Concern    | Choice                											  |
 | ---------- | --------------------------------------------------- |
 | Framework  | Astro 5 (static output)                             |
 | Content    | Markdown/MDX via Astro Content Collections          |
 | Charts     | Vega-Lite specs → SVG at build (headless Vega)       |
-| Styling    | Plain scoped CSS + one global stylesheet            |
+| Design     | Carbon Design System — tokens, type scale, spacing, motion, themes |
+| Typeface   | IBM Plex Sans / Mono (self-hosted via `@fontsource`) |
+| Styling    | Token-driven CSS (`src/styles/global.css`)          |
 | Hosting    | GitHub Pages (via GitHub Actions)                   |
 | Language   | TypeScript                                          |
 
+### On the Carbon adoption
+
+Carbon ships React/web-component libraries built for application UIs and they
+ship JavaScript; this is a static content site, so instead of the component
+runtime we adopt Carbon at the **design-token level** — its color tokens and
+White/Gray-100 themes, the 8px spacing scale, the productive/expressive type
+distinction (IBM Plex), motion tokens, square geometry, the focus ring, and
+Carbon's **data-visualization palette** for the charts (validated for
+colorblind-safety and contrast on the chart surface).
+
 ## Project layout
 
 ```

package.json

@@ -12,6 +12,8 @@
   },
   "dependencies": {
     "@astrojs/mdx": "^4.2.0",
+    "@fontsource/ibm-plex-mono": "^5.3.0",
+    "@fontsource/ibm-plex-sans": "^5.3.0",
     "astro": "^5.6.0",
     "vega": "^5.30.0",
     "vega-lite": "^5.21.0"

src/charts/dual-axis-bad.json

@@ -19,15 +19,15 @@
   },
   "layer": [
     {
-      "mark": { "type": "line", "color": "#c0392b", "point": true },
+      "mark": { "type": "line", "color": "#fa4d56", "point": true },
       "encoding": {
-        "y": { "field": "icecream", "type": "quantitative", "title": "Ice cream sales", "axis": { "titleColor": "#c0392b" } }
+        "y": { "field": "icecream", "type": "quantitative", "title": "Ice cream sales", "axis": { "titleColor": "#fa4d56" } }
       }
     },
     {
-      "mark": { "type": "line", "color": "#2980b9", "point": true },
+      "mark": { "type": "line", "color": "#1192e8", "point": true },
       "encoding": {
-        "y": { "field": "sharks", "type": "quantitative", "title": "Shark attacks", "axis": { "titleColor": "#2980b9" } }
+        "y": { "field": "sharks", "type": "quantitative", "title": "Shark attacks", "axis": { "titleColor": "#1192e8" } }
       }
     }
   ],

src/charts/dual-axis-fixed.json

@@ -16,7 +16,7 @@
     {
       "width": 360,
       "height": 110,
-      "mark": { "type": "line", "color": "#c0392b", "point": true },
+      "mark": { "type": "line", "color": "#fa4d56", "point": true },
       "encoding": {
         "x": { "field": "month", "type": "ordinal", "sort": null, "axis": { "title": null, "labels": false } },
         "y": { "field": "icecream", "type": "quantitative", "scale": { "zero": true }, "title": "Ice cream" }
@@ -25,7 +25,7 @@
     {
       "width": 360,
       "height": 110,
-      "mark": { "type": "line", "color": "#2980b9", "point": true },
+      "mark": { "type": "line", "color": "#1192e8", "point": true },
       "encoding": {
         "x": { "field": "month", "type": "ordinal", "sort": null, "axis": { "title": null, "labelAngle": 0 } },
         "y": { "field": "sharks", "type": "quantitative", "scale": { "zero": true }, "title": "Shark attacks" }

src/charts/pie-overload-fixed.json

@@ -14,7 +14,7 @@
       { "browser": "Other", "share": 2 }
     ]
   },
-  "mark": { "type": "bar", "color": "#1e8b5b" },
+  "mark": { "type": "bar", "color": "#198038" },
   "encoding": {
     "y": { "field": "browser", "type": "nominal", "sort": "-x", "axis": { "title": null } },
     "x": { "field": "share", "type": "quantitative", "title": "Share (%)" }

src/charts/truncated-axis-bad.json

@@ -12,7 +12,7 @@
       { "month": "Jun", "revenue": 98 }
     ]
   },
-  "mark": { "type": "bar", "color": "#c0392b" },
+  "mark": { "type": "bar", "color": "#da1e28" },
   "encoding": {
     "x": {
       "field": "month",

src/charts/truncated-axis-fixed.json

@@ -12,7 +12,7 @@
       { "month": "Jun", "revenue": 98 }
     ]
   },
-  "mark": { "type": "bar", "color": "#1e8b5b" },
+  "mark": { "type": "bar", "color": "#198038" },
   "encoding": {
     "x": {
       "field": "month",

src/components/VegaChart.astro

@@ -1,39 +1,76 @@
 ---
-// Build-time Vega-Lite renderer.
+// Build-time Vega-Lite renderer, themed on Carbon.
 //
-// This component runs only during `astro build` (and dev SSR), never in the
+// Runs only during `astro build` (and dev SSR), never in the browser: it
-// browser. It compiles a Vega-Lite spec to Vega, renders it to a static SVG
+// compiles a Vega-Lite spec to Vega with a Carbon theme (IBM Plex type +
-// string with Vega's headless view, and inlines that SVG. The result ships as
+// Carbon's data-visualization palette), renders it headlessly to a static SVG
-// plain markup — zero client-side JavaScript, no Vega runtime downloaded.
+// string, and inlines it. Zero client-side JavaScript, no Vega runtime shipped.
 //
-// To make a specific chart interactive later, you would swap this component
+// The chart sits on a fixed light Carbon canvas (--chart-canvas) in both
-// out for a client-side vega-embed island on that page only.
+// themes, so this single baked render keeps AA contrast in light and dark.
 import * as vega from 'vega';
-import { compile, type TopLevelSpec } from 'vega-lite';
+import { compile, type TopLevelSpec, type Config } from 'vega-lite';
 
 interface Props {
-  /** A Vega-Lite spec (object). Do not include $schema/width/height/config. */
   spec: TopLevelSpec;
-  /** Accessible description of what the chart shows. */
   title: string;
-  /** Optional caption rendered under the chart. */
   caption?: string;
 }
 
 const { spec, title, caption } = Astro.props;
 
+// Carbon Vega theme — the design-system parameters the renderer consumes.
+const carbonTheme: Config = {
+  font: 'IBM Plex Sans',
+  background: 'transparent',
+  view: { stroke: null },
+  title: {
+    color: '#161616',
+    font: 'IBM Plex Sans',
+    fontSize: 13,
+    fontWeight: 600,
+    anchor: 'start',
+    dy: -8,
+  },
+  axis: {
+    labelFont: 'IBM Plex Sans',
+    labelFontSize: 11,
+    labelColor: '#525252',
+    titleFont: 'IBM Plex Sans',
+    titleFontSize: 12,
+    titleFontWeight: 600,
+    titleColor: '#393939',
+    gridColor: '#e0e0e0',
+    domainColor: '#8d8d8d',
+    tickColor: '#8d8d8d',
+    labelPadding: 4,
+  },
+  legend: {
+    labelFont: 'IBM Plex Sans',
+    labelFontSize: 11,
+    labelColor: '#525252',
+    titleFont: 'IBM Plex Sans',
+    titleFontSize: 12,
+    titleColor: '#393939',
+    symbolType: 'square',
+  },
+  // Carbon data-visualization categorical palette (validated: passes the
+  // dataviz colorblind/contrast checks on the --chart-canvas surface).
+  range: {
+    category: ['#8a3ffc', '#009d9a', '#fa4d56', '#0f62fe', '#24a148', '#d02670', '#b28600', '#1192e8'],
+  },
+};
+
 let svg = '';
 let error: string | null = null;
 
 try {
-  // Compile Vega-Lite -> Vega, then render headlessly to SVG.
+  const vgSpec = compile(spec, { config: carbonTheme }).spec;
-  const vgSpec = compile(spec as TopLevelSpec).spec;
   const view = new vega.View(vega.parse(vgSpec), { renderer: 'none' }).initialize();
   svg = await view.toSVG();
   view.finalize();
 } catch (e) {
   error = e instanceof Error ? e.message : String(e);
-  // Fail loudly in the build log, but don't crash the whole build.
   console.error(`[VegaChart] failed to render "${title}": ${error}`);
 }
 ---
@@ -49,32 +86,3 @@ try {
   )}
   {caption && <figcaption>{caption}</figcaption>}
 </figure>
-
-<style>
-  .vega-chart {
-    margin: 0;
-  }
-  .vega-chart__svg :global(svg) {
-    max-width: 100%;
-    height: auto;
-  }
-  .vega-chart figcaption {
-    margin-top: 0.5rem;
-    font-size: 0.85rem;
-    color: var(--muted);
-    text-align: center;
-  }
-  .vega-chart__error {
-    padding: 1rem;
-    border: 1px dashed var(--sin-red);
-    border-radius: 8px;
-    color: var(--sin-red);
-    font-size: 0.85rem;
-  }
-  .vega-chart__error code {
-    display: block;
-    margin-top: 0.5rem;
-    white-space: pre-wrap;
-    word-break: break-word;
-  }
-</style>

src/layouts/BaseLayout.astro

@@ -1,4 +1,9 @@
 ---
+// IBM Plex, self-hosted via @fontsource (no external requests) — Carbon's typeface.
+import '@fontsource/ibm-plex-sans/300.css';
+import '@fontsource/ibm-plex-sans/400.css';
+import '@fontsource/ibm-plex-sans/600.css';
+import '@fontsource/ibm-plex-mono/400.css';
 import '../styles/global.css';
 import { href } from '../lib/url';
 
@@ -7,7 +12,8 @@ interface Props {
   description?: string;
 }
 
-const { title, description = 'A catalogue of data-visualization sins.' } = Astro.props;
+const { title, description = 'A catalogue of data-visualization sins, styled on the Carbon Design System.' } =
+  Astro.props;
 ---
 
 <!doctype html>
@@ -19,20 +25,38 @@ const { title, description = 'A catalogue of data-visualization sins.' } = Astro
     <title>{title}</title>
   </head>
   <body>
-    <header class="site-header">
+    <a class="skip-link" href="#main">Skip to content</a>
-      <div class="wrap">
+
-        <a class="brand" href={href()}>⚡ Chart Sins</a>
+    <header class="cds-header">
-        <span class="tagline">The bad chart, the repentance, the fixed version.</span>
+      <div class="cds-header__inner">
+        <a class="cds-header__name" href={href()}>
+          Chart&nbsp;Sins <span class="mono">/ honest data-viz</span>
+        </a>
+        <span class="cds-header__tag">built on Carbon</span>
       </div>
     </header>
 
-    <main>
+    <main id="main">
       <slot />
     </main>
 
-    <footer class="site-footer">
+    <footer class="cds-footer">
-      <div class="wrap">
+      <div class="wrap cds-footer__inner">
-        Chart Sins — an educational catalogue of data-visualization mistakes.
+        <div class="cds-footer__col">
+          <strong>Chart Sins</strong>
+          <p>An educational catalogue of data-visualization mistakes — the bad chart, why it deceives, and the honest fix.</p>
+        </div>
+        <div class="cds-footer__col">
+          <strong>Design</strong>
+          <p>
+            Built on the <a href="https://carbondesignsystem.com" rel="noopener">Carbon Design System</a>'s
+            principles — open, modular, consistent, inclusive. Typeface: IBM&nbsp;Plex.
+          </p>
+        </div>
+        <div class="cds-footer__col">
+          <strong>Charts</strong>
+          <p>Authored in Vega-Lite, rendered to static SVG at build time on Carbon's data-visualization palette.</p>
+        </div>
       </div>
     </footer>
   </body>

src/lib/charts.ts

@@ -23,7 +23,24 @@ export function getChartSpec(name: string): TopLevelSpec {
   return spec;
 }
 
-/** Render a 1–5 severity as flame glyphs for display. */
+/** A 1–5 severity as five booleans, for the Carbon-style severity meter. */
-export function severityFlames(severity: number): string {
+export function severityUnits(severity: number): boolean[] {
-  return '🔥'.repeat(severity) + '·'.repeat(Math.max(0, 5 - severity));
+  return Array.from({ length: 5 }, (_, i) => i < severity);
+}
+
+// Stable category -> Carbon tag color. Known categories get a hand-picked hue;
+// anything new hashes to a stable colour so the palette never churns.
+const TAG_COLORS = ['purple', 'teal', 'red', 'blue', 'magenta'] as const;
+const CATEGORY_TAG: Record<string, (typeof TAG_COLORS)[number]> = {
+  'Misleading Scales': 'blue',
+  'False Relationships': 'magenta',
+  'Chart-Type Abuse': 'purple',
+};
+
+/** Map a category label to a Carbon tag colour modifier. */
+export function tagModifier(category: string): (typeof TAG_COLORS)[number] {
+  if (CATEGORY_TAG[category]) return CATEGORY_TAG[category];
+  let hash = 0;
+  for (let i = 0; i < category.length; i++) hash = (hash * 31 + category.charCodeAt(i)) >>> 0;
+  return TAG_COLORS[hash % TAG_COLORS.length];
 }

src/pages/index.astro

@@ -1,7 +1,7 @@
 ---
 import { getCollection } from 'astro:content';
 import BaseLayout from '../layouts/BaseLayout.astro';
-import { severityFlames } from '../lib/charts';
+import { severityUnits, tagModifier } from '../lib/charts';
 import { href } from '../lib/url';
 
 const sins = (await getCollection('sins', ({ data }) => !data.draft)).sort((a, b) => {
@@ -13,10 +13,11 @@ const sins = (await getCollection('sins', ({ data }) => !data.draft)).sort((a, b
 
 <BaseLayout title="Chart Sins">
   <section class="wrap hero">
-    <h1>A catalogue of chart sins.</h1>
+    <p class="hero__eyebrow">// a catalogue of data-visualization sins</p>
-    <p>
+    <h1 class="expressive-display">Charts that lie,<br />and the honest fix.</h1>
-      Every entry is a data-visualization mistake in the wild: the chart that
+    <p class="hero__lede">
-      misleads, why it fools the eye, and the honest version that fixes it.
+      Each entry is a data-visualization mistake in the wild: the chart that
+      misleads, why it fools the eye, and the honest version that repents.
     </p>
   </section>
 
@@ -24,15 +25,19 @@ const sins = (await getCollection('sins', ({ data }) => !data.draft)).sort((a, b
     <div class="gallery">
       {
         sins.map((sin) => (
-          <a class="card" href={href(`sins/${sin.id}/`)}>
+          <a class="tile" href={href(`sins/${sin.id}/`)}>
-            <span class="pill">{sin.data.category}</span>
+            <span class={`tag tag--${tagModifier(sin.data.category)}`}>{sin.data.category}</span>
-            <h3>{sin.data.title}</h3>
+            <h2 class="tile__title">{sin.data.title}</h2>
-            <p>{sin.data.summary}</p>
+            <p class="tile__summary">{sin.data.summary}</p>
-            <div class="meta">
+            <div class="tile__meta">
-              <span class="severity" title={`Severity ${sin.data.severity} of 5`}>
+              <span class="severity" aria-label={`Severity ${sin.data.severity} of 5`}>
-                {severityFlames(sin.data.severity)}
+                <span class="severity__meter" aria-hidden="true">
+                  {severityUnits(sin.data.severity).map((on) => (
+                    <span class={`severity__unit${on ? ' severity__unit--on' : ''}`} />
+                  ))}
+                </span>
               </span>
-              <span class="pill">Read →</span>
+              <span class="tile__go">Read →</span>
             </div>
           </a>
         ))

src/pages/sins/[...slug].astro

@@ -2,7 +2,7 @@
 import { getCollection, render } from 'astro:content';
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import VegaChart from '../../components/VegaChart.astro';
-import { getChartSpec, severityFlames } from '../../lib/charts';
+import { getChartSpec, severityUnits, tagModifier } from '../../lib/charts';
 import { href } from '../../lib/url';
 
 export async function getStaticPaths() {
@@ -22,24 +22,33 @@ const fixedSpec = getChartSpec(sin.data.fixedChart);
 
 <BaseLayout title={`${sin.data.title} — Chart Sins`} description={sin.data.summary}>
   <article class="wrap sin">
-    <header>
+    <nav class="breadcrumb"><a href={href()}>All sins</a> / {sin.data.title}</nav>
-      <span class="pill">{sin.data.category}</span>
+
-      <h1>{sin.data.title}</h1>
+    <header class="sin__head">
-      <span class="severity" title={`Severity ${sin.data.severity} of 5`}>
+      <div class="sin__meta">
-        {severityFlames(sin.data.severity)}
+        <span class={`tag tag--${tagModifier(sin.data.category)}`}>{sin.data.category}</span>
-      </span>
+        <span class="severity" aria-label={`Severity ${sin.data.severity} of 5`}>
-      <div class="tags">
+          <span class="severity__meter" aria-hidden="true">
-        {sin.data.tags.map((t) => <span class="pill">{t}</span>)}
+            {severityUnits(sin.data.severity).map((on) => (
+              <span class={`severity__unit${on ? ' severity__unit--on' : ''}`} />
+            ))}
+          </span>
+          Severity {sin.data.severity}/5
+        </span>
+      </div>
+      <h1 class="sin__title expressive-heading">{sin.data.title}</h1>
+      <div class="sin__tags">
+        {sin.data.tags.map((t) => <span class="tag">{t}</span>)}
       </div>
     </header>
 
     <div class="compare">
-      <div class="panel bad">
+      <div class="panel panel--bad">
-        <h2>The Sin</h2>
+        <p class="panel__label">The Sin</p>
         <VegaChart spec={badSpec} title={`Misleading chart: ${sin.data.title}`} />
       </div>
-      <div class="panel good">
+      <div class="panel panel--good">
-        <h2>The Fix</h2>
+        <p class="panel__label">The Fix</p>
         <VegaChart spec={fixedSpec} title={`Honest chart: ${sin.data.title}`} />
       </div>
     </div>
@@ -47,7 +56,5 @@ const fixedSpec = getChartSpec(sin.data.fixedChart);
     <div class="prose">
       <Content />
     </div>
-
-    <a class="back-link" href={href()}>← All sins</a>
   </article>
 </BaseLayout>

src/styles/global.css

@@ -1,235 +1,575 @@
+/*
+  Chart Sins — styled on the Carbon Design System.
+
+  This is a token-driven layer, the way Carbon itself is built:
+  - Color/theme tokens mirror Carbon's White + Gray 100 themes, layered
+    (background -> layer-01 -> layer-02) rather than picked ad hoc.
+  - Spacing follows Carbon's 8px mini-unit scale ($spacing-01..13).
+  - Type is IBM Plex, split into Carbon's "productive" (UI/reading) and
+    "expressive" (large, light-weight display) moments.
+  - Motion uses Carbon's productive easing + duration tokens.
+  - Geometry is Carbon: square corners, 1px subtle borders, a 2px focus ring.
+*/
+
+/* ------------------------------------------------------------------ *\
+   Tokens — White theme (light) is the default :root.
+\* ------------------------------------------------------------------ */
 :root {
-  --bg: #fbf9f6;
+  /* --- spacing scale (Carbon $spacing-01 .. 13) --- */
-  --surface: #ffffff;
+  --spacing-01: 0.125rem;
-  --text: #1c1a17;
+  --spacing-02: 0.25rem;
-  --muted: #6b6660;
+  --spacing-03: 0.5rem;
-  --border: #e6e1d9;
+  --spacing-04: 0.75rem;
-  --accent: #7c3aed;
+  --spacing-05: 1rem;
-  --sin-red: #c0392b;
+  --spacing-06: 1.5rem;
-  --good-green: #1e8b5b;
+  --spacing-07: 2rem;
-  --maxw: 68rem;
+  --spacing-08: 2.5rem;
-  --radius: 12px;
+  --spacing-09: 3rem;
-  font-family: system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --spacing-10: 4rem;
+  --spacing-11: 5rem;
+  --spacing-12: 6rem;
+  --spacing-13: 10rem;
+
+  /* --- motion (Carbon) --- */
+  --ease-productive: cubic-bezier(0.2, 0, 0.38, 0.9);
+  --ease-expressive: cubic-bezier(0.4, 0.14, 0.3, 1);
+  --dur-fast: 110ms;
+  --dur-moderate: 150ms;
+  --dur-slow: 240ms;
+
+  /* --- layout --- */
+  --page-max: 82rem;
+  --measure: 40rem; /* Carbon reading measure ~640px */
+
+  /* --- color tokens: White theme --- */
+  --background: #ffffff;
+  --layer-01: #f4f4f4;
+  --layer-02: #ffffff;
+  --layer-hover-01: #e8e8e8;
+  --border-subtle: #e0e0e0;
+  --border-strong: #8d8d8d;
+  --text-primary: #161616;
+  --text-secondary: #525252;
+  --text-helper: #6f6f6f;
+  --text-on-color: #ffffff;
+  --link-primary: #0f62fe;
+  --link-hover: #0043ce;
+  --interactive: #0f62fe;
+  --focus: #0f62fe;
+  --support-error: #da1e28;
+  --support-success: #198038;
+
+  /* header/footer shell is always dark in Carbon */
+  --shell-bg: #161616;
+  --shell-border: #393939;
+  --shell-text: #f4f4f4;
+  --shell-text-secondary: #a8a8a8;
+
+  /* chart canvas — a fixed light Carbon layer in BOTH themes, so the
+     build-time-baked chart ink keeps AA contrast without theme-reactive SVG */
+  --chart-canvas: #f4f4f4;
+
+  --font-sans: "IBM Plex Sans", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --font-mono: "IBM Plex Mono", ui-monospace, "SF Mono", Menlo, monospace;
+
+  color-scheme: light;
 }
 
+/* --- Gray 100 theme (dark) --- */
 @media (prefers-color-scheme: dark) {
   :root {
-    --bg: #16140f;
+    --background: #161616;
-    --surface: #201d17;
+    --layer-01: #262626;
-    --text: #f3efe8;
+    --layer-02: #393939;
-    --muted: #a8a196;
+    --layer-hover-01: #333333;
-    --border: #35302a;
+    --border-subtle: #393939;
-    --accent: #a78bfa;
+    --border-strong: #6f6f6f;
-    --sin-red: #e07668;
+    --text-primary: #f4f4f4;
-    --good-green: #4cc38a;
+    --text-secondary: #c6c6c6;
+    --text-helper: #8d8d8d;
+    --text-on-color: #ffffff;
+    --link-primary: #78a9ff;
+    --link-hover: #a6c8ff;
+    --interactive: #4589ff;
+    --focus: #ffffff;
+    --support-error: #fa4d56;
+    --support-success: #42be65;
+    color-scheme: dark;
   }
 }
 
+/* ------------------------------------------------------------------ *\
+   Base
+\* ------------------------------------------------------------------ */
 * {
   box-sizing: border-box;
 }
 
 html {
-  background: var(--bg);
+  background: var(--background);
-  color: var(--text);
+  color: var(--text-primary);
-  scroll-behavior: smooth;
+  font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
 }
 
 body {
   margin: 0;
-  line-height: 1.6;
+  /* Carbon productive body-02 */
+  font-size: 1rem;
+  line-height: 1.5;
+  letter-spacing: 0;
 }
 
 a {
-  color: var(--accent);
+  color: var(--link-primary);
-  text-decoration-thickness: 1px;
-  text-underline-offset: 2px;
-}
-
-.wrap {
-  max-width: var(--maxw);
-  margin-inline: auto;
-  padding-inline: 1.25rem;
-}
-
-.site-header {
-  border-bottom: 1px solid var(--border);
-  background: var(--surface);
-}
-.site-header .wrap {
-  display: flex;
-  align-items: baseline;
-  gap: 1rem;
-  padding-block: 1rem;
-  flex-wrap: wrap;
-}
-.site-header a.brand {
-  font-weight: 800;
-  font-size: 1.25rem;
-  letter-spacing: -0.01em;
-  color: var(--text);
   text-decoration: none;
+  border-bottom: 1px solid transparent;
+  transition: border-color var(--dur-fast) var(--ease-productive),
+    color var(--dur-fast) var(--ease-productive);
 }
-.site-header .tagline {
+a:hover {
-  color: var(--muted);
+  color: var(--link-hover);
-  font-size: 0.9rem;
+  border-bottom-color: currentColor;
 }
 
-.site-footer {
+/* Carbon focus ring — 2px, high-contrast, square */
-  border-top: 1px solid var(--border);
+:where(a, button, [tabindex]):focus-visible {
-  margin-top: 4rem;
+  outline: 2px solid var(--focus);
-  color: var(--muted);
+  outline-offset: 2px;
-  font-size: 0.85rem;
+  border-radius: 0;
-}
-.site-footer .wrap {
-  padding-block: 2rem;
 }
 
-.severity {
+code {
-  letter-spacing: 1px;
+  font-family: var(--font-mono);
-  font-size: 0.9rem;
+  font-size: 0.875em;
-  color: var(--sin-red);
+  background: var(--layer-01);
+  border: 1px solid var(--border-subtle);
+  padding: 0 var(--spacing-02);
 }
 
-.pill {
+/* ------------------------------------------------------------------ *\
-  display: inline-block;
+   Type scale — productive + expressive (Carbon)
-  font-size: 0.75rem;
+\* ------------------------------------------------------------------ */
-  padding: 0.15rem 0.6rem;
+.expressive-display {
-  border-radius: 999px;
+  font-weight: 300; /* Carbon expressive uses light weight at large sizes */
-  border: 1px solid var(--border);
+  font-size: clamp(2.25rem, 1.4rem + 4.2vw, 4rem);
-  color: var(--muted);
+  line-height: 1.07;
-  background: var(--bg);
-}
-
-/* --- index gallery --- */
-.hero {
-  padding-block: 3rem 1.5rem;
-}
-.hero h1 {
-  font-size: clamp(2rem, 5vw, 3.2rem);
-  line-height: 1.1;
-  margin: 0 0 0.75rem;
   letter-spacing: -0.02em;
+  margin: 0;
 }
-.hero p {
+.expressive-heading {
-  color: var(--muted);
+  font-weight: 400;
-  font-size: 1.1rem;
+  font-size: clamp(1.5rem, 1.1rem + 1.6vw, 2rem);
-  max-width: 44rem;
+  line-height: 1.25;
+  letter-spacing: 0;
+  margin: 0;
+}
+.productive-heading-03 {
+  font-weight: 400;
+  font-size: 1.25rem;
+  line-height: 1.4;
+  margin: var(--spacing-07) 0 var(--spacing-03);
+}
+.label-01 {
+  font-size: 0.75rem;
+  line-height: 1.34;
+  letter-spacing: 0.32px;
+  color: var(--text-helper);
+}
+.helper {
+  color: var(--text-secondary);
 }
 
+/* ------------------------------------------------------------------ *\
+   Layout primitives
+\* ------------------------------------------------------------------ */
+.wrap {
+  max-width: var(--page-max);
+  margin-inline: auto;
+  padding-inline: var(--spacing-05);
+}
+@media (min-width: 42rem) {
+  .wrap {
+    padding-inline: var(--spacing-07);
+  }
+}
+
+/* ------------------------------------------------------------------ *\
+   UI Shell header — Carbon's header is dark in every theme
+\* ------------------------------------------------------------------ */
+.cds-header {
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  background: var(--shell-bg);
+  border-bottom: 1px solid var(--shell-border);
+}
+.cds-header__inner {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-05);
+  height: 3rem;
+  max-width: var(--page-max);
+  margin-inline: auto;
+  padding-inline: var(--spacing-05);
+}
+.cds-header__name {
+  color: var(--shell-text);
+  font-weight: 600;
+  font-size: 1rem;
+  letter-spacing: 0.1px;
+  text-decoration: none;
+  border: 0;
+}
+.cds-header__name:hover {
+  color: var(--shell-text);
+}
+.cds-header__name .mono {
+  font-family: var(--font-mono);
+  font-weight: 400;
+}
+.cds-header__tag {
+  color: var(--shell-text-secondary);
+  font-size: 0.8125rem;
+  font-family: var(--font-mono);
+  letter-spacing: 0;
+}
+@media (max-width: 40rem) {
+  .cds-header__tag {
+    display: none;
+  }
+}
+
+/* ------------------------------------------------------------------ *\
+   Tag (Carbon tags are the one rounded element)
+\* ------------------------------------------------------------------ */
+.tag {
+  display: inline-flex;
+  align-items: center;
+  height: 1.5rem;
+  padding-inline: var(--spacing-04);
+  border-radius: 999px;
+  font-size: 0.75rem;
+  line-height: 1;
+  letter-spacing: 0.16px;
+  white-space: nowrap;
+  background: var(--layer-01);
+  color: var(--text-secondary);
+  border: 1px solid transparent;
+}
+/* Carbon tag color pairings (light bg + readable ink) */
+.tag--purple { background: #e8daff; color: #491d8b; }
+.tag--teal   { background: #9ef0f0; color: #005d5d; }
+.tag--red    { background: #ffd7d9; color: #a2191f; }
+.tag--blue   { background: #d0e2ff; color: #002d9c; }
+.tag--magenta{ background: #ffd6e8; color: #9f1853; }
+@media (prefers-color-scheme: dark) {
+  .tag--purple { background: #491d8b; color: #e8daff; }
+  .tag--teal   { background: #005d5d; color: #9ef0f0; }
+  .tag--red    { background: #a2191f; color: #ffd7d9; }
+  .tag--blue   { background: #0043ce; color: #d0e2ff; }
+  .tag--magenta{ background: #9f1853; color: #ffd6e8; }
+}
+
+/* ------------------------------------------------------------------ *\
+   Severity meter — 5 geometric units (Carbon-flavored, not emoji)
+\* ------------------------------------------------------------------ */
+.severity {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-03);
+  font-size: 0.75rem;
+  color: var(--text-helper);
+  letter-spacing: 0.32px;
+}
+.severity__meter {
+  display: inline-flex;
+  gap: 3px;
+}
+.severity__unit {
+  width: 0.75rem;
+  height: 0.75rem;
+  background: var(--border-subtle);
+}
+.severity__unit--on {
+  background: var(--support-error);
+}
+
+/* ------------------------------------------------------------------ *\
+   Hero
+\* ------------------------------------------------------------------ */
+.hero {
+  padding-block: var(--spacing-10) var(--spacing-07);
+  border-bottom: 1px solid var(--border-subtle);
+}
+.hero__eyebrow {
+  font-family: var(--font-mono);
+  font-size: 0.8125rem;
+  letter-spacing: 0.16px;
+  color: var(--text-helper);
+  margin: 0 0 var(--spacing-05);
+}
+.hero__lede {
+  color: var(--text-secondary);
+  font-size: 1.25rem;
+  line-height: 1.4;
+  max-width: var(--measure);
+  margin: var(--spacing-05) 0 0;
+  font-weight: 300;
+}
+
+/* ------------------------------------------------------------------ *\
+   Gallery of tiles
+\* ------------------------------------------------------------------ */
 .gallery {
   display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(18rem, 1fr));
+  grid-template-columns: repeat(auto-fill, minmax(19rem, 1fr));
-  gap: 1.25rem;
+  gap: 1px; /* Carbon tiles sit in a 1px grid of border color */
-  padding-block: 1rem 2rem;
+  background: var(--border-subtle);
+  border: 1px solid var(--border-subtle);
+  margin-block: var(--spacing-09) var(--spacing-10);
 }
-
+.tile {
-.card {
   display: flex;
   flex-direction: column;
-  gap: 0.6rem;
+  gap: var(--spacing-04);
-  padding: 1.25rem;
+  padding: var(--spacing-06);
-  background: var(--surface);
+  min-height: 12rem;
-  border: 1px solid var(--border);
+  background: var(--layer-01);
-  border-radius: var(--radius);
-  text-decoration: none;
   color: inherit;
-  transition: transform 0.12s ease, border-color 0.12s ease;
+  text-decoration: none;
+  border: 0;
+  position: relative;
+  transition: background var(--dur-fast) var(--ease-productive);
 }
-.card:hover {
+.tile:hover {
-  transform: translateY(-2px);
+  background: var(--layer-hover-01);
-  border-color: var(--accent);
+  color: inherit;
 }
-.card h3 {
+/* interactive affordance: a blue rule that slides in on hover (productive motion) */
+.tile::after {
+  content: "";
+  position: absolute;
+  left: 0;
+  bottom: 0;
+  height: 3px;
+  width: 0;
+  background: var(--interactive);
+  transition: width var(--dur-moderate) var(--ease-productive);
+}
+.tile:hover::after {
+  width: 100%;
+}
+.tile__title {
+  font-size: 1.25rem;
+  font-weight: 400;
+  line-height: 1.3;
   margin: 0;
-  font-size: 1.15rem;
+  letter-spacing: 0;
-  letter-spacing: -0.01em;
 }
-.card p {
+.tile__summary {
   margin: 0;
-  color: var(--muted);
+  color: var(--text-secondary);
-  font-size: 0.92rem;
+  font-size: 0.875rem;
+  line-height: 1.43;
 }
-.card .meta {
+.tile__meta {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: 0.5rem;
+  gap: var(--spacing-05);
   margin-top: auto;
+  padding-top: var(--spacing-04);
+}
+.tile__go {
+  font-family: var(--font-mono);
+  font-size: 0.8125rem;
+  color: var(--interactive);
 }
 
-/* --- sin detail page --- */
+/* ------------------------------------------------------------------ *\
+   Sin detail
+\* ------------------------------------------------------------------ */
+.breadcrumb {
+  font-family: var(--font-mono);
+  font-size: 0.8125rem;
+  padding-top: var(--spacing-07);
+}
 .sin {
-  padding-block: 2.5rem;
+  padding-bottom: var(--spacing-10);
 }
-.sin header {
+.sin__head {
-  margin-bottom: 2rem;
+  padding-block: var(--spacing-05) var(--spacing-07);
+  border-bottom: 1px solid var(--border-subtle);
 }
-.sin h1 {
+.sin__meta {
-  font-size: clamp(1.8rem, 4vw, 2.6rem);
-  margin: 0.4rem 0 0.5rem;
-  letter-spacing: -0.02em;
-}
-.sin .tags {
   display: flex;
-  gap: 0.4rem;
   flex-wrap: wrap;
-  margin-top: 0.75rem;
+  align-items: center;
+  gap: var(--spacing-05);
+  margin-bottom: var(--spacing-05);
+}
+.sin__title {
+  margin: 0;
+}
+.sin__tags {
+  display: flex;
+  gap: var(--spacing-03);
+  flex-wrap: wrap;
+  margin-top: var(--spacing-05);
 }
 
 .compare {
   display: grid;
   grid-template-columns: 1fr;
-  gap: 1.5rem;
+  gap: 1px;
-  margin: 2rem 0;
+  background: var(--border-subtle);
+  border: 1px solid var(--border-subtle);
+  margin-block: var(--spacing-08);
 }
-@media (min-width: 46rem) {
+@media (min-width: 48rem) {
   .compare {
     grid-template-columns: 1fr 1fr;
   }
 }
-.compare .panel {
+.panel {
-  padding: 1.25rem;
+  background: var(--layer-01);
-  border-radius: var(--radius);
+  padding: var(--spacing-06);
-  border: 1px solid var(--border);
-  background: var(--surface);
 }
-.compare .panel.bad {
+.panel__label {
-  border-top: 4px solid var(--sin-red);
+  display: flex;
-}
+  align-items: center;
-.compare .panel.good {
+  gap: var(--spacing-03);
-  border-top: 4px solid var(--good-green);
+  margin: 0 0 var(--spacing-05);
-}
+  font-size: 0.75rem;
-.compare .panel h2 {
+  font-weight: 600;
-  margin: 0 0 1rem;
+  letter-spacing: 0.32px;
-  font-size: 1rem;
   text-transform: uppercase;
-  letter-spacing: 0.05em;
 }
-.compare .panel.bad h2 {
+.panel__label::before {
-  color: var(--sin-red);
+  content: "";
+  width: 0.75rem;
+  height: 0.75rem;
 }
-.compare .panel.good h2 {
+.panel--bad .panel__label {
-  color: var(--good-green);
+  color: var(--support-error);
+}
+.panel--bad .panel__label::before {
+  background: var(--support-error);
+}
+.panel--good .panel__label {
+  color: var(--support-success);
+}
+.panel--good .panel__label::before {
+  background: var(--support-success);
 }
 
+/* build-time chart, on a fixed light Carbon canvas */
+.vega-chart {
+  margin: 0;
+}
+.vega-chart__svg {
+  background: var(--chart-canvas);
+  padding: var(--spacing-05);
+  overflow-x: auto;
+}
+.vega-chart__svg svg {
+  max-width: 100%;
+  height: auto;
+  display: block;
+}
+.vega-chart figcaption {
+  margin-top: var(--spacing-04);
+  font-size: 0.75rem;
+  color: var(--text-helper);
+}
+.vega-chart__error {
+  padding: var(--spacing-05);
+  border: 1px solid var(--support-error);
+  color: var(--support-error);
+  font-family: var(--font-mono);
+  font-size: 0.8125rem;
+}
+.vega-chart__error code {
+  display: block;
+  margin-top: var(--spacing-03);
+  white-space: pre-wrap;
+  word-break: break-word;
+  background: none;
+  border: 0;
+  padding: 0;
+}
+
+/* long-form prose — Carbon reading measure + productive type */
 .prose {
-  max-width: 42rem;
+  max-width: var(--measure);
+  margin-top: var(--spacing-08);
+}
+.prose > :first-child {
+  margin-top: 0;
 }
 .prose h2 {
-  margin-top: 2rem;
+  font-size: 1.25rem;
-  letter-spacing: -0.01em;
+  font-weight: 600;
+  line-height: 1.4;
+  margin: var(--spacing-08) 0 var(--spacing-03);
 }
-.prose code {
+.prose p {
-  background: var(--surface);
+  margin: 0 0 var(--spacing-05);
-  border: 1px solid var(--border);
+  color: var(--text-secondary);
-  border-radius: 4px;
+}
-  padding: 0.1rem 0.35rem;
+.prose strong {
-  font-size: 0.9em;
+  color: var(--text-primary);
+  font-weight: 600;
+}
+.prose em {
+  color: var(--text-primary);
 }
 
-.back-link {
+/* ------------------------------------------------------------------ *\
-  display: inline-block;
+   Footer + colophon
-  margin-top: 3rem;
+\* ------------------------------------------------------------------ */
-  font-size: 0.9rem;
+.cds-footer {
+  background: var(--layer-01);
+  border-top: 1px solid var(--border-subtle);
+  margin-top: var(--spacing-12);
+}
+.cds-footer__inner {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--spacing-05) var(--spacing-09);
+  padding-block: var(--spacing-08);
+  font-size: 0.8125rem;
+  color: var(--text-secondary);
+}
+.cds-footer__col strong {
+  display: block;
+  color: var(--text-primary);
+  font-weight: 600;
+  margin-bottom: var(--spacing-03);
+}
+.cds-footer__col p {
+  margin: 0;
+  max-width: 22rem;
+  line-height: 1.5;
+}
+
+.skip-link {
+  position: absolute;
+  left: -9999px;
+}
+.skip-link:focus {
+  left: var(--spacing-05);
+  top: var(--spacing-03);
+  z-index: 20;
+  background: var(--interactive);
+  color: var(--text-on-color);
+  padding: var(--spacing-03) var(--spacing-05);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  * {
+    transition: none !important;
+  }
 }