tokka 0.2.0 → 0.2.2

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
+  }
+}