tokka 0.2.1 → 0.2.3

package/compiler/generators/css.ts

@@ -0,0 +1,146 @@
+import { type ResolvedToken, type System } from "../types.js"
+
+export interface CSSGeneratorOptions {
+  modeSelector?: {
+    strategy: "class" | "data-attribute"
+    selectors?: {
+      light: string
+      dark: string
+      [key: string]: string
+    }
+  }
+}
+
+/**
+ * Convert token ID to CSS variable name
+ * surface.brand → --surface-brand
+ * button.primary.bg → --button-primary-bg
+ */
+export function tokenIdToCSSVar(id: string): string {
+  return `--${id.replace(/\./g, "-")}`
+}
+
+/**
+ * Parse color value to HSL triplet format
+ * Supports: hsl(...), oklch(...), hex, rgb(...)
+ */
+export function parseColorToHSLTriplet(value: string): string {
+  // If already a triplet (e.g., "220 90% 56%"), return as-is
+  if (/^\d+\s+\d+%\s+\d+%$/.test(value.trim())) {
+    return value.trim()
+  }
+
+  // If it's hsl(...), extract the triplet
+  const hslMatch = value.match(/hsl\(([^)]+)\)/)
+  if (hslMatch) {
+    return hslMatch[1].trim()
+  }
+
+  // If it's oklch(...), we'll need conversion (simplified for v1)
+  const oklchMatch = value.match(/oklch\(([^)]+)\)/)
+  if (oklchMatch) {
+    // For v1, just pass through - users should provide HSL
+    // In production, would convert OKLCH to HSL
+    return value
+  }
+
+  // For other formats, pass through as-is
+  return value
+}
+
+/**
+ * Generate CSS variables for a mode
+ */
+export function generateCSSForMode(
+  tokens: ResolvedToken[],
+  mode: string | "default",
+  options: CSSGeneratorOptions = {}
+): string {
+  const lines: string[] = []
+
+  const selector =
+    mode === "default"
+      ? ":root"
+      : options.modeSelector?.strategy === "data-attribute"
+        ? options.modeSelector.selectors?.[mode] || `[data-theme="${mode}"]`
+        : options.modeSelector?.selectors?.[mode] || `.${mode}`
+
+  lines.push(`${selector} {`)
+
+  for (const token of tokens) {
+    const cssVar = tokenIdToCSSVar(token.id)
+    let value: string | undefined
+
+    // Get value for this mode
+    if (mode === "default") {
+      value = token.resolvedValue || token.value
+    } else if (token.resolvedModes?.[mode]) {
+      value = token.resolvedModes[mode]
+    } else if (token.modes?.[mode]) {
+      value = token.modes[mode]
+    }
+
+    if (value === undefined) continue
+
+    // Convert colors to HSL triplet format
+    if (token.type === "color") {
+      const triplet = parseColorToHSLTriplet(String(value))
+      lines.push(`  ${cssVar}: ${triplet};`)
+    } else {
+      lines.push(`  ${cssVar}: ${value};`)
+    }
+  }
+
+  lines.push("}")
+
+  return lines.join("\n")
+}
+
+/**
+ * Generate complete CSS output
+ */
+export function generateCSS(
+  tokens: ResolvedToken[],
+  system: System,
+  options: CSSGeneratorOptions = {}
+): string {
+  const output: string[] = []
+
+  // Header comment
+  output.push("/**")
+  output.push(` * Design tokens for ${system.name}`)
+  output.push(" * Generated by figma-base - do not edit directly")
+  output.push(" */")
+  output.push("")
+
+  // Generate default (light) mode
+  const lightMode = system.modes.includes("light") ? "light" : system.modes[0]
+  output.push(generateCSSForMode(tokens, "default", options))
+
+  // Generate other modes
+  for (const mode of system.modes) {
+    if (mode !== lightMode) {
+      output.push("")
+      output.push(generateCSSForMode(tokens, mode, options))
+    }
+  }
+
+  return output.join("\n")
+}
+
+/**
+ * Generate CSS output files
+ */
+export interface CSSOutput {
+  "tokens.css": string
+}
+
+export function generateCSSOutput(
+  tokens: ResolvedToken[],
+  system: System,
+  options: CSSGeneratorOptions = {}
+): CSSOutput {
+  return {
+    "tokens.css": generateCSS(tokens, system, options),
+  }
+}

package/compiler/generators/figma.ts

