@fragments-sdk/cli 0.2.2

package/src/core/token-types.ts

@@ -0,0 +1,287 @@
+/**
+ * Design Token Types for Fragments
+ *
+ * These types define the structure for CSS custom property (CSS variable) discovery,
+ * parsing, and reverse lookup capabilities. The token system enables:
+ *
+ * 1. Automatic discovery of design tokens from CSS/SCSS files
+ * 2. Reverse lookup: given a computed value, find which token(s) produce it
+ * 3. Detection of hardcoded values vs token usage
+ * 4. AI-friendly fix suggestions
+ */
+
+/**
+ * Token categories for grouping and filtering
+ */
+export type TokenCategory =
+  | "color"
+  | "spacing"
+  | "typography"
+  | "radius"
+  | "shadow"
+  | "sizing"
+  | "border"
+  | "animation"
+  | "z-index"
+  | "other";
+
+/**
+ * A single design token (CSS custom property)
+ */
+export interface DesignToken {
+  /** Token name with leading dashes (e.g., "--color-primary") */
+  name: string;
+
+  /** Raw value as written in CSS (e.g., "var(--color-cobalt-50)") */
+  rawValue: string;
+
+  /** Fully resolved value (e.g., "#0051c2") */
+  resolvedValue: string;
+
+  /** Inferred category based on naming convention */
+  category: TokenCategory;
+
+  /**
+   * Token level in the design system hierarchy:
+   * - 1 = Base/primitive tokens (raw values like colors, sizes)
+   * - 2 = Semantic tokens (references to base tokens with meaning)
+   * - 3 = Component tokens (component-specific tokens)
+   */
+  level: 1 | 2 | 3;
+
+  /**
+   * Reference chain showing how the value was resolved
+   * e.g., ["--color-primary", "--color-cobalt-50"] means
+   * --color-primary references --color-cobalt-50
+   */
+  referenceChain: string[];
+
+  /** Source file where this token was defined */
+  sourceFile: string;
+
+  /** Line number in source file */
+  lineNumber?: number;
+
+  /** Theme this token belongs to (e.g., "default", "dark", "light") */
+  theme: string;
+
+  /** CSS selector where this token is defined (e.g., ":root", "[data-theme='dark']") */
+  selector: string;
+
+  /** Optional description from comments */
+  description?: string;
+}
+
+/**
+ * Token registry for fast lookups
+ */
+export interface TokenRegistry {
+  /** Lookup by token name (e.g., "--color-primary") */
+  byName: Map<string, DesignToken>;
+
+  /**
+   * REVERSE lookup: resolved value -> token names
+   * Key is normalized value (e.g., "#0051c2" lowercase)
+   * Value is array of token names that resolve to this value
+   */
+  byValue: Map<string, string[]>;
+
+  /** Tokens grouped by theme */
+  byTheme: Map<string, DesignToken[]>;
+
+  /** Tokens grouped by category */
+  byCategory: Map<TokenCategory, DesignToken[]>;
+
+  /** Registry metadata */
+  meta: TokenRegistryMeta;
+}
+
+/**
+ * Token registry metadata
+ */
+export interface TokenRegistryMeta {
+  /** When tokens were discovered */
+  discoveredAt: Date;
+
+  /** Source files that were parsed */
+  sourceFiles: string[];
+
+  /** Total number of tokens discovered */
+  totalTokens: number;
+
+  /** Time taken to parse (ms) */
+  parseTimeMs: number;
+
+  /** Number of circular references detected */
+  circularRefs: number;
+
+  /** Number of unresolved references */
+  unresolvedRefs: number;
+}
+
+/**
+ * Enhanced style diff item with token information
+ */
+export interface EnhancedStyleDiffItem {
+  /** CSS property name (e.g., "backgroundColor") */
+  property: string;
+
+  /** Value from Figma design */
+  figma: string;
+
+  /** Value from rendered component */
+  rendered: string;
+
+  /** Whether values match (within tolerance) */
+  match: boolean;
+
+  /** Token name if Figma value matches a known token */
+  figmaToken?: string;
+
+  /** Token name if rendered value uses a token */
+  renderedToken?: string;
+
+  /**
+   * True if rendered value doesn't use a token but should
+   * (i.e., Figma uses a token but code uses hardcoded value)
+   */
+  isHardcoded: boolean;
+
+  /** Suggested fix if hardcoded */
+  suggestedFix?: TokenFix;
+}
+
+/**
+ * Token-based fix suggestion
+ */
+export interface TokenFix {
+  /** Token name to use (e.g., "--color-primary") */
+  tokenName: string;
+
+  /** Token's resolved value */
+  tokenValue: string;
+
+  /** Code snippet to fix the issue */
+  codeFix: string;
+
+  /** Confidence score 0-1 */
+  confidence: number;
+
+  /** Human-readable explanation */
+  reason: string;
+}
+
+/**
+ * Configuration for token discovery
+ */
+export interface TokenConfig {
+  /**
+   * Glob patterns for files to scan for tokens
+   * e.g., ["src/styles/theme.scss", "src/styles/variables.css"]
+   */
+  include: string[];
+
+  /**
+   * Glob patterns to exclude
+   * @example ["node_modules"]
+   */
+  exclude?: string[];
+
+  /**
+   * Map CSS selectors to theme names
+   * @example { ":root": "default", "[data-theme='dark']": "dark" }
+   */
+  themeSelectors?: Record<string, string>;
+
+  /** Enable token comparison in style diffs (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Result of parsing a CSS/SCSS file for tokens
+ */
+export interface TokenParseResult {
+  /** Tokens discovered in the file */
+  tokens: DesignToken[];
+
+  /** Errors encountered during parsing */
+  errors: TokenParseError[];
+
+  /** Warnings (non-fatal issues) */
+  warnings: string[];
+
+  /** Parse time in ms */
+  parseTimeMs: number;
+}
+
+/**
+ * Error during token parsing
+ */
+export interface TokenParseError {
+  /** Error message */
+  message: string;
+
+  /** File where error occurred */
+  file: string;
+
+  /** Line number if known */
+  line?: number;
+
+  /** The problematic content if available */
+  content?: string;
+}
+
+/**
+ * Request to match a value to tokens
+ */
+export interface TokenMatchRequest {
+  /** The value to find tokens for (e.g., "#0051c2") */
+  value: string;
+
+  /** Property type hint for better matching (e.g., "color") */
+  propertyType?: "color" | "spacing" | "typography" | "other";
+
+  /** Specific theme to search in */
+  theme?: string;
+}
+
+/**
+ * Result of token matching
+ */
+export interface TokenMatchResult {
+  /** Exact matches (same resolved value) */
+  exactMatches: DesignToken[];
+
+  /** Close matches (similar value, useful for colors) */
+  closeMatches: Array<{
+    token: DesignToken;
+    /** How close the match is (0-1, 1 = exact) */
+    similarity: number;
+  }>;
+
+  /** Whether any match was found */
+  found: boolean;
+}
+
+/**
+ * Summary of token usage in a component
+ */
+export interface TokenUsageSummary {
+  /** Total CSS properties checked */
+  totalProperties: number;
+
+  /** Properties using design tokens */
+  usingTokens: number;
+
+  /** Properties with hardcoded values */
+  hardcoded: number;
+
+  /** Properties matching but not using tokens explicitly */
+  implicitMatches: number;
+
+  /** Compliance percentage (usingTokens / totalProperties * 100) */
+  compliancePercent: number;
+
+  /** List of hardcoded properties with fix suggestions */
+  hardcodedProperties: EnhancedStyleDiffItem[];
+}