TrailCSS

A modern utility-first CSS framework with:

• JIT compilation
• Custom utilities
• Custom components
• Plugins
• Presets
• Responsive variants
• Obfuscation
• Minification
• CLI support

Built with a modular compiler architecture inspired by modern frameworks.

Features

✅ Utility-first workflow ✅ Component system ✅ JIT compiler ✅ Arbitrary values ✅ Responsive breakpoints ✅ Theme system ✅ Plugin architecture ✅ Preset system ✅ Production obfuscation ✅ CSS minification ✅ CLI (trail dev, trail build) ✅ Watch mode ✅ Lightweight architecture

Installation

1. Clone TrailCSS

git clone <your-repository>

2. Install dependencies

pnpm install

3. Link globally

Inside the framework folder:

pnpm link --global .

This enables:

trail dev
trail build

globally on your machine.

Creating a Project

Example structure:

my-project/
│
├── playground/
│   └── index.html
│
├── output/
│
└── trail.config.js

Running TrailCSS

Development mode

trail dev

Starts:

• file watcher
• automatic rebuilds
• development compilation

Production build

trail build

Enables:

• CSS minification
• class obfuscation
• production optimization

trail.config.js

This is the main configuration file.

Example:

import defaultPreset
  from "./src/presets/defaultPreset.js"

export default {
  content: ["playground"],

  output: {
    css: "output/trail.css",
    html: "output/index.html",
  },

  build: {
    obfuscate: true,
  },

  theme: {
    colors: {
      primary: "#2563eb",
    },

    breakpoints: {
      sm: "640px",
      md: "768px",
    },
  },

  plugins: [],

  presets: [
    defaultPreset,
  ],
}

Config Options

content

Defines which folder TrailCSS scans.

Example:

content: ["playground"]

If you rename your project folder:

playground → app

update config:

content: ["app"]

output

Defines generated files.

output: {
  css: "output/trail.css",
  html: "output/index.html",
}

build.obfuscate

Controls class obfuscation.

Enable obfuscation

build: {
  obfuscate: true,
}

Disable obfuscation

build: {
  obfuscate: false,
}

Custom Utilities

Edit:

src/registries/utilities.js

Example:

export const utilities = {
  "my-box": {
    padding: "1rem",
    borderRadius: "1rem",
  },
}

Usage:

<div class="my-box">

Custom Components

Edit:

src/registries/components.js

Example:

export const components = {
  card: {
    base: {
      padding: "1rem",
      background: "white",
    },
  },
}

Usage:

<div class="card">

Custom Selectors

Edit:

src/registries/selectors.js

Example:

export const selectors = {
  body: {
    margin: "0",
  },
}

Custom Shortcuts

Edit:

src/registries/shortcuts.js

Example:

export const shortcuts = {
  "flex-center": [
    "flex",
    "items-center",
    "justify-center",
  ],
}

Usage:

<div class="flex-center">

Theme Customization

Inside:

theme: {
  colors: {},
  darkMode: {},
  breakpoints: {},
}

You can customize:

• colors
• dark mode colors
• responsive breakpoints

Plugins

Create plugins inside:

src/plugins/modules

Example:

export default ({ addUtilities }) => {
  addUtilities({
    "text-glow": {
      textShadow: "0 0 10px white",
    },
  })
}

Presets

Presets allow reusable framework configurations.

Location:

src/presets

Example preset:

const myPreset = () => {
  return {
    utilities: {},
    components: {},
    shortcuts: {},
  }
}

export default myPreset

Architecture

TrailCSS uses a layered modular compiler architecture.

Core Pipeline

CLI
 ↓
Build Orchestrator
 ↓
Scanner
 ↓
Parser
 ↓
Compiler
 ↓
Optimizer
 ↓
Output

Main Architecture Layers

CLI Layer

Handles:

• commands
• build mode
• watch mode

Files:

src/cli

Compiler Layer

Converts utilities into CSS.

Files:

src/compiler

Registry Layer

Stores:

• utilities
• components
• selectors
• shortcuts

Files:

src/registries

Plugin Layer

Extends framework functionality.

Files:

src/plugins

Preset Layer

Reusable framework configurations.

Files:

src/presets

If You Rename the Framework

Update inside:

package.json

Example:

"bin": {
  "trail": "./src/cli/index.js"
}

Changing:

"trail"

changes the global command.

Example:

"mycss"

Then relink:

pnpm link --global .

New command:

mycss dev

If You Rename the Project Folder

Usually nothing breaks.

But if you rename folders used in config:

playground
output

update:

trail.config.js

accordingly.

After Changing Utilities or Components

TrailCSS automatically rebuilds in dev mode.

If not running:

trail dev

restart watcher or rebuild manually:

trail build

Development Philosophy

TrailCSS is designed around:

• modular architecture
• scalability
• maintainability
• extensibility
• compiler-driven optimization

Inspired by modern utility-first frameworks while remaining highly customizable.

Current Capabilities

✅ JIT engine ✅ Responsive variants ✅ Arbitrary values ✅ Theme variables ✅ Plugin API ✅ Presets ✅ Production pipeline ✅ Obfuscation ✅ Minification ✅ Global CLI

Future Goals

• Advanced parser engine
• Nested variants
• Arbitrary selectors
• Live reload
• AST compiler
• Performance optimization
• Framework integrations

License

See LICENSE for details.

Author

omsu