diff --git a/Cargo.lock b/Cargo.lock
index bb53c1d..27fac81 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1363,6 +1363,7 @@ dependencies = [
 name = "plumb-config"
 version = "0.0.1"
 dependencies = [
+ "dunce",
  "figment",
  "indexmap",
  "miette",
@@ -1371,9 +1372,12 @@ dependencies = [
  "serde",
  "serde_json",
  "serde_yaml",
+ "sha2",
  "tempfile",
  "thiserror 2.0.18",
  "toml 1.1.2+spec-1.1.0",
+ "tracing",
+ "which",
 ]
 
 [[package]]
@@ -1902,6 +1906,17 @@ dependencies = [
  "digest",
 ]
 
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
 [[package]]
 name = "sharded-slab"
 version = "0.1.7"
diff --git a/Cargo.toml b/Cargo.toml
index c4fe180..855f7df 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -77,6 +77,16 @@ tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
 indexmap = { version = "2", features = ["serde"] }
 ahash = "0.8"
 
+# Subprocess discovery (Tailwind adapter).
+which = "8"
+
+# Content hashing (Tailwind cache key).
+sha2 = "0.10"
+
+# Path canonicalization that strips `\\?\` UNC prefix on Windows
+# (Tailwind adapter — node's `require()` doesn't handle the prefix).
+dunce = "1"
+
 # Color distance (CIEDE2000, D65).
 palette = { version = "0.7", default-features = false, features = ["std"] }
 
diff --git a/crates/plumb-config/Cargo.toml b/crates/plumb-config/Cargo.toml
index ab442cb..c2d10b2 100644
--- a/crates/plumb-config/Cargo.toml
+++ b/crates/plumb-config/Cargo.toml
@@ -24,6 +24,10 @@ serde_yaml = { workspace = true }
 miette = { workspace = true }
 thiserror = { workspace = true }
 schemars = { workspace = true }
+tracing = { workspace = true }
+which = { workspace = true }
+sha2 = { workspace = true }
+dunce = { workspace = true }
 
 [dev-dependencies]
 tempfile = { workspace = true }
diff --git a/crates/plumb-config/src/lib.rs b/crates/plumb-config/src/lib.rs
index fe90258..7641ca3 100644
--- a/crates/plumb-config/src/lib.rs
+++ b/crates/plumb-config/src/lib.rs
@@ -22,12 +22,14 @@ use thiserror::Error;
 mod css_props;
 mod dtcg;
 mod span;
+pub mod tailwind;
 mod validate;
 
 pub use css_props::{CssPropertyScrape, ScrapedValue, scrape_css_properties};
 pub use dtcg::{DtcgImport, DtcgSource, DtcgWarning, DtcgWarningKind, MAX_NESTING, merge_dtcg};
 
 use span::{SourceFormat, locate_path};
+pub use tailwind::{TailwindOptions, merge_tailwind};
 use validate::ValidationIssue;
 
 /// Underlying config parse errors.
@@ -145,6 +147,39 @@ pub enum ConfigError {
         /// Human-readable explanation.
         reason: String,
     },
+    /// The Tailwind adapter could not run because Node is missing
+    /// or otherwise unavailable.
+    #[error("tailwind adapter unavailable: {reason}")]
+    #[diagnostic(
+        code(plumb::config::tailwind_unavailable),
+        help("install Node.js (https://nodejs.org) or pass --tailwind-node <path>")
+    )]
+    TailwindUnavailable {
+        /// Why the adapter couldn't run (missing Node, missing override, …).
+        reason: String,
+    },
+    /// The Tailwind config path is malformed or escapes the project tree.
+    #[error("invalid tailwind config path `{path}`: {reason}")]
+    #[diagnostic(code(plumb::config::tailwind_bad_path))]
+    TailwindBadPath {
+        /// User-supplied tailwind config path.
+        path: String,
+        /// Why we rejected it.
+        reason: String,
+    },
+    /// Node ran but the Tailwind config evaluation failed.
+    #[error("failed to evaluate tailwind config `{path}`: {reason}")]
+    #[diagnostic(code(plumb::config::tailwind_eval))]
+    TailwindEval {
+        /// User-supplied tailwind config path.
+        path: String,
+        /// Reason text — either the loader's structured error or the
+        /// shape of the subprocess failure.
+        reason: String,
+        /// Captured stderr from the Node subprocess. Empty when the
+        /// child closed without writing diagnostics.
+        stderr: String,
+    },
 }
 
 /// Load a `Config` from disk. The file extension decides the parser.