@@ -0,0 +1,147 @@
+import { type ResolvedToken, type System } from "../types.js"
+
+/**
+ * Format a color value for Tokens Studio compatibility
+ * Converts Tailwind-style HSL (e.g., "220 90% 56%") to proper hsl() format
+ */
+function formatColorValue(value: string): string {
+  // Check if it's an HSL value without the hsl() wrapper (Tailwind format)
+  if (/^\d+\s+\d+%\s+\d+%$/.test(value.trim())) {
+    return `hsl(${value})`
+  }
+  // Return as-is for hex, rgb(), hsl(), or other formats
+  return value
+}
+
+/**
+ * Format a token value based on its type
+ */
+function formatTokenValue(token: ResolvedToken, value: string): string {
+  // Don't format references
+  if (value.startsWith("{") && value.endsWith("}")) {
+    return value
+  }
+  
+  // Format colors
+  if (token.type === "color") {
+    return formatColorValue(value)
+  }
+  
+  return value
+}
+
+/**
+ * Generate Tokens Studio compatible format
+ */
+export function generateFigmaTokens(
+  tokens: ResolvedToken[],
+  _system: System
+): Record<string, any> {
+  const output: Record<string, any> = {}
+
+  // Group tokens by source
+  const primitiveTokens = tokens.filter((t) => t.source === "primitive")
+  const semanticTokens = tokens.filter((t) => t.source === "semantic")
+  const componentTokens = tokens.filter((t) => t.source === "component")
+
+  // Build nested structure for primitives
+  const primitiveTree: Record<string, any> = {}
+  for (const token of primitiveTokens) {
+    const parts = token.id.split(".")
+    let current = primitiveTree
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (!current[parts[i]]) {
+        current[parts[i]] = {}
+      }
+      current = current[parts[i]]
+    }
+    const lastPart = parts[parts.length - 1]
+    const rawValue = token.resolvedValue || token.value
+    const formattedValue = formatTokenValue(token, rawValue)
+    
+    current[lastPart] = {
+      value: formattedValue,
+      type: token.type,
+      description: token.description,
+    }
+  }
+  output.global = primitiveTree
+
+  // Build nested structure for semantics
+  const semanticTree: Record<string, any> = {}
+  for (const token of semanticTokens) {
+    const parts = token.id.split(".")
+    let current = semanticTree
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (!current[parts[i]]) {
+        current[parts[i]] = {}
+      }
+      current = current[parts[i]]
+    }
+    const lastPart = parts[parts.length - 1]
+
+    // Use reference format if token has references
+    const rawValue =
+      token.references && token.references.length > 0
+        ? `{${token.references[0]}}`
+        : token.resolvedValue || token.value
+    
+    const formattedValue = formatTokenValue(token, rawValue)
+
+    current[lastPart] = {
+      value: formattedValue,
+      type: token.type,
+      description: token.description,
+    }
+  }
+  output.semantic = semanticTree
+
+  // Build component tokens if any
+  if (componentTokens.length > 0) {
+    const componentTree: Record<string, any> = {}
+    for (const token of componentTokens) {
+      const parts = token.id.split(".")
+      let current = componentTree
+      for (let i = 0; i < parts.length - 1; i++) {
+        if (!current[parts[i]]) {
+          current[parts[i]] = {}
+        }
+        current = current[parts[i]]
+      }
+      const lastPart = parts[parts.length - 1]
+
+      const rawValue =
+        token.references && token.references.length > 0
+          ? `{${token.references[0]}}`
+          : token.resolvedValue || token.value
+      
+      const formattedValue = formatTokenValue(token, rawValue)
+
+      current[lastPart] = {
+        value: formattedValue,
+        type: token.type,
+        description: token.description,
+      }
+    }
+    output.component = componentTree
+  }
+
+  return output
+}
+
+/**
+ * Generate Figma token export file
+ */
+export interface FigmaTokenOutput {
+  "tokka.tokens.json": string
+}
+
+export function generateFigmaTokenOutput(
+  tokens: ResolvedToken[],
+  system: System
+): FigmaTokenOutput {
+  const tokensObject = generateFigmaTokens(tokens, system)
+  return {
+    "tokka.tokens.json": JSON.stringify(tokensObject, null, 2),
+  }
+}

package/compiler/generators/tailwind.ts

