typesafe-css

README

TypeSafe CSS

A type-safe CSS authoring library for Go that eliminates stringly-typed CSS generation footguns.

Features

• Type-safe CSS APIs - No more string concatenation or typos in CSS properties
• Compact and readable output - Generates clean, valid CSS
• Template integration - Works seamlessly with Go's html/template
• Shorthand helpers - Convenient functions for common CSS patterns
• Zero runtime dependencies - Pure Go implementation

Quick Start

package main

import (
    "fmt"
    "github.com/ahmed-com/typesafe-css/css"
)

func main() {
    // Create type-safe CSS rules
    btn := css.RuleSet(".btn",
        css.Set(css.Display, css.DisplayInline),
        css.Set(css.ColorP, css.Hex("#0af")),
        css.Set(css.Padding, css.PadXY(css.Px(8), css.Px(12))),
        css.Set(css.FontSize, css.Rem(0.875)),
        css.Set(css.BorderRadius, css.Px(4)),
    )

    // Output CSS
    fmt.Println(css.PrettyCSS(btn))
}

Output:

.btn {
  display:inline;
  color:#0af;
  padding:12px 8px;
  font-size:0.875rem;
  border-radius:4px;
}

Core Types

Values

• css.Keyword - CSS keywords like "block", "flex", "auto"
• css.Length - Lengths with units (px, rem, em, %)
• css.Color - Colors (hex, rgb, rgba)
• css.Raw - Raw CSS values for complex expressions

Constructors

• css.Px(16) → "16px"
• css.Rem(1.5) → "1.5rem"
• css.Hex("#ff0000") → "#ff0000"
• css.RGB(255, 0, 0) → "rgb(255 0 0)"

Structure

• css.Property - CSS property names
• css.Decl - Property-value pairs
• css.Rule - Selector + declarations
• css.AtRule - @media, @keyframes, etc.
• css.Stylesheet - Collection of rules

Advanced Usage

Responsive Design

mobile := css.AtRule{
    Name:   "media",
    Params: "(max-width: 640px)",
    Body: []css.Item{
        css.RuleSet(".btn", 
            css.Set(css.Display, css.DisplayBlock),
            css.Set(css.Width, css.Percent(100)),
        ),
    },
}

Flexbox Helpers

container := css.RuleSet(".container",
    css.FlexCenter()..., // display: flex; justify-content: center; align-items: center;
)

Template Integration

htmlTemplate := `<style>{{ . }}</style>`
t := template.Must(template.New("styles").Parse(htmlTemplate))
t.Execute(w, css.PrettyCSS(rules...))

Project Status

This project follows a comprehensive roadmap for building a complete type-safe CSS solution. Current progress is tracked in todo.md.

Current Status: ✅ Phase 1 Complete - Core API implemented and tested

Completed

• ✅ Core value types and constructors
• ✅ Property and rule structures
• ✅ CSS serialization (compact and pretty-printed)
• ✅ Shorthand helpers for common patterns
• ✅ Template integration
• ✅ Comprehensive tests
• ✅ Tailwind CSS utilities package - Utility-first CSS with type safety

Next Steps

• Code generation pipeline for comprehensive CSS property coverage
• Advanced validation and linting capabilities
• Performance optimizations

Tailwind CSS Utilities

The project now includes a comprehensive Tailwind CSS-style utilities package for utility-first CSS authoring:

import "github.com/ahmed-com/typesafe-css/tailwind"

var stylesheet css.Stylesheet
stylesheet.Add(
    tailwind.BgBlue500(),        // .bg-blue-500 { background-color: #3b82f6; }
    tailwind.TextWhite(),        // .text-white { color: #ffffff; }
    tailwind.P4(),               // .p-4 { padding: 1rem; }
    tailwind.Flex(),             // .flex { display: flex; }
    tailwind.JustifyCenter(),    // .justify-center { justify-content: center; }
    // Arbitrary values for custom styles
    tailwind.Bg("#bada55"),      // .bg-[#bada55] { background-color: #bada55; }
)

Features:

• Utility-first approach - Compose styles from small, reusable utilities
• Tree-shaking friendly - Only called utility functions are included
• Theme system - Configurable colors, spacing, typography, and breakpoints
• Automatic deduplication - Utilities are generated only once
• Custom themes - Override defaults or add your own design tokens
• 140+ pre-built utilities - Common classes ready to use
• Arbitrary value support - Use custom values when needed

See tailwind/README.md for complete documentation.

Installation

go get github.com/ahmed-com/typesafe-css

Documentation & Examples

📚 Comprehensive Guides

• COOKBOOK.md - Practical recipes and use cases with step-by-step examples
• docs/ - Structured documentation covering all aspects of TypeSafe CSS
  • Getting Started Guide - Quick 5-minute setup
  • Tailwind Utilities Guide - Complete utility-first CSS guide
  • Core API Guide - Deep dive into the core API

💡 Working Examples

• examples/basic/ - Core API fundamentals and template integration
• examples/tailwind/ - Comprehensive Tailwind utilities demonstration
• examples/generated/ - Type-safe generated properties and mixed API usage
• examples/enhanced-tailwind/ - Advanced typed configuration system
• examples/mdn-validation/ - MDN-validated CSS properties in action
• examples/typed-config/ - Structured theme configuration

Each example includes detailed README files explaining the concepts and use cases.

License

MIT License - see LICENSE for details.

Documentation

Overview

Package main includes go:generate directives for code generation.