TCSS - Thematic CSS

A powerful CSS preprocessor that adds functions, variables, and expressions to CSS with Python-style indentation.

🎯 Project Status

Version 1.0.0 - Production Ready! 🎉

All 12 Phases: COMPLETE ✅

Completed Features ✅

• ✅ Lexer & Parser - Full TCSS syntax support
• ✅ Executor - Function execution and variable resolution
• ✅ CSS Generator - Optimized CSS output with minification
• ✅ CLI Tool - Command-line interface with watch mode
• ✅ WASM Bindings - Browser support via WebAssembly
• ✅ JavaScript Integration - npm package and browser loader
• ✅ 24 Built-in Functions - Colors, math, and string utilities
• ✅ Import System - File imports with circular detection and caching
• ✅ Comprehensive Tests - 150+ tests with 80%+ code coverage
• ✅ Complete Documentation - 2,000+ lines of documentation
• ✅ Performance Optimization - Benchmarks and optimized builds
• ✅ Publishing Ready - Prepared for crates.io and npm

✨ Features

• ✅ Variables - Define reusable values
• ✅ Functions - Create custom functions with parameters
• ✅ Expressions - Perform calculations in CSS
• ✅ 24 Built-in Functions - Colors, math, and string utilities
• ✅ Import System - Split code across multiple files
• ✅ Python-style Indentation - Clean, readable syntax
• ✅ Type Safety - Compile-time type checking
• ✅ Zero Runtime - Compiles to pure CSS
• ✅ WASM Support - Run in the browser
• ✅ Fast - Written in Rust for maximum performance

📦 Project Structure

TCSS/
├── tcss-core/           # Core compiler library ✅
│   ├── src/
│   │   ├── lexer.rs     # Tokenizer ✅
│   │   ├── parser.rs    # AST parser ✅
│   │   ├── executor.rs  # Function executor ✅
│   │   ├── generator.rs # CSS generator ✅
│   │   ├── import.rs    # Import processor ✅
│   │   ├── resolver.rs  # Path resolver ✅
│   │   └── builtins/    # Built-in functions ✅
│   └── tests/           # Comprehensive test suite ✅
├── tcss-cli/            # Command-line interface ✅
├── tcss-wasm/           # WebAssembly bindings ✅
├── tcss-js/             # JavaScript wrapper ✅
├── docs/                # Complete documentation ✅
└── examples/            # Example projects ✅

🚀 Quick Start

Installation

# Using Cargo
cargo install tcss-cli

# Using npm
npm install tcss-js

Your First TCSS File

styles.tcss:

@var primary: #3498db
@var spacing: 16px

@fn button-padding(size):
    return size * spacing

.button:
    background: primary
    padding: button-padding(1)
    border-radius: 4px
    color: white

.button:hover:
    background: lighten(primary, 10)

Compile

tcss compile styles.tcss -o styles.css

Output

.button {
    background: #3498db;
    padding: 16px;
    border-radius: 4px;
    color: white;
}

.button:hover {
    background: #5dade2;
}

📚 Documentation

Getting Started

• Quick Reference - Quick syntax reference
• User Guide - Complete user documentation
• Examples - Example TCSS files

API & Reference

• API Documentation - Rust and JavaScript API
• Built-in Functions - Function reference
• Import System - Import documentation

Development

• Testing Guide - How to run and write tests
• Contributing Guide - How to contribute
• Optimization Guide - Performance optimization

Publishing

• Publishing Guide - How to publish releases
• Changelog - Version history
• Project Summary - Complete project overview

💡 Examples

Variables & Functions

@var primary-color: #3498db
@var base-spacing: 16px

@fn spacing(multiplier):
    return multiplier * base-spacing

.card:
    padding: spacing(2)
    background: primary-color

Built-in Functions

// Color manipulation
.button:
    background: darken(#3498db, 10)
    border-color: lighten(#3498db, 10)
    color: rgba(255, 255, 255, 0.9)

// Math operations
.box:
    width: max(100px, 50%)
    padding: clamp(16px, 2vw, 32px)

// String utilities
.text:
    font-family: uppercase("arial")

Imports

@import './colors.tcss'
@import './theme/base.tcss'
@import '@tcss/core'

.button:
    background: primary

🧪 Testing

Run the comprehensive test suite:

# Run all tests
cargo test

# Run specific test suite
cargo test --test integration_tests
cargo test --test e2e_tests

# Run with coverage
cargo tarpaulin --out Html

Test Coverage: 80%+

• ✅ Unit Tests - All core modules (lexer, parser, executor, generator, etc.)
• ✅ Integration Tests - End-to-end compilation workflows
• ✅ E2E Tests - File I/O, imports, and complete workflows
• ✅ Built-in Function Tests - All 24 built-in functions
• ✅ Import System Tests - Circular detection, caching, resolution

🛠️ Usage

CLI

# Compile a file
tcss compile input.tcss -o output.css

# Compile with minification
tcss compile input.tcss -o output.css --minify

# Watch for changes
tcss watch input.tcss -o output.css

Rust API

use tcss_core::{Lexer, Parser, Executor, Generator};

let source = r#"
    @var primary: #3498db
    .button:
        background: primary
"#;

let mut lexer = Lexer::new(source);
let tokens = lexer.tokenize()?;
let mut parser = Parser::new(tokens);
let program = parser.parse()?;
let mut executor = Executor::new();
let executed = executor.execute(&program)?;
let mut generator = Generator::new();
let css = generator.generate(&executed)?;

JavaScript API

import { compile } from 'tcss-js';

const tcss = `
@var primary: #3498db

.button:
    background: primary
`;

const css = compile(tcss);

Browser

<link rel="tcss" href="styles.tcss">
<script type="module">
    import { init } from './tcss-js/index.js';
    await init();
</script>

📋 Development Roadmap

• Phase 1: Core Lexer/Tokenizer ✅
• Phase 2: AST Parser ✅
• Phase 3: Expression Evaluator ✅
• Phase 4: CSS Generator ✅
• Phase 5: Error Handling ✅
• Phase 6: CLI Tool ✅
• Phase 7: WebAssembly Bindings ✅
• Phase 8: JavaScript Integration ✅
• Phase 9: Built-in Functions Library ✅
• Phase 10: Import System ✅
• Phase 11: Testing & Documentation ✅
• Phase 12: Optimization & Publishing ✅

🛠️ Technology Stack

• Rust - Core implementation language
• wasm-bindgen - WebAssembly bindings
• serde - Serialization framework
• clap - CLI argument parsing
• tempfile - Testing utilities

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by Sass, Less, and Stylus
• Built with Rust for performance and safety
• Uses wasm-bindgen for WebAssembly support

💬 Support

• GitHub Issues: Report bugs or request features
• Documentation: Read the docs
• Examples: See examples

Made with ❤️ by TCSS Contributors

Current Version: 1.0.0 - Production Ready! 🎉