michaelschiemer/docs/todo/css-generation-system.md

CSS Generation System - Todo List

Status: Planning Phase Priority: Medium Estimated Effort: Large (2-3 weeks)

Context

Evaluate and potentially implement a CSS generation system that leverages the existing PHP Component System and Design Token architecture to automatically generate CSS from PHP definitions.

Key Decision Points

• Architecture Decision: How much CSS should be generated?

  • Option A: Only Design Tokens (CSS Custom Properties)
  • Option B: Design Tokens + Component Base Styles
  • Option C: Full CSS Generation with Manual Extensions

• Primary Source: What becomes the single source of truth?

  • Option A: PHP Components are primary, CSS is generated
  • Option B: CSS is primary, PHP components read from CSS
  • Option C: Hybrid: Tokens in PHP, Components in CSS

• Build Integration: How is generation triggered?

  • Option A: Manual console command
  • Option B: Automatic on file change (watch mode)
  • Option C: Integrated into npm build pipeline

Phase 1: Foundation & Analysis

1.1 Design Token CSS Generation

• Implement DesignTokenCssGenerator service

  • Input: Array of DesignToken Value Objects
  • Output: CSS Custom Properties (:root { --token-name: value; })
  • File: src/Framework/Design/Generators/DesignTokenCssGenerator.php

• Create console command for token generation

  • Command: php console.php design:generate-tokens
  • Output: resources/css/settings/_generated-tokens.css
  • Include timestamp and "DO NOT EDIT MANUALLY" warning

• Test with existing Design Tokens

  • Color tokens (RGBColor Value Objects)
  • Spacing tokens
  • Typography tokens

1.2 Component CSS Analysis

• Design ComponentCssDefinition interface

  • Methods: getCssClasses(), getCssVariables(), getCssRules()
  • Purpose: Define CSS requirements in PHP components
  • File: src/Framework/View/Contracts/ComponentCssDefinition.php

• Implement ComponentCssMetadata Value Object

  • Properties: baseClass, variants, modifiers, sizes
  • CSS rule definitions for each variant
  • File: src/Framework/View/ValueObjects/ComponentCssMetadata.php

• Create ComponentCssSyncChecker for validation

  • Compare PHP component definition with actual CSS file
  • Report missing classes, extra classes, sync status
  • File: src/Framework/Design/Validation/ComponentCssSyncChecker.php

Phase 2: Component CSS Generation

2.1 Component CSS Generator

• Implement ComponentCssGenerator service

  • Discovers all components implementing ComponentCssDefinition
  • Generates base CSS for each component
  • Output: resources/css/components/_generated-{component}.css

• Add component metadata to existing components

  • Start with Button component
  • Then Card, Badge, Alert
  • Define all variants, sizes, modifiers in PHP

• Create console command

  • Command: php console.php design:generate-component-css
  • Options: --component=Button (single component)
  • Option: --watch (regenerate on file changes)

2.2 Incremental Generation

• Implement IncrementalCssGenerator

  • Track component hashes/checksums
  • Only regenerate changed components
  • Cache last generation state
  • File: src/Framework/Design/Generators/IncrementalCssGenerator.php

• Add component change detection

  • Use file modification times
  • Hash component class definition
  • Store in cache for comparison

Phase 3: Hybrid Approach Implementation

3.1 Generated + Manual CSS

