climaybe 1.7.2 → 1.8.0

package/src/cursor/rules/liquid.mdc

@@ -0,0 +1,228 @@
+---
+description: Liquid syntax standards — render tag, valid tags/filters, formatting
+globs:
+  - "**/*.liquid"
+alwaysApply: false
+---
+
+# Liquid Syntax Standards
+
+## Render tag: assign before passing computed values
+
+**Do not use filters or `append` inside a `render` tag's parameter values.** Assign the computed string to a variable first, then pass that variable.
+
+```liquid
+{%- assign props = 'data-section-id="' | append: section.id | append: '"' -%}
+{% render 'a--button', properties: props %}
+```
+
+**Wrong:** `render 'snippet', properties: 'data-id="' | append: section.id | append: '"'` — inline append in a render parameter is invalid/unreliable. Always assign, then pass.
+
+## Valid Tags with Parameters
+
+**Control Flow:**
+
+- `if condition` / `endif` - Conditional logic
+- `unless condition` / `endunless` - Negative conditional
+- `case variable` / `when value` / `endcase` - Switch statement
+- `for item in array` / `endfor` - Loop with optional `limit:`, `offset:`
+
+**Variable Assignment:**
+
+- `assign variable = value` - Create variable
+- `capture variable` / `endcapture` - Capture output
+- `increment variable` - Add 1 to counter
+- `decrement variable` - Subtract 1 from counter
+
+**Template Inclusion:**
+
+- `render 'snippet-name'` - Include snippet
+- `render 'snippet-name', param: value` - With parameters
+- `section 'section-name'` - Include section
+
+**Forms:**
+
+- `form 'cart'` / `endform` - Cart form
+- `form 'product'` / `endform` - Product form
+- `form 'customer_login'` / `endform` - Login form
+
+**Other:**
+
+- `paginate collection.products by 12` / `endpaginate` - Paginate results
+- `liquid` / `endliquid` - Multiline Liquid block
+- `comment` / `endcomment` - Block comments
+- `raw` / `endraw` - Output without processing
+
+## Valid Filters
+
+**Array Filters:**
+
+- `compact` - Remove nil values: `array | compact`
+- `concat` - Join arrays: `array | concat: array`
+- `find` - Find object: `array | find: property, value`
+- `where` - Filter objects: `array | where: property, value`
+- `map` - Extract property: `array | map: property`
+- `sort` - Sort array: `array | sort`
+- `reverse` - Reverse order: `array | reverse`
+- `first` - First item: `array | first`
+- `last` - Last item: `array | last`
+- `size` - Count items: `array | size`
+
+**String Filters:**
+
+- `escape` - HTML escape: `string | escape`
+- `truncate` - Limit length: `string | truncate: 150`
+- `handleize` - URL handle: `string | handleize`
+- `replace` - Replace text: `string | replace: 'old', 'new'`
+- `split` - Split string: `string | split: 'delimiter'`
+- `upcase` - Uppercase: `string | upcase`
+- `downcase` - Lowercase: `string | downcase`
+- `capitalize` - Capitalize: `string | capitalize`
+
+**Money Filters:**
+
+- `money` - Format price: `price | money`
+- `money_with_currency` - With symbol: `price | money_with_currency`
+- `money_without_currency` - No symbol: `price | money_without_currency`
+
+**Media Filters:**
+
+- `image_url` - Responsive image: `image | image_url: width: 800`
+- `image_tag` - Complete img tag: `image | image_tag`
+- `asset_url` - Theme asset: `'style.css' | asset_url`
+
+## Syntax Rules
+
+- Use `{% liquid %}` for multiline code blocks
+- Use `{% # comment %}` for inline comments
+- Never invent new filters, tags, or objects
+- Follow proper tag closing order (last opened, first closed)
+- Use object dot notation: `product.title` not `product['title']`
+- Respect object scope and availability
+
+## Render Tag Formatting Rules
+
+### Within Liquid Blocks
+When using `render` within a `{% liquid %}` block, all parameters must be on the same line:
+
+**✅ Do this (single line within liquid block):**
+```liquid
+{% liquid
+  render 'm--electric-slider', id: 'slider-1', feed: content, per_row_mobile: 1, per_row_tablet: 2, per_row_desktop: 2, gap: 'gap-x-4', nav: false
+%}
+```
+
+**❌ Don't do this (multiline within liquid block):**
+```liquid
+{% liquid
+  render 'm--electric-slider', 
+    id: 'slider-1',
+    feed: content,
+    per_row_mobile: 1,
+    per_row_tablet: 2,
+    per_row_desktop: 2
+%}
+```
+
+### Standalone Render Tags
+When using `render` as a standalone tag (outside of `{% liquid %}` blocks), you can and should use multiline formatting for readability:
+
+**✅ Do this (multiline standalone render):**
+```liquid
+{% render 'm--electric-slider',
+  id: 'slider-1',
+  feed: content,
+  per_row_mobile: 1,
+  per_row_tablet: 2,
+  per_row_desktop: 2,
+  gap: 'gap-x-4',
+  nav: false
+%}
+```
+
+**✅ Also acceptable (single line standalone render):**
+```liquid
+{% render 'm--electric-slider', id: 'slider-1', feed: content, per_row_mobile: 1 %}
+```
+
+## Inline Variables Pattern
+
+For props that are relatively straightforward, prefer to inline the liquid instead of declaring extra variables. In smaller components it doesn't make a big difference, but in bigger ones it helps not having to scroll up and down to know what is being applied where.
+
+**✅ Do this (inline approach):**
+
+```liquid
+<div
+  class='component component--{{ settings.style_modifier }}'
+  style='
+    color: {{ settings.text_color }};
+    {% if settings.show_border %}
+      border: 1px solid {{ settings.border_color }};
+    {% endif %}
+  '
+>
+  <h2>{{ 'sections.component.title' | t }}</h2>
+
+  {{ content | truncate: settings.max_length | default: 200 }}
+
+  <a
+    href='{{ link_url }}'
+    class='link--{{ settings.link_style | default: 'primary' }}'
+  >
+    {{ 'general.read_more' | t }}
+  </a>
+</div>
+```
+
+**❌ Don't do this (variable declaration approach):**
+
+```liquid
+{% liquid
+  assign component_class = 'component component--' | append: settings.style_modifier
+  assign text_color = settings.text_color
+  assign truncate_length = settings.max_length | default: 200
+  assign link_class = 'link--' | append: settings.link_style | default: 'primary'
+%}
+
+{% capture component_style %}
+  color: {{ text_color }};
+  {% if settings.show_border %}
+    border: 1px solid {{ settings.border_color }};
+  {% endif %}
+{% endcapture %}
+
+<div
+  class='{{ component_class }}'
+  style='{{ component_style }}'
+>
+  <h2>{{ 'sections.component.title' | t }}</h2>
+
+  {{ content | truncate: truncate_length }}
+
+  <a
+    href='{{ link_url }}'
+    class='{{ link_class }}'
+  >
+    {{ 'general.read_more' | t }}
+  </a>
+</div>
+```
+
+**Exceptions:**
+
+- When Liquid filter parameters require string values and complex logic cannot be inlined
+- When the same complex calculation is used multiple times
+- When the logic is extremely complex and would harm readability
+- When you need to build a string incrementally with conditional parts
+
+**Benefits:**
+
+- Easier to understand what's being applied where
+- No need to scroll up and down to find variable definitions
+- Reduces cognitive load in larger components
+- Makes the code more maintainable
+
+- Easier to understand what's being applied where
+- No need to scroll up and down to find variable definitions
+- Reduces cognitive load in larger components
+- Makes the code more maintainable

