diff --git a/cline_docs/permanent_rules.md b/cline_docs/permanent_rules.md index b2f61d3d..4b5e1035 100644 --- a/cline_docs/permanent_rules.md +++ b/cline_docs/permanent_rules.md @@ -42,5 +42,49 @@ All API directory structures MUST match URL nesting patterns. No exceptions. If - Need to extend type classifications to all ride categories - Maintain clear separation between type (how it works) and model (what product it is) +## UI Component Standards + +### DJANGO-COTTON COMPONENT REQUIREMENT +**MANDATORY RULE**: All new card components and reusable UI patterns MUST be implemented using Django Cotton components. + +#### Component Organization +- **Location**: All Django Cotton components must be stored in `templates/cotton/` +- **Naming**: Component files must use snake_case naming (e.g., `park_card.html`, `ride_card.html`) +- **Documentation**: Every component must include comprehensive documentation comments with usage examples +- **Parameters**: Components must use `` for parameter definition with sensible defaults + +#### Standardized Card Components +The following standardized components are available and MUST be used instead of custom implementations: + +##### Park Card Component (`templates/cotton/park_card.html`) +- **Usage**: `` +- **Features**: Supports both list and grid modes, status badges, operator info, stats +- **Required for**: All park listing and display use cases + +##### Ride Card Component (`templates/cotton/ride_card.html`) +- **Usage**: `` +- **Features**: Image handling, status badges, stats grid, special features, manufacturer info +- **Required for**: All ride listing and display use cases + +#### Implementation Requirements +- **No Duplication**: Do not create new card templates that duplicate existing Cotton component functionality +- **Consistent Styling**: All components must follow established Tailwind CSS patterns and design system +- **Responsive Design**: Components must include proper responsive breakpoints and mobile-first design +- **Accessibility**: All components must include proper ARIA labels and semantic HTML +- **Performance**: Components should be optimized for rendering performance and minimize template complexity + +#### Legacy Template Migration +- **Existing Templates**: When modifying existing templates, refactor them to use Cotton components +- **Gradual Migration**: Priority should be given to high-traffic pages and frequently modified templates +- **Testing Required**: All migrations must include thorough testing to ensure functionality preservation + +#### Exceptions +The only acceptable reasons to NOT use Django Cotton components are: +- Technical limitations that prevent Cotton usage in specific contexts +- Performance-critical pages where component overhead is measurably problematic +- Temporary prototyping (with clear migration path to Cotton components) + +All exceptions must be documented with justification and include a plan for eventual Cotton migration. + ## Enforcement These rules are MANDATORY and must be followed in all development work. Any violation should be immediately corrected.