MonorailCss.Framework: Instructions file for Claude Code

MonorailCSS

MonorailCss is a JIT CSS compiler that aims to be a Tailwind CSS 4.3 compatible CSS engine written in .NET. It processes utility class names and generates optimized CSS output.

Architecture Overview

Core Components

1. CssFramework (src/MonorailCss/CssFramework.cs): Main entry point that orchestrates the entire processing pipeline. It handles parsing, compilation, post-processing, and CSS generation.

2. Utilities System (src/MonorailCss/Utilities/): Self-contained components that compile CSS class candidates into AST nodes. Each utility handles specific CSS properties:

   • Static utilities extend BaseStaticUtility for fixed property/value mappings
   • Functional utilities extend BaseFunctionalUtility for theme-aware dynamic values
   • Specialized base classes exist for common patterns (colors, spacing, filters)

3. Candidate System (src/MonorailCss/Candidates/): Represents parsed utility classes with variants and modifiers. The CandidateParser tokenizes and structures raw class names.

4. AST (Abstract Syntax Tree) (src/MonorailCss/Ast/): Intermediate representation of CSS rules before final generation. Includes Declaration, Rule, ComponentRule nodes.

5. Processing Pipeline (src/MonorailCss/Pipeline/): Multi-stage transformation pipeline that processes AST nodes through:

   • Theme variable tracking
   • Arbitrary value validation
   • Negative value normalization
   • Color modifier processing
   • Important flag handling
   • Variable fallback resolution
   • Declaration merging
   • Media query consolidation
   • Layer assignment

6. Theme System (src/MonorailCss/Theme/): Manages design tokens and CSS custom properties. Supports theme customization and usage tracking for optimization.

7. Variant System (src/MonorailCss/Variants/): Handles pseudo-classes, media queries, and other CSS modifiers. Built-in variants are automatically registered.

8. Merging System (src/MonorailCss/Merging/): tailwind-merge equivalent (ClassMerger, exposed via CssFramework.Merge). Conflicts are derived from each class's compiled declarations (with shorthand expansion and a scaffold heuristic for --tw-* composition), not from a hand-maintained config — new utilities participate automatically. Utilities with reset semantics (e.g. touch-none) override IUtility.GetMergeInfo to declare the keys they cover. When a later longhand only partially overrides an earlier shorthand, the shorthand is decomposed into the longhand classes that survive (my-4 mt-6 → mb-4 mt-6) using a one-level class-prefix table (ShorthandDecomposition) over the functional axis families. The rewrite is fail-safe — it only commits when it actually drops a conflicting side, and a synthesized child that doesn't round-trip or that writes a key outside the parent (overloaded roots) is rejected, leaving the original class untouched.