meno-core 1.1.0 → 1.1.2

package/lib/server/themeCssStore.ts

@@ -0,0 +1,210 @@
+/**
+ * theme.css store — the read/modify/write layer over a project's `src/styles/theme.css`,
+ * which is the single source of truth for design tokens (colors + variables). It replaces
+ * the old `colors.json` / `variables.json` pair for astro-format projects.
+ *
+ * Colors and variables share ONE file, so {@link saveColors} / {@link saveVariables} each
+ * re-read the current file and replace only their half (preserving the other half AND any
+ * `raw` passthrough), then re-serialize. All writes are funnelled through a single in-process
+ * queue so a colors save and a variables save can't clobber each other.
+ *
+ * On first access for a project that still carries legacy JSON, {@link migrateIfNeeded}
+ * regenerates theme.css from those JSON files (authoritative) and deletes them — a one-way,
+ * idempotent migration. Legacy JSON-format projects (no `src/pages`) are not handled here;
+ * the services keep their JSON path for those.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getProjectRoot } from './projectContext';
+import { writeFile, readTextFile, fileExists, ensureDir } from './runtime';
+import { configService } from './services/configService';
+import { parseThemeCss, serializeThemeCss, type ScaleConfig, type ThemeModel } from './themeCssCodec';
+import type { ThemeConfig } from '../shared/types/colors';
+import type { CSSVariable } from '../shared/types/variables';
+import { createLogger } from '../shared/logger';
+
+const log = createLogger('themeCssStore');
+
+/** Absolute path to a project's theme stylesheet. */
+export function themeCssPath(root: string = getProjectRoot()): string {
+  return join(root, 'src', 'styles', 'theme.css');
+}
+
+/**
+ * True when a project keeps its tokens in `theme.css` (astro-format). Detected by an
+ * existing theme.css, an `src/pages` layout, or an explicit `"format": "astro"`. Legacy
+ * JSON-format projects return false and keep reading colors.json / variables.json.
+ */
+export function isThemeCssProject(root: string = getProjectRoot()): boolean {
+  if (existsSync(themeCssPath(root))) return true;
+  if (existsSync(join(root, 'src', 'pages'))) return true;
+  try {
+    const cfg = JSON.parse(readFileSync(join(root, 'project.config.json'), 'utf8')) as { format?: string };
+    if (cfg.format === 'astro') return true;
+  } catch {
+    /* no/invalid config → not astro */
+  }
+  return false;
+}
+
+// All writes (and the migration) run serialized so concurrent color/variable saves
+// read-modify-write the shared file without races.
+let writeChain: Promise<unknown> = Promise.resolve();
+function enqueue<T>(fn: () => Promise<T>): Promise<T> {
+  const run = writeChain.then(fn, fn);
+  writeChain = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  return run;
+}
+
+async function readJsonSafe<T>(path: string): Promise<T | null> {
+  try {
+    return JSON.parse(await readTextFile(path)) as T;
+  } catch {
+    return null;
+  }
+}
+
+function scaleConfig(): ScaleConfig {
+  return { breakpoints: configService.getBreakpoints(), responsiveScales: configService.getResponsiveScales() };
+}
+
+/** Empty-but-valid model for a project with no theme.css yet. */
+function emptyModel(): ThemeModel {
+  return { themes: { default: 'default', themes: { default: { colors: {} } } }, variables: [], raw: [] };
+}
+
+/** Parse the on-disk theme.css (or an empty model if absent). Assumes config is loaded. */
+async function readModel(root: string): Promise<ThemeModel> {
+  const path = themeCssPath(root);
+  if (!(await fileExists(path))) return emptyModel();
+  return parseThemeCss(await readTextFile(path), configService.getBreakpoints());
+}
+
+/** Serialize + persist a model (creating `src/styles` as needed). Assumes config is loaded. */
+async function writeModel(root: string, model: ThemeModel): Promise<void> {
+  const css = serializeThemeCss(model, scaleConfig());
+  await ensureDir(join(root, 'src', 'styles'));
+  await writeFile(themeCssPath(root), css);
+}
+
+/** True when a theme has at least one color (i.e. theme.css already holds real tokens). */
+function hasColors(themes: ThemeConfig): boolean {
+  return Object.values(themes.themes ?? {}).some((t) => Object.keys(t.colors ?? {}).length > 0);
+}
+
+/** Union of two theme configs — `current` (theme.css) wins on conflict; incoming adds keys. */
+function mergeThemes(current: ThemeConfig, incoming: ThemeConfig | null): ThemeConfig {
+  if (!incoming?.themes) return current;
+  if (!hasColors(current)) return incoming; // empty theme.css → adopt the JSON wholesale
+  const out: ThemeConfig = { default: current.default, palette: current.palette, themes: { ...current.themes } };
+  for (const [name, theme] of Object.entries(incoming.themes)) {
+    const existing = out.themes[name];
+    out.themes[name] = existing ? { ...existing, colors: { ...theme.colors, ...existing.colors } } : theme;
+  }
+  return out;
+}
+
+/** Union of two variable lists by `cssVar` — `current` wins on conflict; incoming adds new. */
+function mergeVariables(current: CSSVariable[], incoming: CSSVariable[] | undefined): CSSVariable[] {
+  if (!incoming?.length) return current;
+  const seen = new Set(current.map((v) => v.cssVar));
+  return [...current, ...incoming.filter((v) => !seen.has(v.cssVar))];
+}
+
+/** Marker the serializer always stamps — distinguishes an authored theme.css from a derived one. */
+const AUTHORED_MARKER = 'Meno design tokens';
+
+/**
+ * Fold a project's `colors.json` + `variables.json` into theme.css, then delete the JSON.
+ * Serves two cases:
+ *   - Legacy migration — theme.css is absent or in the OLD derived format (the previous
+ *     converter's DO-NOT-EDIT output). The JSON is authoritative: theme.css is rebuilt from it
+ *     (we must NOT merge the derived file, whose unsectioned `:root` + duplicate `[theme]` blocks
+ *     would parse into a bogus extra theme).
+ *   - Overlay — theme.css is already authored (new format) and an external tool (e.g. the
+ *     style-guide applier) dropped JSON additions. A UNION merge (theme.css wins on key conflict,
+ *     JSON adds new keys) folds those in without clobbering anything.
+ * Foreign CSS (`raw`, e.g. @font-face) is preserved either way. No-op when no JSON is present, so
+ * it's safe to run on every load/save. Must be called inside {@link enqueue}.
+ */
+async function migrateIfNeeded(root: string): Promise<void> {
+  const colorsJson = join(root, 'colors.json');
+  const variablesJson = join(root, 'variables.json');
+  const hasColorsJson = existsSync(colorsJson);
+  const hasVarsJson = existsSync(variablesJson);
+  if (!hasColorsJson && !hasVarsJson) return;
+  try {
+    const jsonColors = hasColorsJson ? await readJsonSafe<ThemeConfig>(colorsJson) : null;
+    const jsonVars = hasVarsJson ? await readJsonSafe<{ variables: CSSVariable[] }>(variablesJson) : null;
+
+    let current = emptyModel();
+    let authored = false;
+    if (await fileExists(themeCssPath(root))) {
+      const text = await readTextFile(themeCssPath(root));
+      authored = text.includes(AUTHORED_MARKER);
+      current = parseThemeCss(text, configService.getBreakpoints());
+    }
+    // Authored → overlay-merge (theme.css wins). Derived/absent → JSON authoritative (base empty),
+    // but keep any foreign CSS the derived file happened to carry.
+    const base = authored ? current : emptyModel();
+    const merged: ThemeModel = {
+      themes: mergeThemes(base.themes, jsonColors?.themes ? jsonColors : null),
+      variables: mergeVariables(base.variables, jsonVars?.variables),
+      raw: current.raw,
+    };
+    await writeModel(root, merged);
+    await rm(colorsJson, { force: true });
+    await rm(variablesJson, { force: true });
+    log.info('Folded colors.json / variables.json into src/styles/theme.css');
+  } catch (err) {
+    // Leave the JSON in place so a later attempt can retry; surface but don't throw.
+    log.warn('theme.css migration failed; keeping JSON files:', err);
+  }
+}
+
+/** Load the full token model (runs the one-time JSON→theme.css migration first). */
+export async function loadThemeModel(root: string = getProjectRoot()): Promise<ThemeModel> {
+  await configService.load();
+  return enqueue(async () => {
+    await migrateIfNeeded(root);
+    return readModel(root);
+  });
+}
+
+/** Persist colors (themes) into theme.css, preserving the variables + raw already there. */
+export async function saveColors(themes: ThemeConfig, root: string = getProjectRoot()): Promise<void> {
+  await configService.load();
+  return enqueue(async () => {
+    await migrateIfNeeded(root);
+    const current = await readModel(root);
+    await writeModel(root, { themes, variables: current.variables, raw: current.raw });
+  });
+}
+
+/** Persist variables into theme.css, preserving the colors + raw already there. */
+export async function saveVariables(variables: CSSVariable[], root: string = getProjectRoot()): Promise<void> {
+  await configService.load();
+  return enqueue(async () => {
+    await migrateIfNeeded(root);
+    const current = await readModel(root);
+    await writeModel(root, { themes: current.themes, variables, raw: current.raw });
+  });
+}
+
+/**
+ * Re-serialize theme.css from its own current contents — used after a `project.config.json`
+ * scale-knob change to regenerate the AUTO `@media` region from the new config.
+ */
+export async function regenerateThemeCss(root: string = getProjectRoot()): Promise<void> {
+  await configService.load();
+  return enqueue(async () => {
+    await migrateIfNeeded(root);
+    if (!(await fileExists(themeCssPath(root)))) return;
+    await writeModel(root, await readModel(root));
+  });
+}