package/src/cursor/rules/project-overview.mdc

@@ -0,0 +1,81 @@
+---
+description: Electric Maybe Shopify Theme project overview and development standards
+globs:
+  - "**/*"
+alwaysApply: true
+---
+# Electric Maybe Shopify Theme Development Rules
+
+## Project Overview
+This is a professional Shopify theme project for Electric Maybe agency. All code must follow the highest standards for performance, accessibility, and maintainability.
+
+## JavaScript Development Standards
+
+All JavaScript code must follow the comprehensive standards defined in `javascript-standards.mdc`. 
+
+### Core Requirements
+- **Zero external dependencies** - Native browser APIs only
+- **Performance first** - Operations < 16ms
+- **Accessibility always** - WCAG 2.1 AA minimum
+- **Memory conscious** - Proper cleanup, no leaks
+- **Documentation complete** - JSDoc for all public APIs
+
+### Key Patterns
+- Private fields/methods with `#` syntax (never `_` or `private`)
+- AbortController for all event listeners
+- Try-catch boundaries around critical operations
+- RequestAnimationFrame for animations
+- Debounce/throttle for expensive operations
+- Custom events with typed detail objects
+
+### Reference Implementation
+Use `_scripts/electric-modal.js` as the gold standard for all web components.
+
+## Liquid Template Standards
+
+### Sections (sections/*.liquid)
+- Semantic HTML structure
+- ARIA attributes for accessibility
+- Performance-optimized asset loading
+- Responsive design patterns
+- Schema settings properly typed
+
+### Snippets (snippets/*.liquid)
+- Reusable and modular
+- Clear parameter documentation
+- DRY principles
+- Consistent naming conventions
+
+## CSS/Tailwind Standards
+- Mobile-first responsive design
+- Utility-first with Tailwind classes
+- Custom properties for theming
+- Performance-optimized animations
+- Print styles where appropriate
+
+## File Organization
+```
+_scripts/        # Web components and utilities
+assets/          # Compiled CSS/JS and static assets
+sections/        # Liquid section files
+snippets/        # Reusable Liquid snippets
+templates/       # Page templates
+locales/         # Translation files
+config/          # Theme settings
+```
+
+## Code Review Requirements
+All code must pass the checklist in `javascript-standards.mdc` before merge.
+
+## Browser Support
+- Chrome 74+ (for private class fields)
+- Firefox 90+
+- Safari 15+
+- Edge 79+
+
+## Performance Targets
+- Component initialization: < 16ms
+- Event handlers: < 8ms
+- Animation frames: 60fps
+- First Contentful Paint: < 1.5s
+- Time to Interactive: < 3.5s

