@sustainablewebsites/verdant-design 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Ivan Storck
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @sustainablewebsites/verdant-design
+
+Verdant is a [PandaCSS](https://panda-css.com) preset with defaults aligned to selected [W3C Web Sustainability Guidelines](https://w3c.github.io/sustainableweb-wsg/): system fonts instead of downloaded ones, only the CSS a page actually uses, contrast-verified semantic colour tokens, and dark mode, reduced motion and increased contrast respected out of the box.
+
+It ships tokens, recipes, layout primitives and a theme contract — not a component library. You write your own markup.
+
+```bash
+npm install -D @sustainablewebsites/verdant-design
+```
+
+```js
+// panda.config.ts
+import { defineConfig } from '@pandacss/dev'
+import { verdantPreset } from '@sustainablewebsites/verdant-design'
+
+export default defineConfig({
+  preflight: true,
+  presets: ['@pandacss/dev/presets', verdantPreset],
+  include: ['./src/**/*.{js,jsx,ts,tsx}'],
+  outdir: 'styled-system',
+})
+```
+
+To make an explicit Light/Dark choice work you also need the theme runtime shipped at
+`@sustainablewebsites/verdant-design/theme-toggle.js`. Without it you get `prefers-color-scheme` only.
+
+**[Full installation guide, token reference and known gaps →](https://github.com/ivanoats/verdant-wsg-demo/blob/main/docs/INSTALL.md)**
+
+## What's in it
+
+- **Tokens** — a 7-step spacing scale, 4 radii, 6 type sizes, system `sans`/`mono` stacks. No web fonts.
+- **Semantic colours** — `surface.*`, `ink.*`, `accent.*`, `border.*`, status colours, each with light and dark values. 17 pairings contrast-verified in both themes; worst text pairing 4.80:1, worst functional 4.35:1.
+- **Recipes** — `button`, `card`, `fieldInput`, `switchTrack`, `spinner`, `skeleton`. 44px minimum targets; animation bounded and gated behind `prefers-reduced-motion`.
+- **Patterns** — `container`, `stack`, `grid`, replacing Panda's built-ins so defaults come from Verdant's scale.
+- **Theme contract** — System/Light/Dark from one token set, plus a `prefers-contrast: more` set verified at 7:1 text and 4.5:1 boundaries.
+
+## Status
+
+0.x — the API may change between minor versions. See [known gaps](https://github.com/ivanoats/verdant-wsg-demo/blob/main/docs/INSTALL.md#known-gaps).
+
+Live demo and reference implementation: [verdant-wsg-demo.netlify.app](https://verdant-wsg-demo.netlify.app/)
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@sustainablewebsites/verdant-design",
+  "version": "0.1.0",
+  "description": "A Green Web Design System with Sustainable Defaults following W3C WSG guidelines",
+  "type": "module",
+  "license": "ISC",
+  "author": "Ivan Storck",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ivanoats/verdant-wsg-demo.git",
+    "directory": "packages/verdant-design"
+  },
+  "homepage": "https://github.com/ivanoats/verdant-wsg-demo/blob/main/docs/INSTALL.md",
+  "keywords": ["pandacss", "panda-preset", "design-system", "sustainability", "wsg", "accessibility"],
+  "exports": {
+    ".": "./src/preset.mjs",
+    "./tokens": "./src/tokens.mjs",
+    "./theme": "./src/theme.mjs",
+    "./theme-toggle.js": "./src/theme-toggle.js"
+  },
+  "files": ["src", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@pandacss/dev": ">=1.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/preset.mjs

@@ -0,0 +1,240 @@
+// The Verdant design system as a PandaCSS preset: tokens, semantic colours,
+// recipes, layout primitives and the theme/contrast contract.
+//
+// Everything here is theme data. The site that consumes it supplies its own
+// `include`/`outdir` (see the repo's panda.config.ts for a worked example).
+import { definePreset } from '@pandacss/dev'
+import { fontFamilyTokens, spacingTokens, radiiTokens, fontSizeTokens, lineHeightTokens } from './tokens.mjs'
+import { explicitThemeVars, highContrastVars, semanticColorTokens, themeOverrideAttr, themeResolvedAttr } from './theme.mjs'
+
+const important = (vars) =>
+  Object.fromEntries(Object.entries(vars).map(([name, value]) => [name, `${value} !important`]))
+
+export const verdantPreset = definePreset({
+  name: 'verdant-design',
+  conditions: {
+    dark: '@media (prefers-color-scheme: dark)',
+  },
+
+  theme: {
+    extend: {
+      tokens: {
+        fonts: Object.fromEntries(Object.entries(fontFamilyTokens).map(([key, value]) => [key, { value }])),
+        spacing: Object.fromEntries(Object.entries(spacingTokens).map(([key, value]) => [key, { value }])),
+        radii: Object.fromEntries(Object.entries(radiiTokens).map(([key, value]) => [key, { value }])),
+        fontSizes: Object.fromEntries(Object.entries(fontSizeTokens).map(([key, value]) => [key, { value }])),
+        lineHeights: Object.fromEntries(Object.entries(lineHeightTokens).map(([key, value]) => [key, { value }])),
+      },
+      semanticTokens: {
+        colors: {
+          ...semanticColorTokens,
+        },
+        shadows: {
+          sm: {
+            value: {
+              base: '0 1px 2px rgba(28,26,21,0.08), 0 1px 1px rgba(28,26,21,0.04)',
+              _dark: '0 1px 2px rgba(0,0,0,0.45), 0 1px 1px rgba(0,0,0,0.3)',
+            },
+          },
+        },
+      },
+      recipes: {
+        button: {
+          className: 'btn',
+          base: {
+            fontSize: 'bodySm', lineHeight: 'bodySm', fontWeight: '600', letterSpacing: '0.02em',
+            minHeight: '44px', paddingBlock: '2', paddingInline: '4', borderRadius: 'md', border: '1px solid transparent',
+            cursor: 'pointer', outlineOffset: '2px', display: 'inline-flex', alignItems: 'center', justifyContent: 'center', textDecorationLine: 'none',
+            _motionSafe: { transition: 'background-color 120ms ease, border-color 120ms ease' },
+            _disabled: { opacity: '0.5', cursor: 'not-allowed' },
+          },
+          variants: {
+            variant: {
+              primary: {
+                background: 'accent', color: 'accent.ink', _hover: { background: 'accent.strong' },
+                // Toggle buttons: the pressed look follows aria-pressed, so the
+                // visual and announced state can't drift apart.
+                '&[aria-pressed=true]': { background: 'accent.strong' },
+              },
+              secondary: { background: 'transparent', color: 'ink', borderColor: 'border.control', _hover: { borderColor: 'accent', color: 'accent' } },
+            },
+          },
+          defaultVariants: { variant: 'primary' },
+        },
+        card: {
+          className: 'card',
+          base: {
+            background: 'surface.200', border: '1px solid', borderColor: 'border',
+            borderRadius: 'md', padding: '4',
+          },
+        },
+        fieldInput: {
+          className: 'fieldInput',
+          base: {
+            fontSize: 'body', lineHeight: 'body', fontFamily: 'sans',
+            width: '100%', minHeight: '44px', paddingBlock: '2', paddingInline: '3', border: '1px solid', borderColor: 'border.control',
+            borderRadius: 'sm', background: 'surface.200', color: 'ink',
+            _placeholder: { color: 'ink.placeholder', opacity: '1' },
+            _focusVisible: { outline: '2px solid', outlineColor: 'focusRing', outlineOffset: '1px', borderColor: 'transparent' },
+            _readOnly: { background: 'surface.100', color: 'ink.muted' },
+          },
+        },
+        switchTrack: {
+          className: 'switchTrack',
+          base: {
+            position: 'relative', width: '44px', height: '44px', borderRadius: 'full',
+            background: 'transparent', border: 'none', cursor: 'pointer', padding: '0', flex: 'none',
+            _before: {
+              content: '""',
+              position: 'absolute',
+              top: '10px',
+              left: '0',
+              width: '44px',
+              height: '24px',
+              borderRadius: 'full',
+              background: 'border.control',
+            },
+            _motionSafe: { _before: { transition: 'background-color 150ms ease' } },
+            // State lives in aria-checked at runtime, so the track colour follows
+            // it here (inside the recipe layer, so it outranks the base colour).
+            '&[aria-checked="true"]': { _before: { background: 'accent' } },
+          },
+          variants: {
+            on: { true: { _before: { background: 'accent' } } },
+          },
+        },
+        spinner: {
+          className: 'spinner',
+          base: {
+            width: '28px', height: '28px', borderRadius: 'full',
+            border: '3px solid', borderColor: 'border', borderTopColor: 'accent',
+          },
+          variants: {
+            preview: {
+              true: {
+                _motionSafe: { animation: 'spin 900ms linear 4' },
+              },
+            },
+          },
+        },
+        skeleton: {
+          className: 'skeleton',
+          base: {
+            borderRadius: 'sm', background: 'border', opacity: '0.5',
+          },
+          variants: {
+            preview: {
+              true: {
+                _motionSafe: { animation: 'pulse 1400ms ease-in-out 3' },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+
+  // Layout primitives. These replace Panda's built-in container, stack and
+  // grid so every default comes from Verdant's tokens: a 1080px page
+  // container with token padding, and 16px (spacing 4) gaps. Grid tracks use
+  // minmax(0, 1fr), and auto-fit tracks cap their minimum at 100%, so a wide
+  // fallback font can never push a column past a 320px viewport.
+  patterns: {
+    extend: {
+      container: {
+        description: 'Centered page container, capped at 1080px, with responsive token padding.',
+        properties: { maxWidth: { type: 'property', value: 'maxWidth' } },
+        defaultValues: { maxWidth: '1080px' },
+        transform(props) {
+          const { maxWidth, ...rest } = props
+          return { position: 'relative', width: '100%', maxWidth, marginInline: 'auto', paddingInline: { base: '4', md: '6' }, ...rest }
+        },
+      },
+      stack: {
+        description: 'Vertical (or horizontal) flow with a spacing-token gap.',
+        properties: {
+          align: { type: 'property', value: 'alignItems' },
+          justify: { type: 'property', value: 'justifyContent' },
+          direction: { type: 'property', value: 'flexDirection' },
+          gap: { type: 'property', value: 'gap' },
+        },
+        defaultValues: { direction: 'column', gap: '4' },
+        transform(props) {
+          const { align, justify, direction, gap, ...rest } = props
+          return { display: 'flex', flexDirection: direction, alignItems: align, justifyContent: justify, gap, ...rest }
+        },
+      },
+      grid: {
+        description: 'Responsive grid: fixed columns, or auto-fit columns with a minimum child width.',
+        properties: {
+          gap: { type: 'property', value: 'gap' },
+          columns: { type: 'number' },
+          minChildWidth: { type: 'string' },
+        },
+        defaultValues: { gap: '4' },
+        transform(props, { map }) {
+          const { gap, columns, minChildWidth, ...rest } = props
+          const tracks = () => {
+            if (columns != null) return map(columns, (v) => `repeat(${v}, minmax(0, 1fr))`)
+            if (minChildWidth != null) return map(minChildWidth, (v) => `repeat(auto-fit, minmax(min(${v}, 100%), 1fr))`)
+            return undefined
+          }
+          return { display: 'grid', gridTemplateColumns: tracks(), gap, ...rest }
+        },
+      },
+    },
+  },
+
+  globalCss: {
+    'html': { colorScheme: 'light dark' },
+    // Panda emits token variables in the `tokens` layer, which comes after
+    // `base` (where globalCss lives), so a plain declaration here would lose
+    // to them. `!important` in an earlier layer beats normal declarations in
+    // any later layer, which is exactly the override an explicit choice needs.
+    [`html[${themeOverrideAttr}="light"]`]: important(explicitThemeVars.light),
+    [`html[${themeOverrideAttr}="dark"]`]: important(explicitThemeVars.dark),
+    // prefers-contrast: more — stronger token values in whichever theme is
+    // showing, plus thicker boundaries. Same !important reasoning as above;
+    // these come later in the same layer, so they win over the plain theme.
+    '@media (prefers-contrast: more)': {
+      [`html:not([${themeOverrideAttr}]), html[${themeOverrideAttr}="light"]`]: important(highContrastVars.light),
+      [`html[${themeOverrideAttr}="dark"]`]: important(highContrastVars.dark),
+      '.fieldInput, .btn--variant_secondary, .card': { borderWidth: '2px !important' },
+      ':focus-visible': { outlineWidth: '3px !important' },
+      'a': { textDecorationThickness: '0.12em' },
+    },
+    '@media (prefers-contrast: more) and (prefers-color-scheme: dark)': {
+      [`html:not([${themeOverrideAttr}])`]: important(highContrastVars.dark),
+    },
+    [`html[${themeResolvedAttr}="light"]`]: { colorScheme: 'light' },
+    [`html[${themeResolvedAttr}="dark"]`]: { colorScheme: 'dark' },
+    'body': { margin: '0', background: 'surface.100', color: 'ink', fontFamily: 'sans', fontSize: 'body', lineHeight: 'body' },
+    'a': {
+      color: 'accent',
+      textDecoration: 'underline',
+      textUnderlineOffset: '0.15em',
+      textDecorationThickness: '0.08em',
+    },
+    'a:hover': { color: 'accent.strong' },
+    ':focus-visible': { outline: '2px solid', outlineColor: 'focusRing', outlineOffset: '2px' },
+    '@keyframes spin': { to: { transform: 'rotate(360deg)' } },
+    '@keyframes pulse': { '0%, 100%': { opacity: '0.35' }, '50%': { opacity: '0.65' } },
+    // Verdant's art grows in once, then holds still. Only referenced from
+    // inside prefers-reduced-motion: no-preference (see scripts/art.mjs).
+    '@keyframes leafGrow': { from: { transform: 'scale(0)' }, to: { transform: 'scale(1)' } },
+    '@keyframes stemGrow': { from: { transform: 'scaleY(0)' }, to: { transform: 'scaleY(1)' } },
+    '@keyframes hillRise': { from: { opacity: '0', transform: 'translateY(40px)' }, to: { opacity: '1', transform: 'translateY(0)' } },
+    '@keyframes sprout': { from: { transform: 'scale(0.2)', opacity: '0' }, to: { transform: 'scale(1)', opacity: '1' } },
+    '@keyframes sunRise': { from: { opacity: '0', transform: 'translateY(24px)' }, to: { opacity: '1', transform: 'translateY(0)' } },
+    '.switchTrack .knob': {
+      position: 'absolute', top: '12px', left: '2px', width: '20px', height: '20px',
+      borderRadius: 'var(--radii-full)', background: 'var(--colors-surface-200)',
+    },
+    '@media (prefers-reduced-motion: no-preference)': {
+      '.switchTrack .knob': { transition: 'transform 150ms ease' },
+    },
+    '.switchTrack[aria-checked="true"] .knob': { transform: 'translateX(20px)' },
+  },
+})
+
+export default verdantPreset

package/src/theme-toggle.js

@@ -0,0 +1,117 @@
+// Verdant theme runtime. Load this synchronously in <head>, before the
+// stylesheet, so the stored preference is applied before first paint and there
+// is no flash of the wrong theme.
+//
+// The preset's globalCss keys off data-theme-override, so without this script a
+// page gets prefers-color-scheme only and an explicit Light/Dark choice cannot
+// take effect. See docs/INSTALL.md.
+//
+// The constants below mirror src/theme.mjs; tests/theme-contract.test.mjs
+// fails the build if the two ever drift apart.
+(function () {
+  const STORAGE_KEY = "verdant-theme-preference";
+  const OVERRIDE_ATTR = "data-theme-override";
+  const PREFERENCE_ATTR = "data-theme-preference";
+  const RESOLVED_ATTR = "data-theme-resolved";
+  const CONTROL_NAME = "theme-preference";
+  const THEME_COLOR = { light: "#faf8f3", dark: "#15140f" };
+  const RADIO_SELECTOR = `input[name="${CONTROL_NAME}"]`;
+  const media = window.matchMedia ? window.matchMedia("(prefers-color-scheme: dark)") : null;
+
+  // Declared before the functions that close over it: applyPreference runs
+  // immediately below, and the listeners read it long after.
+  let currentPreference = "system";
+
+  function systemTheme() {
+    return media?.matches ? "dark" : "light";
+  }
+
+  function readPreference() {
+    try {
+      const saved = window.localStorage.getItem(STORAGE_KEY);
+      if (saved === "light" || saved === "dark") return saved;
+    } catch {
+      // Private mode or blocked storage: fall through to the system default.
+    }
+    return "system";
+  }
+
+  function persistPreference(value) {
+    try {
+      if (value === "system") window.localStorage.removeItem(STORAGE_KEY);
+      else window.localStorage.setItem(STORAGE_KEY, value);
+    } catch {
+      // Storage is unavailable; the choice still applies for this page view.
+    }
+  }
+
+  // Browser chrome follows the resolved theme: an explicit choice pins every
+  // theme-color meta to that theme; System restores the media-query fallbacks.
+  function syncThemeColor(value, resolved) {
+    for (const meta of document.querySelectorAll('meta[name="theme-color"]')) {
+      if (!meta.hasAttribute("data-media")) {
+        meta.setAttribute("data-media", meta.getAttribute("media") || "");
+        meta.setAttribute("data-content", meta.getAttribute("content") || "");
+      }
+      if (value === "system") {
+        meta.setAttribute("media", meta.getAttribute("data-media"));
+        meta.setAttribute("content", meta.getAttribute("data-content"));
+      } else {
+        meta.removeAttribute("media");
+        meta.setAttribute("content", THEME_COLOR[resolved]);
+      }
+    }
+  }
+
+  function applyPreference(value) {
+    const resolved = value === "system" ? systemTheme() : value;
+    const root = document.documentElement;
+    root.setAttribute(PREFERENCE_ATTR, value);
+    root.setAttribute(RESOLVED_ATTR, resolved);
+    if (value === "system") root.removeAttribute(OVERRIDE_ATTR);
+    else root.setAttribute(OVERRIDE_ATTR, value);
+    syncThemeColor(value, resolved);
+    return resolved;
+  }
+
+  function syncControls() {
+    for (const radio of document.querySelectorAll(RADIO_SELECTOR)) {
+      radio.checked = radio.value === currentPreference;
+    }
+  }
+
+  currentPreference = readPreference();
+  applyPreference(currentPreference);
+
+  // Declared once rather than per radio: every control shares one handler, and
+  // the chosen value comes from the event, not from the loop.
+  function handlePreferenceChange(event) {
+    currentPreference = event.target.value;
+    persistPreference(currentPreference);
+    applyPreference(currentPreference);
+  }
+
+  document.addEventListener("DOMContentLoaded", function () {
+    syncControls();
+    for (const radio of document.querySelectorAll(RADIO_SELECTOR)) {
+      radio.addEventListener("change", handlePreferenceChange);
+    }
+  });
+
+  // A page restored from the back/forward cache keeps its old DOM state:
+  // re-read the stored choice in case it changed on another page meanwhile.
+  window.addEventListener("pageshow", function (event) {
+    if (!event.persisted) return;
+    currentPreference = readPreference();
+    applyPreference(currentPreference);
+    syncControls();
+  });
+
+  if (media) {
+    const onSystemChange = function () {
+      if (currentPreference === "system") applyPreference("system");
+    };
+    if (typeof media.addEventListener === "function") media.addEventListener("change", onSystemChange);
+    else if (typeof media.addListener === "function") media.addListener(onSystemChange);
+  }
+})();

package/src/theme.mjs

@@ -0,0 +1,116 @@
+export const themePreferenceStorageKey = 'verdant-theme-preference'
+export const themePreferenceControlName = 'theme-preference'
+export const themePreferenceValues = ['system', 'light', 'dark']
+export const themePreferenceAttr = 'data-theme-preference'
+export const themeResolvedAttr = 'data-theme-resolved'
+export const themeOverrideAttr = 'data-theme-override'
+
+export const themeVarName = (name) =>
+  `--colors-${name.replace(/\./g, '-').replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()}`
+
+export const themeTokens = {
+  'surface.100': { light: '#faf8f3', dark: '#15140f' },
+  'surface.200': { light: '#ffffff', dark: '#1e1c15' },
+  border: { light: '#c7bda9', dark: '#514b3b' },
+  'border.control': { light: '#7f735b', dark: '#8f866f' },
+  ink: { light: '#1c1a15', dark: '#f1ede2' },
+  'ink.muted': { light: '#5b5548', dark: '#b6ae9c' },
+  'ink.placeholder': { light: '#75726a', dark: '#8d8a81' },
+  accent: { light: '#2f6b4a', dark: '#7fcfa3' },
+  'accent.strong': { light: '#234f38', dark: '#5fb98c' },
+  'accent.ink': { light: '#ffffff', dark: '#10241a' },
+  focusRing: { light: '#a5670a', dark: '#e8a83e' },
+  foliage: { light: '#3ca24a', dark: '#45ad55' },
+  'foliage.far': { light: '#cdeaae', dark: '#1c3a22' },
+  'foliage.mid': { light: '#9ed65f', dark: '#2d6b34' },
+  'foliage.deep': { light: '#1f6a31', dark: '#2a7d3a' },
+  'foliage.bright': { light: '#6fcd4f', dark: '#86dc62' },
+  sunlight: { light: '#f4b63f', dark: '#e8a83e' },
+  positive: { light: '#1f7a6c', dark: '#5cc9b7' },
+  info: { light: '#2b5f8e', dark: '#8cbcea' },
+  warning: { light: '#8a5a00', dark: '#f2c14e' },
+  critical: { light: '#c1440e', dark: '#ff8f5e' },
+}
+
+const hasChildren = (key) => Object.keys(themeTokens).some((candidate) => candidate.startsWith(`${key}.`))
+
+const nestToken = (root, key, value) => {
+  const parts = key.includes('.') ? key.split('.') : hasChildren(key) ? [key, 'DEFAULT'] : [key]
+  let cursor = root
+  for (const part of parts.slice(0, -1)) {
+    cursor[part] ||= {}
+    cursor = cursor[part]
+  }
+  cursor[parts.at(-1)] = value
+}
+
+export const semanticColorTokens = Object.entries(themeTokens).reduce((colors, [name, value]) => {
+  nestToken(colors, name, { value: { base: value.light, _dark: value.dark } })
+  return colors
+}, {})
+
+const themeVarsFor = (mode) => Object.fromEntries(
+  Object.entries(themeTokens).map(([name, value]) => [themeVarName(name), value[mode]])
+)
+
+export const explicitThemeVars = {
+  light: themeVarsFor('light'),
+  dark: themeVarsFor('dark'),
+}
+
+export const themeTokenCount = Object.keys(themeTokens).length
+
+// Stronger values for people whose OS asks for more contrast
+// (prefers-contrast: more). Only the tokens that carry supporting text,
+// status, boundaries and focus change; ink and surfaces are already at the
+// extremes. The build verifies these against stricter targets: 7:1 for text
+// and 4.5:1 for control borders and focus rings.
+export const highContrastTokens = {
+  'ink.muted': { light: '#3f3a30', dark: '#d6cfbf' },
+  'ink.placeholder': { light: '#4f4b42', dark: '#bdb8ab' },
+  border: { light: '#7f735b', dark: '#8f866f' },
+  'border.control': { light: '#4f4636', dark: '#b3a88e' },
+  focusRing: { light: '#8a5200', dark: '#ffc15a' },
+  accent: { light: '#245a3d', dark: '#9be0bb' },
+  'accent.strong': { light: '#1a3f2c', dark: '#7fd0a5' },
+  positive: { light: '#145e52', dark: '#7fdccb' },
+  info: { light: '#1f4f7a', dark: '#a9cff2' },
+  warning: { light: '#6e4700', dark: '#ffd57a' },
+  critical: { light: '#922e08', dark: '#ffab85' },
+}
+
+const highContrastVarsFor = (mode) => Object.fromEntries(
+  Object.entries(highContrastTokens).map(([name, value]) => [themeVarName(name), value[mode]])
+)
+
+export const highContrastVars = {
+  light: highContrastVarsFor('light'),
+  dark: highContrastVarsFor('dark'),
+}
+
+export const interfacePaletteOrder = [
+  'accent',
+  'accent.strong',
+  'positive',
+  'info',
+  'warning',
+  'critical',
+  'focusRing',
+  'accent.ink',
+  'ink',
+  'ink.muted',
+  'ink.placeholder',
+  'border',
+  'border.control',
+  'surface.200',
+  'surface.100',
+]
+
+export const illustrationPaletteOrder = [
+  'foliage.bright',
+  'foliage',
+  'foliage.deep',
+  'foliage.mid',
+  'foliage.far',
+  'sunlight',
+]

package/src/tokens.mjs

@@ -0,0 +1,120 @@
+import { themeTokens, interfacePaletteOrder, illustrationPaletteOrder } from './theme.mjs'
+
+export const fontFamilyTokens = {
+  sans: 'system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+  mono: 'ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace',
+}
+
+export const spacingTokens = {
+  1: '4px',
+  2: '8px',
+  3: '12px',
+  4: '16px',
+  6: '24px',
+  8: '32px',
+  12: '48px',
+}
+
+export const radiiTokens = {
+  sm: '4px',
+  md: '8px',
+  lg: '16px',
+  full: '999px',
+}
+
+export const fontSizeTokens = {
+  displayLg: '32px',
+  displayMd: '24px',
+  displaySm: '20px',
+  body: '16px',
+  bodySm: '14px',
+  label: '13px',
+}
+
+export const lineHeightTokens = {
+  displayLg: '40px',
+  displayMd: '32px',
+  displaySm: '28px',
+  body: '24px',
+  bodySm: '20px',
+  label: '16px',
+}
+
+const includeExisting = (keys) => keys.filter((key) => key in themeTokens)
+const orderedInterfaceKeys = includeExisting(interfacePaletteOrder)
+const orderedIllustrationKeys = includeExisting(illustrationPaletteOrder)
+const orderedTokenSet = new Set([...orderedInterfaceKeys, ...orderedIllustrationKeys])
+const interfaceExtras = Object.keys(themeTokens).filter((key) => !orderedTokenSet.has(key))
+
+export const paletteSections = [
+  {
+    title: 'Interface',
+    note: 'Public colors for text, controls, state, and supporting UI tones. Use the verified pairings below rather than assuming every token combination is readable.',
+    keys: [...orderedInterfaceKeys, ...interfaceExtras],
+  },
+  {
+    title: 'Illustration only',
+    note: 'Decorative foliage and sunlight tokens. They are available for art, but not approved as default text, controls, or status meaning.',
+    keys: orderedIllustrationKeys,
+  },
+]
+
+// Every pairing the UI actually uses, checked at build time: scripts/build.mjs
+// fails the build if any drops below its minimum in either theme. `border`
+// itself is a decorative divider (below 3:1 by design); controls use
+// `border.control`.
+const pairingRows = [
+  // [category, title, foreground, background, minimum contrast, note]
+  ['text', 'Body text on site canvas', 'ink', 'surface.100', 4.5, 'Default long-form copy and labels on the page background.'],
+  ['text', 'Body text on raised surface', 'ink', 'surface.200', 4.5, 'Card and field content when a component steps onto the raised surface.'],
+  ['text', 'Supporting text on site canvas', 'ink.muted', 'surface.100', 4.5, 'Secondary copy such as intros, captions and helper text.'],
+  ['text', 'Supporting text on raised surface', 'ink.muted', 'surface.200', 4.5, 'Card bodies, palette tiles, hints and the bands that sit on surface-200.'],
+  ['text', 'Placeholder text in fields', 'ink.placeholder', 'surface.200', 4.5, 'Example values inside inputs, which sit on the raised surface.'],
+  ['text', 'Links and accents on site canvas', 'accent', 'surface.100', 4.5, 'Inline links, eyebrows and stat values on the page background.'],
+  ['text', 'Links and accents on raised surface', 'accent', 'surface.200', 4.5, 'Links and accent text inside cards and bands.'],
+  ['text', 'Primary button label', 'accent.ink', 'accent', 4.5, 'Default primary action styling.'],
+  ['text', 'Primary button label on hover', 'accent.ink', 'accent.strong', 4.5, 'Hover state for the primary action.'],
+  ['text', 'Positive status on raised surface', 'positive', 'surface.200', 4.5, 'Success status inside cards, e.g. the scorecard.'],
+  ['text', 'Info status on raised surface', 'info', 'surface.200', 4.5, 'Neutral guidance or sample-only notes inside cards.'],
+  ['text', 'Warning status on raised surface', 'warning', 'surface.200', 4.5, 'Non-blocking cautions inside cards, e.g. open items on the scorecard.'],
+  ['text', 'Critical status on raised surface', 'critical', 'surface.200', 4.5, 'Errors, failures and destructive actions only.'],
+  ['functional', 'Control border on site canvas', 'border.control', 'surface.100', 3, 'Input, secondary button and switch-track outlines on the page background.'],
+  ['functional', 'Control border on raised surface', 'border.control', 'surface.200', 3, 'Input and secondary button outlines on the raised surface.'],
+  ['functional', 'Focus ring on site canvas', 'focusRing', 'surface.100', 3, 'Visible focus indicator against the main page background.'],
+  ['functional', 'Focus ring on raised surface', 'focusRing', 'surface.200', 3, 'Visible focus indicator inside cards and bands.'],
+]
+
+// Stricter targets for the prefers-contrast: more token set: WCAG AAA for
+// text and 4.5:1 for control borders and focus rings.
+export const highContrastMinimum = { text: 7, functional: 4.5 }
+
+export const verifiedPairings = pairingRows.map(([category, title, foreground, background, minimum, note]) => (
+  { category, title, foreground, background, minimum, note }
+))
+
+export const publicTokenScope = {
+  spacing: Object.entries(spacingTokens).map(([token, value]) => ({ token, value })),
+  radii: Object.entries(radiiTokens).map(([token, value]) => ({ token, value })),
+  typography: {
+    families: Object.entries(fontFamilyTokens).map(([token, value]) => ({ token, value })),
+    sizes: Object.keys(fontSizeTokens).map((token) => ({
+      token,
+      fontSize: fontSizeTokens[token],
+      lineHeight: lineHeightTokens[token],
+    })),
+  },
+  layout: {
+    primitives: [
+      '`container()` — centered, capped at 1080px (override with `maxWidth`), inline padding of spacing `4`, then `6` from `md`.',
+      '`stack()` — a flex column by default with a spacing-`4` gap; takes `direction`, `align`, `justify` and `gap`.',
+      '`grid()` — `columns` (a number or responsive object) makes `minmax(0, 1fr)` tracks; `minChildWidth` (a CSS length) makes auto-fit tracks capped at 100%; default gap is spacing `4`.',
+    ],
+    inherited: [
+      'Responsive rules use Panda defaults (`base`, `sm`, `md`, `lg`) because Verdant does not publish a custom breakpoint token scale.',
+    ],
+    pageSpecific: [
+      'Hero wordmark: 56px at base and 88px from `md` upward; this is page artwork, not a reusable type token.',
+      'Components and 404 page titles: 40px at base and 56px from `md` upward; also page-specific, not public tokens.',
+    ],
+  },
+}