diff --git a/crates/plumb-config/src/tailwind/cache.rs b/crates/plumb-config/src/tailwind/cache.rs
new file mode 100644
index 0000000..1e108c8
--- /dev/null
+++ b/crates/plumb-config/src/tailwind/cache.rs
@@ -0,0 +1,207 @@
+//! mtime-based cache for resolved Tailwind themes.
+//!
+//! ## Determinism
+//!
+//! The cache is a performance optimization, not a correctness contract.
+//! Reads return the cached `theme` value byte-for-byte. Writes happen
+//! only after a successful Node spawn produced a valid theme. The
+//! decision tree is:
+//!
+//! 1. Stat the user's Tailwind config file → `mtime_unix_ms`.
+//! 2. Hash the absolute config path with SHA-256 → cache filename.
+//! 3. If `<cache_dir>/<hash>.json` exists and its `mtime_unix_ms`
+//!    matches, deserialize and return. Otherwise the caller spawns Node.
+//!
+//! Mismatched or unreadable cache entries are treated as a miss; we
+//! never error out of a corrupted cache.
+//!
+//! ## No env access
+//!
+//! This module never reads `TMPDIR` / `TEMP` / `TMP` or any other
+//! process-global state. The caller passes the cache directory in
+//! explicitly. When no directory is supplied, the caller treats it as
+//! "cache disabled" and the functions in this module are not invoked.
+
+use std::fs;
+use std::io;
+use std::path::{Path, PathBuf};
+use std::time::SystemTimeError;
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+/// Wire format for the cache file.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub(super) struct CacheEntry {
+    /// Modification time of the source config file in milliseconds since
+    /// the Unix epoch. This is the cache key beyond the filename hash.
+    pub(super) mtime_unix_ms: u128,
+    /// The resolved theme JSON object. Stored as `serde_json::Value`
+    /// so the cache file is self-describing — no schema migrations
+    /// required when Plumb adds new theme keys.
+    pub(super) theme: serde_json::Value,
+}
+
+/// SHA-256 hex digest of the absolute config path. Stable across runs.
+pub(super) fn config_path_hash(path: &Path) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(path.as_os_str().as_encoded_bytes());
+    let digest = hasher.finalize();
+    let mut hex = String::with_capacity(digest.len() * 2);
+    for byte in digest {
+        // hex-encode without an extra dependency.
+        const TABLE: &[u8; 16] = b"0123456789abcdef";
+        let upper = TABLE[(byte >> 4) as usize];
+        let lower = TABLE[(byte & 0x0f) as usize];
+        hex.push(char::from(upper));
+        hex.push(char::from(lower));
+    }
+    hex
+}
+
+/// Compute the absolute path of the cache entry for a given config.
+pub(super) fn cache_path_for(config_path: &Path, dir: &Path) -> PathBuf {
+    let hash = config_path_hash(config_path);
+    dir.join(format!("{hash}.json"))
+}
+
+/// Read the file's mtime as milliseconds since the Unix epoch.
+pub(super) fn mtime_unix_ms(path: &Path) -> Result<u128, MtimeError> {
+    let meta = fs::metadata(path).map_err(MtimeError::Io)?;
+    let modified = meta.modified().map_err(MtimeError::Io)?;
+    let dur = modified
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_err(MtimeError::SystemTime)?;
+    Ok(dur.as_millis())
+}
+
+/// Failure modes when reading a file's mtime.
+#[derive(Debug)]
+pub(super) enum MtimeError {
+    /// Underlying I/O error (file missing, permission denied, etc.).
+    Io(io::Error),
+    /// File mtime predates the Unix epoch — shouldn't happen on any
+    /// modern filesystem but we surface it instead of panicking.
+    SystemTime(SystemTimeError),
+}
+
+impl std::fmt::Display for MtimeError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Io(err) => write!(f, "{err}"),
+            Self::SystemTime(err) => write!(f, "{err}"),
+        }
+    }
+}
+
+/// Look up a cached theme for `config_path`. Returns `None` on any cache
+/// miss (file missing, JSON malformed, mtime mismatch). Never errors;
+/// cache problems are silent.
+pub(super) fn read(config_path: &Path, dir: &Path) -> Option<CacheEntry> {
+    let mtime = mtime_unix_ms(config_path).ok()?;
+    let cache_path = cache_path_for(config_path, dir);
+    let bytes = fs::read(&cache_path).ok()?;
+    let entry: CacheEntry = serde_json::from_slice(&bytes).ok()?;
+    if entry.mtime_unix_ms == mtime {
+        Some(entry)
+    } else {
+        None
+    }
+}
+
+/// Persist a resolved theme to the cache. Best-effort — failures are
+/// logged at `debug` level and otherwise swallowed; the caller already
+/// has a valid theme, so a missing cache entry just costs a re-spawn
+/// next time.
+pub(super) fn write(
+    config_path: &Path,
+    theme: &serde_json::Value,
+    dir: &Path,
+) -> Result<(), io::Error> {
+    let mtime = mtime_unix_ms(config_path).map_err(|err| match err {
+        MtimeError::Io(io) => io,
+        MtimeError::SystemTime(_) => io::Error::other("config mtime predates the Unix epoch"),
+    })?;
+    let entry = CacheEntry {
+        mtime_unix_ms: mtime,
+        theme: theme.clone(),
+    };
+    let cache_path = cache_path_for(config_path, dir);
+    if let Some(parent) = cache_path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    let serialized = serde_json::to_vec(&entry).map_err(io::Error::other)?;
+    // Write to a sibling temp file then rename, so a partial write is
+    // never observable. The OS rename is atomic on POSIX and Windows
+    // (`MoveFileEx` with `MOVEFILE_REPLACE_EXISTING` semantics under
+    // `fs::rename` on stable Rust).
+    let tmp_path = cache_path.with_extension("json.tmp");
+    fs::write(&tmp_path, &serialized)?;
+    fs::rename(&tmp_path, &cache_path)?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn config_path_hash_is_stable_and_64_chars() {
+        let path = Path::new("/tmp/example/tailwind.config.js");
+        let h1 = config_path_hash(path);
+        let h2 = config_path_hash(path);
+        assert_eq!(h1, h2);
+        assert_eq!(h1.len(), 64);
+        assert!(
+            h1.chars()
+                .all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase())
+        );
+    }
+
+    #[test]
+    fn config_path_hash_distinguishes_paths() {
+        let a = config_path_hash(Path::new("/a/tailwind.config.js"));
+        let b = config_path_hash(Path::new("/b/tailwind.config.js"));
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn cache_round_trip_through_temp_dir() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let cfg_path = dir.path().join("tailwind.config.js");
+        std::fs::write(&cfg_path, "module.exports = {};").expect("write config");
+
+        let theme = serde_json::json!({"colors": {"red": "#ff0000"}});
+        write(&cfg_path, &theme, dir.path()).expect("write cache");
+
+        let entry = read(&cfg_path, dir.path()).expect("hit cache");
+        assert_eq!(entry.theme, theme);
+    }
+
+    #[test]
+    fn cache_miss_when_mtime_changes() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let cfg_path = dir.path().join("tailwind.config.js");
+        std::fs::write(&cfg_path, "module.exports = {};").expect("write config");
+        let theme = serde_json::json!({"colors": {"red": "#ff0000"}});
+        write(&cfg_path, &theme, dir.path()).expect("write cache");
+
+        // Bump mtime by rewriting the config file with later content.
+        // sleep-free: set mtime explicitly via filetime if available;
+        // the simpler path is to rewrite and accept that filesystem
+        // resolution is millisecond-or-coarser — write a guaranteed
+        // distinct mtime by using `set_modified` from std.
+        let later = std::time::UNIX_EPOCH + std::time::Duration::from_secs(2_000_000_000);
+        let file = std::fs::OpenOptions::new()
+            .write(true)
+            .open(&cfg_path)
+            .expect("open");
+        file.set_modified(later).expect("set mtime");
+        drop(file);
+
+        assert!(
+            read(&cfg_path, dir.path()).is_none(),
+            "mtime change should invalidate cache"
+        );
+    }
+}
diff --git a/crates/plumb-config/src/tailwind/loader.js b/crates/plumb-config/src/tailwind/loader.js
new file mode 100644
index 0000000..37d6b50
--- /dev/null
+++ b/crates/plumb-config/src/tailwind/loader.js
@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// plumb-tailwind loader.
+//
+// Reads a Tailwind config file path from argv and writes the
+// resolved `theme` object as JSON to stdout. Diagnostic messages go to
+// stderr — never stdout, since stdout is parsed as JSON by the caller.
+//
+// Behaviour:
+//   1. If the config path ends in `.ts` or `.mts` / `.cts`, attempt to
+//      register a TypeScript loader (`tsx/cjs`, then `ts-node/register`,
+//      then `esbuild-register`). If none are available, exit with
+//      structured error code "TS_LOADER_MISSING".
+//   2. Try to `require` `tailwindcss/resolveConfig` from the config
+//      file's directory (so the user project's installed version wins).
+//      If it succeeds, run it on the loaded user config and emit
+//      `result.theme`.
+//   3. Fall back to a small in-process resolver that merges
+//      `theme.extend` into `theme` for the keys we care about. This
+//      preserves the contract for projects that haven't `npm install`ed
+//      Tailwind, and is the path exercised by Plumb's own tests.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KEYS = [
+  'colors',
+  'spacing',
+  'fontSize',
+  'fontWeight',
+  'fontFamily',
+  'borderRadius',
+];
+
+function emitError(code, message) {
+  // Write a single-line JSON object so the Rust side can pattern-match
+  // on `code` without parsing free-form text.
+  const payload = JSON.stringify({ plumbTailwindError: { code, message } });
+  process.stdout.write(payload + '\n');
+  process.exit(2);
+}
+
+function tryRegisterTsLoader(configDir) {
+  const candidates = ['tsx/cjs', 'ts-node/register/transpile-only', 'esbuild-register'];
+  for (const candidate of candidates) {
+    try {
+      // Resolve from the user project so we pick up its own dev deps.
+      const resolved = require.resolve(candidate, { paths: [configDir] });
+      // eslint-disable-next-line import/no-dynamic-require, global-require
+      require(resolved);
+      return candidate;
+    } catch (_err) {
+      // try the next candidate
+    }
+  }
+  return null;
+}
+
+function loadUserConfig(configPath) {
+  const ext = path.extname(configPath).toLowerCase();
+  const isTs = ext === '.ts' || ext === '.mts' || ext === '.cts';
+  if (isTs) {
+    const loader = tryRegisterTsLoader(path.dirname(configPath));
+    if (!loader) {
+      emitError(
+        'TS_LOADER_MISSING',
+        'No TypeScript loader found. Install one of `tsx`, `ts-node`, or `esbuild-register` in your project, or convert the config to .js/.mjs/.cjs.',
+      );
+    }
+  }
+  let mod;
+  try {
+    // eslint-disable-next-line import/no-dynamic-require, global-require
+    mod = require(configPath);
+  } catch (err) {
+    emitError('CONFIG_REQUIRE_FAILED', `Failed to load Tailwind config: ${err && err.message ? err.message : String(err)}`);
+  }
+  // ESM default-export interop.
+  if (mod && typeof mod === 'object' && 'default' in mod && Object.keys(mod).length === 1) {
+    return mod.default;
+  }
+  return mod;
+}
+
+function tryResolveWithTailwind(userConfig, configDir) {
+  try {
+    const resolved = require.resolve('tailwindcss/resolveConfig', {
+      paths: [configDir],
+    });
+    // eslint-disable-next-line import/no-dynamic-require, global-require
+    const resolveConfig = require(resolved);
+    const result = resolveConfig(userConfig);
+    return result && result.theme ? result.theme : null;
+  } catch (_err) {
+    return null;
+  }
+}
+
+function fallbackResolveTheme(userConfig) {
+  // Minimal Tailwind-shaped resolver. Sufficient for tests and for
+  // projects that author tokens directly in their config without
+  // depending on Tailwind's own preset machinery.
+  const theme = (userConfig && userConfig.theme) || {};
+  const extend = theme.extend || {};
+  const out = {};
+  for (const key of KEYS) {
+    const base = theme[key];
+    const ext = extend[key];
+    if (base === undefined && ext === undefined) continue;
+    if (typeof base !== 'object' || base === null) {
+      out[key] = ext === undefined ? base : ext;
+      continue;
+    }
+    out[key] = Object.assign({}, base, ext || {});
+  }
+  return out;
+}
+
+function pickTheme(theme) {
+  // Restrict the emitted JSON to the keys Plumb merges. This keeps the
+  // payload small (matters for cache files) and avoids leaking arbitrary
+  // user-defined theme keys.
+  const out = {};
+  for (const key of KEYS) {
+    if (theme && Object.prototype.hasOwnProperty.call(theme, key)) {
+      out[key] = theme[key];
+    }
+  }
+  return out;
+}
+
+function main() {
+  // When invoked as `node -e <script> -- <path>`, Node strips both `-e`
+  // and the `--` separator, so the first script argument is `argv[1]`.
+  // When invoked as `node script.js <path>`, the path also lands in
+  // `argv[1]`. Skip the `--` separator if a caller forwarded it.
+  let configPath = process.argv[1];
+  if (configPath === '--') {
+    configPath = process.argv[2];
+  }
+  if (!configPath) {
+    emitError('USAGE', 'Usage: loader.js <tailwind-config-path>');
+  }
+  if (!fs.existsSync(configPath)) {
+    emitError('CONFIG_NOT_FOUND', `Tailwind config not found: ${configPath}`);
+  }
+  const absolute = path.resolve(configPath);
+  const configDir = path.dirname(absolute);
+  const userConfig = loadUserConfig(absolute);
+  if (!userConfig || typeof userConfig !== 'object') {
+    emitError('CONFIG_NOT_OBJECT', 'Tailwind config did not export an object.');
+  }
+  const resolved = tryResolveWithTailwind(userConfig, configDir);
+  const theme = resolved !== null ? resolved : fallbackResolveTheme(userConfig);
+  const picked = pickTheme(theme);
+  process.stdout.write(JSON.stringify(picked));
+  process.stdout.write('\n');
+}
+
+main();
diff --git a/crates/plumb-config/src/tailwind/mod.rs b/crates/plumb-config/src/tailwind/mod.rs
new file mode 100644
index 0000000..71859e9
--- /dev/null
+++ b/crates/plumb-config/src/tailwind/mod.rs
@@ -0,0 +1,942 @@
+//! Tailwind config adapter.
+//!
+//! Reads a user's `tailwind.config.{js,ts,mjs,cjs}` and merges the
+//! resolved `theme` into a Plumb [`Config`]. JavaScript / TypeScript
+//! evaluation happens in a Node subprocess; Plumb itself ships zero
+//! JS-runtime code at runtime.
+//!
+//! The pipeline is:
+//!
+//! 1. Validate the user-supplied path: must be a regular file with one
+//!    of the supported extensions, and (when [`TailwindOptions::cwd_root`]
+//!    is `Some`) live under that root or one of its ancestors.
+//! 2. Look up `node` on `PATH` (or honour an explicit override) — if
+//!    missing, surface [`ConfigError::TailwindUnavailable`].
+//! 3. Consult the mtime cache. On hit, skip the spawn entirely.
+//! 4. Spawn `node <embedded-loader.js> <config-path>` with stdin closed,
+//!    stdout/stderr captured, and a configurable timeout (default 30 s).
+//! 5. Parse stdout as JSON. The loader emits a small object whose top-
+//!    level keys are a strict subset of the Tailwind theme keys Plumb
+//!    cares about.
+//! 6. Merge the parsed theme into the supplied [`Config`].
+//!
+//! ## Determinism
+//!
+//! - Cache reads return byte-identical themes to a fresh spawn.
+//! - Cache writes happen only after a fresh spawn produced a parseable
+//!   theme. A cache file is never the *first* witness of a theme.
+//! - Merging is deterministic: tokens are inserted into [`IndexMap`]s in
+//!   the order Tailwind emitted them, and scales are sorted ascending
+//!   with duplicates removed.
+//!
+//! ## Hard rules upheld here
+//!
+//! - `#![forbid(unsafe_code)]` on the parent crate covers this module.
+//! - No `unwrap`/`expect`/`panic!`. Errors surface as
+//!   [`ConfigError::TailwindUnavailable`] or
+//!   [`ConfigError::TailwindEval`].
+//! - No `println!`/`eprintln!`. Diagnostic noise routes through `tracing`.
+//! - Subprocess hygiene: arguments pass through `Command::arg`, no
+//!   shell concatenation; stderr stays separate from stdout; the spawn
+//!   is bounded by a `try_wait` polling loop that counts ticks instead
+//!   of measuring wall-clock time (`std::time::Instant::now` is on the
+//!   workspace's `clippy::disallowed_methods` list).
+
+use std::ffi::OsStr;
+use std::io::Read;
+use std::path::{Path, PathBuf};
+use std::process::{Command, ExitStatus, Stdio};
+use std::thread;
+use std::time::Duration;
+
+use indexmap::IndexMap;
+use plumb_core::Config;
+use plumb_core::config::{ColorSpec, RadiusSpec, SpacingSpec, TypeScaleSpec};
+use serde::Deserialize;
+use serde_json::Value;
+
+use crate::ConfigError;
+
+mod cache;
+
+/// Embedded Node loader script. Read at compile time so Plumb has no
+/// runtime dependency on the script's location on disk.
+const LOADER_JS: &str = include_str!("loader.js");
+
+/// Default subprocess timeout. Tailwind themes resolve in well under a
+/// second; 60 s is loud-failure territory.
+const DEFAULT_TIMEOUT_SECS: u64 = 60;
+
+/// Polling cadence for the `try_wait` loop. We can't use
+/// `std::time::Instant::now` (banned by `clippy::disallowed_methods`) so
+/// the timeout budget is expressed as a tick count rather than a wall-
+/// clock deadline. 50 ms balances responsiveness against the cost of
+/// repeatedly polling the OS.
+const POLL_INTERVAL: Duration = Duration::from_millis(50);
+
+/// Supported config file extensions. Anything else is rejected before
+/// we spawn Node — keeps the failure mode predictable.
+const SUPPORTED_EXTENSIONS: &[&str] = &["js", "mjs", "cjs", "ts", "mts", "cts"];
+
+/// Options for [`merge_tailwind`]. All fields are optional; defaults
+/// match the issue contract.
+#[derive(Debug, Clone, Default)]
+pub struct TailwindOptions {
+    /// Override the discovered `node` executable. Useful in tests and
+    /// in Nix-style build environments where `which` would fail.
+    pub node_path: Option<PathBuf>,
+    /// Cache directory for resolved themes.
+    ///
+    /// When `None`, the cache is disabled — every call spawns Node
+    /// fresh. The library never reads `TMPDIR` / `TEMP` / `TMP`; the
+    /// caller (typically `plumb-cli`) decides where to cache.
+    pub cache_dir: Option<PathBuf>,
+    /// Skip the cache entirely. Defaults to `false`. When `cache_dir`
+    /// is `None` the cache is already disabled, so this flag is only
+    /// meaningful alongside an explicit `cache_dir`.
+    pub no_cache: bool,
+    /// Subprocess timeout. Defaults to 60 seconds.
+    pub timeout: Option<Duration>,
+    /// CWD root used for the path-traversal guard.
+    ///
+    /// When `Some(root)`, the validated config path must be `root`
+    /// itself, a descendant of `root`, or a sibling under any
+    /// ancestor of `root` (so `--config /repo/tailwind.config.js`
+    /// works from `/repo/sub/`).
+    ///
+    /// When `None`, the path-traversal guard is skipped entirely.
+    /// Callers that need the guard MUST populate this with a canonical
+    /// project root; `plumb-cli` reads `current_dir()` itself before
+    /// invoking the adapter. The library never reads
+    /// [`std::env::current_dir`].
+    pub cwd_root: Option<PathBuf>,
+}
+
+/// Merge the resolved Tailwind theme at `tailwind_config_path` into
+/// `config` and return the merged config.
+///
+/// # Errors
+///
+/// - [`ConfigError::TailwindUnavailable`] when `node` cannot be found
+///   on PATH and no override is supplied.
+/// - [`ConfigError::TailwindEval`] when the subprocess exits non-zero,
+///   times out, or emits unparseable JSON.
+/// - [`ConfigError::TailwindBadPath`] when the config path doesn't
+///   exist, has the wrong extension, or escapes the CWD ancestor tree.
+pub fn merge_tailwind(
+    config: Config,
+    tailwind_config_path: &Path,
+    options: &TailwindOptions,
+) -> Result<Config, ConfigError> {
+    let theme = resolve_theme(tailwind_config_path, options)?;
+    Ok(merge_theme_into_config(config, &theme))
+}
+
+/// Resolve the Tailwind theme for the given config file. Wraps the
+/// cache lookup → Node spawn → cache write pipeline.
+///
+/// The cache is consulted only when [`TailwindOptions::cache_dir`] is
+/// `Some(_)` and [`TailwindOptions::no_cache`] is `false`. When
+/// `cache_dir` is `None` the library never reads or writes a cache
+/// file; the caller is responsible for choosing a directory.
+fn resolve_theme(config_path: &Path, options: &TailwindOptions) -> Result<Value, ConfigError> {
+    let validated = validate_config_path(config_path, options.cwd_root.as_deref())?;
+    let cache_dir = options.cache_dir.as_deref().filter(|_| !options.no_cache);
+
+    if let Some(dir) = cache_dir
+        && let Some(entry) = cache::read(&validated, dir)
+    {
+        tracing::debug!(
+            target: "plumb_config::tailwind",
+            path = %config_path.display(),
+            "tailwind cache hit"
+        );
+        return Ok(entry.theme);
+    }
+
+    let node = find_node(options)?;
+    let theme = spawn_loader(&node, &validated, options)?;
+
+    if let Some(dir) = cache_dir {
+        // Best-effort write. If the cache directory is read-only or full,
+        // we still return a valid theme; subsequent runs will re-spawn.
+        if let Err(err) = cache::write(&validated, &theme, dir) {
+            tracing::debug!(
+                target: "plumb_config::tailwind",
+                path = %config_path.display(),
+                error = %err,
+                "tailwind cache write failed"
+            );
+        }
+    }
+
+    Ok(theme)
+}
+
+/// Validate the user-supplied config path. We require:
+///
+/// 1. A supported extension (`.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`).
+/// 2. The file exists and is a regular file.
+/// 3. When `cwd_override` is `Some`, after canonicalization the path
+///    must be under at least one of:
+///    - `cwd_override` itself,
+///    - any of `cwd_override`'s ancestors (so users can pass
+///      `--config /abs/path` pointing at a parent monorepo root),
+///    - the path itself if it was already absolute and exists on disk
+///      (covered by the ancestor check via the canonical form).
+///
+/// When `cwd_override` is `None`, the path-traversal guard is skipped.
+/// The library never reads [`std::env::current_dir`]; callers that
+/// want the guard MUST supply a canonical project root.
+///
+/// We return the canonical absolute path so downstream callers don't
+/// re-resolve it.
+fn validate_config_path(path: &Path, cwd_override: Option<&Path>) -> Result<PathBuf, ConfigError> {
+    let ext = path
+        .extension()
+        .and_then(OsStr::to_str)
+        .map(str::to_ascii_lowercase)
+        .unwrap_or_default();
+    if !SUPPORTED_EXTENSIONS.iter().any(|e| *e == ext) {
+        return Err(ConfigError::TailwindBadPath {
+            path: path.display().to_string(),
+            reason: format!(
+                "unsupported extension `.{ext}`; expected one of {SUPPORTED_EXTENSIONS:?}"
+            ),
+        });
+    }
+    let canonical = dunce::canonicalize(path).map_err(|err| ConfigError::TailwindBadPath {
+        path: path.display().to_string(),
+        reason: format!("could not resolve path: {err}"),
+    })?;
+    if !canonical.is_file() {
+        return Err(ConfigError::TailwindBadPath {
+            path: path.display().to_string(),
+            reason: "not a regular file".to_owned(),
+        });
+    }
+
+    if let Some(cwd) = cwd_override {
+        let cwd_canonical =
+            dunce::canonicalize(cwd).map_err(|err| ConfigError::TailwindBadPath {
+                path: path.display().to_string(),
+                reason: format!("could not resolve cwd root: {err}"),
+            })?;
+
+        if !is_under_or_ancestor(&canonical, &cwd_canonical) {
+            return Err(ConfigError::TailwindBadPath {
+                path: path.display().to_string(),
+                reason: "config path resolves outside the current working directory tree"
+                    .to_owned(),
+            });
+        }
+    }
+
+    Ok(canonical)
+}
+
+/// Returns `true` when `candidate` is `cwd`, a descendant of `cwd`, or a
+/// file whose parent directory is `cwd` or any non-root ancestor of
+/// `cwd`.
+///
+/// This covers the "pass `--config` pointing at a monorepo root" case
+/// while rejecting `..`-traversal attacks that escape the user's
+/// project tree. Crucially, the ancestor branch refuses to match when
+/// the candidate's parent is just the filesystem root (e.g.
+/// `/tailwind.config.js` on Unix); `cwd.starts_with("/")` is trivially
+/// true on Unix and would otherwise let any root-level file slip past
+/// the guard.
+fn is_under_or_ancestor(candidate: &Path, cwd: &Path) -> bool {
+    if candidate.starts_with(cwd) {
+        return true;
+    }
+    // The candidate's *parent* must be `cwd` or a non-root ancestor of
+    // `cwd`. Equivalently: `cwd` must start with the candidate's
+    // parent, AND that parent must contain at least one named
+    // component (so it's not just `/` or a Windows prefix).
+    let Some(candidate_parent) = candidate.parent() else {
+        return false;
+    };
+    let parent_has_named_component = candidate_parent
+        .components()
+        .any(|c| matches!(c, std::path::Component::Normal(_)));
+    if !parent_has_named_component {
+        return false;
+    }
+    cwd.starts_with(candidate_parent)
+}
+
+/// Find the `node` executable.
+fn find_node(options: &TailwindOptions) -> Result<PathBuf, ConfigError> {
+    if let Some(explicit) = &options.node_path {
+        if explicit.is_file() {
+            return Ok(explicit.clone());
+        }
+        return Err(ConfigError::TailwindUnavailable {
+            reason: format!(
+                "configured node executable `{}` does not exist",
+                explicit.display()
+            ),
+        });
+    }
+    which::which("node").map_err(|err| ConfigError::TailwindUnavailable {
+        reason: format!("`node` not found on PATH: {err}. Install Node.js (https://nodejs.org)"),
+    })
+}
+
+/// Drain a stdout/stderr reader thread, returning an empty buffer on
+/// any failure. Reader-thread errors are intentionally swallowed; the
+/// caller surfaces a higher-level `TailwindEval` error and a partial
+/// or empty buffer is fine for diagnostic context.
+fn drain_reader(handle: Option<thread::JoinHandle<std::io::Result<Vec<u8>>>>) -> Vec<u8> {
+    match handle {
+        None => Vec::new(),
+        Some(h) => match h.join() {
+            Ok(Ok(buf)) => buf,
+            Ok(Err(_)) | Err(_) => Vec::new(),
+        },
+    }
+}
+
+/// Outcome of polling a child process for completion.
+enum WaitOutcome {
+    /// The child exited with a final status before the budget expired.
+    Exited(ExitStatus),
+    /// `try_wait` returned an I/O error.
+    Errored(std::io::Error),
+    /// The poll budget elapsed without a final status.
+    TimedOut,
+}
+
+/// Poll `try_wait` on a tick cadence until either the child exits or
+/// the tick budget expires. We can't use `Instant::now` (workspace
+/// `clippy::disallowed_methods`), so the deadline is expressed as a
+/// tick count.
+fn wait_with_timeout(child: &mut std::process::Child, timeout: Duration) -> WaitOutcome {
+    let max_ticks = (timeout.as_millis() / POLL_INTERVAL.as_millis()).max(1);
+    for _ in 0..max_ticks {
+        match child.try_wait() {
+            Ok(Some(status)) => return WaitOutcome::Exited(status),
+            Ok(None) => thread::sleep(POLL_INTERVAL),
+            Err(err) => return WaitOutcome::Errored(err),
+        }
+    }
+    WaitOutcome::TimedOut
+}
+
+/// Drive the Node loader subprocess and parse its JSON output.
+fn spawn_loader(
+    node: &Path,
+    config_path: &Path,
+    options: &TailwindOptions,
+) -> Result<Value, ConfigError> {
+    let timeout = options
+        .timeout
+        .unwrap_or_else(|| Duration::from_secs(DEFAULT_TIMEOUT_SECS));
+
+    let mut child = Command::new(node)
+        // `-e` evaluates the embedded loader; the `--` separates Node's
+        // own argv from the script argv. We rely on `Command::arg` for
+        // shell-safe escaping — the user-supplied path is never
+        // concatenated into a shell string.
+        .arg("-e")
+        .arg(LOADER_JS)
+        .arg("--")
+        .arg(config_path.as_os_str())
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .map_err(|err| ConfigError::TailwindUnavailable {
+            reason: format!("failed to spawn `node`: {err}"),
+        })?;
+
+    // Reader threads MUST be spawned before we wait. Node can write
+    // more than one OS pipe buffer (~64 KiB on Linux) of stdout or
+    // stderr; without concurrent drainers the child blocks on `write`
+    // and we deadlock on the wait below.
+    let stdout = child.stdout.take();
+    let stderr = child.stderr.take();
+    let stdout_handle = stdout.map(|mut s| {
+        thread::spawn(move || -> std::io::Result<Vec<u8>> {
+            let mut buf = Vec::new();
+            s.read_to_end(&mut buf)?;
+            Ok(buf)
+        })
+    });
+    let stderr_handle = stderr.map(|mut s| {
+        thread::spawn(move || -> std::io::Result<Vec<u8>> {
+            let mut buf = Vec::new();
+            s.read_to_end(&mut buf)?;
+            Ok(buf)
+        })
+    });
+
+    let status = match wait_with_timeout(&mut child, timeout) {
+        WaitOutcome::Exited(status) => status,
+        WaitOutcome::TimedOut => {
+            // Kill the child, reap it with `wait` to release the OS
+            // resources, then surface a structured error.
+            let _ = child.kill();
+            let _ = child.wait();
+            let stderr_bytes = drain_reader(stderr_handle);
+            let _ = drain_reader(stdout_handle);
+            return Err(ConfigError::TailwindEval {
+                path: config_path.display().to_string(),
+                reason: format!("node subprocess timed out after {timeout:?}"),
+                stderr: String::from_utf8_lossy(&stderr_bytes).into_owned(),
+            });
+        }
+        WaitOutcome::Errored(err) => {
+            let stderr_bytes = drain_reader(stderr_handle);
+            let _ = drain_reader(stdout_handle);
+            return Err(ConfigError::TailwindEval {
+                path: config_path.display().to_string(),
+                reason: format!("failed to wait for node subprocess: {err}"),
+                stderr: String::from_utf8_lossy(&stderr_bytes).into_owned(),
+            });
+        }
+    };
+
+    let stdout_bytes = drain_reader(stdout_handle);
+    let stderr_bytes = drain_reader(stderr_handle);
+
+    if !status.success() {
+        // The loader emits a structured JSON error to stdout when it
+        // exits with code 2. Surface that structured form when present;
+        // otherwise fall back to whatever stderr captured.
+        let reason = parse_loader_error(&stdout_bytes).unwrap_or_else(|| {
+            format!(
+                "node exited with {} (stdout was {} bytes)",
+                status,
+                stdout_bytes.len()
+            )
+        });
+        return Err(ConfigError::TailwindEval {
+            path: config_path.display().to_string(),
+            reason,
+            stderr: String::from_utf8_lossy(&stderr_bytes).into_owned(),
+        });
+    }
+
+    let stdout = String::from_utf8(stdout_bytes).map_err(|err| ConfigError::TailwindEval {
+        path: config_path.display().to_string(),
+        reason: format!("node stdout was not valid UTF-8: {err}"),
+        stderr: String::from_utf8_lossy(&stderr_bytes).into_owned(),
+    })?;
+
+    let value: Value =
+        serde_json::from_str(stdout.trim()).map_err(|err| ConfigError::TailwindEval {
+            path: config_path.display().to_string(),
+            reason: format!("could not parse loader output as JSON: {err}"),
+            stderr: String::from_utf8_lossy(&stderr_bytes).into_owned(),
+        })?;
+
+    Ok(value)
+}
+
+/// Pull the structured `plumbTailwindError` payload out of the loader
+/// stdout, if present.
+fn parse_loader_error(stdout: &[u8]) -> Option<String> {
+    #[derive(Deserialize)]
+    struct Wrapper {
+        #[serde(rename = "plumbTailwindError")]
+        plumb_tailwind_error: Inner,
+    }
+    #[derive(Deserialize)]
+    struct Inner {
+        code: String,
+        message: String,
+    }
+    let s = std::str::from_utf8(stdout).ok()?.trim();
+    let parsed: Wrapper = serde_json::from_str(s).ok()?;
+    Some(format!(
+        "{} ({})",
+        parsed.plumb_tailwind_error.message, parsed.plumb_tailwind_error.code
+    ))
+}
+
+/// Apply a resolved Tailwind theme to a [`Config`]. Pure function — no
+/// I/O, no side effects.
+fn merge_theme_into_config(mut config: Config, theme: &Value) -> Config {
+    if let Some(colors) = theme.get("colors").and_then(Value::as_object) {
+        merge_colors(&mut config.color, colors);
+    }
+    if let Some(spacing) = theme.get("spacing").and_then(Value::as_object) {
+        merge_spacing(&mut config.spacing, spacing);
+    }
+    if let Some(font_size) = theme.get("fontSize").and_then(Value::as_object) {
+        merge_font_size(&mut config.type_scale, font_size);
+    }
+    if let Some(font_weight) = theme.get("fontWeight").and_then(Value::as_object) {
+        merge_font_weight(&mut config.type_scale, font_weight);
+    }
+    if let Some(font_family) = theme.get("fontFamily").and_then(Value::as_object) {
+        merge_font_family(&mut config.type_scale, font_family);
+    }
+    if let Some(radius) = theme.get("borderRadius").and_then(Value::as_object) {
+        merge_radius(&mut config.radius, radius);
+    }
+    config
+}
+
+/// Merge `theme.colors`. Nested groups become slash-namespaced tokens
+/// (`"red/500"`, `"bg/canvas"`, …). Non-string leaves are coerced to
+/// hex via [`css_color_to_hex`]; anything we can't normalize is
+/// dropped after a `tracing::debug` event.
+fn merge_colors(spec: &mut ColorSpec, colors: &serde_json::Map<String, Value>) {
+    for (name, value) in colors {
+        match value {
+            Value::String(s) => insert_color_token(spec, name, s),
+            Value::Object(group) => {
+                for (shade, leaf) in group {
+                    if let Value::String(s) = leaf {
+                        let key = format!("{name}/{shade}");
+                        insert_color_token(spec, &key, s);
+                    }
+                }
+            }
+            _ => {
+                tracing::debug!(
+                    target: "plumb_config::tailwind",
+                    name = %name,
+                    "skipping non-string colour leaf"
+                );
+            }
+        }
+    }
+}
+
+fn insert_color_token(spec: &mut ColorSpec, name: &str, css_value: &str) {
+    if let Some(hex) = css_color_to_hex(css_value) {
+        spec.tokens.insert(name.to_owned(), hex);
+    } else {
+        tracing::debug!(
+            target: "plumb_config::tailwind",
+            name = %name,
+            value = %css_value,
+            "skipping unrecognized colour"
+        );
+    }
+}
+
+/// Convert a Tailwind colour value to a six-digit hex string.
+///
+/// Accepts `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, and `rgb(...)` /
+/// `rgba(...)` in either comma- or whitespace-separated form. Alpha is
+/// parsed but not preserved — Plumb's `[color].tokens` stores only the
+/// opaque hex.
+///
+/// Other CSS colour forms (`hsl()`, `hsla()`, `oklch()`, named CSS
+/// colours like `transparent` or `rebeccapurple`) return `None`.
+/// Callers log the dropped token at `tracing::debug` and continue.
+fn css_color_to_hex(value: &str) -> Option<String> {
+    let v = value.trim().to_ascii_lowercase();
+    if let Some(body) = v.strip_prefix('#') {
+        return normalize_hex_body(body);
+    }
+    if let Some(rest) = v.strip_prefix("rgb(").and_then(|r| r.strip_suffix(')')) {
+        return parse_rgb(rest);
+    }
+    if let Some(rest) = v.strip_prefix("rgba(").and_then(|r| r.strip_suffix(')')) {
+        return parse_rgb(rest);
+    }
+    None
+}
+
+fn normalize_hex_body(body: &str) -> Option<String> {
+    let body = body.trim();
+    if !body.bytes().all(|b| b.is_ascii_hexdigit()) {
+        return None;
+    }
+    match body.len() {
+        3 => {
+            // #rgb → #rrggbb
+            let mut out = String::from("#");
+            for ch in body.chars() {
+                out.push(ch);
+                out.push(ch);
+            }
+            Some(out)
+        }
+        4 => {
+            // #rgba → #rrggbb (drop alpha)
+            let mut out = String::from("#");
+            for ch in body.chars().take(3) {
+                out.push(ch);
+                out.push(ch);
+            }
+            Some(out)
+        }
+        6 => Some(format!("#{body}")),
+        8 => Some(format!("#{}", &body[..6])),
+        _ => None,
+    }
+}
+
+fn parse_rgb(body: &str) -> Option<String> {
+    // Tailwind sometimes emits `rgb(255 0 0 / 0.5)` (modern syntax) or
+    // `rgb(255, 0, 0)`. Accept both.
+    let cleaned = body.replace([',', '/'], " ");
+    let mut parts = cleaned.split_ascii_whitespace();
+    let r = parts.next()?.parse::<u32>().ok()?;
+    let g = parts.next()?.parse::<u32>().ok()?;
+    let b = parts.next()?.parse::<u32>().ok()?;
+    if r > 255 || g > 255 || b > 255 {
+        return None;
+    }
+    Some(format!("#{r:02x}{g:02x}{b:02x}"))
+}
+
+/// Merge `theme.spacing`. Tailwind values are commonly `rem` strings;
+/// we convert at the standard 16 px = 1 rem ratio. Tokens that round
+/// to a non-positive integer are dropped.
+fn merge_spacing(spec: &mut SpacingSpec, spacing: &serde_json::Map<String, Value>) {
+    for (name, value) in spacing {
+        let Some(px) = css_length_to_px(value) else {
+            continue;
+        };
+        spec.tokens.insert(name.clone(), px);
+    }
+    rebuild_scale_from_tokens(&mut spec.scale, &spec.tokens);
+}
+
+/// Merge `theme.fontSize`. Tailwind entries are either a string (the
+/// size only) or a `[size, options]` tuple; either way we extract the
+/// size and convert to pixels.
+fn merge_font_size(spec: &mut TypeScaleSpec, font_size: &serde_json::Map<String, Value>) {
+    for (name, value) in font_size {
+        let raw = match value {
+            Value::String(_) | Value::Number(_) => Some(value.clone()),
+            Value::Array(arr) => arr.first().cloned(),
+            _ => None,
+        };
+        let Some(size) = raw else {
+            continue;
+        };
+        let Some(px) = css_length_to_px(&size) else {
+            continue;
+        };
+        spec.tokens.insert(name.clone(), px);
+    }
+    rebuild_scale_from_tokens(&mut spec.scale, &spec.tokens);
+}
+
+/// Merge `theme.fontWeight`. Values are numeric (string or number) per
+/// CSS. We dedupe and sort ascending to keep output deterministic.
+fn merge_font_weight(spec: &mut TypeScaleSpec, font_weight: &serde_json::Map<String, Value>) {
+    let mut existing: Vec<u16> = spec.weights.clone();
+    for value in font_weight.values() {
+        let parsed = match value {
+            Value::String(s) => s.parse::<u16>().ok(),
+            Value::Number(n) => n.as_u64().and_then(|u| u16::try_from(u).ok()),
+            _ => None,
+        };
+        if let Some(w) = parsed {
+            existing.push(w);
+        }
+    }
+    existing.sort_unstable();
+    existing.dedup();
+    spec.weights = existing;
+}
+
+/// Merge `theme.fontFamily`. Each value is typically a `[primary,
+/// fallback...]` array; we keep only the primary family per name and
+/// dedupe in insertion order.
+fn merge_font_family(spec: &mut TypeScaleSpec, font_family: &serde_json::Map<String, Value>) {
+    let mut seen: IndexMap<String, ()> = IndexMap::new();
+    for family in &spec.families {
+        seen.insert(family.clone(), ());
+    }
+    for value in font_family.values() {
+        let primary = match value {
+            Value::String(s) => Some(s.trim().trim_matches(['\'', '"']).to_owned()),
+            Value::Array(arr) => arr
+                .first()
+                .and_then(Value::as_str)
+                .map(|s| s.trim().trim_matches(['\'', '"']).to_owned()),
+            _ => None,
+        };
+        if let Some(family) = primary
+            && !family.is_empty()
+        {
+            seen.insert(family, ());
+        }
+    }
+    spec.families = seen.into_keys().collect();
+}
+
+/// Merge `theme.borderRadius` into [`RadiusSpec`].
+fn merge_radius(spec: &mut RadiusSpec, radius: &serde_json::Map<String, Value>) {
+    let mut values: Vec<u32> = spec.scale.clone();
+    for value in radius.values() {
+        if let Some(px) = css_length_to_px(value) {
+            values.push(px);
+        }
+    }
+    values.sort_unstable();
+    values.dedup();
+    spec.scale = values;
+}
+
+/// Convert a CSS length JSON value to integer pixels.
+///
+/// Supported units: `px` (rounds), `rem` and `em` (×16). Bare numbers
+/// are treated as pixels. Anything else returns `None`.
+fn css_length_to_px(value: &Value) -> Option<u32> {
+    let raw = match value {
+        Value::String(s) => s.trim().to_ascii_lowercase(),
+        Value::Number(n) => return n.as_f64().and_then(u32_from_f64_round),
+        _ => return None,
+    };
+    if raw.is_empty() || raw == "0" {
+        return Some(0);
+    }
+    if let Some(stripped) = raw.strip_suffix("px") {
+        return stripped
+            .trim()
+            .parse::<f64>()
+            .ok()
+            .and_then(u32_from_f64_round);
+    }
+    if let Some(stripped) = raw.strip_suffix("rem").or_else(|| raw.strip_suffix("em")) {
+        return stripped
+            .trim()
+            .parse::<f64>()
+            .ok()
+            .and_then(|f| u32_from_f64_round(f * 16.0));
+    }
+    raw.parse::<f64>().ok().and_then(u32_from_f64_round)
+}
+
+fn u32_from_f64_round(f: f64) -> Option<u32> {
+    if !f.is_finite() || f < 0.0 {
+        return None;
+    }
+    let rounded = f.round();
+    if rounded > f64::from(u32::MAX) {
+        return None;
+    }
+    // `as u32` is well-defined for non-negative finite floats below
+    // `u32::MAX`. We avoid `clippy::cast_possible_truncation` noise by
+    // doing the bound check above.
+    #[allow(clippy::cast_sign_loss, clippy::cast_possible_truncation)]
+    Some(rounded as u32)
+}
+
+fn rebuild_scale_from_tokens(scale: &mut Vec<u32>, tokens: &IndexMap<String, u32>) {
+    let mut combined: Vec<u32> = scale.clone();
+    combined.extend(tokens.values().copied());
+    combined.sort_unstable();
+    combined.dedup();
+    *scale = combined;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn css_color_normalizes_short_hex() {
+        assert_eq!(css_color_to_hex("#fff"), Some("#ffffff".to_owned()));
+        assert_eq!(css_color_to_hex("#FFF"), Some("#ffffff".to_owned()));
+        assert_eq!(css_color_to_hex("#0b7285"), Some("#0b7285".to_owned()));
+    }
+
+    #[test]
+    fn css_color_drops_alpha() {
+        assert_eq!(css_color_to_hex("#0b728580"), Some("#0b7285".to_owned()));
+        assert_eq!(css_color_to_hex("#abcd"), Some("#aabbcc".to_owned()));
+    }
+
+    #[test]
+    fn css_color_parses_rgb() {
+        assert_eq!(
+            css_color_to_hex("rgb(255, 0, 0)"),
+            Some("#ff0000".to_owned())
+        );
+        assert_eq!(
+            css_color_to_hex("rgb(11 114 133)"),
+            Some("#0b7285".to_owned())
+        );
+        assert_eq!(
+            css_color_to_hex("rgba(11, 114, 133, 0.5)"),
+            Some("#0b7285".to_owned())
+        );
+    }
+
+    #[test]
+    fn css_color_rejects_unknown() {
+        assert!(css_color_to_hex("transparent").is_none());
+        assert!(css_color_to_hex("hsl(0, 100%, 50%)").is_none());
+    }
+
+    #[test]
+    fn css_length_handles_rem_and_px() {
+        assert_eq!(css_length_to_px(&Value::String("1rem".into())), Some(16));
+        assert_eq!(css_length_to_px(&Value::String("1.5rem".into())), Some(24));
+        assert_eq!(css_length_to_px(&Value::String("12px".into())), Some(12));
+        assert_eq!(css_length_to_px(&Value::String("0".into())), Some(0));
+        assert_eq!(css_length_to_px(&Value::Number(8.into())), Some(8));
+    }
+
+    #[test]
+    fn merge_colors_supports_groups() {
+        let mut spec = ColorSpec::default();
+        let theme = serde_json::json!({
+            "white": "#ffffff",
+            "red": {
+                "500": "#ef4444",
+                "600": "#dc2626"
+            }
+        });
+        let map = theme.as_object().expect("object");
+        merge_colors(&mut spec, map);
+        assert_eq!(spec.tokens["white"], "#ffffff");
+        assert_eq!(spec.tokens["red/500"], "#ef4444");
+        assert_eq!(spec.tokens["red/600"], "#dc2626");
+    }
+
+    #[test]
+    fn merge_spacing_dedupes_scale() {
+        let mut spec = SpacingSpec {
+            scale: vec![0, 4],
+            ..SpacingSpec::default()
+        };
+        let theme = serde_json::json!({
+            "1": "0.25rem",
+            "2": "0.5rem",
+            "4": "1rem"
+        });
+        let map = theme.as_object().expect("object");
+        merge_spacing(&mut spec, map);
+        assert_eq!(spec.tokens["1"], 4);
+        assert_eq!(spec.tokens["2"], 8);
+        assert_eq!(spec.tokens["4"], 16);
+        // Scale combines existing 0/4 with 4/8/16 → sorted/deduped.
+        assert_eq!(spec.scale, vec![0, 4, 8, 16]);
+    }
+
+    #[test]
+    fn merge_font_size_supports_tuple_form() {
+        let mut spec = TypeScaleSpec::default();
+        let theme = serde_json::json!({
+            "sm": ["0.875rem", { "lineHeight": "1.25rem" }],
+            "base": "1rem"
+        });
+        let map = theme.as_object().expect("object");
+        merge_font_size(&mut spec, map);
+        assert_eq!(spec.tokens["sm"], 14);
+        assert_eq!(spec.tokens["base"], 16);
+        assert_eq!(spec.scale, vec![14, 16]);
+    }
+
+    #[test]
+    fn merge_font_weight_dedupes_and_sorts() {
+        let mut spec = TypeScaleSpec {
+            weights: vec![400],
+            ..TypeScaleSpec::default()
+        };
+        let theme = serde_json::json!({
+            "regular": "400",
+            "medium": 500,
+            "bold": 700
+        });
+        let map = theme.as_object().expect("object");
+        merge_font_weight(&mut spec, map);
+        assert_eq!(spec.weights, vec![400, 500, 700]);
+    }
+
+    #[test]
+    fn merge_font_family_keeps_primary() {
+        let mut spec = TypeScaleSpec::default();
+        let theme = serde_json::json!({
+            "sans": ["Inter", "ui-sans-serif", "system-ui"],
+            "mono": ["JetBrains Mono", "monospace"]
+        });
+        let map = theme.as_object().expect("object");
+        merge_font_family(&mut spec, map);
+        assert_eq!(spec.families, vec!["Inter", "JetBrains Mono"]);
+    }
+
+    #[test]
+    fn merge_radius_sorts_and_dedupes() {
+        let mut spec = RadiusSpec { scale: vec![4] };
+        let theme = serde_json::json!({
+            "sm": "0.125rem",
+            "md": "0.375rem",
+            "DEFAULT": "0.25rem"
+        });
+        let map = theme.as_object().expect("object");
+        merge_radius(&mut spec, map);
+        // 0.125rem→2, 0.25rem→4 (dup), 0.375rem→6 → [2, 4, 6]
+        assert_eq!(spec.scale, vec![2, 4, 6]);
+    }
+
+    #[test]
+    fn validate_rejects_unknown_extension() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let path = dir.path().join("tailwind.config.toml");
+        std::fs::write(&path, "x = 1").expect("write");
+        let err = validate_config_path(&path, Some(dir.path())).unwrap_err();
+        assert!(matches!(err, ConfigError::TailwindBadPath { .. }));
+    }
+
+    #[test]
+    fn validate_rejects_path_outside_cwd_root() {
+        let outside = tempfile::tempdir().expect("outside");
+        let outside_cfg = outside.path().join("tailwind.config.js");
+        std::fs::write(&outside_cfg, "module.exports = {};").expect("write");
+        let inside = tempfile::tempdir().expect("inside");
+        let err = validate_config_path(&outside_cfg, Some(inside.path())).unwrap_err();
+        assert!(matches!(err, ConfigError::TailwindBadPath { .. }));
+    }
+
+    #[test]
+    fn validate_accepts_descendant_of_cwd_root() {
+        let dir = tempfile::tempdir().expect("dir");
+        let path = dir.path().join("tailwind.config.js");
+        std::fs::write(&path, "module.exports = {};").expect("write");
+        let canonical = validate_config_path(&path, Some(dir.path())).expect("ok");
+        assert!(canonical.is_file());
+    }
+
+    #[test]
+    fn is_under_or_ancestor_accepts_descendant() {
+        assert!(is_under_or_ancestor(
+            Path::new("/work/proj/tailwind.config.js"),
+            Path::new("/work/proj")
+        ));
+    }
+
+    #[test]
+    fn is_under_or_ancestor_accepts_ancestor_sibling() {
+        // cwd is /work/proj/sub; config lives at /work/proj/tailwind.config.js
+        assert!(is_under_or_ancestor(
+            Path::new("/work/proj/tailwind.config.js"),
+            Path::new("/work/proj/sub")
+        ));
+    }
+
+    #[test]
+    fn is_under_or_ancestor_rejects_unrelated() {
+        assert!(!is_under_or_ancestor(
+            Path::new("/etc/passwd"),
+            Path::new("/work/proj")
+        ));
+    }
+
+    /// Security regression guard: a candidate at the filesystem root
+    /// (parent is `/`) MUST NOT slip past the ancestor branch on Unix.
+    /// `cwd.starts_with("/")` is trivially true for any absolute path,
+    /// so without the named-component check `/tailwind.config.js`
+    /// would be accepted as if it were a sibling under an ancestor.
+    #[test]
+    fn is_under_or_ancestor_rejects_filesystem_root() {
+        assert!(!is_under_or_ancestor(
+            Path::new("/tailwind.config.js"),
+            Path::new("/work/proj")
+        ));
+    }
+}
diff --git a/crates/plumb-config/tests/fixtures/tailwind/tailwind.config.js b/crates/plumb-config/tests/fixtures/tailwind/tailwind.config.js
new file mode 100644
index 0000000..f32d3e6
--- /dev/null
+++ b/crates/plumb-config/tests/fixtures/tailwind/tailwind.config.js
@@ -0,0 +1,43 @@
+// Sample Tailwind config used by Plumb's adapter tests.
+// CommonJS shape — works without any TS loader installed.
+
+module.exports = {
+  theme: {
+    colors: {
+      white: '#ffffff',
+      black: '#000000',
+      red: {
+        500: '#ef4444',
+        600: '#dc2626',
+      },
+    },
+    spacing: {
+      0: '0',
+      1: '0.25rem',
+      2: '0.5rem',
+      4: '1rem',
+      8: '2rem',
+    },
+    fontSize: {
+      sm: ['0.875rem', { lineHeight: '1.25rem' }],
+      base: ['1rem', { lineHeight: '1.5rem' }],
+      lg: ['1.125rem', { lineHeight: '1.75rem' }],
+    },
+    fontWeight: {
+      normal: '400',
+      medium: '500',
+      bold: '700',
+    },
+    fontFamily: {
+      sans: ['Inter', 'ui-sans-serif', 'system-ui'],
+      mono: ['JetBrains Mono', 'monospace'],
+    },
+    borderRadius: {
+      none: '0',
+      sm: '0.125rem',
+      DEFAULT: '0.25rem',
+      md: '0.375rem',
+      lg: '0.5rem',
+    },
+  },
+};
diff --git a/crates/plumb-config/tests/fixtures/tailwind/tailwind.config.ts b/crates/plumb-config/tests/fixtures/tailwind/tailwind.config.ts
new file mode 100644
index 0000000..b47f360
--- /dev/null
+++ b/crates/plumb-config/tests/fixtures/tailwind/tailwind.config.ts
@@ -0,0 +1,51 @@
+// Sample Tailwind TypeScript config for Plumb's adapter round-trip
+// test. The Rust integration test only runs this when a TS loader
+// (`tsx`, `ts-node`, or `esbuild-register`) is installed in the host
+// project — otherwise the loader emits TS_LOADER_MISSING and the test
+// skips.
+
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  content: [],
+  theme: {
+    colors: {
+      white: '#ffffff',
+      black: '#000000',
+      red: {
+        500: '#ef4444',
+        600: '#dc2626',
+      },
+    },
+    spacing: {
+      0: '0',
+      1: '0.25rem',
+      2: '0.5rem',
+      4: '1rem',
+      8: '2rem',
+    },
+    fontSize: {
+      sm: ['0.875rem', { lineHeight: '1.25rem' }],
+      base: ['1rem', { lineHeight: '1.5rem' }],
+      lg: ['1.125rem', { lineHeight: '1.75rem' }],
+    },
+    fontWeight: {
+      normal: '400',
+      medium: '500',
+      bold: '700',
+    },
+    fontFamily: {
+      sans: ['Inter', 'ui-sans-serif', 'system-ui'],
+      mono: ['JetBrains Mono', 'monospace'],
+    },
+    borderRadius: {
+      none: '0',
+      sm: '0.125rem',
+      DEFAULT: '0.25rem',
+      md: '0.375rem',
+      lg: '0.5rem',
+    },
+  },
+};
+
+export default config;
diff --git a/crates/plumb-config/tests/tailwind_adapter.rs b/crates/plumb-config/tests/tailwind_adapter.rs
new file mode 100644
index 0000000..accdb29
--- /dev/null
+++ b/crates/plumb-config/tests/tailwind_adapter.rs
@@ -0,0 +1,290 @@
+//! Integration tests for [`plumb_config::merge_tailwind`].
+//!
+//! ## Skipping when Node is missing
+//!
+//! These tests spawn a real `node` subprocess. CI runners and most
+//! workstations have Node; some Nix-style environments do not. When
+//! `node` cannot be found we treat that as a skip — same shape as the
+//! `e2e-chromium` tests in `plumb-cdp`.
+
+// allow expect_used — integration-test helpers lack the #[test] proximity
+// that clippy needs to apply `allow-expect-in-tests` from clippy.toml.
+#![allow(clippy::expect_used)]
+
+use std::path::PathBuf;
+use std::time::Duration;
+
+use plumb_config::{ConfigError, TailwindOptions, merge_tailwind};
+use plumb_core::Config;
+
+/// Returns `Some(path)` when a usable `node` is on PATH, `None`
+/// otherwise. Tests that need a real subprocess early-return on `None`
+/// so the suite stays green on Node-less hosts.
+fn node_on_path() -> Option<PathBuf> {
+    which::which("node").ok()
+}
+
+fn fixture_dir() -> PathBuf {
+    let mut p = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    p.push("tests");
+    p.push("fixtures");
+    p.push("tailwind");
+    p
+}
+
+#[test]
+fn merges_round_trip_tailwind_ts_config() {
+    if node_on_path().is_none() {
+        // Skip: host lacks Node.
+        return;
+    }
+    let path = fixture_dir().join("tailwind.config.ts");
+    if !path.exists() {
+        // Skip: fixture not present (e.g. shallow checkout).
+        return;
+    }
+    let cache_dir = tempfile::tempdir().expect("cache tempdir");
+    let opts = TailwindOptions {
+        cache_dir: Some(cache_dir.path().to_path_buf()),
+        // The fixture lives under `crates/plumb-config/tests/...` —
+        // explicitly anchor the guard at the workspace root so the
+        // test passes regardless of the cwd cargo picks at runtime.
+        cwd_root: Some(PathBuf::from(env!("CARGO_MANIFEST_DIR"))),
+        ..Default::default()
+    };
+    let merged = match merge_tailwind(Config::default(), &path, &opts) {
+        Ok(cfg) => cfg,
+        Err(ConfigError::TailwindUnavailable { .. }) => {
+            // Node disappeared between probe and spawn — treat as skip.
+            return;
+        }
+        Err(ConfigError::TailwindEval { reason, .. }) if reason.contains("TS_LOADER_MISSING") => {
+            // Host has no `tsx`/`ts-node`/`esbuild-register` installed.
+            // The .ts round-trip is the real test; without a TS loader
+            // we fall back to the .js fixture exercise via the other
+            // tests in this file.
+            return;
+        }
+        Err(other) => panic!("unexpected error: {other:?}"),
+    };
+
+    // Colours: flat token + nested group → slash-namespaced.
+    assert_eq!(merged.color.tokens["white"], "#ffffff");
+    assert_eq!(merged.color.tokens["red/500"], "#ef4444");
+    assert_eq!(merged.color.tokens["red/600"], "#dc2626");
+
+    // Spacing: rem → px at 16px = 1rem.
+    assert_eq!(merged.spacing.tokens["1"], 4);
+    assert_eq!(merged.spacing.tokens["4"], 16);
+    // Scale rebuilt from tokens, sorted, deduped.
+    assert!(merged.spacing.scale.contains(&4));
+    assert!(merged.spacing.scale.contains(&16));
+
+    // Type: fontSize tuple form keeps the size only.
+    assert_eq!(merged.type_scale.tokens["base"], 16);
+    assert_eq!(merged.type_scale.tokens["lg"], 18);
+    assert_eq!(merged.type_scale.weights, vec![400, 500, 700]);
+    assert!(merged.type_scale.families.contains(&"Inter".to_string()));
+
+    // Radius: rem → px, deduped.
+    assert!(merged.radius.scale.contains(&2));
+    assert!(merged.radius.scale.contains(&4));
+    assert!(merged.radius.scale.contains(&8));
+}
+
+/// Copy the JS fixture into `dir` so this test can mutate the file's
+/// mtime without disturbing parallel tests that read the canonical
+/// fixture under `tests/fixtures/tailwind/`. Returns the destination
+/// path on success, or `None` if the source fixture is missing.
+fn copy_fixture_to(dir: &std::path::Path) -> Option<PathBuf> {
+    let src = fixture_dir().join("tailwind.config.js");
+    if !src.exists() {
+        return None;
+    }
+    let dst = dir.join("tailwind.config.js");
+    std::fs::copy(&src, &dst).expect("copy fixture");
+    Some(dst)
+}
+
+#[test]
+fn cache_hit_skips_node_spawn() {
+    if node_on_path().is_none() {
+        return;
+    }
+    let fixture_root = tempfile::tempdir().expect("fixture tempdir");
+    let Some(path) = copy_fixture_to(fixture_root.path()) else {
+        return;
+    };
+    let cache_dir = tempfile::tempdir().expect("cache tempdir");
+    let opts = TailwindOptions {
+        cache_dir: Some(cache_dir.path().to_path_buf()),
+        cwd_root: Some(fixture_root.path().to_path_buf()),
+        ..Default::default()
+    };
+
+    // First call populates the cache.
+    let first = merge_tailwind(Config::default(), &path, &opts).expect("first call");
+    // Second call must be a cache hit. We force the issue by pointing
+    // `node_path` at a non-existent binary; if the cache is honoured,
+    // we never reach the `find_node` code path.
+    let opts_with_bogus_node = TailwindOptions {
+        cache_dir: Some(cache_dir.path().to_path_buf()),
+        cwd_root: Some(fixture_root.path().to_path_buf()),
+        node_path: Some(PathBuf::from("/definitely/not/a/node/binary")),
+        ..Default::default()
+    };
+    let second =
+        merge_tailwind(Config::default(), &path, &opts_with_bogus_node).expect("cache hit");
+
+    // Same input → same merged config.
+    assert_eq!(first.color.tokens, second.color.tokens);
+    assert_eq!(first.spacing.tokens, second.spacing.tokens);
+    assert_eq!(first.type_scale.tokens, second.type_scale.tokens);
+}
+
+#[test]
+fn cache_invalidates_on_mtime_bump() {
+    if node_on_path().is_none() {
+        return;
+    }
+    let fixture_root = tempfile::tempdir().expect("fixture tempdir");
+    let Some(path) = copy_fixture_to(fixture_root.path()) else {
+        return;
+    };
+    let cache_dir = tempfile::tempdir().expect("cache tempdir");
+    let opts = TailwindOptions {
+        cache_dir: Some(cache_dir.path().to_path_buf()),
+        cwd_root: Some(fixture_root.path().to_path_buf()),
+        ..Default::default()
+    };
+    let _ = merge_tailwind(Config::default(), &path, &opts).expect("first call");
+
+    // Bump the fixture mtime to a guaranteed-distinct future timestamp.
+    let later = std::time::UNIX_EPOCH + std::time::Duration::from_secs(2_000_000_000);
+    std::fs::OpenOptions::new()
+        .write(true)
+        .open(&path)
+        .expect("open fixture")
+        .set_modified(later)
+        .expect("set mtime");
+
+    // Cache miss → must re-spawn. Force failure if it tried the cache
+    // path: same bogus node trick. With an mtime mismatch the cache
+    // won't be consulted, so this must error with `TailwindUnavailable`.
+    let opts_with_bogus_node = TailwindOptions {
+        cache_dir: Some(cache_dir.path().to_path_buf()),
+        cwd_root: Some(fixture_root.path().to_path_buf()),
+        node_path: Some(PathBuf::from("/definitely/not/a/node/binary")),
+        ..Default::default()
+    };
+    let err = merge_tailwind(Config::default(), &path, &opts_with_bogus_node)
+        .expect_err("cache should miss on mtime change");
+    assert!(matches!(err, ConfigError::TailwindUnavailable { .. }));
+}
+
+#[test]
+fn errors_when_node_explicit_path_missing() {
+    let path = fixture_dir().join("tailwind.config.js");
+    if !path.exists() {
+        return;
+    }
+    let cache_dir = tempfile::tempdir().expect("cache tempdir");
+    let opts = TailwindOptions {
+        cache_dir: Some(cache_dir.path().to_path_buf()),
+        node_path: Some(PathBuf::from("/definitely/not/a/node/binary")),
+        no_cache: true,
+        cwd_root: Some(PathBuf::from(env!("CARGO_MANIFEST_DIR"))),
+        ..Default::default()
+    };
+    let err = merge_tailwind(Config::default(), &path, &opts).expect_err("must error");
+    let ConfigError::TailwindUnavailable { reason } = err else {
+        panic!("expected TailwindUnavailable, got {err:?}");
+    };
+    assert!(reason.contains("does not exist"), "reason = {reason}");
+}
+
+#[test]
+fn errors_on_unsupported_extension() {
+    let dir = tempfile::tempdir().expect("tempdir");
+    let path = dir.path().join("tailwind.config.json5");
+    std::fs::write(&path, "{}").expect("write");
+    let opts = TailwindOptions::default();
+    let err = merge_tailwind(Config::default(), &path, &opts).expect_err("must error");
+    assert!(matches!(err, ConfigError::TailwindBadPath { .. }));
+}
+
+// Note: a "path resolves outside cwd" test would need to mutate the
+// process-global CWD, which races with parallel tests in this file.
+// The unit-test `is_under_or_ancestor_rejects_unrelated` covers the
+// rejection logic deterministically.
+
+/// Determinism invariant: calling `merge_tailwind` twice on the same
+/// fixture MUST produce byte-identical output, including across the
+/// cache-miss → cache-hit boundary. The first call populates the
+/// cache; the second call reads from it. Both are functions of
+/// `(snapshot, config)` only, so they must agree exactly.
+#[test]
+fn merge_is_byte_identical_across_runs() {
+    if node_on_path().is_none() {
+        return;
+    }
+    let fixture_root = tempfile::tempdir().expect("fixture tempdir");
+    let Some(path) = copy_fixture_to(fixture_root.path()) else {
+        return;
+    };
+    let cache_dir = tempfile::tempdir().expect("cache tempdir");
+    let opts = TailwindOptions {
+        cache_dir: Some(cache_dir.path().to_path_buf()),
+        cwd_root: Some(fixture_root.path().to_path_buf()),
+        ..Default::default()
+    };
+
+    // First call: cache miss — spawns Node, populates the cache.
+    let first = merge_tailwind(Config::default(), &path, &opts).expect("first call");
+    // Second call: cache hit — reads the cache file we just wrote.
+    let second = merge_tailwind(Config::default(), &path, &opts).expect("second call");
+
+    // `Config` is `PartialEq` (see `plumb-core::config`), so this
+    // covers every nested spec — color, spacing, type_scale, radius,
+    // alignment, a11y — without piecewise comparison.
+    assert_eq!(
+        first, second,
+        "merge_tailwind output must be byte-identical across runs"
+    );
+}
+
+#[test]
+fn errors_when_node_subprocess_times_out() {
+    if node_on_path().is_none() {
+        return;
+    }
+    let dir = tempfile::tempdir().expect("tempdir");
+    // A `.cjs` script that intentionally never exits. `setInterval`
+    // keeps the event loop alive without busy-waiting; the polling
+    // loop in `spawn_loader` should kill it once the budget elapses.
+    let cfg_path = dir.path().join("tailwind.config.cjs");
+    std::fs::write(&cfg_path, "setInterval(() => {}, 1000);\n").expect("write hang script");
+
+    let cache_dir = tempfile::tempdir().expect("cache tempdir");
+    let opts = TailwindOptions {
+        cache_dir: Some(cache_dir.path().to_path_buf()),
+        cwd_root: Some(dir.path().to_path_buf()),
+        // Bypass the cache so the spawn happens.
+        no_cache: true,
+        // 200 ms is long enough to spin up Node on slow CI but short
+        // enough that the test wraps up well under the suite's
+        // per-test budget.
+        timeout: Some(Duration::from_millis(200)),
+        ..Default::default()
+    };
+
+    let err = merge_tailwind(Config::default(), &cfg_path, &opts)
+        .expect_err("hanging subprocess must surface a TailwindEval error");
+    let ConfigError::TailwindEval { reason, .. } = err else {
+        panic!("expected TailwindEval, got {err:?}");
+    };
+    assert!(
+        reason.contains("timed out"),
+        "expected reason to mention `timed out`, got `{reason}`"
+    );
+}