leptos-shadcn-ui/docs/remediation/components/button/DESIGN.md

Button Component Design & Architecture

Component: Button
Priority: HIGH
Status: Needs File Size Refactoring

📊 Current State Analysis

File Structure

packages/leptos/button/src/
├── default.rs (170 lines) ✅
├── implementation_tests.rs (527 lines) ❌ VIOLATION
├── lib.rs (33 lines) ✅
├── new_york_tests.rs (638 lines) ❌ VIOLATION
├── new_york.rs (142 lines) ✅
├── property_tests.rs (334 lines) ❌ VIOLATION
├── signal_managed.rs (391 lines) ❌ VIOLATION
├── standardized.rs (569 lines) ❌ VIOLATION
├── test_helpers.rs (52 lines) ✅
├── test_templates.rs (167 lines) ✅
├── tests_legacy.rs (843 lines) ❌ VIOLATION
├── tests_simple.rs (229 lines) ✅
└── variant_comparison_tests.rs (374 lines) ❌ VIOLATION

Test Coverage Status

• Total Tests: 115 tests passing ✅
• Coverage Quality: Excellent ✅
• Test Organization: Needs refactoring ❌

File Size Violations

File	Lines	Limit	Status
implementation_tests.rs	527	300	❌ VIOLATION
new_york_tests.rs	638	300	❌ VIOLATION
tests_legacy.rs	843	300	❌ VIOLATION
property_tests.rs	334	300	❌ VIOLATION
signal_managed.rs	391	300	❌ VIOLATION
standardized.rs	569	300	❌ VIOLATION
variant_comparison_tests.rs	374	300	❌ VIOLATION

---

🎯 Design Goals

Primary Objectives

1. File Size Compliance: All files under 300 lines
2. Test Organization: Logical grouping of tests
3. Maintainability: Easy to understand and modify
4. Performance: Optimized for production use

Secondary Objectives

1. Documentation: Comprehensive component documentation
2. Accessibility: Full ARIA and keyboard support
3. Theming: Support for multiple design systems
4. Integration: Seamless integration with other components

---

🏗️ Proposed Architecture

Refactored File Structure

packages/leptos/button/src/
├── lib.rs (50 lines) ✅
├── default.rs (170 lines) ✅
├── new_york.rs (142 lines) ✅
├── signal_managed.rs (200 lines) ✅
├── standardized.rs (200 lines) ✅
├── test_helpers.rs (52 lines) ✅
├── tests/
│   ├── mod.rs (20 lines) ✅
│   ├── basic_rendering_tests.rs (250 lines) ✅
│   ├── interaction_tests.rs (250 lines) ✅
│   ├── accessibility_tests.rs (250 lines) ✅
│   ├── theme_tests.rs (250 lines) ✅
│   ├── performance_tests.rs (250 lines) ✅
│   ├── integration_tests.rs (250 lines) ✅
│   └── property_tests.rs (250 lines) ✅
└── legacy/
    ├── tests_legacy.rs (200 lines) ✅
    └── variant_comparison_tests.rs (200 lines) ✅

Module Responsibilities

Core Modules

• lib.rs: Main exports and module organization
• default.rs: Default theme implementation
• new_york.rs: New York theme implementation
• signal_managed.rs: Signal management features
• standardized.rs: API standardization

Test Modules

• basic_rendering_tests.rs: Basic rendering and props
• interaction_tests.rs: Click handlers and events
• accessibility_tests.rs: ARIA attributes and keyboard navigation
• theme_tests.rs: Theme variant testing
• performance_tests.rs: Performance and optimization tests
• integration_tests.rs: Integration with other components
• property_tests.rs: Property-based testing

Legacy Modules

• tests_legacy.rs: Legacy test compatibility
• variant_comparison_tests.rs: Theme variant comparisons

---

🛠️ Implementation Plan

Phase 1: File Size Refactoring (Week 1)

Priority: CRITICAL

Step 1: Split Large Test Files

• Split implementation_tests.rs (527 lines) → 3 modules
• Split new_york_tests.rs (638 lines) → 4 modules
• Split tests_legacy.rs (843 lines) → 6 modules
• Split property_tests.rs (334 lines) → 2 modules

Step 2: Refactor Core Files

• Split signal_managed.rs (391 lines) → 2 modules
• Split standardized.rs (569 lines) → 3 modules
• Split variant_comparison_tests.rs (374 lines) → 2 modules

Step 3: Create Test Module Structure

• Create tests/ directory
• Implement focused test modules
• Organize tests by functionality
• Maintain test coverage

Phase 2: Test Enhancement (Week 2)

Priority: HIGH

Step 1: Accessibility Testing

• Implement comprehensive ARIA tests
• Add keyboard navigation tests
• Create screen reader compatibility tests
• Test focus management

Step 2: Performance Testing

• Add rendering performance tests
• Implement memory usage tests
• Create stress testing scenarios
• Test optimization features

Step 3: Integration Testing

• Test with other components
• Create complex usage scenarios
• Test theme switching
• Validate API contracts

Phase 3: Documentation (Week 3)

Priority: MEDIUM

Step 1: Component Documentation

• Create comprehensive API documentation
• Add usage examples
• Document accessibility features
• Create migration guides

Step 2: Test Documentation

• Document test organization
• Create testing guidelines
• Add performance benchmarks
• Document best practices

---

📊 Success Metrics

File Size Compliance

• Target: All files under 300 lines
• Current: 7 violations
• Goal: 0 violations

Test Coverage

• Current: 115 tests passing
• Target: 150+ tests
• Goal: 100% coverage

Performance Metrics

• Rendering Time: < 5ms
• Memory Usage: < 1MB
• Bundle Size: < 50KB

Accessibility Compliance

• WCAG 2.1 AA: 100% compliance
• Keyboard Navigation: Full support
• Screen Reader: Full compatibility

---

🚀 Implementation Timeline

Week 1: File Size Refactoring

• Days 1-2: Split large test files
• Days 3-4: Refactor core files
• Days 5-7: Create test module structure

Week 2: Test Enhancement

• Days 1-2: Accessibility testing
• Days 3-4: Performance testing
• Days 5-7: Integration testing

Week 3: Documentation

• Days 1-2: Component documentation
• Days 3-4: Test documentation
• Days 5-7: Review and optimization

---

🎯 Quality Gates

Week 1 Gates

• All files under 300 lines
• All tests passing
• No compilation errors

Week 2 Gates

• 150+ tests implemented
• Performance benchmarks met
• Accessibility compliance

Week 3 Gates

• Documentation complete
• Migration guides ready
• Production-ready status

---

💡 Technical Considerations

Refactoring Strategy

• Incremental Changes: Small, testable modifications
• Test Preservation: Maintain all existing tests
• Backward Compatibility: Ensure API stability
• Performance: No performance degradation

Risk Mitigation

• Git Branches: Separate branch for each phase
• Code Reviews: Peer review for all changes
• Rollback Plans: Ability to revert changes
• Testing: Comprehensive test coverage

Quality Assurance

• Automated Testing: CI/CD pipeline integration
• Performance Monitoring: Continuous performance tracking
• Accessibility Testing: Automated accessibility checks
• Documentation: Automated documentation generation

---

Button Component Design created: September 20, 2025
Next review: October 20, 2025