chaincss

ChainCSS

📖 Full Documentation →

A zero-runtime, type-safe style compiler platform for modern web applications.

ChainCSS transforms fluent TypeScript style definitions into optimized CSS through a real compiler pipeline. Instead of generating styles at runtime, it analyzes, validates, optimizes, and emits deterministic outputs during the build, resulting in fast applications, framework-independent styling, and predictable performance.

npm install chaincss

Quick Example

Vite

npm create vite@latest my-app -- --template react-ts
cd my-app && npm install chaincss

// vite.config.ts
import chaincss from 'chaincss/vite'
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [chaincss({ atomic: true }), react()],
})

// button.chain.ts
import { chain } from 'chaincss';

export const button = chain()
  .box({ p: '12px 24px', br: 8 })
  .background({ color: '#6366f1' })
  .typography({ color: '#ffffff', fontWeight: '600' })
  .hover()
    .background({ color: '#4f46e5' })
  .end()
  .$el('btn');

Use in your component

import { button } from './button.chain';

export function App() {
  return <button className={button}>Click Me</button>;
}

Why ChainCSS?

Unlike traditional CSS-in-JS libraries, ChainCSS is built around a compiler architecture.

Your styles become an Intermediate Representation (IR), pass through multiple optimization stages, and are emitted into deterministic outputs such as CSS, Atomic CSS, Tailwind configuration, Design Tokens, or Figma tokens.

This keeps the runtime extremely small while enabling sophisticated compile-time analysis and optimization.

Compiler Architecture

ChainCSS is built as a compiler platform—not simply a styling library.

Features

Structured Styling API

Group related CSS properties into 16 expressive typed methods instead of large flat objects.

chain()
  .flex({ direction: 'column', align: 'center', gap: 16 })
  .box({ p: 24, br: 12, w: '100%' })
  .background({ color: '#6366f1' })
  .typography({ color: 'white', fw: 600 })
  .transition({ tr: 'all 0.2s ease' })
  .hover()
    .background({ color: '#4f46e5' })
    .transform({ custom: 'scale(1.02)' })
  .end()
  .$el('btn')

Intelligent Unit Inference

Numeric values automatically receive CSS units where appropriate. Knows which properties are unitless (lineHeight, opacity, zIndex, fontWeight, etc.).

chain().box({ width: 300, borderRadius: 8 })

↓

width: 300px; border-radius: 8px;

Transform Composition

Individual transform properties are composed into a single transform declaration in the correct order.

chain().box({ x: 10, y: 20, rotate: 45 })

↓

transform: translateX(10px) translateY(20px) rotate(45deg);

Mixed Static + Dynamic Rendering

ChainCSS is the only library that allows per-property mixing of static and dynamic styles in a single definition. Static values compile to zero-runtime CSS. Dynamic values become CSS custom properties. Both use the same fluent API—no separate recipes, no different syntax, no compromises.

export const btn = chain.dynamic()
  .box({ padding: '12px 24px', borderRadius: 8 })                          // -> static CSS
  .background({ color: (ctx) => ctx.isActive ? '#6366f1' : '#a5b4fc' })    // -> runtime var
  .shadow({ box: (ctx) => ctx.isActive
    ? '0 8px 25px rgba(99,102,241,0.4)'
    : '0 2px 8px rgba(0,0,0,0.1)'
  })
  .$el('btn')

10 properties are static. 2 are dynamic. The CSS file contains 12 declarations—10 real values and 2 var() placeholders. The JS file contains only the 2 functions that actually need runtime evaluation.

/* Generated CSS */
.chain-btn {
  padding: 12px 24px;
  border-radius: 8px;
  background-color: var(--chain-btn-background-color);
  box-shadow: var(--chain-btn-box-shadow);
}

import { useChainStyles } from 'chaincss/runtime'
import { btn } from './button.chain'

function Button({ isActive }: { isActive: boolean }) {
  const { classes, styleVars } = useChainStyles({ btn }, { isActive })
  return <button className={classes.btn} style={styleVars}>Click</button>
}

Framework Adapters

useChainStyles returns { classes, styleVars } in every framework. Each adapter uses the framework's native reactivity system.

Token Dependency Graph