package/lib/shared/cssGeneration.test.ts

@@ -694,6 +694,16 @@ describe('styleObjectToCSS', () => {
     expect(styleObjectToCSS({ color: 'rgb(0,0,0)' })).toBe('color: rgb(0,0,0)');
   });
 
+  test('named CSS colors and keywords pass through — never wrapped in var()', () => {
+    // Regression: a literal `red` was being emitted as `var(--red)` (a token
+    // that does not exist) instead of the real CSS color.
+    expect(styleObjectToCSS({ color: 'red' })).toBe('color: red');
+    expect(styleObjectToCSS({ backgroundColor: 'transparent' })).toBe('background-color: transparent');
+    expect(styleObjectToCSS({ color: 'currentColor' })).toBe('color: currentColor');
+    expect(styleObjectToCSS({ borderColor: 'rebeccapurple' })).toBe('border-color: rebeccapurple');
+    expect(styleObjectToCSS({ color: 'inherit' })).toBe('color: inherit');
+  });
+
   test('skips _mapping (binding) values — bound props yield empty/partial output', () => {
     expect(styleObjectToCSS({ color: { _mapping: { prop: 'x' } } as never })).toBe('');
     expect(styleObjectToCSS({ color: { _mapping: { prop: 'x' } } as never, padding: '4px' })).toBe('padding: 4px');

package/lib/shared/cssGeneration.ts

@@ -11,6 +11,7 @@ import {
   breakpointClassPrefixes,
   resolveRootProperty,
   camelToKebab,
+  isBareColorTokenName,
 } from './utilityClassNames';
 import { getStyleValue, getDynamicStyle, isDynamicClass } from './styleValueRegistry';
 import type { BreakpointConfig } from './breakpoints';
@@ -213,6 +214,9 @@ export function generateRuleForClass(className: string, knownTokens?: ReadonlySe
   }
 
   // Multi-property roots (Tailwind axis shorthands)
+  if (root === 'size') {
+    return `width: ${value}; height: ${value};`;
+  }
   if (root === 'px') {
     return `padding-left: ${value}; padding-right: ${value};`;
   }
@@ -726,15 +730,13 @@ export function styleObjectToCSS(style: StyleObject): string {
     // Convert camelCase to kebab-case
     const cssProperty = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
 
-    // Handle CSS variable references for color properties
+    // Handle CSS variable references for color properties. Only a bare Meno
+    // color *token* (e.g. `primary`) is wrapped in `var(--token)`. Named CSS
+    // colors (`red`), hex, color functions and Tailwind palette names are real
+    // values and pass through untouched — mirrors the utility-class engine so
+    // the interactive path and the static path resolve colors identically.
     let cssValue = String(value);
-    if (
-      (prop === 'backgroundColor' || prop === 'color' || prop === 'borderColor') &&
-      !cssValue.startsWith('#') &&
-      !cssValue.startsWith('rgb') &&
-      !cssValue.startsWith('var(') &&
-      !cssValue.includes('(')
-    ) {
+    if ((prop === 'backgroundColor' || prop === 'color' || prop === 'borderColor') && isBareColorTokenName(cssValue)) {
       cssValue = `var(--${cssValue})`;
     }
 

package/lib/shared/index.ts

@@ -30,6 +30,12 @@ export { splitVariantPrefix, normalizeBreakpointVariant } from './utilityClassNa
 // Utility-class catalog pieces — the seed for the Styles panel's class-bar autocomplete (§13 Phase 5).
 // Selective (not `export *`) to keep the barrel collision-free.
 export { propertyMap, staticUtilityReverse, keywordValues, presetClassReverse } from './utilityClassConfig';
+// Tailwind theme-scale tokens + the seed-variable generator (`text-lg` → `var(--text-lg, …)`).
+export {
+  THEME_SCALE_ENTRIES,
+  defaultTailwindThemeVariables,
+  type ThemeScaleEntry,
+} from './tailwindThemeScale';
 export * from './elementClassName';
 export * from './styleValueRegistry';
 

package/lib/shared/interactiveStyles.test.ts

@@ -33,8 +33,10 @@ describe('generateInteractiveCSS', () => {
       const css = generateInteractiveCSS(elementClass, interactiveStyles);
 
       expect(css).toContain(`.${elementClass}:hover`);
+      // `primary` is a bare Meno token → wrapped in var(); `white` is a real
+      // named CSS color → passes through untouched (not var(--white)).
       expect(css).toContain('background-color: var(--primary)');
-      expect(css).toContain('color: var(--white)');
+      expect(css).toContain('color: white');
     });
 
     test('should generate active styles for page element', () => {

package/lib/shared/tailwindThemeScale.ts

@@ -0,0 +1,256 @@
+/**
+ * Tailwind named-scale → CSS-variable theme table.
+ *
+ * Tailwind's *named* value scales (`text-lg`, `font-semibold`, `rounded-md`, `shadow-lg`,
+ * `max-w-md`, `leading-tight`, `tracking-wide`, `font-sans`) have no single numeric mapping — each
+ * name is a theme token. Meno is token-based, so the class resolves to a plain variable reference
+ * with **no baked default** — it renders the project's variable when defined, and is inert when not
+ * (Meno deliberately does NOT smuggle Tailwind's opinionated defaults into the render):
+ *
+ *   `text-lg`  →  `font-size: var(--text-lg)`
+ *
+ * Define `--text-lg` (in `variables.json`) → `text-lg` uses it everywhere; leave it undefined →
+ * the declaration has no effect (use an arbitrary value like `text-[18px]` for a one-off). See the
+ * styling docs for the authoring guidance.
+ *
+ * This table is the single source of truth for:
+ *   - the parser (`parseUtilityClass`): class → `var(--token)`
+ *   - the inverse mapper (`propertyValueToClass`): `var(--token)` → compact class
+ *   - `defaultTailwindThemeVariables()`: an OPT-IN starter set (Tailwind values) a user can choose
+ *     to create — it is never auto-applied and never a render fallback.
+ */
+
+import type { CSSVariable, VariableGroup, VariableType } from './types/variables';
+
+/** One Tailwind theme token: the class it backs, its CSS var, default value and UI grouping. */
+export interface ThemeScaleEntry {
+  /** Full utility class, e.g. `text-lg`, or the bare default (`rounded`, `shadow`). */
+  className: string;
+  /** The class root (`text`, `font`, `rounded`, `shadow`, `max-w`, `leading`, `tracking`). */
+  root: string;
+  /** CSS custom property, e.g. `--text-lg`. */
+  cssVar: string;
+  /** kebab-case CSS property the class targets. */
+  property: string;
+  /** Tailwind's default value — the starter value for the OPT-IN seed set, NOT a render fallback. */
+  value: string;
+  /** Variable picker group + scaling type for the seeded variable. */
+  group: VariableGroup;
+  /** Human label for the seeded variable, e.g. `Text LG`. */
+  label: string;
+}
+
+type ScaleSpec = {
+  root: string;
+  property: string;
+  group: VariableGroup;
+  /** Prefix for the css var; class is `${root}-${name}` (or bare `${root}` when name is ''). */
+  varPrefix: string;
+  /** Human label prefix for the seeded variable. */
+  labelPrefix: string;
+  /** [classSuffix, cssValue] pairs. '' suffix = the bare class (`rounded`, `shadow`). */
+  values: [string, string][];
+};
+
+const SANS = 'ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif';
+const SERIF = 'ui-serif, Georgia, Cambria, serif';
+const MONO = 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace';
+
+const SPECS: ScaleSpec[] = [
+  {
+    root: 'text',
+    property: 'font-size',
+    group: 'font-size',
+    varPrefix: 'text',
+    labelPrefix: 'Text',
+    values: [
+      ['xs', '0.75rem'],
+      ['sm', '0.875rem'],
+      ['base', '1rem'],
+      ['lg', '1.125rem'],
+      ['xl', '1.25rem'],
+      ['2xl', '1.5rem'],
+      ['3xl', '1.875rem'],
+      ['4xl', '2.25rem'],
+      ['5xl', '3rem'],
+      ['6xl', '3.75rem'],
+      ['7xl', '4.5rem'],
+      ['8xl', '6rem'],
+      ['9xl', '8rem'],
+    ],
+  },
+  {
+    // Only the weights Meno's static utilities don't already cover (normal/bold stay static).
+    root: 'font',
+    property: 'font-weight',
+    group: 'font-weight',
+    varPrefix: 'font-weight',
+    labelPrefix: 'Font Weight',
+    values: [
+      ['thin', '100'],
+      ['extralight', '200'],
+      ['light', '300'],
+      ['medium', '500'],
+      ['semibold', '600'],
+      ['extrabold', '800'],
+      ['black', '900'],
+    ],
+  },
+  {
+    root: 'font',
+    property: 'font-family',
+    group: 'font-family',
+    varPrefix: 'font',
+    labelPrefix: 'Font',
+    values: [
+      ['sans', SANS],
+      ['serif', SERIF],
+      ['mono', MONO],
+    ],
+  },
+  {
+    root: 'rounded',
+    property: 'border-radius',
+    group: 'border-radius',
+    varPrefix: 'radius',
+    labelPrefix: 'Radius',
+    values: [
+      ['', '0.25rem'],
+      ['sm', '0.125rem'],
+      ['md', '0.375rem'],
+      ['lg', '0.5rem'],
+      ['xl', '0.75rem'],
+      ['2xl', '1rem'],
+      ['3xl', '1.5rem'],
+    ],
+  },
+  {
+    root: 'shadow',
+    property: 'box-shadow',
+    group: 'shadow',
+    varPrefix: 'shadow',
+    labelPrefix: 'Shadow',
+    values: [
+      ['', '0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)'],
+      ['sm', '0 1px 2px 0 rgb(0 0 0 / 0.05)'],
+      ['md', '0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)'],
+      ['lg', '0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)'],
+      ['xl', '0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)'],
+      ['2xl', '0 25px 50px -12px rgb(0 0 0 / 0.25)'],
+    ],
+  },
+  {
+    root: 'max-w',
+    property: 'max-width',
+    group: 'size',
+    varPrefix: 'container',
+    labelPrefix: 'Container',
+    values: [
+      ['xs', '20rem'],
+      ['sm', '24rem'],
+      ['md', '28rem'],
+      ['lg', '32rem'],
+      ['xl', '36rem'],
+      ['2xl', '42rem'],
+      ['3xl', '48rem'],
+      ['4xl', '56rem'],
+      ['5xl', '64rem'],
+      ['6xl', '72rem'],
+      ['7xl', '80rem'],
+      ['prose', '65ch'],
+    ],
+  },
+  {
+    root: 'leading',
+    property: 'line-height',
+    group: 'line-height',
+    varPrefix: 'leading',
+    labelPrefix: 'Leading',
+    values: [
+      ['none', '1'],
+      ['tight', '1.25'],
+      ['snug', '1.375'],
+      ['relaxed', '1.625'],
+      ['loose', '2'],
+    ],
+  },
+  {
+    root: 'tracking',
+    property: 'letter-spacing',
+    group: 'letter-spacing',
+    varPrefix: 'tracking',
+    labelPrefix: 'Tracking',
+    values: [
+      ['tighter', '-0.05em'],
+      ['tight', '-0.025em'],
+      ['wide', '0.025em'],
+      ['wider', '0.05em'],
+      ['widest', '0.1em'],
+    ],
+  },
+];
+
+/** Size codes read better uppercased (`LG`, `2XL`); word names get title case (`Semibold`). */
+function labelSuffix(suffix: string): string {
+  if (/^(xs|sm|md|lg|xl|\dxl)$/.test(suffix)) return suffix.toUpperCase();
+  return suffix.charAt(0).toUpperCase() + suffix.slice(1);
+}
+
+/** All theme entries, flattened. */
+export const THEME_SCALE_ENTRIES: ThemeScaleEntry[] = SPECS.flatMap((spec) =>
+  spec.values.map(([suffix, value]) => {
+    const className = suffix ? `${spec.root}-${suffix}` : spec.root;
+    const cssVar = suffix ? `--${spec.varPrefix}-${suffix}` : `--${spec.varPrefix}`;
+    const label = suffix ? `${spec.labelPrefix} ${labelSuffix(suffix)}` : spec.labelPrefix;
+    return { className, root: spec.root, cssVar, property: spec.property, value, group: spec.group, label };
+  }),
+);
+
+/** className → entry (parser lookup). e.g. `text-lg`, `rounded`, `font-sans`. */
+export const THEME_SCALE_BY_CLASS: ReadonlyMap<string, ThemeScaleEntry> = new Map(
+  THEME_SCALE_ENTRIES.map((e) => [e.className, e]),
+);
+
+/** cssVar → entry (inverse-mapper lookup). e.g. `--text-lg` → `text-lg`. */
+export const THEME_SCALE_BY_CSSVAR: ReadonlyMap<string, ThemeScaleEntry> = new Map(
+  THEME_SCALE_ENTRIES.map((e) => [e.cssVar, e]),
+);
+
+/**
+ * The CSS value a themed class resolves to: a plain `var(--token)` reference with no fallback.
+ * Renders the project variable when defined, inert otherwise (token-based by design — no baked
+ * Tailwind default in the render path).
+ */
+export function themeScaleValue(entry: ThemeScaleEntry): string {
+  return `var(${entry.cssVar})`;
+}
+
+/** Map a variable group to its responsive-scaling type (mirrors getDefaultScalingType). */
+function scalingTypeFor(group: VariableGroup): VariableType {
+  switch (group) {
+    case 'font-size':
+      return 'fontSize';
+    case 'border-radius':
+      return 'borderRadius';
+    case 'size':
+      return 'size';
+    default:
+      return 'none';
+  }
+}
+
+/**
+ * The full set of Tailwind theme tokens as Meno `CSSVariable`s, ready to merge into a project's
+ * `variables.json`. Seeding makes the tokens visible/editable in the variable picker (filed under
+ * their group); rendering does NOT require seeding — the class carries the Tailwind default as the
+ * `var()` fallback. Idempotent merge is the caller's job (skip a `cssVar` that already exists).
+ */
+export function defaultTailwindThemeVariables(): CSSVariable[] {
+  return THEME_SCALE_ENTRIES.map((e) => ({
+    name: e.label,
+    cssVar: e.cssVar,
+    value: e.value,
+    type: scalingTypeFor(e.group),
+    group: e.group,
+  }));
+}

package/lib/shared/types/colors.ts

@@ -12,10 +12,14 @@ export interface ColorVariables {
 }
 
 /**
- * Theme configuration with color set and metadata
+ * Theme configuration with color set and metadata.
+ *
+ * `label` is an editor-only display string. The theme.css codec does not persist
+ * it (a theme is identified by its name — the `[theme="<name>"]` selector), so it
+ * is optional; consumers fall back to the (prettified) theme name.
  */
 export interface Theme {
-  label: string;
+  label?: string;
   colors: Record<string, string>;
 }
 

package/lib/shared/types/variables.ts

@@ -146,22 +146,29 @@ export function getGroupForProperty(prop: string): VariableGroup | null {
 }
 
 /**
- * A single CSS custom property definition
+ * A single CSS custom property definition.
+ *
+ * Source of truth is `src/styles/theme.css` (the `theme.css` codec), so the CSS
+ * variable name (`cssVar`) IS a token's identity — `name`/`prop_name` are
+ * editor-only labels that the codec no longer persists, and `group`/`type` are
+ * DERIVED on parse (from the var's comment-section header, falling back to a
+ * value heuristic), not stored. They stay on the in-memory object because the
+ * pickers and the responsive-scaling generator still consult them.
  */
 export interface CSSVariable {
-  /** Display name (e.g., "H1 Font Size") */
-  name: string;
-  /** Optional prop name alias for organizational purposes */
+  /** Optional display label. Not persisted by the theme.css codec — defaults to `cssVar`. */
+  name?: string;
+  /** Optional prop name alias for organizational purposes (legacy; not persisted). */
   prop_name?: string;
-  /** CSS custom property name (e.g., "--h1-fs") */
+  /** CSS custom property name (e.g., "--h1-fs") — the token's persistent identity. */
   cssVar: string;
   /** Base value (e.g., "48px") */
   value: string;
-  /** Category for responsive scaling */
+  /** Category for responsive scaling (derived from {@link group} via getDefaultScalingType). */
   type: VariableType;
   /** Optional per-variable breakpoint scale overrides */
   scales?: Record<string, string>;
-  /** Optional UI filtering group for the variable picker */
+  /** UI filtering group for the variable picker (derived from the theme.css comment section). */
   group?: VariableGroup;
 }