@tfrc/foundation 1.0.0

package/CONTRACT.md

@@ -0,0 +1,58 @@
+# Token contract
+
+Any package that defines a semantic layer (`@tfrc/marketing`, `@tfrc/product`, or any
+future sibling) MUST define every token below in its `tokens.css`.
+Components reference these names only — never a `--ramp-*` value directly,
+and never a raw color literal. See `AGENTS.md` rule 2.
+
+`scripts/check-contract.js` verifies this mechanically for every file it's
+pointed at. Run it before merging any new or edited `tokens.css`.
+
+The other side of the contract — that a *consumer* uses only these names and
+never a raw value — is checked by `tfrc-verify`, which ships as an
+executable in this package and runs inside the consumer's own repo. See
+`CONSUMING.md` and `decisions/0009.md`.
+
+## Surfaces
+- `--color-surface`
+- `--color-surface-raised`
+- `--color-surface-sunken`
+
+## Borders
+- `--color-border-subtle`
+- `--color-border-strong`
+
+## Text
+- `--color-text-primary`
+- `--color-text-secondary`
+- `--color-text-muted`
+
+## Action
+- `--color-accent`
+- `--color-accent-hover`
+- `--color-accent-fg`
+- `--color-accent-bg`
+- `--color-accent-bg-fg`
+
+## System
+- `--color-focus`
+
+## Status
+- `--color-info-bg`, `--color-info-fg`, `--color-info-line`
+- `--color-danger-bg`, `--color-danger-fg`, `--color-danger-line`, `--color-danger-solid`
+- `--color-success-bg`, `--color-success-fg`, `--color-success-line`
+
+## Reserved — `@tfrc/product` only
+These must NOT be defined or referenced in `@tfrc/marketing`. See
+`decisions/0002-reserved-hues-for-financial-semantics.md`.
+
+- `--color-gain`, `--color-gain-tint`
+- `--color-loss`, `--color-loss-tint`
+
+## Contrast floor
+- `--color-text-primary` ≥ 4.5:1 against both `--color-surface` and
+  `--color-surface-raised`.
+- `--color-accent-fg` ≥ 4.5:1 against `--color-accent`.
+
+Check with any WCAG contrast tool before merging. This is not currently
+automated — see `STATE.md`'s known gaps for v1.3.

package/README.md

@@ -0,0 +1,28 @@
+# @tfrc/foundation
+
+Ships no user-facing CSS directly. Consumed by `@tfrc/marketing` and
+`@tfrc/product`, and therefore installed transitively by every consumer —
+which is why the consumer-side checker lives here rather than in a fourth
+package (`decisions/0009.md`).
+
+Contains:
+- `bin/tfrc-verify.js` — the check a *consumer* runs on itself, via
+  `npx tfrc-verify`. Enforces one-dialect-only, pinned versions, no raw
+  color values, and the reserved gain/loss colors, in repositories this one
+  cannot see. Tested by `scripts/test-verify-consumer.js`.
+- `src/palettes/meridian.css` — the active v1 palette (raw ramps only)
+- `src/palettes/{lilac,meadow,daylight}.css` — designed alternates, not
+  wired into any shipped package. See `decisions/0003.md`.
+- `src/base.css` — reset, focus-visible, reduced-motion, the 4px spacing
+  scale, and shared easing curve shapes (not durations — those diverge
+  per package, see `decisions/0004.md`).
+- `src/index.css` — imports the active palette + base, in that order.
+
+Does **not** contain semantic tokens (`--color-accent` and friends) or any
+component. See `CONTRACT.md` for what every consumer must define, and
+`decisions/0004-token-contract-not-shared-values.md` for why the contract
+lives here but the values don't.
+
+To change the active palette, do not edit this package — point
+`@tfrc/marketing`'s and `@tfrc/product`'s `tokens.css` imports at a different
+palette file, and update `STATE.md`.