@@ -0,0 +1,106 @@
+import { type ResolvedToken, type System } from "../types.js"
+import { tokenIdToCSSVar } from "./css.js"
+
+/**
+ * Semantic token mapping to Tailwind color names
+ * Maps semantic tokens to Tailwind's expected color scheme
+ */
+const SEMANTIC_TO_TAILWIND_MAPPING: Record<string, string> = {
+  "surface.brand": "primary",
+  "text.on-brand": "primary-foreground",
+  "surface.secondary": "secondary",
+  "text.on-secondary": "secondary-foreground",
+  "surface.destructive": "destructive",
+  "text.on-destructive": "destructive-foreground",
+  "surface.default": "background",
+  "text.default": "foreground",
+  "surface.card": "card",
+  "text.on-card": "card-foreground",
+  "surface.popover": "popover",
+  "text.on-popover": "popover-foreground",
+  "surface.muted": "muted",
+  "text.muted": "muted-foreground",
+  "surface.accent": "accent",
+  "text.on-accent": "accent-foreground",
+  "border.default": "border",
+  "border.input": "input",
+  "focus.ring": "ring",
+}
+
+/**
+ * Generate Tailwind config mapping semantic tokens to CSS vars
+ */
+export function generateTailwindConfig(
+  tokens: ResolvedToken[],
+  _system: System
+): Record<string, any> {
+  const colors: Record<string, string> = {}
+  const spacing: Record<string, string> = {}
+  const borderRadius: Record<string, string> = {}
+  const boxShadow: Record<string, string> = {}
+
+  for (const token of tokens) {
+    // Only map semantic tokens to Tailwind (not primitives)
+    if (token.source !== "semantic") continue
+
+    const cssVar = tokenIdToCSSVar(token.id)
+
+    // Map semantic tokens to Tailwind color names
+    if (token.type === "color") {
+      const tailwindName = SEMANTIC_TO_TAILWIND_MAPPING[token.id]
+      if (tailwindName) {
+        colors[tailwindName] = `hsl(var(${cssVar}))`
+      } else {
+        // Also include the semantic token by its own name
+        const name = token.id.replace(/\./g, "-")
+        colors[name] = `hsl(var(${cssVar}))`
+      }
+    }
+
+    // Map spacing tokens
+    if (token.type === "dimension" && token.id.startsWith("space.")) {
+      const name = token.id.replace("space.", "")
+      spacing[name] = `var(${cssVar})`
+    }
+
+    // Map radius tokens
+    if (token.type === "radius" && token.id.startsWith("radius.")) {
+      const name = token.id.replace("radius.", "")
+      borderRadius[name] = `var(${cssVar})`
+    }
+
+    // Map shadow tokens
+    if (token.type === "shadow" && token.id.startsWith("shadow.")) {
+      const name = token.id.replace("shadow.", "")
+      boxShadow[name] = `var(${cssVar})`
+    }
+  }
+
+  return {
+    theme: {
+      extend: {
+        colors,
+        spacing,
+        borderRadius,
+        boxShadow,
+      },
+    },
+  }
+}
+
+/**
+ * Generate Tailwind config file content
+ */
+export function generateTailwindOutput(
+  tokens: ResolvedToken[],
+  system: System
+): string {
+  const config = generateTailwindConfig(tokens, system)
+
+  return `/**
+ * Tailwind config for ${system.name}
+ * Generated by figma-base - do not edit directly
+ */
+export default ${JSON.stringify(config, null, 2)}
+`
+}

package/compiler/generators/typescript.ts

@@ -0,0 +1,113 @@
+import { type ResolvedToken, type System } from "../types.js"
+
+/**
+ * Generate TypeScript token map with full typing
+ */
+export function generateTypeScript(
+  tokens: ResolvedToken[],
+  system: System
+): string {
+  const lines: string[] = []
+
+  // Header
+  lines.push("/**")
+  lines.push(` * Token type definitions for ${system.name}`)
+  lines.push(" * Generated by figma-base - do not edit directly")
+  lines.push(" */")
+  lines.push("")
+
+  // Token type enum
+  lines.push("export type TokenType =")
+  lines.push('  | "color"')
+  lines.push('  | "number"')
+  lines.push('  | "dimension"')
+  lines.push('  | "radius"')
+  lines.push('  | "shadow"')
+  lines.push('  | "typography"')
+  lines.push('  | "motion"')
+  lines.push('  | "opacity"')
+  lines.push('  | "zIndex"')
+  lines.push("")
+
+  // Token source enum
+  lines.push("export type TokenSource = \"primitive\" | \"semantic\" | \"component\"")
+  lines.push("")
+
+  // Token interface
+  lines.push("export interface Token {")
+  lines.push("  id: string")
+  lines.push("  type: TokenType")
+  lines.push("  source: TokenSource")
+  lines.push("  description: string")
+  lines.push("  value?: string")
+  lines.push("  modes?: Record<string, string>")
+  lines.push("}")
+  lines.push("")
+
+  // All token IDs union type
+  lines.push("export type TokenId =")
+  tokens.forEach((token, index) => {
+    const isLast = index === tokens.length - 1
+    lines.push(`  | "${token.id}"${isLast ? "" : ""}`)
+  })
+  lines.push("")
+
+  // Token map object
+  lines.push("export const tokens: Record<TokenId, Token> = {")
+  for (const token of tokens) {
+    lines.push(`  "${token.id}": {`)
+    lines.push(`    id: "${token.id}",`)
+    lines.push(`    type: "${token.type}",`)
+    lines.push(`    source: "${token.source}",`)
+    lines.push(`    description: ${JSON.stringify(token.description)},`)
+
+    if (token.resolvedValue) {
+      lines.push(`    value: ${JSON.stringify(token.resolvedValue)},`)
+    }
+
+    if (token.resolvedModes && Object.keys(token.resolvedModes).length > 0) {
+      lines.push(`    modes: {`)
+      for (const [mode, value] of Object.entries(token.resolvedModes)) {
+        lines.push(`      "${mode}": ${JSON.stringify(value)},`)
+      }
+      lines.push(`    },`)
+    }
+
+    lines.push(`  },`)
+  }
+  lines.push("} as const")
+  lines.push("")
+
+  // Helper functions
+  lines.push("export function getToken(id: TokenId): Token | undefined {")
+  lines.push("  return tokens[id]")
+  lines.push("}")
+  lines.push("")
+
+  lines.push("export function getTokensByType(type: TokenType): Token[] {")
+  lines.push("  return Object.values(tokens).filter(t => t.type === type)")
+  lines.push("}")
+  lines.push("")
+
+  lines.push("export function getTokensBySource(source: TokenSource): Token[] {")
+  lines.push("  return Object.values(tokens).filter(t => t.source === source)")
+  lines.push("}")
+
+  return lines.join("\n")
+}
+
+/**
+ * Generate TypeScript output
+ */
+export interface TypeScriptOutput {
+  "tokens.ts": string
+}
+
+export function generateTypeScriptOutput(
+  tokens: ResolvedToken[],
+  system: System
+): TypeScriptOutput {
+  return {
+    "tokens.ts": generateTypeScript(tokens, system),
+  }
+}

