Sassy — Feature Inventory

Authoring Formats

• YAML Input — Write themes in clean, human-readable YAML

Variable System

• Palette Layer — Define raw colour values in an isolated, self-contained palette scope
• Vars Layer — Build semantic meaning on top of palette with a dedicated variable layer
• Nested Variables — Define deeply nested variable hierarchies with dot-path addressing
• Three Reference Syntaxes — $(var), $var, ${var} — pick the style that fits the context
• Palette Aliases — $$name shorthand auto-expands to $(palette.name) for concise palette references
• Cross-Layer References — Variables can reference other variables, palette entries, and theme values
• Recursive Resolution — Multi-pass evaluation engine resolves chained variable references automatically
• Circular Dependency Detection — Catches self-referential or looping variable chains before they hang

Colour Functions

• lighten / darken — Perceptually uniform brightness adjustments via OKLCH
• mix — Blend two colours at any ratio with OKLCH interpolation
• alpha — Set exact transparency on any colour
• fade / solidify — Relative opacity adjustments — reduce or increase alpha proportionally
• invert — Flip lightness while preserving hue and saturation
• saturate / desaturate — Adjust chroma intensity in OKLCH space
• mute / pop — Semantic aliases for desaturation and saturation
• tint / shade — Mix toward white or black by a given percentage
• shiftHue — Rotate hue by arbitrary degrees
• complement — 180° hue shift in one call
• grayscale — Strip all chroma for a perceptually accurate greyscale
• contrast — Returns black or white, whichever has better contrast against the input
• css() — Use any CSS named colour (css(tomato), css(deepskyblue), etc.)
• Composable Functions — Nest function calls inside each other: fade(lighten($(bg), 20), 0.5)

Colour Space Support

• Hex — #rgb, #rrggbb, #rrggbbaa — with short-form auto-expansion
• RGB / RGBA — rgb(r, g, b) and rgba(r, g, b, a) constructors
• HSL / HSLA — hsl(h, s, l) and hsla(h, s, l, a) constructors
• HSV / HSVA — hsv(h, s, v) and hsva(h, s, v, a) constructors
• OKLCH / OKLCHA — Perceptually uniform colour space for professional palette design
• Any Culori Format — LAB, LCH, HWB, Display P3, Rec. 2020 — if Culori parses it, Sassy compiles it
• Cross-Space Mixing — Freely combine colours from different spaces in the same theme
• Alpha Preservation — Hex alpha channels are tracked and preserved through transformations

Import & Composition

• File Imports — Pull in external YAML files via config.import
• Deep Object Merging — Palette, vars, colors, semanticTokenColors merge by deep key override
• Append-Only tokenColors — Imported tokenColors prepend, your file’s rules append — correct precedence by default
• Multi-File Import Chains — Import as many files as needed, merged in declaration order
• Modular Theme Architecture — Split palettes, variables, UI colours, syntax rules, and semantics into separate files
• Shared Palettes — One palette file, many theme variants
• Dynamic Import Paths — Use variables in import paths: ./import/palette-$(type).yaml

Séance Operator

• Prior Value References — ^ references the same key’s value from a previously imported file
• Derived Variants — Create “hushed”, “vivid”, or any theme variant by transforming inherited values: shade(^, 25)
• Multi-Layer Séance — Chain through multiple import layers with automatic versioned tracking

Theme Sections

• colors — Full support for VS Code workbench colour properties
• tokenColors — TextMate-style syntax highlighting rules with scope selectors
• semanticTokenColors — Semantic token colour definitions for language-aware highlighting
• config.custom — Pass-through block for arbitrary VS Code properties like semanticHighlighting: true
• config.$schema — Embed the VS Code colour theme schema reference in output

CLI — Build Command

• Single or Multi-File Builds — Compile one or many theme files in a single invocation
• Watch Mode — Live recompilation on file save with automatic dependency tracking
• Dependency-Aware Watching — Edits to any imported file trigger a rebuild of the parent theme
• Custom Output Directory — Route compiled output wherever you want with --output-dir
• Dry Run — Print compiled JSON to stdout without writing any files
• Silent Mode — Suppress all output except errors — ideal for scripts and CI
• Nerd Mode — Verbose error traces with full stack context for debugging
• Interactive Watch Controls — F5 to force rebuild, Ctrl-C to quit — with a live prompt
• Hash-Based Skip — SHA-256 output comparison prevents unnecessary file writes
• Graceful Signal Handling — Clean shutdown on SIGINT, SIGTERM, SIGHUP

CLI — Resolve Command

• Color Resolution — Trace any colors.* property through its full variable chain
• tokenColor Resolution — Resolve any TextMate scope to its final foreground value
• semanticTokenColor Resolution — Resolve any semantic token scope to its final value
• Full Resolution Trail — See every substitution step from raw expression to final hex
• Scope Disambiguation — When a scope appears in multiple rules, lists all matches with selectable qualifiers
• Precedence-Aware Resolution — Shows when a broader scope masks your specific one
• Colour Swatches — Truecolour terminal swatches next to resolved hex values
• Alpha Compositing Preview — --bg flag composites transparent colours against a background for preview