package/bin/tfrc-verify.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+/**
+ * tfrc-verify — the consumer-side half of this design system's governance.
+ *
+ * Ships with @tfrc/foundation so that a product repo, which this design
+ * system's maintainers cannot see, can check itself:
+ *
+ *   npx tfrc-verify
+ *
+ * Why this exists: once the packages are installed from a registry
+ * (decisions/0007.md), nothing inside the design-system repo can stop a
+ * consumer from mixing the two dialects, using a reserved market-direction
+ * color as decoration, or hard-coding a hex value next to a token. Both of
+ * the first two are forbidden by Articles VI and V of the constitution, and
+ * both were unreachable states while the only consumers lived in-repo.
+ * Article II ("every rule that can be mechanically checked must be")
+ * therefore obliges us to ship a check a consumer can run. See
+ * specs/002-product-consumption-contract/ for the requirements this
+ * implements (FR-002, FR-006, FR-007, FR-008).
+ *
+ * Dependency-free by design: it must run via `npx` in a repo that has
+ * installed nothing but this package.
+ *
+ * Exit codes: 0 = compliant, 1 = violation(s) found, 2 = usage error.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const SCAN_EXTENSIONS = new Set([
+  ".css",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".ts",
+  ".tsx",
+  ".html",
+  ".svelte",
+  ".vue",
+  ".astro",
+]);
+
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  ".hg",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "vendor",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  ".output",
+  ".turbo",
+  ".cache",
+  ".vercel",
+  ".astro",
+]);
+
+const MARKETING_PKG = "@tfrc/marketing";
+const PRODUCT_PKG = "@tfrc/product";
+const RESERVED_TOKENS = ["--color-gain", "--color-loss"];
+
+// oklch hue bands reserved for market direction. Kept in sync with
+// STATE.md's reserved_hue_bands and decisions/0002.md.
+const RESERVED_HUE_BANDS = [
+  { name: "gain", min: 130, max: 170 },
+  { name: "loss", min: 5, max: 40 },
+];
+
+// An escape hatch that is deliberately NOT silent: a raw value preceded by
+// `tfrc-allow-raw: <reason>` is downgraded from a violation to a reported
+// allowance, and the summary always prints how many exist. specs/002's edge
+// cases require that a local override be visible rather than accepted
+// quietly; a hatch that produced no output would fail that.
+const ALLOW_RAW = /tfrc-allow-raw:\s*\S/;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(
+    [
+      "tfrc-verify — verify a consumer repo against The Full Remote Company design system",
+      "",
+      "Usage: npx tfrc-verify [--dir <path>] [--quiet]",
+      "",
+      "  --dir <path>   directory to verify (default: current working directory)",
+      "  --quiet        print only violations and the summary line",
+      "",
+      "Checks:",
+      "  1. exactly one dialect     — @tfrc/marketing and @tfrc/product are never combined",
+      "  2. reserved colors         — gain/loss tokens and hue bands mean market direction only",
+      "  3. no raw values           — every color resolves through a named token",
+      "  4. pinned version          — every @tfrc/* dependency is an exact version",
+      "",
+      "Exit codes: 0 compliant, 1 violations found, 2 usage error.",
+    ].join("\n")
+  );
+  process.exit(0);
+}
+
+const quiet = args.includes("--quiet");
+const dirFlag = args.indexOf("--dir");
+const ROOT = path.resolve(dirFlag === -1 ? process.cwd() : args[dirFlag + 1] || "");
+
+if (!fs.existsSync(ROOT) || !fs.statSync(ROOT).isDirectory()) {
+  console.error(`✗ Not a directory: ${ROOT}`);
+  process.exit(2);
+}
+
+const violations = [];
+const allowances = [];
+
+function violation(code, file, line, message) {
+  violations.push({ code, file, line, message });
+}
+
+function walk(dir, out = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      walk(full, out);
+    } else if (SCAN_EXTENSIONS.has(path.extname(entry.name)) && !/\.min\.(css|js)$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/* Check 4 (first, because it also tells us which dialect we are)      */
+/* FR-002: one explicit, recorded version. FR-003: one dialect only.   */
+/* ------------------------------------------------------------------ */
+
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const pkgPath = path.join(ROOT, "package.json");
+let declaredDeps = {};
+
+if (!fs.existsSync(pkgPath)) {
+  violation("NO_MANIFEST", "package.json", 0, "no package.json found — cannot determine which dialect or version this consumer adopted");
+} else {
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  } catch (err) {
+    console.error(`✗ package.json is not valid JSON: ${err.message}`);
+    process.exit(2);
+  }
+  declaredDeps = Object.assign({}, pkg.dependencies, pkg.devDependencies, pkg.peerDependencies);
+  for (const [name, range] of Object.entries(declaredDeps)) {
+    if (!name.startsWith("@tfrc/")) continue;
+    if (!EXACT_VERSION.test(String(range))) {
+      violation(
+        "VERSION_PIN",
+        "package.json",
+        0,
+        `${name} is declared as "${range}" — must be an exact version (e.g. "1.0.0") so this consumer's appearance cannot change without a deliberate upgrade`
+      );
+    }
+  }
+}
+
+const dependsOnMarketing = Object.prototype.hasOwnProperty.call(declaredDeps, MARKETING_PKG);
+const dependsOnProduct = Object.prototype.hasOwnProperty.call(declaredDeps, PRODUCT_PKG);
+
+const files = walk(ROOT);
+
+// Source-level dialect references, so a dialect reached around package.json
+// (a transitive dep, a vendored copy, a CDN link) is still caught.
+const referencedInSource = { marketing: [], product: [] };
+const RESERVED_TOKEN_USES = [];
+
+const HEX = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{4}|[0-9a-fA-F]{3})(?![0-9a-zA-Z_-])/;
+const FUNCTIONAL_COLOR = /\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\([^)\n]*\)?/;
+const OKLCH_LITERAL = /\boklch\(\s*([0-9.]+%?)\s+([0-9.]+%?)\s+([0-9.]+)/g;
+
+for (const file of files) {
+  const rel = path.relative(ROOT, file) || path.basename(file);
+  let content;
+  try {
+    content = fs.readFileSync(file, "utf8");
+  } catch {
+    continue;
+  }
+  const lines = content.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    const prev = i > 0 ? lines[i - 1] : "";
+    const allowed = ALLOW_RAW.test(line) || ALLOW_RAW.test(prev);
+
+    if (/@tfrc\/marketing/.test(line)) referencedInSource.marketing.push(`${rel}:${lineNo}`);
+    if (/@tfrc\/product/.test(line)) referencedInSource.product.push(`${rel}:${lineNo}`);
+
+    /* --- Check 2: reserved market-direction colors (FR-008) --- */
+    for (const token of RESERVED_TOKENS) {
+      const defines = new RegExp(`${token}\\s*:`).test(line);
+      const uses = new RegExp(`var\\(\\s*${token}\\s*[,)]`).test(line);
+      if (defines) {
+        violation(
+          "RESERVED_REDEFINE",
+          rel,
+          lineNo,
+          `redefines ${token}, which is owned by ${PRODUCT_PKG} — a consumer may use it, never redefine it`
+        );
+      } else if (uses) {
+        RESERVED_TOKEN_USES.push({ rel, lineNo, token });
+      }
+    }
+
+    // Raw oklch inside a reserved hue band: the half of the reserved-hue
+    // rule that a token-name grep cannot see. Only oklch is checked, because
+    // only oklch states its hue directly; a hex in the same band will still
+    // be caught as a raw value below, just with a less specific message.
+    // This is a known, deliberate limit, not an oversight.
+    OKLCH_LITERAL.lastIndex = 0;
+    let m;
+    while ((m = OKLCH_LITERAL.exec(line))) {
+      const hue = parseFloat(m[3]);
+      if (Number.isNaN(hue)) continue;
+      const band = RESERVED_HUE_BANDS.find((b) => hue >= b.min && hue <= b.max);
+      if (band) {
+        violation(
+          "RESERVED_HUE",
+          rel,
+          lineNo,
+          `raw oklch hue ${hue} falls in the reserved "${band.name}" band (${band.min}–${band.max}), which means market direction only — never decoration or brand`
+        );
+      }
+    }
+
+    /* --- Check 3: no raw values (FR-006) --- */
+    const hexMatch = matchHexValue(line);
+    const funcMatch = line.match(FUNCTIONAL_COLOR);
+    const rawFound = hexMatch || (funcMatch ? funcMatch[0] : null);
+    if (rawFound) {
+      if (allowed) {
+        allowances.push({ rel, lineNo, value: rawFound });
+      } else {
+        violation(
+          "RAW_VALUE",
+          rel,
+          lineNo,
+          `raw color value "${rawFound}" — every color must resolve through a named token from the design system's contract`
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Hex colors are only reported in a value position. A bare `#abc {` is an
+ * ID selector, and `href="#abc"` is a fragment link; flagging either would
+ * make the tool cry wolf, and a tool that cries wolf gets switched off.
+ */
+function matchHexValue(line) {
+  if (/\b(?:href|xlink:href|url)\s*[=(]/.test(line)) return null;
+  const m = line.match(HEX);
+  if (!m) return null;
+  const before = line.slice(0, m.index);
+  // A value position: after a CSS `prop:`, a JS assignment, or inside a string.
+  if (!/[:=]|["'`]/.test(before)) return null;
+  return m[0];
+}
+
+/* ------------------------------------------------------------------ */
+/* Check 1: exactly one dialect (FR-003, FR-007)                       */
+/* ------------------------------------------------------------------ */
+
+const usesMarketing = dependsOnMarketing || referencedInSource.marketing.length > 0;
+const usesProduct = dependsOnProduct || referencedInSource.product.length > 0;
+
+if (usesMarketing && usesProduct) {
+  const where = [...referencedInSource.marketing.slice(0, 3), ...referencedInSource.product.slice(0, 3)];
+  violation(
+    "MIXED_DIALECT",
+    where[0] ? where[0].split(":")[0] : "package.json",
+    0,
+    `both ${MARKETING_PKG} and ${PRODUCT_PKG} are present — they are two dialects of one language and must never be combined in one bundle` +
+      (where.length ? ` (seen at ${where.join(", ")})` : "")
+  );
+} else if (!usesMarketing && !usesProduct) {
+  violation(
+    "NO_DIALECT",
+    "package.json",
+    0,
+    `neither ${MARKETING_PKG} nor ${PRODUCT_PKG} is present — nothing to verify. Add exactly one as an exact-version dependency.`
+  );
+}
+
+// A marketing consumer may not touch the reserved tokens at all; a product
+// consumer may use them, for market direction, which is what they're for.
+for (const use of RESERVED_TOKEN_USES) {
+  if (usesMarketing && !usesProduct) {
+    violation(
+      "RESERVED_TOKEN",
+      use.rel,
+      use.lineNo,
+      `uses ${use.token}, which belongs to ${PRODUCT_PKG} only — the marketing dialect must never reference market-direction color`
+    );
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* Report                                                             */
+/* ------------------------------------------------------------------ */
+
+const dialect = usesMarketing && !usesProduct ? "marketing" : usesProduct && !usesMarketing ? "product" : "indeterminate";
+
+if (!quiet) {
+  console.log(`tfrc-verify — ${path.relative(process.cwd(), ROOT) || "."}`);
+  console.log(`  dialect: ${dialect}`);
+  console.log(`  files scanned: ${files.length}`);
+  const pinned = Object.entries(declaredDeps).filter(([n]) => n.startsWith("@tfrc/"));
+  if (pinned.length) {
+    console.log(`  design system: ${pinned.map(([n, v]) => `${n}@${v}`).join(", ")}`);
+  }
+  console.log("");
+}
+
+if (allowances.length) {
+  console.log(`! ${allowances.length} explicitly-allowed raw value${allowances.length === 1 ? "" : "s"} (tfrc-allow-raw):`);
+  for (const a of allowances) console.log(`    ${a.rel}:${a.lineNo}  ${a.value}`);
+  console.log("  Allowed, but counted. Each one is a value the shared language does not cover.");
+  console.log("");
+}
+
+if (violations.length) {
+  console.error(`✗ ${violations.length} violation${violations.length === 1 ? "" : "s"} found:\n`);
+  for (const v of violations) {
+    const loc = v.line ? `${v.file}:${v.line}` : v.file;
+    console.error(`  [${v.code}] ${loc}`);
+    console.error(`      ${v.message}`);
+  }
+  console.error("\nSee https://github.com/the-full-remote-company/design-system — CONSUMING.md");
+  process.exit(1);
+}
+
+console.log("✓ Consumer is compliant: one dialect, pinned version, no raw values, reserved colors respected.");

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@tfrc/foundation",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Color ramps, spacing base, reset, and the token contract. No user-facing components. Consumed by @tfrc/marketing and @tfrc/product — never the other way around.",
+  "keywords": ["design-system", "design-tokens", "css", "tailwind"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/the-full-remote-company/design-system.git",
+    "directory": "packages/foundation"
+  },
+  "homepage": "https://github.com/the-full-remote-company/design-system/tree/main/packages/foundation#readme",
+  "bugs": "https://github.com/the-full-remote-company/design-system/issues",
+  "main": "src/index.css",
+  "exports": {
+    ".": "./src/index.css",
+    "./palettes/*": "./src/palettes/*.css"
+  },
+  "bin": {
+    "tfrc-verify": "bin/tfrc-verify.js"
+  },
+  "files": ["src", "bin", "CONTRACT.md", "README.md"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/base.css

@@ -0,0 +1,47 @@
+/* ==========================================================================
+   @tfrc/foundation — base
+   Reset, accessibility floor, shared spacing scale, shared easing shapes.
+   No semantic color tokens live here — see decisions/0004.md.
+   ========================================================================== */
+
+*, *::before, *::after { box-sizing: border-box; }
+
+html { -webkit-text-size-adjust: 100%; }
+
+body { margin: 0; -webkit-font-smoothing: antialiased; }
+
+/* Both @tfrc/marketing and @tfrc/product must define --color-focus in their own
+   tokens.css for this to resolve — see CONTRACT.md. */
+:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+:root {
+  /* 4px base unit — shared unchanged across web and app.
+     See ARCHITECTURE.md's shared-vs-diverged table. */
+  --space-1:  0.25rem;
+  --space-2:  0.5rem;
+  --space-3:  0.75rem;
+  --space-4:  1rem;
+  --space-5:  1.25rem;
+  --space-6:  1.5rem;
+  --space-8:  2rem;
+  --space-10: 2.5rem;
+  --space-12: 3rem;
+  --space-16: 4rem;
+
+  /* Easing SHAPES are shared. Durations are not — each package sets its
+     own --duration-* scale, since web's motion budget is generous and
+     app's is not. See decisions/0001.md. */
+  --ease-quint: cubic-bezier(0.22, 1, 0.36, 1);
+  --ease-snap:  cubic-bezier(0.34, 1.4, 0.64, 1);
+}

package/src/index.css

@@ -0,0 +1,8 @@
+/* ==========================================================================
+   @tfrc/foundation — entry point
+   Imports the ACTIVE palette (see STATE.md), then the base layer.
+   Consuming packages import this, then define their own tokens.css on top.
+   ========================================================================== */
+
+@import "./palettes/meridian.css";
+@import "./base.css";

package/src/palettes/daylight.css

@@ -0,0 +1,46 @@
+/* ==========================================================================
+   DAYLIGHT — the original amber/ink direction, predating the finance/
+   real-estate scope. Kept as a documented alternate. Not imported by any
+   shipped package.
+   ========================================================================== */
+
+[data-palette="daylight"] {
+  --ramp-neutral-50:  oklch(0.975 0.004 265);
+  --ramp-neutral-100: oklch(0.945 0.006 265);
+  --ramp-neutral-200: oklch(0.885 0.009 265);
+  --ramp-neutral-300: oklch(0.785 0.013 265);
+  --ramp-neutral-400: oklch(0.655 0.018 265);
+  --ramp-neutral-500: oklch(0.545 0.022 265);
+  --ramp-neutral-600: oklch(0.445 0.026 265);
+  --ramp-neutral-700: oklch(0.350 0.028 265);
+  --ramp-neutral-800: oklch(0.272 0.028 265);
+  --ramp-neutral-900: oklch(0.208 0.026 265);
+  --ramp-neutral-950: oklch(0.158 0.024 265);
+
+  --ramp-brand-50:  oklch(0.975 0.022 88);
+  --ramp-brand-100: oklch(0.945 0.048 88);
+  --ramp-brand-200: oklch(0.895 0.090 86);
+  --ramp-brand-300: oklch(0.850 0.125 82);
+  --ramp-brand-400: oklch(0.800 0.148 78);
+  --ramp-brand-500: oklch(0.752 0.158 72);
+  --ramp-brand-600: oklch(0.672 0.150 65);
+  --ramp-brand-700: oklch(0.560 0.128 58);
+  --ramp-brand-800: oklch(0.452 0.100 55);
+  --ramp-brand-900: oklch(0.362 0.078 55);
+
+  --ramp-support-50:  oklch(0.972 0.015 195);
+  --ramp-support-100: oklch(0.930 0.032 195);
+  --ramp-support-200: oklch(0.862 0.056 194);
+  --ramp-support-300: oklch(0.772 0.080 193);
+  --ramp-support-400: oklch(0.665 0.092 192);
+  --ramp-support-500: oklch(0.562 0.092 192);
+  --ramp-support-600: oklch(0.472 0.082 192);
+  --ramp-support-700: oklch(0.392 0.066 193);
+  --ramp-support-800: oklch(0.312 0.050 194);
+  --ramp-support-900: oklch(0.252 0.040 195);
+
+  --color-gain:      oklch(0.510 0.120 150);
+  --color-gain-tint: oklch(0.945 0.045 150);
+  --color-loss:      oklch(0.530 0.190 25);
+  --color-loss-tint: oklch(0.940 0.040 25);
+}

package/src/palettes/lilac.css

@@ -0,0 +1,50 @@
+/* ==========================================================================
+   LILAC — pastel violet alternate. Designed and contract-compliant, but
+   NOT imported by any shipped package. See decisions/0003.md.
+
+   Behind [data-palette="lilac"] so it can be trialed without touching the
+   default. To make this the active palette, point @tfrc/marketing's and
+   @tfrc/product's tokens.css imports here instead of meridian.css, and update
+   STATE.md.
+   ========================================================================== */
+
+[data-palette="lilac"] {
+  --ramp-neutral-50:  oklch(0.980 0.006 300);
+  --ramp-neutral-100: oklch(0.952 0.011 300);
+  --ramp-neutral-200: oklch(0.898 0.018 300);
+  --ramp-neutral-300: oklch(0.802 0.026 300);
+  --ramp-neutral-400: oklch(0.675 0.034 300);
+  --ramp-neutral-500: oklch(0.565 0.040 300);
+  --ramp-neutral-600: oklch(0.465 0.046 300);
+  --ramp-neutral-700: oklch(0.370 0.048 300);
+  --ramp-neutral-800: oklch(0.290 0.046 300);
+  --ramp-neutral-900: oklch(0.228 0.042 300);
+  --ramp-neutral-950: oklch(0.174 0.038 300);
+
+  --ramp-brand-50:  oklch(0.978 0.016 300);
+  --ramp-brand-100: oklch(0.948 0.038 300);
+  --ramp-brand-200: oklch(0.900 0.072 300);
+  --ramp-brand-300: oklch(0.832 0.112 300);
+  --ramp-brand-400: oklch(0.738 0.158 300);
+  --ramp-brand-500: oklch(0.638 0.198 300);
+  --ramp-brand-600: oklch(0.552 0.214 300);
+  --ramp-brand-700: oklch(0.468 0.192 300);
+  --ramp-brand-800: oklch(0.385 0.152 300);
+  --ramp-brand-900: oklch(0.308 0.112 300);
+
+  --ramp-support-50:  oklch(0.976 0.012 232);
+  --ramp-support-100: oklch(0.942 0.028 232);
+  --ramp-support-200: oklch(0.882 0.050 232);
+  --ramp-support-300: oklch(0.802 0.072 232);
+  --ramp-support-400: oklch(0.708 0.090 232);
+  --ramp-support-500: oklch(0.608 0.105 232);
+  --ramp-support-600: oklch(0.512 0.100 232);
+  --ramp-support-700: oklch(0.422 0.085 234);
+  --ramp-support-800: oklch(0.338 0.066 236);
+  --ramp-support-900: oklch(0.270 0.050 238);
+
+  --color-gain:      oklch(0.510 0.120 150);
+  --color-gain-tint: oklch(0.945 0.045 150);
+  --color-loss:      oklch(0.530 0.190 25);
+  --color-loss-tint: oklch(0.940 0.040 25);
+}

package/src/palettes/meadow.css

@@ -0,0 +1,51 @@
+/* ==========================================================================
+   MEADOW — Spotify-adjacent green alternate. Designed and contract-
+   compliant, but NOT imported by any shipped package, and should not
+   become the brand accent while any product does gain/loss display —
+   see decisions/0002.md and decisions/0003.md.
+   ========================================================================== */
+
+[data-palette="meadow"] {
+  --ramp-neutral-50:  oklch(0.980 0.005 165);
+  --ramp-neutral-100: oklch(0.950 0.009 165);
+  --ramp-neutral-200: oklch(0.896 0.014 165);
+  --ramp-neutral-300: oklch(0.798 0.020 165);
+  --ramp-neutral-400: oklch(0.670 0.026 165);
+  --ramp-neutral-500: oklch(0.560 0.030 165);
+  --ramp-neutral-600: oklch(0.460 0.034 165);
+  --ramp-neutral-700: oklch(0.364 0.036 165);
+  --ramp-neutral-800: oklch(0.284 0.036 165);
+  --ramp-neutral-900: oklch(0.222 0.032 165);
+  --ramp-neutral-950: oklch(0.170 0.028 165);
+
+  /* NOTE: this brand ramp's mid-to-high steps sit inside the reserved
+     gain hue band (130-170) per decisions/0002.md. That collision is
+     exactly why this palette is not shipped while the finance product
+     is in scope — kept here as a documented alternate only. */
+  --ramp-brand-50:  oklch(0.978 0.018 150);
+  --ramp-brand-100: oklch(0.948 0.044 150);
+  --ramp-brand-200: oklch(0.902 0.084 150);
+  --ramp-brand-300: oklch(0.844 0.124 149);
+  --ramp-brand-400: oklch(0.774 0.158 148);
+  --ramp-brand-500: oklch(0.702 0.180 148);
+  --ramp-brand-600: oklch(0.622 0.166 148);
+  --ramp-brand-700: oklch(0.522 0.140 148);
+  --ramp-brand-800: oklch(0.422 0.110 149);
+  --ramp-brand-900: oklch(0.336 0.086 150);
+
+  --ramp-support-50:  oklch(0.974 0.014 235);
+  --ramp-support-100: oklch(0.940 0.030 235);
+  --ramp-support-200: oklch(0.880 0.052 235);
+  --ramp-support-300: oklch(0.800 0.074 235);
+  --ramp-support-400: oklch(0.702 0.092 235);
+  --ramp-support-500: oklch(0.600 0.105 235);
+  --ramp-support-600: oklch(0.507 0.098 235);
+  --ramp-support-700: oklch(0.417 0.082 237);
+  --ramp-support-800: oklch(0.332 0.064 239);
+  --ramp-support-900: oklch(0.265 0.048 240);
+
+  --color-gain:      oklch(0.510 0.120 150);
+  --color-gain-tint: oklch(0.945 0.045 150);
+  --color-loss:      oklch(0.530 0.190 25);
+  --color-loss-tint: oklch(0.940 0.040 25);
+}

package/src/palettes/meridian.css

@@ -0,0 +1,69 @@
+/* ==========================================================================
+   MERIDIAN — the v1 shipped palette. See decisions/0003.md for why.
+
+   Three ramps. Components in @tfrc/marketing and @tfrc/product never reference these
+   variables directly — only through each package's own semantic tokens/
+   tokens.css, per decisions/0004.md. This file's only job is to define the
+   raw color material.
+   ========================================================================== */
+
+:root {
+  /* neutral — cool slate, tuned for dense financial tables */
+  --ramp-neutral-50:  oklch(0.980 0.004 270);
+  --ramp-neutral-100: oklch(0.950 0.007 270);
+  --ramp-neutral-200: oklch(0.896 0.012 270);
+  --ramp-neutral-300: oklch(0.798 0.018 270);
+  --ramp-neutral-400: oklch(0.668 0.024 270);
+  --ramp-neutral-500: oklch(0.558 0.028 270);
+  --ramp-neutral-600: oklch(0.458 0.032 270);
+  --ramp-neutral-700: oklch(0.362 0.034 270);
+  --ramp-neutral-800: oklch(0.282 0.032 270);
+  --ramp-neutral-900: oklch(0.220 0.028 270);
+  --ramp-neutral-950: oklch(0.166 0.024 270);
+
+  /* brand — indigo. The parent brand accent. See decisions/0002.md for
+     why hue 275 (clear of both reserved gain/loss bands). */
+  --ramp-brand-50:  oklch(0.978 0.014 275);
+  --ramp-brand-100: oklch(0.946 0.034 275);
+  --ramp-brand-200: oklch(0.896 0.062 275);
+  --ramp-brand-300: oklch(0.820 0.100 275);
+  --ramp-brand-400: oklch(0.700 0.150 275);
+  --ramp-brand-500: oklch(0.600 0.180 275);
+  --ramp-brand-600: oklch(0.520 0.190 275);
+  --ramp-brand-700: oklch(0.440 0.168 275);
+  --ramp-brand-800: oklch(0.360 0.132 275);
+  --ramp-brand-900: oklch(0.290 0.098 275);
+
+  /* support — gold. The property/real-estate association. */
+  --ramp-support-50:  oklch(0.978 0.018 68);
+  --ramp-support-100: oklch(0.950 0.042 68);
+  --ramp-support-200: oklch(0.902 0.078 67);
+  --ramp-support-300: oklch(0.848 0.108 66);
+  --ramp-support-400: oklch(0.762 0.130 65);
+  --ramp-support-500: oklch(0.680 0.140 65);
+  --ramp-support-600: oklch(0.590 0.130 64);
+  --ramp-support-700: oklch(0.490 0.108 62);
+  --ramp-support-800: oklch(0.398 0.086 60);
+  --ramp-support-900: oklch(0.320 0.068 58);
+
+  /* Reserved market-direction colors. @tfrc/product only — never @tfrc/marketing.
+     See decisions/0002-reserved-hues-for-financial-semantics.md. */
+  --color-gain:      oklch(0.510 0.120 150);
+  --color-gain-tint: oklch(0.945 0.045 150);
+  --color-loss:      oklch(0.530 0.190 25);
+  --color-loss-tint: oklch(0.940 0.040 25);
+
+  /* Product spectrum — @tfrc/product only. Constant L/C, hue varies.
+     See decisions/0005-product-spectrum-hue-ceiling.md before adding one. */
+  --product-capital: oklch(0.545 0.185 275);
+  --product-estate:  oklch(0.590 0.130 65);
+  --product-lending: oklch(0.545 0.100 195);
+  --product-insight: oklch(0.560 0.150 235);
+  --product-legal:   oklch(0.545 0.200 305);
+  --product-market:  oklch(0.560 0.185 340);
+}
+
+.dark {
+  /* Ramps don't change in dark mode — only the semantic layer in each
+     consuming package's tokens.css does. Nothing to override here. */
+}