package/compiler/index.ts

@@ -0,0 +1,45 @@
+export * from "./types.js"
+export * from "./loader.js"
+export * from "./validator.js"
+export * from "./resolver.js"
+export * from "./generators/css.js"
+export * from "./generators/tailwind.js"
+export * from "./generators/typescript.js"
+export * from "./generators/figma.js"
+
+import { loadTokens, loadSystem, type LoadOptions } from "./loader.js"
+import { validateTokens } from "./validator.js"
+import { buildDependencyGraph, resolveTokens } from "./resolver.js"
+import { type CompilationResult } from "./types.js"
+
+/**
+ * Main compilation function
+ */
+export async function compile(options: LoadOptions): Promise<CompilationResult> {
+  // Load tokens and system
+  const loadedTokens = await loadTokens(options)
+  const system = await loadSystem(options)
+
+  // Validate tokens
+  const validationErrors = validateTokens(loadedTokens.all, system.modes, {
+    strict: false, // Tier 0 default
+  })
+
+  if (validationErrors.length > 0) {
+    return {
+      tokens: [],
+      errors: validationErrors,
+      warnings: [],
+    }
+  }
+
+  // Build dependency graph and resolve
+  const graph = buildDependencyGraph(loadedTokens.all)
+  const { resolved, errors } = resolveTokens(loadedTokens.all, graph)
+
+  return {
+    tokens: resolved,
+    errors,
+    warnings: [],
+  }
+}

package/compiler/loader.ts

