@snagtag/design-system 0.2.1 → 0.2.3

package/dist/index.cjs

@@ -61,6 +61,7 @@ __export(index_exports, {
   createOverlay: () => createOverlay,
   createReassignmentState: () => createReassignmentState,
   createThemeEditorState: () => createThemeEditorState,
+  customTokenDefaults: () => customTokenDefaults,
   darken: () => darken,
   downloadAuditReport: () => downloadAuditReport,
   downloadStyleGuide: () => downloadStyleGuide,
@@ -327,6 +328,11 @@ function suggestPalettes(primaryHex) {
 }
 
 // src/theme-defaults.ts
+function customTokenDefaults(tokens = []) {
+  const out = {};
+  for (const t of tokens) out[t.key] = t.defaultValue;
+  return out;
+}
 var THEME_DEFAULTS = {
   // Primitives
   primaryColor: "#2563eb",
@@ -334,6 +340,17 @@ var THEME_DEFAULTS = {
   primaryLightColor: "#dbeafe",
   secondaryColor: "#64748b",
   accentColor: "#f59e0b",
+  // Foundations — global semantic text + border tokens.
+  // These are app-wide roles (not component-scoped) so host apps can map their
+  // own primary/secondary/muted text and default/subtle borders one-to-one.
+  // Defaults deliberately match the closest existing primitives so adopting
+  // them causes no visual shift (text-primary = ink-900, etc.).
+  textPrimary: "#0f172a",
+  textSecondary: "#64748b",
+  textMuted: "#94a3b8",
+  textInverse: "#ffffff",
+  borderDefault: "#e2e8f0",
+  borderSubtle: "#f1f5f9",
   // Sidebar
   sidebarBg: "#ffffff",
   sidebarText: "#475569",
@@ -418,6 +435,13 @@ var THEME_KEY_TO_CSS = {
   primaryLightColor: "--color-brand-100",
   secondaryColor: "--color-ink-500",
   accentColor: "--color-accent",
+  // Foundations — global semantic text + border tokens
+  textPrimary: "--color-text-primary",
+  textSecondary: "--color-text-secondary",
+  textMuted: "--color-text-muted",
+  textInverse: "--color-text-inverse",
+  borderDefault: "--color-border-default",
+  borderSubtle: "--color-border-subtle",
   // Sidebar
   sidebarBg: "--color-sidebar-bg",
   sidebarText: "--color-sidebar-text",
@@ -498,6 +522,10 @@ var THEME_CATEGORIES = [
     label: "Brand",
     keys: ["primaryColor", "primaryHoverColor", "primaryLightColor", "secondaryColor", "accentColor"]
   },
+  {
+    label: "Foundations",
+    keys: ["textPrimary", "textSecondary", "textMuted", "textInverse", "borderDefault", "borderSubtle"]
+  },
   {
     label: "Sidebar",
     keys: ["sidebarBg", "sidebarText", "sidebarActiveBg"]
@@ -719,6 +747,14 @@ var SEMANTIC_COLOURS = [
   { cssVar: "--color-info", label: "Info", category: "colour", defaultValue: "#3b82f6", themeKey: "infoColor" },
   { cssVar: "--color-info-light", label: "Info Light", category: "colour", defaultValue: "#dbeafe", themeKey: "infoLightColor" }
 ];
+var FOUNDATION_TOKENS = [
+  { cssVar: "--color-text-primary", label: "Text Primary", category: "colour", defaultValue: "#0f172a", references: "--color-ink-900", themeKey: "textPrimary" },
+  { cssVar: "--color-text-secondary", label: "Text Secondary", category: "colour", defaultValue: "#64748b", references: "--color-ink-500", themeKey: "textSecondary" },
+  { cssVar: "--color-text-muted", label: "Text Muted", category: "colour", defaultValue: "#94a3b8", references: "--color-ink-400", themeKey: "textMuted" },
+  { cssVar: "--color-text-inverse", label: "Text Inverse", category: "colour", defaultValue: "#ffffff", themeKey: "textInverse" },
+  { cssVar: "--color-border-default", label: "Border Default", category: "colour", defaultValue: "#e2e8f0", references: "--color-ink-200", themeKey: "borderDefault" },
+  { cssVar: "--color-border-subtle", label: "Border Subtle", category: "colour", defaultValue: "#f1f5f9", references: "--color-ink-100", themeKey: "borderSubtle" }
+];
 var SURFACE_TOKENS = [
   { cssVar: "--color-surface-page", label: "Page Background", category: "colour", defaultValue: "#f8fafc", references: "--color-ink-50", themeKey: "surfacePageColor" },
   { cssVar: "--color-surface-card", label: "Card Surface", category: "colour", defaultValue: "#ffffff", themeKey: "surfaceCardColor" },
@@ -853,6 +889,7 @@ var TOKEN_REGISTRY = [
   { label: "Accent Colours", tokens: ACCENT_PRIMITIVES },
   { label: "Sidebar", tokens: SIDEBAR_TOKENS },
   { label: "Semantic Colours", tokens: SEMANTIC_COLOURS },
+  { label: "Foundations (Text & Border)", tokens: FOUNDATION_TOKENS },
   { label: "Surface", tokens: SURFACE_TOKENS },
   { label: "Interactive", tokens: INTERACTIVE_TOKENS },
   { label: "Button", tokens: BUTTON_TOKENS },
@@ -2756,7 +2793,7 @@ function downloadAuditReport(report) {
 }
 
 // src/dom.ts
-function applyThemeToDOM(merged) {
+function applyThemeToDOM(merged, customTokens = []) {
   const root = document.documentElement;
   if (merged.primaryColor) {
     merged.primaryColor = ensureContrastOnWhite(merged.primaryColor);
@@ -2793,12 +2830,23 @@ function applyThemeToDOM(merged) {
   const accent = merged.accentColor || THEME_DEFAULTS.accentColor;
   root.style.setProperty("--color-accent-light", lighten(accent, 0.85));
   root.style.setProperty("--color-accent-hover", darken(accent, 0.15));
+  for (const token of customTokens) {
+    const value = merged[token.key] ?? token.defaultValue;
+    if (value) {
+      root.style.setProperty(token.cssVar, value);
+    } else {
+      root.style.removeProperty(token.cssVar);
+    }
+  }
 }
-function clearThemeFromDOM() {
+function clearThemeFromDOM(customTokens = []) {
   const root = document.documentElement;
   for (const cssVar of Object.values(THEME_KEY_TO_CSS)) {
     root.style.removeProperty(cssVar);
   }
+  for (const token of customTokens) {
+    root.style.removeProperty(token.cssVar);
+  }
   for (const v of [
     "--color-sidebar-border",
     "--color-sidebar-hover",
@@ -3164,6 +3212,7 @@ function calculateQualityScore2(overrides) {
   createOverlay,
   createReassignmentState,
   createThemeEditorState,
+  customTokenDefaults,
   darken,
   downloadAuditReport,
   downloadStyleGuide,

package/dist/index.d.cts

@@ -140,6 +140,27 @@ declare function suggestPalettes(primaryHex: string): ColourSuggestion[];
  * These are the canonical defaults for the design system package.
  */
 
+/**
+ * A host-defined theme token, declared by a consuming app so its own bespoke
+ * tokens flow through the SnagTag editor + DOM pipeline without forking the
+ * built-in maps. See docs/LAYER2-HOST-EXTENSIBLE-TOKENS-PROPOSAL.md.
+ */
+interface CustomTokenDef {
+    /** Theme key used in the persisted overrides map + editor state (e.g. 'statusWatching'). */
+    key: string;
+    /** CSS custom property written to :root (e.g. '--status-watching'). */
+    cssVar: string;
+    /** Default colour value, used until the user overrides it. */
+    defaultValue: string;
+    /** Editor category to group the swatch under. Defaults to 'Custom'. */
+    category?: string;
+    /** Optional human label (the colour editor otherwise derives one from `key`). */
+    label?: string;
+    /** Optional CSS var this token references, for inspector chain tracing. */
+    references?: string;
+}
+/** Build a { key: defaultValue } map from custom token definitions. */
+declare function customTokenDefaults(tokens?: CustomTokenDef[]): Record<string, string>;
 /**
  * The hardcoded defaults matching a standard design system theme.
  * These are the "factory" values used when no overrides are set.
@@ -803,13 +824,18 @@ declare function downloadAuditReport(report: AuditReport): void;
  * DOM utilities for applying and clearing theme values on the document root.
  * These functions set/remove CSS custom properties on document.documentElement.
  */
+
 /**
  * Apply a merged theme to the DOM by setting CSS custom properties on :root.
  * Derives sidebar states and accent variants automatically.
+ *
+ * Pass `customTokens` to also write host-defined tokens (each `cssVar` is set
+ * from `merged[key]`, falling back to the token's `defaultValue`). Omitting it
+ * leaves behaviour identical to before.
  */
-declare function applyThemeToDOM(merged: Record<string, string>): void;
+declare function applyThemeToDOM(merged: Record<string, string>, customTokens?: CustomTokenDef[]): void;
 /** Remove all theme overrides from :root, restoring CSS defaults. */
-declare function clearThemeFromDOM(): void;
+declare function clearThemeFromDOM(customTokens?: CustomTokenDef[]): void;
 
 /**
  * Contrast Fix Engine - scans colour token pairs for WCAG AA failures
@@ -881,4 +907,4 @@ interface QualityBreakdown {
  */
 declare function calculateQualityScore(overrides?: Record<string, string>): QualityBreakdown;
 
-export { type ConsistencyIssue$1 as AuditConsistencyIssue, type ContrastIssue$1 as AuditContrastIssue, type QualityBreakdown$1 as AuditQualityBreakdown, type AuditReport, BUILT_IN_PRESETS, COLOUR_BLINDNESS_TYPES, type ColourBlindnessInfo, type ColourBlindnessType, type ColourSuggestion, type ConsistencyIssue, type ContrastIssue$2 as ContrastIssue, type CustomPreset, DENSITY_CONFIGS, type DarkModeConfig, type DensityConfig, type DensityMode, type DesignSystemAdapter, type ThemePreset as DesignThemePreset, EASING_PRESETS, type EasingPreset, type ExtractedTokenDef, FONT_PAIRINGS, type FontPairing, type HSL, type HarmonyType, type QualityBreakdown$2 as QualityBreakdown, type ReassignmentAction, type ReassignmentState, type RegistryOverlay, SCALE_RATIOS, SURFACE_DEFINITIONS, type ScaleRatio, type SurfaceDefinition, type SurfaceType, THEME_CATEGORIES, THEME_DEFAULTS, THEME_KEY_TO_CSS, TOKEN_REGISTRY, type ThemeEditorState, type ThemeExport, type ThemeExportPayload, type ThemePreset$1 as ThemePreset, type ThemeSnapshot, type ThemeVersion, type TokenCategory, type TokenDefinition, type TokenUsageResult, type TypeScale, type TypeScaleLevel, type UnusedTokenResult, addCustomCategory, addExtractedToken, adjustSemanticForDark, applyAddCategory, applyBulkChange, applyBulkMove, applyChange, applyDarkModeToDOM, applyDensity, applyDensityToDOM, applyExtract, applyMove, applySurface, applySurfaceToDOM, applyThemeToDOM, auditReportToMarkdown, bulkMoveTokens, calculateQualityScore, captureSnapshot, checkConsistency, clampControlPoint, clearSnapshots, clearSurface, clearThemeFromDOM, clearUsageCache, contrastRatio, countTokenUsage, createOverlay, createReassignmentState, createThemeEditorState, darken, downloadAuditReport, downloadStyleGuide, downloadThemeAsJSON, downloadW3CTokens, ensureContrastOnWhite, exportTheme, exportToW3CFormat, extractToken, findContrastIssues, findPreset, findPresetByValue, findToken, findUnusedTokens, formatCubicBezier, generateAuditReport, generateDarkTheme, generateScale, generateStyleGuide, generateTypeScale, getActiveDensity, getActiveSurface, getAllCategoryLabels, getDensityCSS, getDependents, getEffectiveCategories, getOpeningSnapshot, getPresetsByCategory, getSnapshot, getSurfaceDefinition, getSurfaceOverrides, getTokenCategory, getTokenChain, getTokenUsageCount, getTokenUsageStats, hasExtractedToken, hexToHSL, hexToHsl, hslToHex$1 as hslToHex, hslToHex as hslToHexDark, invertLightness, isDark, isDarkMode, lighten, luminance, makePreset, markSaved, moveToken, parseCubicBezier, readSnapshots, readThemeFromFile, redo, redoReassignment, resetToDefaults, resolveMode, rotateHue, sampleBezierCurve, setDarkMode, simulateColourBlindness, simulateThemeColourBlindness, snapToGrid, suggestFix, suggestPairings, suggestPalettes, suggestTokenName, systemPrefersDark, themesAreEqual, typeScaleToCSSVars, undo, undoReassignment, validateImport, validateTokenName };
+export { type ConsistencyIssue$1 as AuditConsistencyIssue, type ContrastIssue$1 as AuditContrastIssue, type QualityBreakdown$1 as AuditQualityBreakdown, type AuditReport, BUILT_IN_PRESETS, COLOUR_BLINDNESS_TYPES, type ColourBlindnessInfo, type ColourBlindnessType, type ColourSuggestion, type ConsistencyIssue, type ContrastIssue$2 as ContrastIssue, type CustomPreset, type CustomTokenDef, DENSITY_CONFIGS, type DarkModeConfig, type DensityConfig, type DensityMode, type DesignSystemAdapter, type ThemePreset as DesignThemePreset, EASING_PRESETS, type EasingPreset, type ExtractedTokenDef, FONT_PAIRINGS, type FontPairing, type HSL, type HarmonyType, type QualityBreakdown$2 as QualityBreakdown, type ReassignmentAction, type ReassignmentState, type RegistryOverlay, SCALE_RATIOS, SURFACE_DEFINITIONS, type ScaleRatio, type SurfaceDefinition, type SurfaceType, THEME_CATEGORIES, THEME_DEFAULTS, THEME_KEY_TO_CSS, TOKEN_REGISTRY, type ThemeEditorState, type ThemeExport, type ThemeExportPayload, type ThemePreset$1 as ThemePreset, type ThemeSnapshot, type ThemeVersion, type TokenCategory, type TokenDefinition, type TokenUsageResult, type TypeScale, type TypeScaleLevel, type UnusedTokenResult, addCustomCategory, addExtractedToken, adjustSemanticForDark, applyAddCategory, applyBulkChange, applyBulkMove, applyChange, applyDarkModeToDOM, applyDensity, applyDensityToDOM, applyExtract, applyMove, applySurface, applySurfaceToDOM, applyThemeToDOM, auditReportToMarkdown, bulkMoveTokens, calculateQualityScore, captureSnapshot, checkConsistency, clampControlPoint, clearSnapshots, clearSurface, clearThemeFromDOM, clearUsageCache, contrastRatio, countTokenUsage, createOverlay, createReassignmentState, createThemeEditorState, customTokenDefaults, darken, downloadAuditReport, downloadStyleGuide, downloadThemeAsJSON, downloadW3CTokens, ensureContrastOnWhite, exportTheme, exportToW3CFormat, extractToken, findContrastIssues, findPreset, findPresetByValue, findToken, findUnusedTokens, formatCubicBezier, generateAuditReport, generateDarkTheme, generateScale, generateStyleGuide, generateTypeScale, getActiveDensity, getActiveSurface, getAllCategoryLabels, getDensityCSS, getDependents, getEffectiveCategories, getOpeningSnapshot, getPresetsByCategory, getSnapshot, getSurfaceDefinition, getSurfaceOverrides, getTokenCategory, getTokenChain, getTokenUsageCount, getTokenUsageStats, hasExtractedToken, hexToHSL, hexToHsl, hslToHex$1 as hslToHex, hslToHex as hslToHexDark, invertLightness, isDark, isDarkMode, lighten, luminance, makePreset, markSaved, moveToken, parseCubicBezier, readSnapshots, readThemeFromFile, redo, redoReassignment, resetToDefaults, resolveMode, rotateHue, sampleBezierCurve, setDarkMode, simulateColourBlindness, simulateThemeColourBlindness, snapToGrid, suggestFix, suggestPairings, suggestPalettes, suggestTokenName, systemPrefersDark, themesAreEqual, typeScaleToCSSVars, undo, undoReassignment, validateImport, validateTokenName };

package/dist/index.d.ts

@@ -140,6 +140,27 @@ declare function suggestPalettes(primaryHex: string): ColourSuggestion[];
  * These are the canonical defaults for the design system package.
  */
 
+/**
+ * A host-defined theme token, declared by a consuming app so its own bespoke
+ * tokens flow through the SnagTag editor + DOM pipeline without forking the
+ * built-in maps. See docs/LAYER2-HOST-EXTENSIBLE-TOKENS-PROPOSAL.md.
+ */
+interface CustomTokenDef {
+    /** Theme key used in the persisted overrides map + editor state (e.g. 'statusWatching'). */
+    key: string;
+    /** CSS custom property written to :root (e.g. '--status-watching'). */
+    cssVar: string;
+    /** Default colour value, used until the user overrides it. */
+    defaultValue: string;
+    /** Editor category to group the swatch under. Defaults to 'Custom'. */
+    category?: string;
+    /** Optional human label (the colour editor otherwise derives one from `key`). */
+    label?: string;
+    /** Optional CSS var this token references, for inspector chain tracing. */
+    references?: string;
+}
+/** Build a { key: defaultValue } map from custom token definitions. */
+declare function customTokenDefaults(tokens?: CustomTokenDef[]): Record<string, string>;
 /**
  * The hardcoded defaults matching a standard design system theme.
  * These are the "factory" values used when no overrides are set.
@@ -803,13 +824,18 @@ declare function downloadAuditReport(report: AuditReport): void;
  * DOM utilities for applying and clearing theme values on the document root.
  * These functions set/remove CSS custom properties on document.documentElement.
  */
+
 /**
  * Apply a merged theme to the DOM by setting CSS custom properties on :root.
  * Derives sidebar states and accent variants automatically.
+ *
+ * Pass `customTokens` to also write host-defined tokens (each `cssVar` is set
+ * from `merged[key]`, falling back to the token's `defaultValue`). Omitting it
+ * leaves behaviour identical to before.
  */
-declare function applyThemeToDOM(merged: Record<string, string>): void;
+declare function applyThemeToDOM(merged: Record<string, string>, customTokens?: CustomTokenDef[]): void;
 /** Remove all theme overrides from :root, restoring CSS defaults. */
-declare function clearThemeFromDOM(): void;
+declare function clearThemeFromDOM(customTokens?: CustomTokenDef[]): void;
 
 /**
  * Contrast Fix Engine - scans colour token pairs for WCAG AA failures
@@ -881,4 +907,4 @@ interface QualityBreakdown {
  */
 declare function calculateQualityScore(overrides?: Record<string, string>): QualityBreakdown;
 
-export { type ConsistencyIssue$1 as AuditConsistencyIssue, type ContrastIssue$1 as AuditContrastIssue, type QualityBreakdown$1 as AuditQualityBreakdown, type AuditReport, BUILT_IN_PRESETS, COLOUR_BLINDNESS_TYPES, type ColourBlindnessInfo, type ColourBlindnessType, type ColourSuggestion, type ConsistencyIssue, type ContrastIssue$2 as ContrastIssue, type CustomPreset, DENSITY_CONFIGS, type DarkModeConfig, type DensityConfig, type DensityMode, type DesignSystemAdapter, type ThemePreset as DesignThemePreset, EASING_PRESETS, type EasingPreset, type ExtractedTokenDef, FONT_PAIRINGS, type FontPairing, type HSL, type HarmonyType, type QualityBreakdown$2 as QualityBreakdown, type ReassignmentAction, type ReassignmentState, type RegistryOverlay, SCALE_RATIOS, SURFACE_DEFINITIONS, type ScaleRatio, type SurfaceDefinition, type SurfaceType, THEME_CATEGORIES, THEME_DEFAULTS, THEME_KEY_TO_CSS, TOKEN_REGISTRY, type ThemeEditorState, type ThemeExport, type ThemeExportPayload, type ThemePreset$1 as ThemePreset, type ThemeSnapshot, type ThemeVersion, type TokenCategory, type TokenDefinition, type TokenUsageResult, type TypeScale, type TypeScaleLevel, type UnusedTokenResult, addCustomCategory, addExtractedToken, adjustSemanticForDark, applyAddCategory, applyBulkChange, applyBulkMove, applyChange, applyDarkModeToDOM, applyDensity, applyDensityToDOM, applyExtract, applyMove, applySurface, applySurfaceToDOM, applyThemeToDOM, auditReportToMarkdown, bulkMoveTokens, calculateQualityScore, captureSnapshot, checkConsistency, clampControlPoint, clearSnapshots, clearSurface, clearThemeFromDOM, clearUsageCache, contrastRatio, countTokenUsage, createOverlay, createReassignmentState, createThemeEditorState, darken, downloadAuditReport, downloadStyleGuide, downloadThemeAsJSON, downloadW3CTokens, ensureContrastOnWhite, exportTheme, exportToW3CFormat, extractToken, findContrastIssues, findPreset, findPresetByValue, findToken, findUnusedTokens, formatCubicBezier, generateAuditReport, generateDarkTheme, generateScale, generateStyleGuide, generateTypeScale, getActiveDensity, getActiveSurface, getAllCategoryLabels, getDensityCSS, getDependents, getEffectiveCategories, getOpeningSnapshot, getPresetsByCategory, getSnapshot, getSurfaceDefinition, getSurfaceOverrides, getTokenCategory, getTokenChain, getTokenUsageCount, getTokenUsageStats, hasExtractedToken, hexToHSL, hexToHsl, hslToHex$1 as hslToHex, hslToHex as hslToHexDark, invertLightness, isDark, isDarkMode, lighten, luminance, makePreset, markSaved, moveToken, parseCubicBezier, readSnapshots, readThemeFromFile, redo, redoReassignment, resetToDefaults, resolveMode, rotateHue, sampleBezierCurve, setDarkMode, simulateColourBlindness, simulateThemeColourBlindness, snapToGrid, suggestFix, suggestPairings, suggestPalettes, suggestTokenName, systemPrefersDark, themesAreEqual, typeScaleToCSSVars, undo, undoReassignment, validateImport, validateTokenName };
+export { type ConsistencyIssue$1 as AuditConsistencyIssue, type ContrastIssue$1 as AuditContrastIssue, type QualityBreakdown$1 as AuditQualityBreakdown, type AuditReport, BUILT_IN_PRESETS, COLOUR_BLINDNESS_TYPES, type ColourBlindnessInfo, type ColourBlindnessType, type ColourSuggestion, type ConsistencyIssue, type ContrastIssue$2 as ContrastIssue, type CustomPreset, type CustomTokenDef, DENSITY_CONFIGS, type DarkModeConfig, type DensityConfig, type DensityMode, type DesignSystemAdapter, type ThemePreset as DesignThemePreset, EASING_PRESETS, type EasingPreset, type ExtractedTokenDef, FONT_PAIRINGS, type FontPairing, type HSL, type HarmonyType, type QualityBreakdown$2 as QualityBreakdown, type ReassignmentAction, type ReassignmentState, type RegistryOverlay, SCALE_RATIOS, SURFACE_DEFINITIONS, type ScaleRatio, type SurfaceDefinition, type SurfaceType, THEME_CATEGORIES, THEME_DEFAULTS, THEME_KEY_TO_CSS, TOKEN_REGISTRY, type ThemeEditorState, type ThemeExport, type ThemeExportPayload, type ThemePreset$1 as ThemePreset, type ThemeSnapshot, type ThemeVersion, type TokenCategory, type TokenDefinition, type TokenUsageResult, type TypeScale, type TypeScaleLevel, type UnusedTokenResult, addCustomCategory, addExtractedToken, adjustSemanticForDark, applyAddCategory, applyBulkChange, applyBulkMove, applyChange, applyDarkModeToDOM, applyDensity, applyDensityToDOM, applyExtract, applyMove, applySurface, applySurfaceToDOM, applyThemeToDOM, auditReportToMarkdown, bulkMoveTokens, calculateQualityScore, captureSnapshot, checkConsistency, clampControlPoint, clearSnapshots, clearSurface, clearThemeFromDOM, clearUsageCache, contrastRatio, countTokenUsage, createOverlay, createReassignmentState, createThemeEditorState, customTokenDefaults, darken, downloadAuditReport, downloadStyleGuide, downloadThemeAsJSON, downloadW3CTokens, ensureContrastOnWhite, exportTheme, exportToW3CFormat, extractToken, findContrastIssues, findPreset, findPresetByValue, findToken, findUnusedTokens, formatCubicBezier, generateAuditReport, generateDarkTheme, generateScale, generateStyleGuide, generateTypeScale, getActiveDensity, getActiveSurface, getAllCategoryLabels, getDensityCSS, getDependents, getEffectiveCategories, getOpeningSnapshot, getPresetsByCategory, getSnapshot, getSurfaceDefinition, getSurfaceOverrides, getTokenCategory, getTokenChain, getTokenUsageCount, getTokenUsageStats, hasExtractedToken, hexToHSL, hexToHsl, hslToHex$1 as hslToHex, hslToHex as hslToHexDark, invertLightness, isDark, isDarkMode, lighten, luminance, makePreset, markSaved, moveToken, parseCubicBezier, readSnapshots, readThemeFromFile, redo, redoReassignment, resetToDefaults, resolveMode, rotateHue, sampleBezierCurve, setDarkMode, simulateColourBlindness, simulateThemeColourBlindness, snapToGrid, suggestFix, suggestPairings, suggestPalettes, suggestTokenName, systemPrefersDark, themesAreEqual, typeScaleToCSSVars, undo, undoReassignment, validateImport, validateTokenName };

package/dist/index.js

@@ -189,6 +189,11 @@ function suggestPalettes(primaryHex) {
 }
 
 // src/theme-defaults.ts
+function customTokenDefaults(tokens = []) {
+  const out = {};
+  for (const t of tokens) out[t.key] = t.defaultValue;
+  return out;
+}
 var THEME_DEFAULTS = {
   // Primitives
   primaryColor: "#2563eb",
@@ -196,6 +201,17 @@ var THEME_DEFAULTS = {
   primaryLightColor: "#dbeafe",
   secondaryColor: "#64748b",
   accentColor: "#f59e0b",
+  // Foundations — global semantic text + border tokens.
+  // These are app-wide roles (not component-scoped) so host apps can map their
+  // own primary/secondary/muted text and default/subtle borders one-to-one.
+  // Defaults deliberately match the closest existing primitives so adopting
+  // them causes no visual shift (text-primary = ink-900, etc.).
+  textPrimary: "#0f172a",
+  textSecondary: "#64748b",
+  textMuted: "#94a3b8",
+  textInverse: "#ffffff",
+  borderDefault: "#e2e8f0",
+  borderSubtle: "#f1f5f9",
   // Sidebar
   sidebarBg: "#ffffff",
   sidebarText: "#475569",
@@ -280,6 +296,13 @@ var THEME_KEY_TO_CSS = {
   primaryLightColor: "--color-brand-100",
   secondaryColor: "--color-ink-500",
   accentColor: "--color-accent",
+  // Foundations — global semantic text + border tokens
+  textPrimary: "--color-text-primary",
+  textSecondary: "--color-text-secondary",
+  textMuted: "--color-text-muted",
+  textInverse: "--color-text-inverse",
+  borderDefault: "--color-border-default",
+  borderSubtle: "--color-border-subtle",
   // Sidebar
   sidebarBg: "--color-sidebar-bg",
   sidebarText: "--color-sidebar-text",
@@ -360,6 +383,10 @@ var THEME_CATEGORIES = [
     label: "Brand",
     keys: ["primaryColor", "primaryHoverColor", "primaryLightColor", "secondaryColor", "accentColor"]
   },
+  {
+    label: "Foundations",
+    keys: ["textPrimary", "textSecondary", "textMuted", "textInverse", "borderDefault", "borderSubtle"]
+  },
   {
     label: "Sidebar",
     keys: ["sidebarBg", "sidebarText", "sidebarActiveBg"]
@@ -581,6 +608,14 @@ var SEMANTIC_COLOURS = [
   { cssVar: "--color-info", label: "Info", category: "colour", defaultValue: "#3b82f6", themeKey: "infoColor" },
   { cssVar: "--color-info-light", label: "Info Light", category: "colour", defaultValue: "#dbeafe", themeKey: "infoLightColor" }
 ];
+var FOUNDATION_TOKENS = [
+  { cssVar: "--color-text-primary", label: "Text Primary", category: "colour", defaultValue: "#0f172a", references: "--color-ink-900", themeKey: "textPrimary" },
+  { cssVar: "--color-text-secondary", label: "Text Secondary", category: "colour", defaultValue: "#64748b", references: "--color-ink-500", themeKey: "textSecondary" },
+  { cssVar: "--color-text-muted", label: "Text Muted", category: "colour", defaultValue: "#94a3b8", references: "--color-ink-400", themeKey: "textMuted" },
+  { cssVar: "--color-text-inverse", label: "Text Inverse", category: "colour", defaultValue: "#ffffff", themeKey: "textInverse" },
+  { cssVar: "--color-border-default", label: "Border Default", category: "colour", defaultValue: "#e2e8f0", references: "--color-ink-200", themeKey: "borderDefault" },
+  { cssVar: "--color-border-subtle", label: "Border Subtle", category: "colour", defaultValue: "#f1f5f9", references: "--color-ink-100", themeKey: "borderSubtle" }
+];
 var SURFACE_TOKENS = [
   { cssVar: "--color-surface-page", label: "Page Background", category: "colour", defaultValue: "#f8fafc", references: "--color-ink-50", themeKey: "surfacePageColor" },
   { cssVar: "--color-surface-card", label: "Card Surface", category: "colour", defaultValue: "#ffffff", themeKey: "surfaceCardColor" },
@@ -715,6 +750,7 @@ var TOKEN_REGISTRY = [
   { label: "Accent Colours", tokens: ACCENT_PRIMITIVES },
   { label: "Sidebar", tokens: SIDEBAR_TOKENS },
   { label: "Semantic Colours", tokens: SEMANTIC_COLOURS },
+  { label: "Foundations (Text & Border)", tokens: FOUNDATION_TOKENS },
   { label: "Surface", tokens: SURFACE_TOKENS },
   { label: "Interactive", tokens: INTERACTIVE_TOKENS },
   { label: "Button", tokens: BUTTON_TOKENS },
@@ -2618,7 +2654,7 @@ function downloadAuditReport(report) {
 }
 
 // src/dom.ts
-function applyThemeToDOM(merged) {
+function applyThemeToDOM(merged, customTokens = []) {
   const root = document.documentElement;
   if (merged.primaryColor) {
     merged.primaryColor = ensureContrastOnWhite(merged.primaryColor);
@@ -2655,12 +2691,23 @@ function applyThemeToDOM(merged) {
   const accent = merged.accentColor || THEME_DEFAULTS.accentColor;
   root.style.setProperty("--color-accent-light", lighten(accent, 0.85));
   root.style.setProperty("--color-accent-hover", darken(accent, 0.15));
+  for (const token of customTokens) {
+    const value = merged[token.key] ?? token.defaultValue;
+    if (value) {
+      root.style.setProperty(token.cssVar, value);
+    } else {
+      root.style.removeProperty(token.cssVar);
+    }
+  }
 }
-function clearThemeFromDOM() {
+function clearThemeFromDOM(customTokens = []) {
   const root = document.documentElement;
   for (const cssVar of Object.values(THEME_KEY_TO_CSS)) {
     root.style.removeProperty(cssVar);
   }
+  for (const token of customTokens) {
+    root.style.removeProperty(token.cssVar);
+  }
   for (const v of [
     "--color-sidebar-border",
     "--color-sidebar-hover",
@@ -3025,6 +3072,7 @@ export {
   createOverlay,
   createReassignmentState,
   createThemeEditorState,
+  customTokenDefaults,
   darken,
   downloadAuditReport,
   downloadStyleGuide,

package/dist/manifest.json

@@ -1,8 +1,8 @@
 {
   "name": "@snagtag/design-system",
-  "version": "0.1.0",
-  "buildTimestamp": "2026-06-09T21:34:53.445Z",
-  "contentHash": "2effc038e3d2626a",
+  "version": "0.2.3",
+  "buildTimestamp": "2026-06-14T12:39:20.596Z",
+  "contentHash": "2a8368cc6251997e",
   "changes": [],
   "breaking": false,
   "siblings": {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snagtag/design-system",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",