CLI — Proof Command

• Composed Document View — See the fully merged theme document after all imports, overrides, and séance are applied — before any evaluation
• Séance Inlining — ^ operators replaced with the actual prior values so the output reads naturally: shade(#4b8ebd, 25)
• YAML Output — Outputs in the authoring language, not the compiled format — stays in your world
• Import-Free Output — Imports are resolved and merged; the import key is gone — what you see is what the engine sees
• Aerial Debugging — Orient yourself in a layered theme before reaching for resolve — the map before the dig

CLI — Lint Command

• Duplicate Scope Detection — Finds TextMate scopes that appear in multiple tokenColors rules
• Undefined Variable Detection — Catches references to variables that don’t exist
• Unused Variable Detection — Identifies vars defined but never referenced in theme content
• Scope Precedence Analysis — Warns when a broad scope masks a more specific one due to rule ordering
• Token Colour Settings Validation — Validates settings objects: hex colours, fontStyle keywords, unknown properties
• Missing/Empty Settings Detection — Catches tokenColors entries with no settings or empty settings objects
• Deprecated Background Detection — Flags the deprecated background property in tokenColors settings
• Multiple Global Default Detection — Warns when multiple scopeless tokenColors entries exist (only the last takes effect)
• Unknown Settings Property Detection — Flags unrecognised properties in tokenColors settings objects
• Semantic Selector Validation — Validates semanticTokenColors selectors against VS Code’s parser rules
• Semantic Token Type Registry — Checks token types and modifiers against VS Code’s 23 standard types and 10 standard modifiers
• Semantic Value Validation — Validates hex colours, fontStyle keywords, and catches the fontStyle-vs-boolean override trap
• Semantic Coherence Checks — Warns when semanticTokenColors rules exist but semanticHighlighting is not enabled
• Duplicate Selector Detection — Finds semanticTokenColors selectors that are identical after modifier normalisation
• Shadowed Rule Detection — Identifies semantic rules overshadowed by higher-specificity rules with the same properties
• Deprecated Usage Warnings — Flags the deprecated member token type and non-functional background property
• Cross-Section Linting — Validates variables in colors, tokenColors, and semanticTokenColors
• Strict Mode — --strict treats warnings as errors for CI enforcement
• Severity Levels — Issues categorised as high/medium/low with colour-coded terminal output
• Source Location Reporting — Every lint issue includes file, line, and column — even across imported files
• Unnamed Rule Labels — Unnamed tokenColors entries display as (unnamed rule #N) for easy identification
• Import-Aware Analysis — Lints across all imported files, not just the main theme
• Modular Rule Architecture — Lint rules organised in dedicated modules for maintainability

Output

• VS Code .color-theme.json — Standard output format, ready for use in VS Code extensions
• Deterministic Output — Same input always produces the same output
• Pretty-Printed JSON — 2-space indented, human-readable output
• Automatic File Naming — my-theme.yaml → my-theme.color-theme.json

Architecture & Performance

• Compose-Then-Evaluate Pipeline — Shared composition step (import → merge → séance) feeds both compile and proof — one source of truth, two consumers
• Phase-Based Compilation — Compose → decompose → evaluate → resolve → assemble — clean, predictable pipeline
• File Caching — Imported files are cached and reused across themes in the same session
• Colour Caching — Parsed colours and mix results are memoised for repeat calls
• OKLCH-Native Operations — Lighten, darken, mix, and saturate all work in perceptually uniform space
• Structured Error Reporting — Chained error contexts with .trace() for precise failure diagnostics
• Max-Iteration Guards — Bounded resolution passes prevent runaway compilation

Programmatic API

• ES Module Exports — import {Theme, Lint, Resolve, Proof, Colour} from '@gesslar/sassy'
• Builder Pattern — new Theme().setCwd(cwd).setThemeFile(file).setOptions(opts) — no CLI dependencies required
• Engine Classes — Lint, Resolve, and Proof work standalone — give them a Theme, get structured data back
• Cache-Optional Loading — load() falls back to FileObject.loadData() when no cache is set
• Embeddable Compilation — Build themes programmatically without the CLI
• Lint Engine — new Lint().run(theme) — returns categorised issues with severity levels
• Resolve Engine — new Resolve().color(theme, key) — trace any token through its resolution chain
• Proof Engine — new Proof().run(theme) — composed document view before evaluation
• YamlSource Export — YamlSource class available for source location tracking in custom tooling
• Source Location Lookup — Theme.findSourceLocation(path) maps compiled output paths back to source file positions
• Lint Issue Locations — Lint issue objects include a location property with file, line, and column
• Full Class Access — Theme, Colour, and all engine classes are importable

Developer Experience

• Zero-Install Usage — npx @gesslar/sassy build — no global install required
• TypeScript Definitions — Auto-generated .d.ts files from JSDoc for editor support
• Docusaurus Documentation Site — Full docs at sassy.gesslar.io
• Example Themes — Simple and advanced examples included in the repository