@@ -0,0 +1,92 @@
+import fs from "fs/promises"
+import path from "path"
+import { tokenFileSchema, systemSchema, type Token, type System } from "./types.js"
+
+export interface LoadOptions {
+  cwd: string
+  tokensDir?: string
+}
+
+export interface LoadedTokens {
+  primitives: Token[]
+  semantics: Token[]
+  components: Token[]
+  all: Token[]
+}
+
+/**
+ * Load token files from a project directory
+ */
+export async function loadTokens(options: LoadOptions): Promise<LoadedTokens> {
+  const tokensDir = options.tokensDir || path.join(options.cwd, "tokens")
+
+  // Load primitives (required)
+  const primitivesPath = path.join(tokensDir, "primitives.json")
+  const primitivesContent = await fs.readFile(primitivesPath, "utf-8")
+  const primitivesData = tokenFileSchema.parse(JSON.parse(primitivesContent))
+  const primitives = primitivesData.tokens
+
+  // Load semantics (required)
+  const semanticsPath = path.join(tokensDir, "semantics.json")
+  const semanticsContent = await fs.readFile(semanticsPath, "utf-8")
+  const semanticsData = tokenFileSchema.parse(JSON.parse(semanticsContent))
+  const semantics = semanticsData.tokens
+
+  // Load component tokens (optional - Tier 2)
+  const components: Token[] = []
+  const componentsDir = path.join(tokensDir, "components")
+  try {
+    const componentFiles = await fs.readdir(componentsDir)
+    for (const file of componentFiles) {
+      if (file.endsWith(".json")) {
+        const componentPath = path.join(componentsDir, file)
+        const componentContent = await fs.readFile(componentPath, "utf-8")
+        const componentData = tokenFileSchema.parse(JSON.parse(componentContent))
+        components.push(...componentData.tokens)
+      }
+    }
+  } catch (error) {
+    // Components directory is optional
+  }
+
+  return {
+    primitives,
+    semantics,
+    components,
+    all: [...primitives, ...semantics, ...components],
+  }
+}
+
+/**
+ * Load system metadata
+ */
+export async function loadSystem(options: LoadOptions): Promise<System> {
+  const systemPath = path.join(options.cwd, "system.json")
+  const systemContent = await fs.readFile(systemPath, "utf-8")
+  const system = systemSchema.parse(JSON.parse(systemContent))
+  return system
+}
+
+/**
+ * Check if tokens directory exists
+ */
+export async function hasTokens(cwd: string): Promise<boolean> {
+  try {
+    await fs.access(path.join(cwd, "tokens"))
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if system.json exists
+ */
+export async function hasSystem(cwd: string): Promise<boolean> {
+  try {
+    await fs.access(path.join(cwd, "system.json"))
+    return true
+  } catch {
+    return false
+  }
+}

package/compiler/resolver.ts

@@ -0,0 +1,177 @@
+import { type Token, type ResolvedToken, type CompilationError } from "./types.js"
+
+/**
+ * Build a dependency graph from token references
+ */
+export function buildDependencyGraph(tokens: Token[]): Map<string, Set<string>> {
+  const graph = new Map<string, Set<string>>()
+
+  // Initialize nodes
+  for (const token of tokens) {
+    graph.set(token.id, new Set())
+  }
+
+  // Add edges
+  for (const token of tokens) {
+    if (token.references) {
+      const deps = graph.get(token.id)!
+      for (const ref of token.references) {
+        deps.add(ref)
+      }
+    }
+  }
+
+  return graph
+}
+
+/**
+ * Detect cycles in the dependency graph
+ */
+export function detectCycles(graph: Map<string, Set<string>>): string[][] {
+  const cycles: string[][] = []
+  const visited = new Set<string>()
+  const recursionStack = new Set<string>()
+
+  function dfs(node: string, path: string[]): boolean {
+    visited.add(node)
+    recursionStack.add(node)
+    path.push(node)
+
+    const neighbors = graph.get(node) || new Set()
+    for (const neighbor of neighbors) {
+      if (!visited.has(neighbor)) {
+        if (dfs(neighbor, path)) {
+          return true
+        }
+      } else if (recursionStack.has(neighbor)) {
+        // Found a cycle
+        const cycleStart = path.indexOf(neighbor)
+        cycles.push([...path.slice(cycleStart), neighbor])
+        return true
+      }
+    }
+
+    recursionStack.delete(node)
+    path.pop()
+    return false
+  }
+
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) {
+      dfs(node, [])
+    }
+  }
+
+  return cycles
+}
+
+/**
+ * Topological sort of tokens by dependencies
+ */
+export function topologicalSort(
+  tokens: Token[],
+  graph: Map<string, Set<string>>
+): Token[] {
+  const sorted: Token[] = []
+  const visited = new Set<string>()
+  const tokenMap = new Map(tokens.map((t) => [t.id, t]))
+
+  function visit(tokenId: string) {
+    if (visited.has(tokenId)) return
+
+    visited.add(tokenId)
+    const deps = graph.get(tokenId) || new Set()
+    for (const dep of deps) {
+      visit(dep)
+    }
+
+    const token = tokenMap.get(tokenId)
+    if (token) {
+      sorted.push(token)
+    }
+  }
+
+  for (const token of tokens) {
+    visit(token.id)
+  }
+
+  return sorted
+}
+
+/**
+ * Resolve token values (alias-only in v1)
+ */
+export function resolveTokens(
+  tokens: Token[],
+  graph: Map<string, Set<string>>
+): { resolved: ResolvedToken[]; errors: CompilationError[] } {
+  const errors: CompilationError[] = []
+
+  // Check for cycles first
+  const cycles = detectCycles(graph)
+  if (cycles.length > 0) {
+    for (const cycle of cycles) {
+      errors.push({
+        type: "cycle",
+        message: `Circular reference detected: ${cycle.join(" → ")}`,
+        tokenId: cycle[0],
+      })
+    }
+    return { resolved: [], errors }
+  }
+
+  // Sort topologically
+  const sorted = topologicalSort(tokens, graph)
+  const resolvedMap = new Map<string, ResolvedToken>()
+
+  // Resolve in dependency order
+  for (const token of sorted) {
+    const resolved: ResolvedToken = { ...token }
+
+    // Resolve direct value
+    if (token.value !== undefined) {
+      resolved.resolvedValue = resolveValue(token.value, resolvedMap)
+    }
+
+    // Resolve modes
+    if (token.modes) {
+      resolved.resolvedModes = {}
+      for (const [mode, value] of Object.entries(token.modes)) {
+        resolved.resolvedModes[mode] = resolveValue(value, resolvedMap)
+      }
+    }
+
+    resolvedMap.set(token.id, resolved)
+  }
+
+  return { resolved: Array.from(resolvedMap.values()), errors }
+}
+
+/**
+ * Resolve a single value (supports alias references)
+ */
+function resolveValue(
+  value: any,
+  resolvedMap: Map<string, ResolvedToken>
+): string {
+  if (typeof value !== "string") {
+    return String(value)
+  }
+
+  // Check if it's a reference to another token
+  // References start with a token ID (no special syntax needed in v1)
+  // If value starts with "var(--", it's a CSS var reference
+  if (value.startsWith("var(--")) {
+    // Extract token ID from CSS var
+    const match = value.match(/var\(--([a-z][a-z0-9-]*)\)/)
+    if (match) {
+      const tokenId = match[1].replace(/-/g, ".")
+      const refToken = resolvedMap.get(tokenId)
+      if (refToken?.resolvedValue) {
+        return refToken.resolvedValue
+      }
+    }
+  }
+
+  return value
+}

