brand_colors: token "cap_natural" is locked and cannot be modified. Unlock it first if a change is intentional.

UPDATE brand_colors SET is_locked = false WHERE token_name = 'cap_natural';
UPDATE brand_colors SET hex_value = '#newvalue', is_locked = true WHERE token_name = 'cap_natural';

global_design_tokens          (54 base tokens)
         +
brand_token_overrides         (per-brand delta -- only overridden values)
         =
TokenWithInheritance[]        (resolved set with inheritance context)

import { resolveTokens, getTokenDiff, injectResolvedTokens } from "@/lib/token-resolver";
 
// 1. Fetch both layers from Supabase
const [{ data: globals }, { data: overrides }] = await Promise.all([
  supabase.from("global_design_tokens").select("*"),
  supabase.from("brand_token_overrides").select("*").eq("entity_id", brandId),
]);
 
// 2. Resolve: every global token appears, with override applied if present
const resolved = resolveTokens(globals ?? [], overrides ?? []);
 
// 3. Split into overridden vs inherited (for diff view)
const { overridden, inherited } = getTokenDiff(resolved);
 
// 4. Inject as CSS custom properties (client-side only)
injectResolvedTokens(resolved);

interface TokenWithInheritance {
  token_name: string;                    // e.g. "brand_green"
  token_type: "color" | "typography" | "spacing";
  category: string | null;              // e.g. "brand", "five_capitals", "scale"
  globalValue: TokenValue;              // always from global_design_tokens
  overrideValue: TokenValue | null;     // from brand_token_overrides, null if inheriting
  resolvedValue: TokenValue;            // overrideValue ?? globalValue
  isOverridden: boolean;                // true if an override row exists
  overrideId: string | null;            // override row UUID (for update/delete)
}

import { cssVarName } from "@regen/design-tokens";
 
cssVarName("brand_green");   // "--brand_green"
cssVarName("cap_natural");   // "--cap_natural"
cssVarName("spacing-4");     // "--spacing-4"

/* Correct -- underscores preserved */
color: var(--brand_green);
background: var(--surface_light);
padding: var(--spacing-4);
 
/* Wrong -- do not convert underscores to dashes */
color: var(--brand-green);

--heading_1-family: "Calibri Light";
--heading_1-size: 20pt;
--heading_1-weight: 700;

// Color (token_type: "color")
{ hex: "#548235", rgb_r: 84, rgb_g: 130, rgb_b: 53 }
 
// Typography (token_type: "typography")
{ font_family: "Calibri Light", font_size_pt: 20, font_weight: 700, context: "document" }
 
// Spacing (token_type: "spacing")
{ value_px: 16, context: "default" }