package/src/cursor/rules/schemas.mdc

@@ -0,0 +1,150 @@
+---
+description: Schema design rules — minimal settings, translation keys, no redundancy
+globs:
+  - "sections/**/*.liquid"
+  - "**/sections/*.liquid"
+  - "blocks/**/*.liquid"
+  - "**/blocks/*.liquid"
+alwaysApply: false
+---
+# Schema Design Rules for Electric Maybe Shopify Theme
+
+## Core Principles
+
+### 1. **Start Simple, Expand Gradually**
+- Begin with minimal, essential settings only
+- Add complexity only when there's a clear, demonstrated need
+- Ask for permission before adding multiple settings at once
+
+### 2. **Avoid Redundancy**
+- If text content exists in translation files (`en.default.json`), don't duplicate it in schema
+- Use translation keys for all text content, not schema text inputs
+- Schema should focus on functionality, not content
+
+### 3. **Question Every Setting**
+Before adding any schema setting, ask:
+- Is this truly necessary for the user?
+- Can this be handled by translation files instead?
+- Will this setting be used by most merchants?
+- Does this add value or just complexity?
+
+### 4. **Limit Settings Per Section**
+- **Maximum 5 settings per section** (excluding headers)
+- If more are needed, consider splitting into multiple sections
+- Group related settings under headers
+
+## Schema Setting Guidelines
+
+### **Essential Settings (Always Include)**
+- Link list selectors for menus
+- Image upload fields for key visuals
+- Color scheme selectors (if theme supports multiple schemes)
+
+### **Optional Settings (Add Only When Needed)**
+- Layout toggles (show/hide elements)
+- Spacing adjustments
+- Text alignment options
+- Background color/image options
+
+### **Avoid These Settings**
+- Text content inputs (use translation files)
+- Toggle switches for every element
+- Complex layout selectors
+- Settings that duplicate existing functionality
+
+## Implementation Rules
+
+### **Before Adding Settings**
+1. Check if the functionality can be achieved through:
+   - Translation files
+   - CSS classes
+   - Existing theme settings
+   - Liquid conditionals
+
+2. Consider the user experience:
+   - Will merchants actually use this setting?
+   - Is it intuitive and discoverable?
+   - Does it solve a real problem?
+
+3. Evaluate maintenance cost:
+   - Will this setting need updates?
+   - Does it create technical debt?
+   - Is it worth the complexity?
+
+### **When Adding Multiple Settings**
+- **Ask for permission first**
+- Explain the reasoning for each setting
+- Consider if they can be grouped or simplified
+- Test with a small subset first
+
+## Examples
+
+### ✅ Good Schema (Simple)
+```json
+{
+  "settings": [
+    {
+      "type": "link_list",
+      "id": "main_menu",
+      "label": "Main menu"
+    },
+    {
+      "type": "image_picker",
+      "id": "logo",
+      "label": "Logo"
+    }
+  ]
+}
+```
+
+### ❌ Bad Schema (Over-engineered)
+```json
+{
+  "settings": [
+    {
+      "type": "link_list",
+      "id": "main_menu",
+      "label": "Main menu"
+    },
+    {
+      "type": "checkbox",
+      "id": "show_menu",
+      "label": "Show menu",
+      "default": true
+    },
+    {
+      "type": "select",
+      "id": "menu_style",
+      "label": "Menu style",
+      "options": [
+        {"value": "horizontal", "label": "Horizontal"},
+        {"value": "vertical", "label": "Vertical"},
+        {"value": "dropdown", "label": "Dropdown"}
+      ]
+    },
+    {
+      "type": "range",
+      "id": "menu_spacing",
+      "min": 0,
+      "max": 50,
+      "step": 5,
+      "label": "Menu spacing"
+    }
+  ]
+}
+```
+
+## Review Process
+
+Before committing any schema changes:
+1. **Count the settings** - Keep under 5 per section
+2. **Check for redundancy** - Ensure no duplicate functionality
+3. **Verify necessity** - Each setting should solve a real problem
+4. **Consider alternatives** - Could this be handled differently?
+5. **Get approval** - For multiple settings or complex changes
+
+## Remember
+- **Simplicity is a feature**
+- **Less is more**
+- **When in doubt, leave it out**
+- **Ask before expanding** 