package/compiler/types.ts

@@ -0,0 +1,118 @@
+import { z } from "zod"
+
+// Token type
+export const tokenTypeSchema = z.enum([
+  "color",
+  "number",
+  "dimension",
+  "radius",
+  "shadow",
+  "typography",
+  "motion",
+  "opacity",
+  "zIndex",
+])
+
+export const tokenSourceSchema = z.enum(["primitive", "semantic", "component"])
+
+export const tokenSchema = z
+  .object({
+    id: z
+      .string()
+      .regex(
+        /^[a-z][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*$/,
+        "Token ID must be lowercase, dot-separated"
+      ),
+    type: tokenTypeSchema,
+    description: z.string(),
+    source: tokenSourceSchema,
+    value: z.any().optional(),
+    modes: z.record(z.string(), z.any()).optional(),
+    references: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+    deprecated: z.boolean().optional(),
+    replacedBy: z.string().optional(),
+    figma: z
+      .object({
+        collection: z.string().optional(),
+        scopes: z.array(z.string()).optional(),
+        variableName: z.string().optional(),
+      })
+      .optional(),
+  })
+  .refine((data) => data.value !== undefined || data.modes !== undefined, {
+    message: "Token must have either value or modes",
+  })
+
+export type Token = z.infer<typeof tokenSchema>
+export type TokenType = z.infer<typeof tokenTypeSchema>
+export type TokenSource = z.infer<typeof tokenSourceSchema>
+
+// Token file structure
+export const tokenFileSchema = z.object({
+  tokens: z.array(tokenSchema),
+})
+
+export type TokenFile = z.infer<typeof tokenFileSchema>
+
+// System metadata
+export const systemSchema = z.object({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/, "System ID must be lowercase kebab-case"),
+  name: z.string(),
+  description: z.string(),
+  tags: z.array(z.string()).optional(),
+  modes: z.array(z.string()).min(1),
+  policies: z
+    .object({
+      radius: z.enum(["sharp", "rounded", "pill"]).optional(),
+      density: z.enum(["compact", "comfortable", "spacious"]).optional(),
+      contrast: z.enum(["low", "medium", "high"]).optional(),
+      motion: z.enum(["none", "subtle", "expressive"]).optional(),
+    })
+    .optional(),
+  defaults: z
+    .object({
+      font: z.string().optional(),
+      iconStyle: z.string().optional(),
+    })
+    .optional(),
+  figma: z
+    .object({
+      collections: z.array(z.string()).optional(),
+    })
+    .optional(),
+})
+
+export type System = z.infer<typeof systemSchema>
+
+// Resolved token (after compilation)
+export interface ResolvedToken extends Token {
+  resolvedValue?: string
+  resolvedModes?: Record<string, string>
+}
+
+// Compilation context
+export interface CompilationContext {
+  tokens: Token[]
+  system: System
+  mode: "tier0" | "tier1" | "tier2"
+}
+
+// Compilation result
+export interface CompilationResult {
+  tokens: ResolvedToken[]
+  errors: CompilationError[]
+  warnings: CompilationWarning[]
+}
+
+export interface CompilationError {
+  type: "schema" | "reference" | "cycle" | "naming" | "layering"
+  message: string
+  tokenId?: string
+}
+
+export interface CompilationWarning {
+  type: "unused" | "deprecated" | "missing-mode"
+  message: string
+  tokenId?: string
+}

package/compiler/validator.ts

