From 7b0984579d806a9b84b3a4c6335fefc6b3501fef Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Tue, 4 Aug 2026 10:39:45 -0400
Subject: [PATCH] feat(design): preview any design system, resolved from the
 record
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The record view listed values as text and drew a swatch only where the value
looked like a colour. Two problems, one cause: a derived value such as
color-mix(in srgb, var(--accent) 15%, transparent) was drawn by resolving
--accent against THIS app, so previewing another project's system showed
Scribe's palette. It looked right, which is why nobody noticed.

TokenPreview draws the system from its own record. Every value is resolved on
an offscreen probe carrying only that system's declarations, so a system whose
app this browser has never loaded renders in its own colours — which is the
difference between a tool and a mirror.

Specimens are chosen by value SHAPE, never by name: colours become swatches,
lengths become rules drawn to scale, gradients and shadows get a surface, font
stacks are set in themselves. Nothing matches --fs-space-* or any other
convention, because the convention belongs to the install (rule #115) — a
system that calls its spacing --gap-N gets the same treatment. Translucent
values sit on a checkerboard, or a 15% tint over a solid card reads as opaque
and shows the wrong colour.

Modes come from the system, not from the app: a system declaring base and
light offers both, independent of the theme this page is in.

The provenance list keeps its swatches only for self-contained colours — the
ones needing no resolution, which it can therefore draw honestly. Everything
with a var() inside is left to the preview built for it.

Step 2 of milestone #274.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UaYUaouG9jjhATyuxCKrQs
---
 frontend/src/components/TokenPreview.vue | 298 +++++++++++++++++++++++
 frontend/src/views/DesignSystemsView.vue |  42 +++-
 2 files changed, 333 insertions(+), 7 deletions(-)
 create mode 100644 frontend/src/components/TokenPreview.vue

diff --git a/frontend/src/components/TokenPreview.vue b/frontend/src/components/TokenPreview.vue
new file mode 100644
index 0000000..4accb5e
--- /dev/null
+++ b/frontend/src/components/TokenPreview.vue
@@ -0,0 +1,298 @@
+<script setup lang="ts">
+/**
+ * A design system's tokens, drawn rather than listed (#2431).
+ *
+ * WHAT MAKES THIS WORK FOR A SYSTEM YOU AREN'T RUNNING
+ * Every value is resolved on an offscreen probe carrying only this system's
+ * declarations (`resolveDeclared`), never read from the page. So a token like
+ * `color-mix(in srgb, var(--accent) 15%, transparent)` shows THIS system's
+ * accent, not the accent of the app you happen to be looking at. Previewing
+ * another project's palette from here is the point; a preview that quietly
+ * borrows the host app's values would be worse than no preview, because it
+ * would look right.
+ *
+ * SPECIMENS ARE CHOSEN BY VALUE SHAPE, NEVER BY NAME
+ * A colour is drawn as a swatch, a length as a rule of that length, a font
+ * stack as text set in it. Nothing here matches `--fs-space-*` or any other
+ * naming convention, because the convention is the install's (rule #115) — a
+ * system that calls its spacing `--gap-N` gets the same treatment.
+ *
+ * A token with no value for the chosen mode is shown as undecided rather than
+ * skipped. A named role awaiting a decision is information; a gap in a grid
+ * is not.
+ */
+import { computed, ref, watch } from "vue";
+
+import type { ResolvedToken } from "@/api/designSystems";
+import { BASE_MODE, modesPresent, resolveDeclared, valueForMode } from "@/utils/designValues";
+
+const props = defineProps<{ tokens: ResolvedToken[] }>();
+
+const modes = computed(() => modesPresent(props.tokens));
+const mode = ref(BASE_MODE);
+
+/** Values as the browser would compute them, for the chosen mode. */
+const rendered = ref<Map<string, string>>(new Map());
+
+function recompute() {
+  const declared = new Map<string, string>();
+  for (const token of props.tokens) {
+    const value = valueForMode(token.value_by_mode, mode.value);
+    if (value) declared.set(token.name, value);
+  }
+  rendered.value = resolveDeclared(declared);
+}
+
+watch(
+  [() => props.tokens, mode],
+  () => {
+    // Keep the selection only while it still exists — switching systems can
+    // drop a mode, and a stale one would silently render as base.
+    if (!modes.value.includes(mode.value)) mode.value = modes.value[0] ?? BASE_MODE;
+    recompute();
+  },
+  { immediate: true, deep: false },
+);
+
+type Shape = "colour" | "surface" | "length" | "font" | "plain";
+
+const COLOUR = /^(#|rgba?\(|hsla?\(|color-mix\(|light-dark\()/;
+const LENGTH = /^-?\d*\.?\d+(px|rem|em|ch|vh|vw)$/;
+const GRADIENT = /gradient\(/;
+/** Two or more space-separated parts ending in a colour — i.e. a shadow. */
+const SHADOW = /^[^,]*\d\s+.*(#|rgba?\(|color-mix\()/;
+/** A stack of family names: commas, no functions, no digits. */
+const FONT_STACK = /^[^(){}\d]+,[^(){}\d]+$/;
+
+function shapeOf(value: string): Shape {
+  const v = value.trim();
+  if (!v) return "plain";
+  if (COLOUR.test(v)) return "colour";
+  if (GRADIENT.test(v) || SHADOW.test(v)) return "surface";
+  if (LENGTH.test(v)) return "length";
+  if (FONT_STACK.test(v)) return "font";
+  return "plain";
+}
+
+interface Specimen {
+  name: string;
+  declared: string;
+  rendered: string;
+  shape: Shape;
+  purpose: string | null;
+  /** True when `var()` substitution changed the value — worth showing on hover. */
+  substituted: boolean;
+}
+
+const groups = computed(() => {
+  const out = new Map<string, Specimen[]>();
+  for (const token of props.tokens) {
+    const declared = valueForMode(token.value_by_mode, mode.value);
+    const value = rendered.value.get(token.name) ?? "";
+    const bucket = out.get(token.group_name ?? "ungrouped") ?? [];
+    bucket.push({
+      name: token.name,
+      declared,
+      rendered: value,
+      shape: shapeOf(value),
+      purpose: token.purpose,
+      substituted: Boolean(declared) && value !== declared,
+    });
+    out.set(token.group_name ?? "ungrouped", bucket);
+  }
+  return [...out.entries()];
+});
+
+/**
+ * Lengths are drawn to scale up to a ceiling, so a 40px heading and a 4px gap
+ * are visibly different — but a stray `100vw` can't stretch the row.
+ */
+function ruleWidth(value: string): string {
+  return `min(${value}, 12rem)`;
+}
+</script>
+
+<template>
+  <div class="tp">
+    <div v-if="modes.length > 1" class="tp-modes">
+      <button
+        v-for="m in modes"
+        :key="m"
+        class="tp-mode"
+        :class="{ active: m === mode }"
+        @click="mode = m"
+      >{{ m }}</button>
+      <span class="tp-modes-note">
+        The system's own modes — independent of the theme this app is in.
+      </span>
+    </div>
+
+    <div v-for="[group, specimens] in groups" :key="group" class="tp-group">
+      <h3 class="tp-group-heading">{{ group }}</h3>
+      <ul class="tp-grid">
+        <li v-for="s in specimens" :key="s.name" class="tp-item">
+          <div
+            class="tp-specimen"
+            :title="s.substituted ? `${s.declared} → ${s.rendered}` : s.declared"
+          >
+            <span
+              v-if="s.shape === 'colour'"
+              class="tp-swatch"
+              :style="{ background: s.rendered }"
+            />
+            <span
+              v-else-if="s.shape === 'surface'"
+              class="tp-surface"
+              :style="s.rendered.includes('gradient(')
+                ? { background: s.rendered }
+                : { boxShadow: s.rendered }"
+            />
+            <span v-else-if="s.shape === 'length'" class="tp-rule-wrap">
+              <span class="tp-rule" :style="{ width: ruleWidth(s.rendered) }" />
+            </span>
+            <span
+              v-else-if="s.shape === 'font'"
+              class="tp-font"
+              :style="{ fontFamily: s.rendered }"
+            >Ag</span>
+            <span v-else-if="!s.declared" class="tp-undecided">to be decided</span>
+            <span v-else class="tp-plain">{{ s.rendered }}</span>
+          </div>
+
+          <code class="tp-name">{{ s.name }}</code>
+          <span class="tp-value">{{ s.declared || "—" }}</span>
+          <span v-if="s.purpose" class="tp-purpose">{{ s.purpose }}</span>
+        </li>
+      </ul>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.tp-modes {
+  display: flex;
+  align-items: center;
+  gap: var(--fs-space-2);
+  flex-wrap: wrap;
+  margin-bottom: var(--fs-space-4);
+}
+
+.tp-mode {
+  padding: 0.2rem 0.6rem;
+  font: inherit;
+  font-size: var(--fs-size-body-sm);
+  color: var(--color-text-secondary);
+  background: transparent;
+  border: 1px solid var(--color-border);
+  border-radius: var(--fs-radius-sm);
+  cursor: pointer;
+}
+.tp-mode:hover { color: var(--color-text); }
+.tp-mode.active {
+  color: var(--color-primary-solid);
+  border-color: var(--color-primary);
+  background: var(--color-primary-faint);
+}
+
+.tp-modes-note {
+  font-size: var(--fs-size-tiny);
+  color: var(--color-text-muted);
+}
+
+.tp-group { margin-bottom: var(--fs-space-5); }
+
+.tp-group-heading {
+  text-transform: capitalize;
+  font-size: var(--fs-size-label);
+  color: var(--color-text-secondary);
+  margin-bottom: var(--fs-space-2);
+}
+
+.tp-grid {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(15rem, 1fr));
+  gap: var(--fs-space-3);
+}
+
+.tp-item {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.15rem;
+}
+
+/* A fixed-height stage so a 40px rule and a 2px one still line up in a grid. */
+.tp-specimen {
+  height: 2.75rem;
+  display: flex;
+  align-items: center;
+  border: 1px solid var(--color-border);
+  border-radius: var(--fs-radius-sm);
+  padding: 0 var(--fs-space-2);
+  overflow: hidden;
+  /* Checks show through anything translucent — a 15% tint over a solid card
+     would otherwise look opaque and read as the wrong colour. */
+  background:
+    repeating-conic-gradient(var(--color-surface) 0% 25%, var(--color-bg) 0% 50%)
+    0 0 / 12px 12px;
+}
+
+.tp-swatch,
+.tp-surface {
+  width: 100%;
+  height: 1.75rem;
+  border-radius: calc(var(--fs-radius-sm) - 1px);
+}
+
+.tp-surface { background: var(--color-surface); }
+
+.tp-rule-wrap {
+  width: 100%;
+  display: flex;
+  align-items: center;
+}
+
+.tp-rule {
+  height: 0.5rem;
+  min-width: 1px;
+  background: var(--color-primary-solid);
+  border-radius: 999px;
+}
+
+.tp-font {
+  font-size: 1.4rem;
+  color: var(--color-text);
+  line-height: 1;
+}
+
+.tp-plain {
+  font-family: var(--fs-font-mono);
+  font-size: var(--fs-size-code);
+  color: var(--color-text-secondary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.tp-undecided {
+  font-size: var(--fs-size-tiny);
+  color: var(--color-text-muted);
+  font-style: italic;
+}
+
+.tp-name {
+  font-size: var(--fs-size-body-sm);
+  color: var(--color-text);
+  word-break: break-all;
+}
+
+.tp-value,
+.tp-purpose {
+  font-size: var(--fs-size-tiny);
+  color: var(--color-text-muted);
+  word-break: break-word;
+}
+</style>
diff --git a/frontend/src/views/DesignSystemsView.vue b/frontend/src/views/DesignSystemsView.vue
index 856957a..d574c1d 100644
--- a/frontend/src/views/DesignSystemsView.vue
+++ b/frontend/src/views/DesignSystemsView.vue
@@ -46,6 +46,7 @@ import {
 import { ApiError } from "@/api/client";
 import { useToastStore } from "@/stores/toast";
 import StarterRolePicker from "@/components/StarterRolePicker.vue";
+import TokenPreview from "@/components/TokenPreview.vue";
 
 const toast = useToastStore();
 
@@ -492,8 +493,23 @@ watch(selectedId, () => {
   snippetCheck.value = null;
 });
 
-function isColourish(value: string): boolean {
-  return /^(#|rgba?\(|hsla?\(|color-mix\()/.test(value.trim());
+/**
+ * A colour this row can draw HONESTLY — self-contained, no `var()` inside.
+ *
+ * The provenance list below shows values as the record states them, and a
+ * `var()` reference states nothing on its own: rendering
+ * `color-mix(in srgb, var(--accent) 15%, transparent)` as a background resolves
+ * `--accent` against THIS app, so a system that isn't the one Scribe runs on
+ * would be drawn in Scribe's palette. It looked right, which is why it went
+ * unnoticed (#274).
+ *
+ * The preview above resolves values properly, on a probe carrying only that
+ * system's declarations. So this list draws only what needs no resolving, and
+ * leaves the rest to the surface built for it.
+ */
+function isSelfContainedColour(value: string): boolean {
+  const v = value.trim();
+  return /^(#|rgba?\(|hsla?\(|color-mix\()/.test(v) && !v.includes("var(");
 }
 </script>
 
@@ -770,7 +786,7 @@ function isColourish(value: string): boolean {
                   <ul class="dupe-list">
                     <li v-for="[value, names] in duplicateEntries" :key="value">
                       <span
-                        v-if="isColourish(value)" class="swatch"
+                        v-if="isSelfContainedColour(value)" class="swatch"
                         :style="{ background: value }" aria-hidden="true"
                       />
                       <code>{{ value }}</code> — {{ names.join(", ") }}
@@ -928,7 +944,7 @@ function isColourish(value: string): boolean {
                   <input v-model="row.mode" class="input mono mode-key" type="text" placeholder="base" />
                   <input v-model="row.value" class="input mono" type="text" placeholder="#14171a" />
                   <span
-                    v-if="isColourish(row.value)" class="swatch"
+                    v-if="isSelfContainedColour(row.value)" class="swatch"
                     :style="{ background: row.value }" aria-hidden="true"
                   />
                   <button
@@ -966,7 +982,7 @@ function isColourish(value: string): boolean {
                 <span class="token-values">
                   <span v-for="(value, mode) in token.value_by_mode" :key="mode" class="mode-chip">
                     <span
-                      v-if="isColourish(value)" class="swatch"
+                      v-if="isSelfContainedColour(value)" class="swatch"
                       :style="{ background: value }" aria-hidden="true"
                     />
                     <span class="mode-name">{{ mode }}</span>
@@ -989,6 +1005,18 @@ function isColourish(value: string): boolean {
             </ul>
           </section>
 
+          <!-- What it looks like. Drawn from the record on an isolated probe,
+               so this is THIS system's palette even when the app around it is
+               running a different one. -->
+          <section v-if="resolved.length" class="ds-section">
+            <h2>Preview</h2>
+            <p class="section-note">
+              {{ selected.title }} as it would render — resolved from the record,
+              not from the stylesheet this app happens to be running.
+            </p>
+            <TokenPreview :tokens="resolved" />
+          </section>
+
           <!-- Effective set -->
           <section class="ds-section">
             <h2>Effective tokens</h2>
@@ -1022,7 +1050,7 @@ function isColourish(value: string): boolean {
                     <div v-if="hasUniformOrigin(token)" class="resolved-modes">
                       <span v-for="origin in modeOrigins(token)" :key="origin.mode" class="mode-chip">
                         <span
-                          v-if="isColourish(origin.value)" class="swatch"
+                          v-if="isSelfContainedColour(origin.value)" class="swatch"
                           :style="{ background: origin.value }" aria-hidden="true"
                         />
                         <span class="mode-name">{{ origin.mode }}</span>
@@ -1043,7 +1071,7 @@ function isColourish(value: string): boolean {
                       <div v-for="origin in modeOrigins(token)" :key="origin.mode" class="mode-line">
                         <span class="mode-chip">
                           <span
-                            v-if="isColourish(origin.value)" class="swatch"
+                            v-if="isSelfContainedColour(origin.value)" class="swatch"
                             :style="{ background: origin.value }" aria-hidden="true"
                           />
                           <span class="mode-name">{{ origin.mode }}</span>