---
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/        # Source: web components and JS utilities (edit here)
_styles/         # Source: Tailwind/CSS entrypoint (_styles/main.css)
_schemas/        # Source: section/block schema definitions
assets/          # GENERATED build outputs + static assets (do not hand-edit generated files)
sections/        # Liquid section files
snippets/        # Reusable Liquid snippets
templates/       # Page templates
locales/         # Translation files
config/          # Theme settings
```

## Build Outputs vs Source

`assets/` contains both static assets and **generated** build outputs. The CLI (`climaybe serve` / `climaybe build`) compiles sources into `assets/` and regenerates them on every save and in CI. Always edit the **source**, never the generated output:

| Source (edit this) | Generated output (do NOT edit) |
| --- | --- |
| `_scripts/main.js` | `assets/index.js` |
| `_scripts/<name>.js` (top-level entry) | `assets/<name>.js` |
| `_styles/main.css` | `assets/style.css` |
| `_schemas/<name>.js` / `.json` | injected `{% schema %}` block in `sections/*.liquid` & `blocks/*.liquid` |

Notes:
- JS bundling follows `import` statements: files imported by a top-level `_scripts/*.js` entry are **inlined** into that bundle, not emitted separately.
- Any manual edit to `assets/index.js`, `assets/*.js`, or `assets/style.css` is **overwritten** on the next save (watcher) or build. Make JS changes in `_scripts/`, CSS in `_styles/`, and schema changes in `_schemas/`.
- **Orphan cleanup:** on a full build (`climaybe build` / `climaybe build-scripts`, and the `serve` watcher), any `assets/*.js` that the current `_scripts/` build does not produce is **deleted** as a stale artifact. To add a new JS asset, create a top-level `_scripts/<name>.js` entry — do not drop a hand-written `.js` into `assets/` (it will be removed). Liquid-processed assets (`*.js.liquid`) and non-JS files are never touched.

## 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