@@ -0,0 +1,194 @@
+import { type Token, type CompilationError } from "./types.js"
+
+// Semantic token category prefixes
+const SEMANTIC_PREFIXES = [
+  "surface.",
+  "text.",
+  "border.",
+  "icon.",
+  "shadow.",
+  "focus.",
+  "overlay.",
+  "motion.",
+  "space.",
+  "radius.",
+  "typography.",
+]
+
+/**
+ * Validate token naming conventions
+ */
+export function validateTokenNaming(tokens: Token[]): CompilationError[] {
+  const errors: CompilationError[] = []
+
+  for (const token of tokens) {
+    // Validate semantic token prefixes
+    if (token.source === "semantic") {
+      const hasValidPrefix = SEMANTIC_PREFIXES.some((prefix) =>
+        token.id.startsWith(prefix)
+      )
+      if (!hasValidPrefix) {
+        errors.push({
+          type: "naming",
+          message: `Semantic token "${token.id}" must start with one of: ${SEMANTIC_PREFIXES.join(", ")}`,
+          tokenId: token.id,
+        })
+      }
+    }
+
+    // Validate component token prefixes (must be component name + dot)
+    if (token.source === "component") {
+      const parts = token.id.split(".")
+      if (parts.length < 2) {
+        errors.push({
+          type: "naming",
+          message: `Component token "${token.id}" must follow format: <component>.<property>`,
+          tokenId: token.id,
+        })
+      }
+    }
+  }
+
+  return errors
+}
+
+/**
+ * Validate token uniqueness
+ */
+export function validateTokenUniqueness(tokens: Token[]): CompilationError[] {
+  const errors: CompilationError[] = []
+  const seen = new Map<string, Token>()
+
+  for (const token of tokens) {
+    if (seen.has(token.id)) {
+      errors.push({
+        type: "schema",
+        message: `Duplicate token ID: "${token.id}"`,
+        tokenId: token.id,
+      })
+    }
+    seen.set(token.id, token)
+  }
+
+  return errors
+}
+
+/**
+ * Validate token references exist
+ */
+export function validateTokenReferences(tokens: Token[]): CompilationError[] {
+  const errors: CompilationError[] = []
+  const tokenIds = new Set(tokens.map((t) => t.id))
+
+  for (const token of tokens) {
+    if (token.references) {
+      for (const ref of token.references) {
+        if (!tokenIds.has(ref)) {
+          errors.push({
+            type: "reference",
+            message: `Token "${token.id}" references non-existent token "${ref}"`,
+            tokenId: token.id,
+          })
+        }
+      }
+    }
+  }
+
+  return errors
+}
+
+/**
+ * Validate token layering rules (Tier 2 only)
+ */
+export function validateTokenLayering(
+  tokens: Token[],
+  strict: boolean = false
+): CompilationError[] {
+  if (!strict) return []
+
+  const errors: CompilationError[] = []
+  const tokenMap = new Map(tokens.map((t) => [t.id, t]))
+
+  for (const token of tokens) {
+    if (!token.references || token.references.length === 0) continue
+
+    // Primitives may not reference anything
+    if (token.source === "primitive") {
+      errors.push({
+        type: "layering",
+        message: `Primitive token "${token.id}" may not reference other tokens`,
+        tokenId: token.id,
+      })
+    }
+
+    // Semantics may reference primitives and other semantics
+    if (token.source === "semantic") {
+      for (const ref of token.references) {
+        const refToken = tokenMap.get(ref)
+        if (refToken && refToken.source === "component") {
+          errors.push({
+            type: "layering",
+            message: `Semantic token "${token.id}" may not reference component token "${ref}"`,
+            tokenId: token.id,
+          })
+        }
+      }
+    }
+
+    // Component tokens may reference semantics and primitives
+    if (token.source === "component") {
+      for (const ref of token.references) {
+        const refToken = tokenMap.get(ref)
+        if (refToken && refToken.source === "component") {
+          // Allow component-to-component references but warn
+          // (could be useful for variants)
+        }
+      }
+    }
+  }
+
+  return errors
+}
+
+/**
+ * Validate mode coverage
+ */
+export function validateModeCoverage(
+  tokens: Token[],
+  requiredModes: string[]
+): CompilationError[] {
+  const errors: CompilationError[] = []
+
+  for (const token of tokens) {
+    if (token.modes) {
+      const tokenModes = Object.keys(token.modes)
+      const missingModes = requiredModes.filter((m) => !tokenModes.includes(m))
+      if (missingModes.length > 0) {
+        errors.push({
+          type: "schema",
+          message: `Token "${token.id}" missing required modes: ${missingModes.join(", ")}`,
+          tokenId: token.id,
+        })
+      }
+    }
+  }
+
+  return errors
+}
+
+/**
+ * Run all validations
+ */
+export function validateTokens(
+  tokens: Token[],
+  requiredModes: string[],
+  options: { strict?: boolean } = {}
+): CompilationError[] {
+  return [
+    ...validateTokenUniqueness(tokens),
+    ...validateTokenNaming(tokens),
+    ...validateTokenReferences(tokens),
+    ...validateModeCoverage(tokens, requiredModes),
+    ...validateTokenLayering(tokens, options.strict),
+  ]
+}

package/dist/index.js