Tokens are relationships—not just variables. Changing one token automatically updates derived colors, harmony palettes, and contrast colors. All computed in the OKLCH color space for perceptual accuracy.

tokens: {
  relationships: [
    { type: 'derived', source: 'colors.primary.500', target: 'colors.primary.100', method: 'mix-white 80%' },
    { type: 'derived', source: 'colors.primary.500', target: 'colors.primary.600', method: 'shade 20%' },
    { type: 'contrast', foreground: 'colors.text.onPrimary', background: 'colors.primary.500', target: 4.5, autoFix: 'auto' },
    { type: 'harmony', source: 'colors.primary.500', targets: ['colors.accent.500', 'colors.accent.300'], rule: 'complementary' }
  ]
}

Semantic Intent System

Design with intent, not implementation.

Instead of repeatedly describing how an element should look using individual CSS properties, ChainCSS lets you describe what the element is or what design concept it represents.

chain()
  .intents(['card'])
  .$el('product-card')

The compiler resolves the intent into its underlying style definition and passes the result through the normal ChainCSS compilation pipeline.

"card"
  ↓
Intent Registry
  ↓
Intent Resolution
  ↓
Style IR
  ↓
Compiler Pipeline
  ↓
Optimized CSS

Built-in intent vocabulary

ChainCSS ships with built-in intents covering common layout, component, semantic, and interaction concepts.

For example, card expands into properties such as display: flex; flex-direction: column; overflow: hidden; including generated interaction states and accessibility metadata.

User-defined intents

The built-in vocabulary is not a closed list. Applications can introduce their own design vocabulary through chaincss.config.ts:

export default defineConfig({
  intents: {
    glass: {
      name: 'glass',
      category: 'visual',
      description: 'Frosted glass effect',
      properties: {
        background: 'rgba(255,255,255,0.1)',
        backdropFilter: 'blur(10px)',
        border: '1px solid rgba(255,255,255,0.2)',
        borderRadius: '12px',
      }
    }
  }
});

The intent can then be used directly:

chain()
  .intents(['glass'])
  .$el('panel')

Composite intents

Intents can be composed from other intents:

intents: {
  premium: {
    name: 'premium',
    category: 'composite',
    resolve: () => ({
      expandsTo: ['card', 'center-content'],
    })
  }
}

chain()
  .intents(['premium'])
  .$el('premium-card')

premium
 ├── card
 └── center-content

Multiple intents

chain()
  .intents(['center-content', 'sticky-header'])
  .box({ minHeight: '400px' })
  .$el('hero')

Natural-language intent descriptions

chain()
  .describe('glass elevated spacious')
  .$el('navbar')

The description is parsed into intent names and resolved through the same intent registry:

"glass elevated spacious"
         ↓
     intent parser
         ↓
["glass", "elevated", "spacious"]
         ↓
   intent registry
         ↓
     Style IR
         ↓
      CSS output

Intent System — Complete Feature Set

ChainCSS includes a four-phase intent system that turns design vocabulary into production CSS.

Phase 1: Relationships & Constraints

Intents know how they relate to each other.

chain()
  .intents(['card', 'compact'])
  .$el('card')

• requires — Auto-adds required intents (card requires rounded)
• conflicts — Prevents invalid combinations (compact conflicts with spacious)
• enhances — Suggests great combinations (card enhances elevated, glass)
• maxCombinations — Limits stacking
• priority — Resolution order

Phase 2: Themes & Variants

Intents adapt to context.

chain()
  .intents(['card'])
  .$el('card')

Compiles both light and dark CSS:

/* Light */
.chain-card { background: #ffffff; }

/* Dark — automatically generated */
[data-theme="dark"] .chain-card { background: #1e293b; }

Variants provide named alternatives:

chain()
  .intents(['card'])
  .$el('premium-card')
// variant: 'premium' → gradient background

Phase 3: Composition Patterns

Intents compose into more complex components.

chain()
  .intents(['premium-card'])
  .$el('premium-card')

premium-card expands to:

card + glass + elevated

With conditional behavior:

// Dark mode automatically:
// + glow
// - elevated

Phase 4: Natural Language

Describe designs in plain English.

chain()
  .describe('dark premium card')
  .$el('premium-dark-card')

The deterministic parser:

• Maps synonyms (frosted → glass)
• Detects themes (dark, light, high-contrast)
• Detects variants (premium, outlined, success)
• Resolves composition (premium card → premium-card)
• Ignores stop words (a, the, with, and)

Intent Resolution Pipeline

.describe('dark premium card')
    ↓
Parser: intents=['premium-card'], theme='dark'
    ↓
Composition: premium-card → card + glass + elevated
    ↓
Conditions: dark → + glow, - elevated
    ↓
Relationships: card requires rounded
    ↓
Themes: apply dark overrides
    ↓
Tokens: resolve $colors.*
    ↓
CSS: [data-theme="dark"] .chain-premium-card { ... }

Intent Catalog

Accessibility Compilation

Six WCAG checks run during compilation—not in CI, not in the browser. Milliseconds, not seconds.

chaincss check --strict    # CI gate — fails on errors
chaincss audit --fix --write  # Auto-fix and write to token files

Compile-Time Optimization

Nine optimization passes run on every stylesheet:

Relationship Macros (100+)

Express CSS relationships rather than selectors. Zero runtime. All outputs are pure CSS.

Multi-Target Emission

A single .chain.ts file compiles to multiple output formats simultaneously from the same IR.

chaincss build --target css,atomic-css,tailwind,design-tokens,figma,graph-json

Component Variants (Recipes)

Type-safe component variants with compound conditions. All variants compile at build time.

export const buttonVariants = recipe({
  base: chain().box({ p: '8px 16px', br: 8 }).$el('btn'),
  variants: {
    color: {
      primary: chain().background('#6366f1').typography({ color: 'white' }).$el(),
      secondary: chain().background('#48bb78').$el(),
      danger: chain().background('#f56565').$el(),
    },
    size: {
      sm: chain().box({ p: '4px 8px' }).typography({ fs: 12 }).$el(),
      md: chain().box({ p: '8px 16px' }).typography({ fs: 14 }).$el(),
      lg: chain().box({ p: '12px 24px' }).typography({ fs: 16 }).$el(),
    }
  },
  defaultVariants: { color: 'primary', size: 'md' },
})

buttonVariants({ color: 'secondary', size: 'lg' })  // -> merged StyleDefinition

Figma Integration

Bidirectional sync: designers change colors in Figma → Tokens Studio pushes to GitHub → GitHub Action runs entanglement → derived tokens update → contrast auto-fixes.

chaincss figma init --repo org/design-tokens --fileId abc123
chaincss entanglement --input tokens.json --watch --fix --figma

Dev Server with HMR

Zero-config development server with hot module replacement, build error overlay, and persistent compiler state.

chaincss dev --port 3000

• Instant HMR: CSS changes stream via SSE, no page reload
• Build error overlay: Compilation errors injected into the page
• Persistent state: Survives restarts for cold-start incremental builds
• Compiler stats: Real-time metrics at /__chaincss_stats

CLI Commands

chaincss init
chaincss create app my-app --template react --pm pnpm
chaincss dev --port 3000
chaincss watch --verbose
chaincss build --minify --atomic --persistent
chaincss build --target css,tailwind,design-tokens,figma,graph-json
chaincss check --strict
chaincss audit --fail-on AA --fix --write
chaincss entanglement --input tokens.json --watch --fix
chaincss figma init --repo org/design-tokens
chaincss cache stats
chaincss cache validate
chaincss timeline list
chaincss timeline diff --snapshot1 0 --snapshot2 5

Supported Frameworks

Build Integrations

• Vite — Plugin with HMR, virtual CSS, persistent state
• Next.js — Server Component + Client Component support
• Webpack — Plugin with incremental compilation
• PostCSS — Drop-in plugin for existing pipelines
• CLI — Full-featured standalone build tool

Performance

Measurements taken on a Lenovo G560 (Node.js v22.23.1, 4 CPUs, 4GB RAM).

Philosophy

ChainCSS approaches styling the same way modern language compilers approach source code.

Instead of treating CSS as strings, it treats styles as structured data that can be analyzed, validated, optimized, transformed, cached, and emitted into multiple targets.

The objective is to provide the ergonomics of a fluent styling API while leveraging compiler techniques typically found in tools such as TypeScript, Babel, SWC, and LLVM.

License

MIT

Author: Rommel Edorot Caneos

Contact | Website

GitHub