# Project Rules and Guidelines
- Please read and understand the RULES.md file before proceeding with any tasks.
- As you progress with project for successful completions you can add rules to remember them later.

## General Guidelines
- All text must be translatable using Laravel's translation system
- Maintain dark mode compatibility across all components
- Use Alpine.js for frontend interactivity
- Keep consistent styling with the existing UI

## Code Standards
- Follow PSR-12 for PHP code
- Use Laravel's best practices
- Keep code DRY (Don't Repeat Yourself)

## Configuration Management

### tools.php Configuration
1. Always update `config/tools.php` when making changes to any tool
2. When modifying a tool's implementation:
   - Add new CSS/JS file references if new dependencies are added
   - Remove CSS/JS file references when dependencies are removed
   - Update any other relevant configuration settings
3. Ensure the configuration matches the actual implementation
4. Keep the configuration clean and free of unused references

### Tool Implementation Guidelines
1. When replacing components (e.g., editors):
   - Remove all related CSS/JS file references from `tools.php`
   - Update any dependent code in the tool's view file
   - Ensure proper cleanup of old dependencies

2. When adding new features:
   - Add necessary CSS/JS file references to `tools.php`
   - Document any new dependencies
   - Follow the existing pattern for configuration structure

4. **Multiple Results Display**:
   - When a tool can return multiple results:
     - Choose the most appropriate display pattern based on the data type and complexity
     - Simple results can use alert boxes for consistency
     - Complex results may require custom-designed cards, tables, or other components
     - Maintain consistent styling within the chosen display pattern
     - Provide copy functionality where appropriate
     - Ensure the display pattern is responsive and works in both light/dark modes

5. **Error State Management**:
   - Tools should implement proper error state management:
     - Clear error messages for each possible error case
     - Input validation before processing
     - User-friendly error display in the UI
     - Consistent error styling across all tools

6. **Tool Component Structure**:
   - Each tool should follow the standard component structure:
     - Livewire component in `app/Http/Livewire/Tools/`
     - View file in `resources/views/modules/tools/[tool-name]/livewire.blade.php`
     - Language file in `lang/en/webtools/tools/[tool-name].php`
     - Settings class in `app/Settings/Tools/[ToolName]Settings.php`

## Code Organization

### File Structure
1. Keep tool-specific files in their respective directories
2. Maintain consistent file naming conventions
3. Organize assets (CSS/JS) in appropriate directories
4. Views should be in `resources/views/modules/tools/`
5. Language files should be in `lang/en/webtools/tools/`
6. CSS files should be in `public/css/`
7. JavaScript files should be in `public/js/`

## UI/UX Guidelines
- Website is built with Bootstrap 5 - use Bootstrap classes and components
- Ensure all tools are responsive using Bootstrap's grid system
- Maintain consistent spacing using Bootstrap spacing utilities (m-*, p-*)
- Follow Bootstrap 5 conventions for components and utilities
- Follow accessibility best practices (ARIA labels, semantic HTML)
- Maintain proper dark/light mode support
- Keep consistent styling across tools
- Avoid custom CSS where Bootstrap utilities can be used
- Use Bootstrap's built-in form components and validation

### Help Text Guidelines
- Keep it simple and clean without icons
- Use opacity for subtle emphasis
- Maintain WCAG 2.1 AA compliance for contrast
- Use Bootstrap's background utilities

### CSS Styling Guidelines
1. Bootstrap Classes:
   - Use Bootstrap's built-in classes as they are
   - Do not override colors or styles of Bootstrap classes
   - Examples: btn-primary, btn-secondary, form-control, text-white

2. Custom Classes:
   - Create custom classes for tool-specific styling
   - Use descriptive names that reflect the component's purpose
   - Example: calculator-display, tool-output, etc.

3. Dark Mode Implementation:
   - Use the .dark class prefix for dark mode styles
   - Only apply dark mode styles to custom classes
   - Format: .dark .custom-class { ... }
   - Example:
     ```css
     .calculator-display {
         background-color: #fff;
         color: #212529;
     }
     .dark .calculator-display {
         background-color: var(--bs-dark);
         color: var(--bs-light);
     }
     ```

4. Color Management:
   - Use Bootstrap's CSS variables for dark mode colors
   - Keep light mode colors in custom classes
   - Use var(--bs-*) for dark mode theme colors
   - Example: var(--bs-dark), var(--bs-light), var(--bs-primary)

5. Responsive Design:
   - Use Bootstrap's responsive classes
   - Keep custom styles responsive
   - Test in both light and dark modes

## Performance Guidelines
- Optimize asset loading
- Minimize unnecessary DOM updates
- Use proper caching strategies
- Keep bundle sizes optimized

## Security Guidelines
- Sanitize all user inputs
- Use CSRF protection
- Follow Laravel's security best practices
- Keep dependencies updated

## Testing Guidelines
- Write unit tests for critical functionality
- Test dark mode compatibility
- Ensure cross-browser compatibility
- Test responsive design
- Verify tool functionality after configuration changes
- Check for broken references
- Ensure proper asset loading

## Documentation Guidelines
- Keep README files updated
- Document all new features
- Maintain clear code comments
- Update language files for new text
- Document significant changes

## Version Control Guidelines
- Use meaningful commit messages
- Keep commits focused and atomic
- Follow Git best practices
- Maintain clean git history

## Maintenance

1. Regular review of `tools.php` for:
   - Unused dependencies
   - Outdated references
   - Configuration consistency

2. Documentation updates when:
   - Adding new tools
   - Modifying existing tools
   - Changing dependencies

3. Cleanup procedures:
   - Remove unused files
   - Update configuration
   - Update documentation

## Tool Development Guidelines

1. **Component Replacement**
   - When replacing components (e.g., editors):
     - Remove all related CSS/JS file references from `tools.php`
     - Update any dependent code in the tool's view file
     - Ensure proper cleanup of old dependencies

2. **New Feature Addition**
   - When adding new features:
     - Add necessary CSS/JS file references to `tools.php`
     - Document any new dependencies
     - Follow the existing pattern for configuration structure

3. **Code Organization**
   - Keep tool-specific files in their respective directories
   - Maintain consistent file naming conventions
   - Organize assets (CSS/JS) in appropriate directories

4. **Testing and Verification**
   - Verify tool functionality after configuration changes
   - Check for broken references
   - Ensure proper asset loading

5. **Multiple Results Display**:
   - When a tool can return multiple results:
     - Choose the most appropriate display pattern based on the data type and complexity
     - Simple results can use alert boxes for consistency
     - Complex results may require custom-designed cards, tables, or other components
     - Maintain consistent styling within the chosen display pattern
     - Provide copy functionality where appropriate
     - Ensure the display pattern is responsive and works in both light/dark modes

6. **Error State Management**:
   - Tools should implement proper error state management:
     - Clear error messages for each possible error case
     - Input validation before processing
     - User-friendly error display in the UI
     - Consistent error styling across all tools

7. **Tool Component Structure**:
   - Each tool should follow the standard component structure:
     - Livewire component in `app/Http/Livewire/Tools/`
     - View file in `resources/views/modules/tools/[tool-name]/livewire.blade.php`
     - Language file in `lang/en/webtools/tools/[tool-name].php`
     - Settings class in `app/Settings/Tools/[ToolName]Settings.php`