climaybe 1.7.2 → 1.8.0

package/src/cursor/rules/liquid-doc-rules.mdc

@@ -0,0 +1,595 @@
+---
+globs: snippets/*.liquid,blocks/*.liquid
+alwaysApply: false
+---
+# LiquidDoc Documentation Rules for Electric Maybe Shopify Theme
+
+## Overview
+This document establishes comprehensive documentation standards for all Liquid snippets and blocks in the Electric Maybe Shopify theme project. Following these rules ensures consistent, maintainable, and developer-friendly code documentation that integrates with Shopify's LiquidDoc tooling.
+
+## Core Documentation Standards
+
+### Required Structure for All Liquid Files
+Every snippet (`.liquid` files in `snippets/`) and block (`.liquid` files in `blocks/`) must include LiquidDoc documentation at the top of the file:
+
+```liquid
+{%- doc -%}
+[Component description - one clear sentence explaining purpose]
+
+[Detailed description - 2-3 sentences explaining functionality, use cases, and key features]
+
+@param {type} param_name - Parameter description
+@param {type} [optional_param] - Optional parameter description
+
+@example
+{% render 'component-name', param: value %}
+
+@example
+{% render 'component-name',
+  param1: value1,
+  param2: value2
+%}
+{%- enddoc -%}
+```
+
+### Documentation Tag Requirements
+- **Required**: All snippets and blocks must have `{%- doc -%}` block
+- **Position**: Must be the first content in the file (after any initial comments)
+- **Format**: Use `{%- doc -%}` and `{%- enddoc -%}` with whitespace control
+- **Content**: Must include description, parameters, and at least one example
+
+## Parameter Documentation Standards
+
+### Parameter Format
+```
+@param {type} param_name - Description of the parameter
+@param {type} [optional_param] - Optional parameter description
+```
+
+### Supported Parameter Types
+- `{string}` - Text values, URLs, class names
+- `{number}` - Numeric values, sizes, counts
+- `{boolean}` - True/false values, flags
+- `{object}` - Complex Liquid objects (product, collection, etc.)
+
+### Parameter Naming Conventions
+- Use `snake_case` for parameter names
+- Wrap optional parameters in square brackets: `[param_name]`
+- Use descriptive names that clearly indicate purpose
+- Avoid abbreviations unless widely understood
+
+### Parameter Description Requirements
+- Clear, concise explanation of purpose
+- Include default values when applicable
+- Mention any constraints or limitations
+- Reference related parameters when relevant
+
+## Example Documentation Standards
+
+### Example Format Requirements
+- Include at least one basic usage example
+- Include one complex example showing multiple parameters
+- Use realistic, practical values
+- Demonstrate common use cases
+- Show proper Liquid syntax formatting
+
+### Multi-line Example Format
+```liquid
+@example
+{% render 'component-name',
+  param1: 'value1',
+  param2: 42,
+  param3: true
+%}
+```
+
+## Component-Specific Documentation Rules
+
+### Atomic Components (`a--*.liquid`)
+- Focus on reusability and flexibility
+- Document all styling parameters
+- Include accessibility considerations
+- Show responsive behavior examples
+
+### Molecular Components (`m--*.liquid`)
+- Document composition of atomic components
+- Explain interaction patterns
+- Include state management parameters
+- Show integration examples
+
+### Section Components (`s--*.liquid`)
+- Document layout and structure parameters
+- Include content management parameters
+- Show responsive breakpoint behavior
+- Document theme customizer integration
+
+### Block Components (`blocks/*.liquid`)
+- Document content editing parameters
+- Include layout and styling options
+- Show theme editor integration
+- Document dynamic content handling
+
+## Accessibility Documentation
+
+### Required Accessibility Parameters
+For components that affect accessibility, document:
+- `aria_label` - Screen reader text
+- `aria_hidden` - Visibility control
+- `role` - ARIA role attributes
+- `tabindex` - Keyboard navigation
+
+### Accessibility Examples
+```liquid
+@example
+{% render 'a--icon', 
+  icon: 'search',
+  aria_label: 'Search products',
+  class: 'sr-only'
+%}
+```
+
+## Performance Documentation
+
+### Performance Parameters
+Document performance-related parameters:
+- `lazy_loading` - Image loading behavior
+- `preload` - Resource preloading
+- `debounce` - Event handling optimization
+- `cache` - Caching behavior
+
+## Error Handling Documentation
+
+### Error Parameters
+Document error handling parameters:
+- `fallback` - Fallback content
+- `error_message` - Error display text
+- `required` - Parameter requirement flags
+
+## Theme Integration Documentation
+
+### Theme Customizer Parameters
+Document theme editor integration:
+- `settings` - Theme setting references
+- `customizable` - Customization flags
+- `presets` - Preset configurations
+
+## Code Quality Standards
+
+### Documentation Validation
+- All parameters must be used in the component
+- Parameter types must match usage
+- Examples must be syntactically correct
+- Descriptions must be clear and accurate
+
+### Consistency Requirements
+- Use consistent terminology across components
+- Follow established naming conventions
+- Maintain consistent formatting
+- Use consistent example patterns
+
+## File Organization Standards
+
+### Documentation Structure
+1. **Component Description** - One clear sentence
+2. **Detailed Description** - 2-3 sentences explaining functionality
+3. **Required Parameters** - All mandatory parameters
+4. **Optional Parameters** - All optional parameters with defaults
+5. **Basic Example** - Simple usage demonstration
+6. **Advanced Example** - Complex usage with multiple parameters
+
+### Documentation Comments
+- Use clear, professional language
+- Avoid technical jargon unless necessary
+- Include practical use cases
+- Reference related components when relevant
+
+## Integration with Development Tools
+
+### Theme Check Integration
+Documentation must pass all Theme Check validations:
+- `UniqueDocParamNames` - No duplicate parameter names
+- `ValidDocParamTypes` - Valid parameter types
+- `UnusedDocParam` - All documented parameters used
+- `MissingRenderSnippetArguments` - Required parameters provided
+
+### Editor Integration
+Documentation enables:
+- Hover documentation in code editors
+- Code completion for parameters
+- Parameter validation warnings
+- Type checking for values
+
+## Maintenance Standards
+
+### Documentation Updates
+- Update documentation when parameters change
+- Add new parameters to documentation
+- Remove deprecated parameters
+- Update examples for new functionality
+
+### Review Process
+- Review documentation during code reviews
+- Validate examples work correctly
+- Ensure parameter descriptions are accurate
+- Check for consistency across components
+
+## Examples of Good Documentation
+
+### Atomic Component Example
+```liquid
+{%- doc -%}
+Icon component for displaying SVG icons with customizable styling and animations.
+
+This component provides a comprehensive set of icons including social media, navigation, UI elements, and e-commerce specific icons. Icons are rendered as inline SVG with customizable colors, sizes, and stroke widths.
+
+@param {string} icon - The icon name to display (required)
+@param {string} [class] - Additional CSS classes to apply to the SVG element
+@param {string} [color] - Icon color (defaults to 'currentColor')
+@param {number} [width] - Icon width in pixels (defaults to 24)
+@param {number} [height] - Icon height in pixels (defaults to 24)
+@param {string} [stroke] - Stroke width classes (defaults to 'stroke-base lg:stroke-lg')
+@param {boolean} [animate] - Whether to apply animation classes for interactive states
+
+@example
+{% render 'a--icon', icon: 'search' %}
+
+@example
+{% render 'a--icon', 
+  class: 'hover:opacity-50',
+  icon: 'chevron-d', 
+  color: '#000000', 
+  stroke: 'stroke-lg',
+  width: 32, 
+  height: 32,
+  animate: true 
+%}
+{%- enddoc -%}
+```
+
+### Molecular Component Example
+```liquid
+{%- doc -%}
+Product card component for displaying product information in grid layouts.
+
+This component renders a complete product card with image, title, price, and action buttons. It supports various display modes, hover effects, and responsive layouts. Includes built-in lazy loading and accessibility features.
+
+@param {object} product - Product object from Shopify (required)
+@param {string} [class] - Additional CSS classes for the card container
+@param {boolean} [show_vendor] - Display vendor name (defaults to false)
+@param {boolean} [show_rating] - Display product rating (defaults to true)
+@param {string} [image_size] - Product image size ('small', 'medium', 'large')
+@param {boolean} [lazy_load] - Enable lazy loading for images (defaults to true)
+@param {string} [badge_text] - Custom badge text to display
+
+@example
+{% render 'm--product-card', product: product %}
+
+@example
+{% render 'm--product-card',
+  product: product,
+  class: 'hover:shadow-lg',
+  show_vendor: true,
+  image_size: 'large',
+  badge_text: 'New'
+%}
+{%- enddoc -%}
+```
+
+## Compliance Checklist
+
+Before committing any Liquid file, ensure:
+
+- [ ] Documentation block is present at file top
+- [ ] Component description is clear and concise
+- [ ] All parameters are documented with types
+- [ ] Optional parameters are marked with brackets
+- [ ] At least one basic example is provided
+- [ ] At least one advanced example is provided
+- [ ] Parameter descriptions are accurate and helpful
+- [ ] Examples use realistic, practical values
+- [ ] Documentation passes Theme Check validation
+- [ ] Accessibility parameters are documented when relevant
+- [ ] Performance parameters are documented when relevant
+- [ ] Error handling is documented when relevant
+
+## References
+
+- [Shopify LiquidDoc Documentation](https://shopify.dev/docs/storefronts/themes/tools/liquid-doc)
+- [Theme Check Documentation](https://shopify.dev/docs/storefronts/themes/tools/theme-check)
+- [Liquid Template Language](https://shopify.dev/docs/api/liquid)
+- [Shopify Theme Development Best Practices](https://shopify.dev/docs/storefronts/themes/best-practices) # LiquidDoc Documentation Rules for Electric Maybe Shopify Theme
+
+## Overview
+This document establishes comprehensive documentation standards for all Liquid snippets and blocks in the Electric Maybe Shopify theme project. Following these rules ensures consistent, maintainable, and developer-friendly code documentation that integrates with Shopify's LiquidDoc tooling.
+
+## Core Documentation Standards
+
+### Required Structure for All Liquid Files
+Every snippet (`.liquid` files in `snippets/`) and block (`.liquid` files in `blocks/`) must include LiquidDoc documentation at the top of the file:
+
+```liquid
+{%- doc -%}
+[Component description - one clear sentence explaining purpose]
+
+[Detailed description - 2-3 sentences explaining functionality, use cases, and key features]
+
+@param {type} param_name - Parameter description
+@param {type} [optional_param] - Optional parameter description
+
+@example
+{% render 'component-name', param: value %}
+
+@example
+{% render 'component-name',
+  param1: value1,
+  param2: value2
+%}
+{%- enddoc -%}
+```
+
+### Documentation Tag Requirements
+- **Required**: All snippets and blocks must have `{%- doc -%}` block
+- **Position**: Must be the first content in the file (after any initial comments)
+- **Format**: Use `{%- doc -%}` and `{%- enddoc -%}` with whitespace control
+- **Content**: Must include description, parameters, and at least one example
+
+## Parameter Documentation Standards
+
+### Parameter Format
+```
+@param {type} param_name - Description of the parameter
+@param {type} [optional_param] - Optional parameter description
+```
+
+### Supported Parameter Types
+- `{string}` - Text values, URLs, class names
+- `{number}` - Numeric values, sizes, counts
+- `{boolean}` - True/false values, flags
+- `{object}` - Complex Liquid objects (product, collection, etc.)
+
+### Parameter Naming Conventions
+- Use `snake_case` for parameter names
+- Wrap optional parameters in square brackets: `[param_name]`
+- Use descriptive names that clearly indicate purpose
+- Avoid abbreviations unless widely understood
+
+### Parameter Description Requirements
+- Clear, concise explanation of purpose
+- Include default values when applicable
+- Mention any constraints or limitations
+- Reference related parameters when relevant
+
+## Example Documentation Standards
+
+### Example Format Requirements
+- Include at least one basic usage example
+- Include one complex example showing multiple parameters
+- Use realistic, practical values
+- Demonstrate common use cases
+- Show proper Liquid syntax formatting
+
+### Multi-line Example Format
+```liquid
+@example
+{% render 'component-name',
+  param1: 'value1',
+  param2: 42,
+  param3: true
+%}
+```
+
+## Component-Specific Documentation Rules
+
+### Atomic Components (`a--*.liquid`)
+- Focus on reusability and flexibility
+- Document all styling parameters
+- Include accessibility considerations
+- Show responsive behavior examples
+
+### Molecular Components (`m--*.liquid`)
+- Document composition of atomic components
+- Explain interaction patterns
+- Include state management parameters
+- Show integration examples
+
+### Section Components (`s--*.liquid`)
+- Document layout and structure parameters
+- Include content management parameters
+- Show responsive breakpoint behavior
+- Document theme customizer integration
+
+### Block Components (`blocks/*.liquid`)
+- Document content editing parameters
+- Include layout and styling options
+- Show theme editor integration
+- Document dynamic content handling
+
+## Accessibility Documentation
+
+### Required Accessibility Parameters
+For components that affect accessibility, document:
+- `aria_label` - Screen reader text
+- `aria_hidden` - Visibility control
+- `role` - ARIA role attributes
+- `tabindex` - Keyboard navigation
+
+### Accessibility Examples
+```liquid
+@example
+{% render 'a--icon', 
+  icon: 'search',
+  aria_label: 'Search products',
+  class: 'sr-only'
+%}
+```
+
+## Performance Documentation
+
+### Performance Parameters
+Document performance-related parameters:
+- `lazy_loading` - Image loading behavior
+- `preload` - Resource preloading
+- `debounce` - Event handling optimization
+- `cache` - Caching behavior
+
+## Error Handling Documentation
+
+### Error Parameters
+Document error handling parameters:
+- `fallback` - Fallback content
+- `error_message` - Error display text
+- `required` - Parameter requirement flags
+
+## Theme Integration Documentation
+
+### Theme Customizer Parameters
+Document theme editor integration:
+- `settings` - Theme setting references
+- `customizable` - Customization flags
+- `presets` - Preset configurations
+
+## Code Quality Standards
+
+### Documentation Validation
+- All parameters must be used in the component
+- Parameter types must match usage
+- Examples must be syntactically correct
+- Descriptions must be clear and accurate
+
+### Consistency Requirements
+- Use consistent terminology across components
+- Follow established naming conventions
+- Maintain consistent formatting
+- Use consistent example patterns
+
+## File Organization Standards
+
+### Documentation Structure
+1. **Component Description** - One clear sentence
+2. **Detailed Description** - 2-3 sentences explaining functionality
+3. **Required Parameters** - All mandatory parameters
+4. **Optional Parameters** - All optional parameters with defaults
+5. **Basic Example** - Simple usage demonstration
+6. **Advanced Example** - Complex usage with multiple parameters
+
+### Documentation Comments
+- Use clear, professional language
+- Avoid technical jargon unless necessary
+- Include practical use cases
+- Reference related components when relevant
+
+## Integration with Development Tools
+
+### Theme Check Integration
+Documentation must pass all Theme Check validations:
+- `UniqueDocParamNames` - No duplicate parameter names
+- `ValidDocParamTypes` - Valid parameter types
+- `UnusedDocParam` - All documented parameters used
+- `MissingRenderSnippetArguments` - Required parameters provided
+
+### Editor Integration
+Documentation enables:
+- Hover documentation in code editors
+- Code completion for parameters
+- Parameter validation warnings
+- Type checking for values
+
+## Maintenance Standards
+
+### Documentation Updates
+- Update documentation when parameters change
+- Add new parameters to documentation
+- Remove deprecated parameters
+- Update examples for new functionality
+
+### Review Process
+- Review documentation during code reviews
+- Validate examples work correctly
+- Ensure parameter descriptions are accurate
+- Check for consistency across components
+
+## Examples of Good Documentation
+
+### Atomic Component Example
+```liquid
+{%- doc -%}
+Icon component for displaying SVG icons with customizable styling and animations.
+
+This component provides a comprehensive set of icons including social media, navigation, UI elements, and e-commerce specific icons. Icons are rendered as inline SVG with customizable colors, sizes, and stroke widths.
+
+@param {string} icon - The icon name to display (required)
+@param {string} [class] - Additional CSS classes to apply to the SVG element
+@param {string} [color] - Icon color (defaults to 'currentColor')
+@param {number} [width] - Icon width in pixels (defaults to 24)
+@param {number} [height] - Icon height in pixels (defaults to 24)
+@param {string} [stroke] - Stroke width classes (defaults to 'stroke-base lg:stroke-lg')
+@param {boolean} [animate] - Whether to apply animation classes for interactive states
+
+@example
+{% render 'a--icon', icon: 'search' %}
+
+@example
+{% render 'a--icon', 
+  class: 'hover:opacity-50',
+  icon: 'chevron-d', 
+  color: '#000000', 
+  stroke: 'stroke-lg',
+  width: 32, 
+  height: 32,
+  animate: true 
+%}
+{%- enddoc -%}
+```
+
+### Molecular Component Example
+```liquid
+{%- doc -%}
+Product card component for displaying product information in grid layouts.
+
+This component renders a complete product card with image, title, price, and action buttons. It supports various display modes, hover effects, and responsive layouts. Includes built-in lazy loading and accessibility features.
+
+@param {object} product - Product object from Shopify (required)
+@param {string} [class] - Additional CSS classes for the card container
+@param {boolean} [show_vendor] - Display vendor name (defaults to false)
+@param {boolean} [show_rating] - Display product rating (defaults to true)
+@param {string} [image_size] - Product image size ('small', 'medium', 'large')
+@param {boolean} [lazy_load] - Enable lazy loading for images (defaults to true)
+@param {string} [badge_text] - Custom badge text to display
+
+@example
+{% render 'm--product-card', product: product %}
+
+@example
+{% render 'm--product-card',
+  product: product,
+  class: 'hover:shadow-lg',
+  show_vendor: true,
+  image_size: 'large',
+  badge_text: 'New'
+%}
+{%- enddoc -%}
+```
+
+## Compliance Checklist
+
+Before committing any Liquid file, ensure:
+
+- [ ] Documentation block is present at file top
+- [ ] Component description is clear and concise
+- [ ] All parameters are documented with types
+- [ ] Optional parameters are marked with brackets
+- [ ] At least one basic example is provided
+- [ ] At least one advanced example is provided
+- [ ] Parameter descriptions are accurate and helpful
+- [ ] Examples use realistic, practical values
+- [ ] Documentation passes Theme Check validation
+- [ ] Accessibility parameters are documented when relevant
+- [ ] Performance parameters are documented when relevant
+- [ ] Error handling is documented when relevant
+
+## References
+
+- [Shopify LiquidDoc Documentation](https://shopify.dev/docs/storefronts/themes/tools/liquid-doc)
+- [Theme Check Documentation](https://shopify.dev/docs/storefronts/themes/tools/theme-check)
+- [Liquid Template Language](https://shopify.dev/docs/api/liquid)
+- [Shopify Theme Development Best Practices](https://shopify.dev/docs/storefronts/themes/best-practices)