@@ -57,9 +57,9 @@ Setting up ${selectedSystem.name}...
   }
   spinner.start("Building tokens...");
   try {
-    const compilerPath = path.join(__dirname, "../../compiler/dist/index.js");
-    const { compile: compile3, generateCSSOutput: generateCSSOutput2, generateTailwindOutput: generateTailwindOutput2, generateTypeScriptOutput: generateTypeScriptOutput2 } = await import(compilerPath);
-    const result = await compile3({ cwd });
+    const compilerPath = path.join(__dirname, "../compiler/index.js");
+    const { compile, generateCSSOutput, generateTailwindOutput, generateTypeScriptOutput } = await import(compilerPath);
+    const result = await compile({ cwd });
     if (result.errors.length > 0) {
       spinner.fail("Build failed");
       for (const error of result.errors) {
@@ -71,9 +71,9 @@ Setting up ${selectedSystem.name}...
     await fs.ensureDir(path.join(cwd, "dist/tailwind"));
     await fs.ensureDir(path.join(cwd, "dist/ts"));
     const systemData = await fs.readJSON(path.join(cwd, "system.json"));
-    const cssOutput = generateCSSOutput2(result.tokens, systemData);
-    const tailwindOutput = generateTailwindOutput2(result.tokens, systemData);
-    const tsOutput = generateTypeScriptOutput2(result.tokens, systemData);
+    const cssOutput = generateCSSOutput(result.tokens, systemData);
+    const tailwindOutput = generateTailwindOutput(result.tokens, systemData);
+    const tsOutput = generateTypeScriptOutput(result.tokens, systemData);
     await fs.writeFile(path.join(cwd, "dist/css/tokens.css"), cssOutput["tokens.css"]);
     await fs.writeFile(
       path.join(cwd, "dist/tailwind/tokens.tailwind.js"),
@@ -219,13 +219,17 @@ async function addCommand(components) {
 // src/commands/build.ts
 import fs3 from "fs-extra";
 import path3 from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
 import ora3 from "ora";
 import kleur3 from "kleur";
-import { compile, generateCSSOutput, generateTailwindOutput, generateTypeScriptOutput } from "@tokka/compiler";
+var __filename3 = fileURLToPath3(import.meta.url);
+var __dirname3 = path3.dirname(__filename3);
 async function buildCommand(options) {
   const cwd = process.cwd();
   const spinner = ora3("Building tokens...").start();
   try {
+    const compilerPath = path3.join(__dirname3, "../compiler/index.js");
+    const { compile, generateCSSOutput, generateTailwindOutput, generateTypeScriptOutput } = await import(compilerPath);
     const result = await compile({ cwd });
     if (result.errors.length > 0) {
       spinner.fail("Build failed");
@@ -270,7 +274,10 @@ async function buildCommand(options) {
 // src/commands/validate.ts
 import fs4 from "fs-extra";
 import path4 from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
 import kleur4 from "kleur";
+var __filename4 = fileURLToPath4(import.meta.url);
+var __dirname4 = path4.dirname(__filename4);
 async function validateCommand() {
   const cwd = process.cwd();
   const configPath = path4.join(cwd, ".figmabase");
@@ -284,7 +291,8 @@ async function validateCommand() {
     process.exit(1);
   }
   console.log(kleur4.cyan("\n\u{1F50D} Validating tokens and manifests...\n"));
-  const { compile: compile3, validateTokens, loadTokens, loadSystem } = await import("@tokka/compiler");
+  const compilerPath = path4.join(__dirname4, "../compiler/index.js");
+  const { compile, validateTokens, loadTokens, loadSystem } = await import(compilerPath);
   try {
     const tokens = await loadTokens({ cwd });
     const system = await loadSystem({ cwd });
@@ -309,9 +317,11 @@ async function validateCommand() {
 // src/commands/export.ts
 import fs5 from "fs-extra";
 import path5 from "path";
+import { fileURLToPath as fileURLToPath5 } from "url";
 import ora4 from "ora";
 import kleur5 from "kleur";
-import { compile as compile2, generateFigmaTokenOutput } from "@tokka/compiler";
+var __filename5 = fileURLToPath5(import.meta.url);
+var __dirname5 = path5.dirname(__filename5);
 async function exportCommand(target, options) {
   if (target !== "figma") {
     console.error(kleur5.red(`\u2716 Unknown export target: ${target}`));
@@ -320,7 +330,9 @@ async function exportCommand(target, options) {
   const cwd = process.cwd();
   const spinner = ora4("Exporting Figma artifacts...").start();
   try {
-    const result = await compile2({ cwd });
+    const compilerPath = path5.join(__dirname5, "../compiler/index.js");
+    const { compile, generateFigmaTokenOutput } = await import(compilerPath);
+    const result = await compile({ cwd });
     if (result.errors.length > 0) {
       spinner.fail("Export failed");
       for (const error of result.errors) {
@@ -351,10 +363,10 @@ async function exportCommand(target, options) {
 // src/commands/list.ts
 import fs6 from "fs-extra";
 import path6 from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { fileURLToPath as fileURLToPath6 } from "url";
 import kleur6 from "kleur";
-var __filename3 = fileURLToPath3(import.meta.url);
-var __dirname3 = path6.dirname(__filename3);
+var __filename6 = fileURLToPath6(import.meta.url);
+var __dirname6 = path6.dirname(__filename6);
 async function listCommand(type, options) {
   if (type === "systems") {
     await listSystems(options.json);
@@ -366,7 +378,7 @@ async function listCommand(type, options) {
   }
 }
 async function listSystems(json) {
-  const systemsDir = path6.join(__dirname3, "../../systems");
+  const systemsDir = path6.join(__dirname6, "../../systems");
   const systems = await loadSystemsMetadata(systemsDir);
   if (json) {
     console.log(JSON.stringify(systems, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokka",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "A shadcn-compatible UI foundation with a real token system and optional Figma exports",
   "bin": "./dist/index.js",
@@ -13,7 +13,8 @@
   "files": [
     "dist",
     "systems",
-    "components"
+    "components",
+    "compiler"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
@@ -22,7 +23,6 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@tokka/compiler": "workspace:*",
     "commander": "^11.1.0",
     "prompts": "^2.4.2",
     "kleur": "^4.1.5",