• Define file naming conventions

  • Generated: _generated-*.css (auto, don't edit)
  • Manual: *-custom.css or *.css (manual extensions)

• Create import structure

  /* components/button.css */
  @import './_generated-button.css';
  @import './button-custom.css';
  

• Document what goes where

  • Generated: Base styles, variants, sizes from PHP
  • Manual: Animations, hover effects, complex selectors

3.2 CSS Parser Integration

• Use existing CssParser for reverse direction

  • Parse existing CSS files
  • Extract Design Tokens to migrate to PHP
  • Generate DesignToken objects from CSS Custom Properties

• Implement DesignTokenMigrator

  • Find hard-coded colors in CSS
  • Replace with var(--token-name)
  • Create new tokens for unmapped values
  • File: src/Framework/Design/Migration/DesignTokenMigrator.php

• Create CssUsageAnalyzer

  • Find unused CSS classes
  • Analyze CSS coverage in templates
  • Report dead CSS
  • File: src/Framework/Design/Analysis/CssUsageAnalyzer.php

Phase 4: Build Pipeline Integration

4.1 Build Process

• Add CSS generation to package.json scripts

  {
    "prebuild": "php console.php design:generate-all-css",
    "build": "vite build"
  }
  

• Create unified generation command

  • Command: php console.php design:generate-all-css
  • Generates tokens + components in one command
  • Shows summary of generated files

• Add to Docker development workflow

  • Update Makefile with CSS generation target
  • Document when to run generation

4.2 Watch Mode for Development

• Implement file watcher for PHP components

  • Watch src/Framework/View/Components/*.php
  • Auto-regenerate CSS on component changes
  • Integrate with Vite dev server

• Add hot reload support

  • Generated CSS changes trigger browser reload
  • Show notification when CSS regenerated

Phase 5: Testing & Validation

5.1 Unit Tests

• Test DesignTokenCssGenerator

  • Input: Various token types
  • Verify correct CSS output format
  • Test edge cases (special characters, etc.)

• Test ComponentCssGenerator

  • Mock component with metadata
  • Verify generated CSS structure
  • Test variant/size generation

• Test ComponentCssSyncChecker

  • Test sync detection (missing/extra classes)
  • Test sync success scenario

5.2 Integration Tests

• Test full generation pipeline

  • PHP components → Generated CSS
  • Verify file creation
  • Verify CSS validity

• Test with existing components

  • Generate CSS for Button
  • Generate CSS for Card
  • Compare with current manual CSS

5.3 Performance Tests

• Benchmark generation speed
  • Measure time for full generation
  • Measure incremental generation
  • Ensure <1s for typical project

Phase 6: Documentation & Guidelines

6.1 Developer Documentation

• Create comprehensive guide

  • When to use generated vs manual CSS
  • How to add new components with CSS metadata
  • How to extend generated CSS
  • File: docs/claude/css-generation.md

• Update existing docs

  • docs/claude/framework-personas.md (Template Design System Persona)
  • docs/claude/guidelines.md (CSS workflow)
  • Add CSS generation to common workflows

6.2 Component Examples

• Document Button component pattern

  • Show PHP component with CSS metadata
  • Show generated CSS output
  • Show manual extension example

• Create component template

  • Template for new components with CSS
  • Include all necessary interfaces
  • Add to framework scaffolding

Decision Log

Decisions to Make

1. Token-only vs Full Generation

   • Pro Token-only: Simple, low risk, easy to implement
   • Pro Full: Complete automation, single source of truth
   • Con Full: Less design flexibility, more complex build

2. PHP-first vs CSS-first

   • PHP-first: Type safety, framework-aligned, validation
   • CSS-first: Familiar workflow, existing ecosystem
   • Hybrid: Best of both (current recommendation)

3. Migration Strategy

   • Big Bang: Migrate all components at once
   • Incremental: Start with tokens, add components later
   • Opt-in: Components choose to implement CSS generation

Current Recommendation

Hybrid Incremental Approach:

1. Start with Design Token generation (Phase 1.1)
2. Test with Button component CSS generation (Phase 2.1)
3. Evaluate results before full rollout
4. Keep manual CSS as valid option for complex cases

Notes & Considerations

Advantages

• ✅ Single source of truth (PHP components)
• ✅ Type safety via PHP type system
• ✅ Automatic sync between component and CSS
• ✅ Framework-compliant (Value Objects, readonly classes)
• ✅ Leverages existing Component Registry
• ✅ Can coexist with manual CSS (hybrid)

Challenges

• ⚠️ Additional build complexity
• ⚠️ Learning curve for developers
• ⚠️ Less direct CSS control for designers
• ⚠️ Need to maintain two systems during migration
• ⚠️ Complex CSS (animations, complex selectors) harder to generate

Open Questions

• How to handle media queries in generated CSS?
• Should @layer (CSS Cascade Layers) be used?
• How to handle CSS preprocessor features (if added later)?
• What about CSS-in-JS for dynamic styles?
• How to version generated CSS (Git commit generated files?)?

Related Files

Existing Infrastructure:

• src/Framework/Design/Parser/CssParser.php - CSS → PHP parsing
• src/Framework/Design/Analyzer/DesignSystemAnalyzer.php - CSS analysis
• src/Framework/Design/ValueObjects/DesignToken.php - Token Value Object
• src/Framework/View/Components/*.php - Existing components

To Be Created:

• src/Framework/Design/Generators/DesignTokenCssGenerator.php
• src/Framework/Design/Generators/ComponentCssGenerator.php
• src/Framework/Design/Generators/IncrementalCssGenerator.php
• src/Framework/View/Contracts/ComponentCssDefinition.php
• src/Framework/View/ValueObjects/ComponentCssMetadata.php
• src/Framework/Design/Validation/ComponentCssSyncChecker.php

Generated Output:

• resources/css/settings/_generated-tokens.css
• resources/css/components/_generated-button.css
• resources/css/components/_generated-card.css
• etc.

---

Last Updated: 2025-10-19 Status: Ready for architectural decision