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
  ```css
  /* 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
  ```json
  {
    "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