package/src/cursor/rules/sections.mdc

@@ -0,0 +1,25 @@
+---
+description: Section development standards — schema, structure, blocks, performance patterns
+globs:
+  - "sections/**/*.liquid"
+  - "**/sections/*.liquid"
+alwaysApply: false
+---
+# Section Development Standards
+
+## Section Requirements
+
+Every section must include:
+
+- `{% schema %}` tag with valid JSON
+- Proper HTML semantic structure
+- CSS scoping with section classes
+- Translation keys for all text
+
+## Section Patterns
+
+_(To be filled in on review.)_
+
+## Performance Patterns
+
+_(To be filled in on review.)_

package/src/cursor/rules/snippets.mdc

@@ -0,0 +1,134 @@
+---
+description: Snippet development standards — LiquidDoc, parameters, patterns
+globs:
+  - "snippets/**/*.liquid"
+  - "**/snippets/*.liquid"
+alwaysApply: false
+---
+# Snippet Development Standards
+
+## Snippet Documentation
+
+Every snippet must include JSDoc-style comments using LiquidDoc:
+
+```liquid
+{% doc %}
+  Product Card Component
+
+  Renders a product card with customizable options.
+
+  @param product {Object} Product object (required)
+  @param show_vendor {Boolean} Display vendor name (default: false)
+  @param show_quick_add {Boolean} Show quick add button (default: false)
+  @param image_ratio {String} Image aspect ratio (default: 'adapt')
+  @param lazy_load {Boolean} Enable lazy loading (default: true)
+  @param card_class {String} Additional CSS classes
+
+  @example
+    {% render 'product-card',
+       product: product,
+       show_vendor: true,
+       image_ratio: 'square'
+    %}
+{% enddoc %}
+```
+
+## Parameter Handling
+
+Always provide defaults and validate parameters:
+
+```liquid
+{% liquid
+  # Parameter validation and defaults
+  assign product = product | default: empty
+  assign show_vendor = show_vendor | default: false
+  assign show_quick_add = show_quick_add | default: false
+  assign image_ratio = image_ratio | default: 'adapt'
+  assign lazy_load = lazy_load | default: true
+  assign card_class = card_class | default: ''
+
+  # Early return if required parameters missing
+  unless product != empty
+    echo '<!-- Error: product parameter required for product-card snippet -->'
+    break
+  endunless
+%}
+```
+
+## Common Snippet Patterns
+
+**Icon Snippet:**
+```liquid
+{% comment %}
+  @param icon {String} Icon name (required)
+  @param size {String} Icon size class (default: 'icon--medium')
+  @param class {String} Additional classes
+{% endcomment %}
+
+{% liquid
+  assign icon = icon | default: ''
+  assign size = size | default: 'icon--medium'
+  assign class = class | default: ''
+
+  unless icon != blank
+    break
+  endunless
+%}
+
+<svg class="icon {{ size }} {{ class }}" aria-hidden="true" focusable="false">
+  <use href="#icon-{{ icon }}"></use>
+</svg>
+```
+
+**Price Snippet:**
+```liquid
+{% comment %}
+  @param product {Object} Product object (required)
+  @param show_compare_at {Boolean} Show compare at price (default: true)
+  @param show_unit_price {Boolean} Show unit price (default: false)
+{% endcomment %}
+
+{% liquid
+  assign show_compare_at = show_compare_at | default: true
+  assign show_unit_price = show_unit_price | default: false
+%}
+
+<div class="price">
+  <div class="price__regular">
+    {{ product.price | money }}
+  </div>
+
+  {% if show_compare_at and product.compare_at_price > product.price %}
+    <div class="price__compare-at">
+      <s>{{ product.compare_at_price | money }}</s>
+    </div>
+  {% endif %}
+
+  {% if show_unit_price and product.selected_or_first_available_variant.unit_price_measurement %}
+    <div class="price__unit">
+      {{ product.selected_or_first_available_variant.unit_price | money }}/
+      {%- if product.selected_or_first_available_variant.unit_price_measurement.reference_value != 1 -%}
+        {{ product.selected_or_first_available_variant.unit_price_measurement.reference_value }}
+      {%- endif -%}
+      {{ product.selected_or_first_available_variant.unit_price_measurement.reference_unit }}
+    </div>
+  {% endif %}
+</div>
+```
+
+## Testing Patterns
+
+Include testing scenarios in comments:
+
+```liquid
+{% comment %}
+  Test cases:
+  - Product with variants
+  - Product without image
+  - Product with compare_at_price
+  - Product with unit pricing
+  - Out of stock product
+{% endcomment %}
+```
+
+[snippet-example.liquid](mdc:.cursor/rules/examples/snippet-example.liquid)