climaybe 1.7.3 → 1.8.1

package/src/cursor/rules/commit-rules.mdc

@@ -0,0 +1,286 @@
+---
+description: Git commit conventions for Shopify theme projects (emoji + type + description)
+globs:
+  - "**/*"
+alwaysApply: false
+---
+# Commit Rules for Shopify Theme Projects
+
+## Commit Convention
+
+Follow conventional commit format with emoji prefixes for all commits:
+
+```
+<emoji> <type>: <description>
+```
+
+## Commit Types
+
+### 🔨 `fix:` - Bug Fixes
+- Fixes for broken functionality
+- Bug patches and error corrections
+- Performance fixes
+
+**Examples:**
+```
+🔨 fix: modal close button not working
+🔨 fix: cart total calculation error
+🔨 fix: mobile navigation menu overlap
+```
+
+### 🚀 `feat:` - New Features
+- New functionality additions
+- Feature implementations
+- New components or sections
+
+**Examples:**
+```
+🚀 feat: add product quick view functionality
+🚀 feat: implement infinite scroll for collections
+🚀 feat: add newsletter signup modal
+```
+
+### ♻️ `refactor:` - Code Refactoring
+- Code restructuring without changing functionality
+- Performance improvements
+- Code cleanup and optimization
+
+**Examples:**
+```
+♻️ refactor: optimize product card rendering
+♻️ refactor: restructure JavaScript build system
+♻️ refactor: improve web component lifecycle management
+```
+
+### 🎨 `style:` - UI/Styling Changes
+- Visual design updates
+- CSS/styling modifications
+- Layout adjustments
+
+**Examples:**
+```
+🎨 style: update button hover states
+🎨 style: improve mobile responsive design
+🎨 style: adjust typography spacing
+```
+
+### 🗑️ `remove:` - Code Removal
+- Removing unused code
+- Deleting deprecated features
+- Cleaning up legacy code
+
+**Examples:**
+```
+🗑️ remove: unused JavaScript functions
+🗑️ remove: deprecated Liquid snippets
+🗑️ remove: old CSS classes
+```
+
+### 🚧 `wip:` - Work in Progress
+- Incomplete features
+- Experimental code
+- Development in progress
+- Temporary implementations
+
+**Examples:**
+```
+🚧 wip: product quick view modal (incomplete)
+🚧 wip: experimental infinite scroll implementation
+🚧 wip: temporary mobile navigation solution
+```
+
+### 📝 `docs:` - Documentation
+- README updates
+- Code documentation
+- Comment additions
+- Documentation improvements
+
+**Examples:**
+```
+📝 docs: update installation instructions
+📝 docs: add component usage examples
+📝 docs: improve code comments
+```
+
+### ✨ `ai:` - AI Rules & Automation
+- AI-generated code improvements
+- Automated refactoring
+- Code optimization rules
+- AI-assisted development
+
+**Examples:**
+```
+✨ ai: implement automated code formatting rules
+✨ ai: optimize web component performance with AI suggestions
+✨ ai: add intelligent error handling patterns
+```
+
+### 🔧 `chore:` - Maintenance Tasks
+- Build system updates
+- Configuration changes
+- Dependency management
+- Development tool updates
+
+**Examples:**
+```
+🔧 chore: update Tailwind CSS to v4
+🔧 chore: add new npm scripts
+🔧 chore: update Shopify CLI version
+```
+
+### ⬆️ `upgrade:` - Dependencies
+- Package updates
+- Version upgrades
+- Security patches
+
+**Examples:**
+```
+⬆️ upgrade: update Shopify CLI to latest version
+⬆️ upgrade: bump Tailwind CSS dependencies
+⬆️ upgrade: security patch for npm packages
+```
+
+## Commit Message Guidelines
+
+### Description Format
+- Use imperative mood ("add" not "added")
+- Keep descriptions concise but descriptive
+- Start with lowercase letter
+- No period at the end
+
+### Good Examples
+```
+🔨 fix: resolve cart total calculation error
+🚀 feat: implement product quick view modal
+♻️ refactor: optimize web component performance
+🎨 style: improve mobile navigation layout
+```
+
+### Bad Examples
+```
+🔨 fix: fixed the bug
+🚀 feat: Added new feature
+♻️ refactor: Refactored code for better performance.
+🎨 style: Updated styling
+```
+
+## Multi-line Commit Messages
+
+For complex changes, use multi-line format:
+
+```
+🔨 fix: resolve cart total calculation error
+
+- Fix floating point precision issues
+- Add proper error handling for invalid prices
+- Update cart API response validation
+
+Closes #123
+```
+
+## Breaking Changes
+
+For breaking changes, use `!` after the type and include migration notes:
+
+```
+♻️ refactor!: restructure web component API
+
+BREAKING CHANGE: Component initialization now requires config object
+Migration: Update component calls to use new API format
+
+- Old: new MyComponent()
+- New: new MyComponent({ config: {} })
+```
+
+## Scope (Optional)
+
+You can add scope to specify the area of change:
+
+```
+🔨 fix(web-components): resolve event listener memory leak
+🚀 feat(sections): add new product grid layout
+🎨 style(header): improve mobile navigation
+```
+
+## File-specific Commits
+
+When committing changes to specific file types, include context:
+
+```
+🔨 fix(liquid): resolve template rendering error in product page
+🚀 feat(js): add new utility functions for DOM manipulation
+🎨 style(css): update button component styling
+```
+
+## Commit Frequency
+
+- Commit frequently with small, focused changes
+- Each commit should represent a single logical change
+- Avoid large commits with multiple unrelated changes
+- Use feature branches for complex changes
+
+## Pre-commit Checklist
+
+Before committing, ensure:
+- [ ] Code follows project standards
+- [ ] All tests pass (if applicable)
+- [ ] No console errors in browser
+- [ ] Responsive design works on all breakpoints
+- [ ] Accessibility requirements met
+- [ ] Performance impact considered
+
+## Branch Naming
+
+Use descriptive branch names:
+- `feature/product-quick-view`
+- `fix/cart-calculation-bug`
+- `refactor/web-components`
+- `style/mobile-navigation`
+
+## Pull Request Guidelines
+
+When creating pull requests:
+- Use descriptive titles
+- Include detailed descriptions
+- Reference related issues
+- Add screenshots for UI changes
+- Test on multiple devices/browsers
+
+## Examples by Category
+
+### Web Components
+```
+🔨 fix: resolve web component memory leak in disconnectedCallback
+🚀 feat: add new electric-slider component with touch support
+♻️ refactor: optimize web component event handling
+```
+
+### Shopify Sections
+```
+🔨 fix: resolve section rendering error in collection page
+🚀 feat: add new product recommendations section
+🎨 style: improve section spacing and layout
+```
+
+### JavaScript
+```
+🔨 fix: resolve async/await error in cart API
+🚀 feat: add utility functions for DOM manipulation
+♻️ refactor: optimize JavaScript build system
+```
+
+### CSS/Styling
+```
+🎨 style: update button component design system
+🎨 style: improve mobile responsive breakpoints
+🎨 style: add new color palette variables
+```
+
+### Liquid Templates
+```
+🔨 fix: resolve Liquid syntax error in product template
+🚀 feat: add new product variant selector
+♻️ refactor: optimize Liquid template performance
+```
+
+This commit convention ensures clear, consistent, and informative commit messages that help track project progress and facilitate collaboration.

package/src/cursor/rules/cursor-rule-template.mdc

@@ -0,0 +1,66 @@
+---
+description: How to add or edit Cursor rules in our project
+globs: 
+alwaysApply: false
+---
+# Cursor Rules Location
+
+How to add new cursor rules to the project
+
+1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
+    ```
+    .cursor/rules/
+    ├── your-rule-name.mdc
+    ├── another-rule.mdc
+    └── ...
+    ```
+
+2. Follow the naming convention:
+    - Use kebab-case for filenames
+    - Always use .mdc extension
+    - Make names descriptive of the rule's purpose
+
+3. Directory structure:
+    ```
+    PROJECT_ROOT/
+    ├── .cursor/
+    │   └── rules/
+    │       ├── your-rule-name.mdc
+    │       └── ...
+    └── ...
+    ```
+
+4. Never place rule files:
+    - In the project root
+    - In subdirectories outside .cursor/rules
+    - In any other location
+
+5. Cursor rules have the following structure:
+
+````
+---
+description: Short description of the rule's purpose
+globs: optional/path/pattern/**/* 
+alwaysApply: false
+---
+# Rule Title
+
+Main content explaining the rule with markdown formatting.
+
+1. Step-by-step instructions
+2. Code examples
+3. Guidelines
+
+Example:
+```typescript
+// Good example
+function goodExample() {
+  // Implementation following guidelines
+}
+
+// Bad example
+function badExample() {
+  // Implementation not following guidelines
+}
+```
+````

package/src/cursor/rules/examples/section-example.liquid

@@ -0,0 +1,52 @@
+{% liquid
+  assign section_id = section.settings.custom_id | default: section.id
+  assign section_class = 'section-' | append: section.type
+%}
+
+<section
+  id="{{ section_id }}"
+  class="{{ section_class }}"
+  style="
+    --section-padding-top: {{ section.settings.padding_top }}px;
+    --section-padding-bottom: {{ section.settings.padding_bottom }}px;
+  "
+>
+  <div class="page-width">
+    {% content_for 'blocks' %}
+  </div>
+</section>
+
+{% stylesheet %}
+.{{ section_class }} {
+  padding-top: var(--section-padding-top, 40px);
+  padding-bottom: var(--section-padding-bottom, 40px);
+}
+{% endstylesheet %}
+
+{% schema %}
+{
+  "name": "t:names.section_name",
+  "tag": "section",
+  "class": "section-name",
+  "blocks": [
+    {"type": "@theme"},
+    {"type": "@app"}
+  ],
+  "settings": [
+    {
+      "type": "range",
+      "id": "padding_top",
+      "label": "t:settings.padding",
+      "min": 0,
+      "max": 100,
+      "default": 40,
+      "unit": "px"
+    }
+  ],
+  "presets": [
+    {
+      "name": "t:names.section_name"
+    }
+  ]
+}
+{% endschema %}

package/src/cursor/rules/examples/snippet-example.liquid

@@ -0,0 +1,83 @@
+{% doc %}
+  Product Card Snippet Template
+
+  @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 card_class - {String} Additional CSS classes
+
+  @example
+  {% render 'product-card',
+       product: product,
+       show_vendor: true,
+       image_ratio: 'square'
+    %}
+{% enddoc %}
+
+{% 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 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
+
+  # Build CSS classes
+  assign card_classes = 'product-card'
+  if card_class != blank
+    assign card_classes = card_classes | append: ' ' | append: card_class
+  endif
+  if image_ratio != 'adapt'
+    assign card_classes = card_classes | append: ' product-card--' | append: image_ratio
+  endif
+%}
+
+<div
+  class="{{ card_classes }}"
+  data-product-id="{{ product.id }}"
+>
+  <div class="product-card__media">
+    {% if product.featured_image %}
+      <a
+        href="{{ product.url }}"
+        class="product-card__link"
+      >
+        {{
+          product.featured_image
+          | image_url: width: 800
+          | image_tag: alt: product.featured_image.alt
+          | default: product.title, loading: 'lazy', class: 'product-card__image'
+        }}
+      </a>
+    {% else %}
+      <div class="product-card__placeholder">
+        {{ 'product-1' | placeholder_svg_tag: 'product-card__placeholder-svg' }}
+      </div>
+    {% endif %}
+  </div>
+
+  <div class="product-card__info">
+    <h3 class="product-card__title">
+      <a href="{{ product.url }}">{{ product.title | escape }}</a>
+    </h3>
+
+    {% if show_vendor and product.vendor != blank %}
+      <p class="product-card__vendor">{{ product.vendor | escape }}</p>
+    {% endif %}
+
+    {% render 'price', product: product, show_compare_at: true %}
+
+    {% if show_quick_add and product.available %}
+      <div class="product-card__actions">
+        {% render 'product-form', product: product, form_type: 'quick-add', show_quantity: false %}
+      </div>
+    {% endif %}
+  </div>
+</div>

package/src/cursor/rules/figma-design-system.mdc

@@ -0,0 +1,182 @@
+---
+description: Rules for implementing Figma designs using the Figma MCP server. Covers component organization, styling conventions, design tokens, asset handling, and the required Figma-to-code workflow for this Shopify theme (Liquid + Tailwind + native JS).
+globs:
+  - "sections/**/*.liquid"
+  - "snippets/**/*.liquid"
+  - "_styles/**/*.css"
+  - "assets/*.css"
+  - "_scripts/**/*.js"
+alwaysApply: false
+---
+
+# Figma Design System Rules — Voldt Theme
+
+This document defines how to translate Figma designs into code for this project. The theme is a **Shopify theme** (Liquid templates, Tailwind CSS v4, native JavaScript web components). Figma MCP output is typically React + Tailwind; treat that as design reference only and implement using this project’s stack and conventions.
+
+---
+
+## 1. Design System Structure
+
+### 1.1 Token Definitions
+
+**Location and format**
+
+- **Primitives (colors, z-index):** `_styles/01_theme/01_primitives.css`  
+  - Raw color scales: `--color-dune-*`, `--color-abbey-*`, `--color-dust-*`, `--color-blue-*`, system colors, `--layer-*`.
+- **Sizes (spacing, breakpoints, borders, grid):** `_styles/02_base/02.01_sizes.css`  
+  - Spacing: `--px-s-*`, `--py-s-*`, `--gaps-x-*`, `--gaps-y-*`, `--mx-s-outer`, `--height-b-*`, `--height-icon-*`.  
+  - Breakpoints: `--breakpoint-lg: 60rem`.  
+  - Border/stroke: `--border-*`, `--stroke-*`.  
+  - Grid: `--grid-columns-base`, `--grid-gutter-base`, `--grid-margin-base`, etc.
+- **Semantic colors:** `_styles/02_base/02.02_colors.css`  
+  - Use these, not raw primitives: `--background-color-surface`, `--background-color-subtle`, `--background-color-emphasis`, `--background-color-accent`, `--text-color-primary`, `--text-color-secondary`, `--text-color-on-accent`, `--border-color-primary`, `--border-color-secondary`.  
+  - Color schemes: utilities `color-schema-primary`, `color-schema-secondary`, `color-schema-muted`, `color-schema-accent-1`, `color-schema-accent-2`, `color-schema-accent-3`, `color-schema-contrast`.
+- **Typography:** `_styles/02_base/02.03_typography.css`  
+  - Font: `--font-body`, `--font-heading`, `--font-weight-*`.  
+  - Utilities: `text-body`, `text-body-lg`, `text-ui-base`, `text-caption`, `display-1`–`display-3`, heading classes `.h1`–`.h6`.
+
+**Rules**
+
+- IMPORTANT: Never hardcode hex/hsl colors in Liquid or CSS. Use semantic tokens (e.g. `bg-surface`, `text-primary`, `border-secondary`) or Tailwind theme values that reference these tokens.
+- Spacing and layout must use the project scale (e.g. `px-s-inner`, `py-s-base`, `gap-x-b-base`, `mx-s-outer`) or Tailwind utilities that map to them.
+- Typography must use the project’s font and size utilities (e.g. `text-body`, `font-heading`, `.h2`).
+
+### 1.2 Component Library
+
+**Where components live**
+
+- **Sections (full-width, schema-driven):** `sections/*.liquid` — e.g. `sections/s--hero-banner.liquid`, `sections/s--featured-collection.liquid`.
+- **Snippets (reusable UI):**  
+  - Atoms: `snippets/a--*.liquid` (e.g. `a--icon.liquid`, `a--button.liquid`, `a--input.liquid`).  
+  - Molecules: `snippets/m--*.liquid` (e.g. `m--product-card.liquid`, `m--accordion.liquid`, `m--modal.liquid`).  
+  - Feature-specific: `snippets/product--*.liquid`, `snippets/cart--*.liquid`, `snippets/header--*.liquid`, etc.
+- **Web components (JS):** `_scripts/*.js` — e.g. `electric-modal.js`, `electric-slider.js`, `electric-disclosure.js`. Reference implementation: `_scripts/electric-modal.js`.
+
+**Architecture**
+
+- No React/Vue. UI is Liquid (sections + snippets) plus native JS web components.
+- New UI from Figma: prefer adding or composing existing snippets/sections; add new snippets/sections only when no fit exists.
+- Sections must have a valid `{% schema %}` and semantic HTML; snippets must have LiquidDoc `{%- doc -%}` and follow `.cursor/rules/snippets.mdc` and `.cursor/rules/liquid.mdc`.
+
+### 1.3 Frameworks & Libraries
+
+- **Templating:** Liquid only (Shopify theme).
+- **Styling:** Tailwind CSS v4. Entry: `_styles/main.css` (imports Tailwind, tokens, component CSS). Compiled output: `assets/style.css`.
+- **Script:** Native JS only (no React/Vue). Web components with `#` private fields, AbortController for listeners, JSDoc; see `.cursor/rules/javascript-standards.mdc`.
+- **Build:** Tailwind processes `_styles/main.css`; content sources (for class scanning) are listed in `_styles/main.css` (`@source` for layout, blocks, sections, snippets, templates, assets).
+
+### 1.4 Asset Management
+
+- **Theme assets:** `assets/` — CSS, JS, and static files. Reference in Liquid with `{{ 'filename.css' | asset_url }}` or `{{ 'filename.js' | asset_url }}`.
+- **Images:** Use Shopify CDN via filters: `{{ image | image_url: width: N }}` for responsive widths; use `srcset` where appropriate (see existing snippets/sections).
+- **Icons:** Do not add new icon packages. Use the icon system below (inline SVG via `a--icon` or assets from Figma MCP when provided).
+- **Figma MCP assets:** If the Figma MCP server returns a localhost (or other) URL for an image/SVG, use that source directly. Do not replace with placeholders when a real URL is given.
+- Store any downloaded assets from Figma in `assets/` and reference via `asset_url`.
+
+### 1.5 Icon System
+
+- **Definition:** Icons are inline SVGs in `snippets/a--icon.liquid`, selected by name via `icon: 'name'`.
+- **Usage:** `{% render 'a--icon', icon: 'search', size: 'base', class: '...' %}`. Parameters: `icon` (required), `class`, `color`, `size` (xxs|xs|sm|base|lg|xl), `width`/`height`, `stroke`, `animate`, `aria_label`, `aria_hidden`, etc. See LiquidDoc in `a--icon.liquid`.
+- **Naming:** kebab-case (e.g. `chevron-d`, `arrow-r-up`, `circle-arrow-r`). Add new icons in the same file as new `when 'name'` branches; keep `fill="none"` and use `{{ color }}` or `currentColor` for strokes/fills.
+- **Sizing:** Prefer `size` (uses `--height-icon-*` tokens); or `width`/`height` for explicit dimensions. Stroke from size or `stroke` param (`stroke-sm`, `stroke-base`, etc.).
+
+### 1.6 Styling Approach
+
+- **Methodology:** Utility-first with Tailwind. Custom utilities and theme in `_styles/main.css` and `_styles/02_base/*.css`, `_styles/01_theme/*.css`.
+- **CRITICAL — Static classes only:** Tailwind scans at build time; Liquid runs on the server. Do not build class names with Liquid variables (e.g. no `duration-{{ x }}`, `text-{{ color }}`). Use fixed classes or conditionals that output full class names, e.g. `{% if size == 'sm' %}text-sm{% else %}text-base{% endif %}`.
+- **Responsive:** Mobile-first. Use `md:` and `lg:` prefixes; breakpoints align with `theme(--breakpoint-md)` and `theme(--breakpoint-lg)`.
+- **Semantic tokens in Tailwind:** Use `bg-surface`, `text-primary`, `border-secondary`, etc., which map to the CSS variables in `02.02_colors.css`. Do not introduce new ad-hoc color names; extend tokens in `_styles/` if needed.
+- **Custom component CSS:** Add in `_styles/` (e.g. `_styles/atoms/`, `_styles/molecules/`) and import from `_styles/main.css`.
+
+### 1.7 Project Structure
+
+```
+_layout/theme.liquid     # Main layout
+_scripts/                # Web components and utilities (native JS)
+_styles/                 # Tailwind entry, tokens, component CSS
+  main.css
+  01_theme/01_primitives.css
+  02_base/02.01_sizes.css, 02.02_colors.css, 02.03_typography.css
+  atoms/, molecules/, core/
+assets/                  # Compiled CSS/JS and static assets
+sections/                # Liquid section files
+snippets/                # Reusable Liquid snippets (a--*, m--*, etc.)
+templates/               # Page templates
+locales/                 # Translation files
+config/                  # Theme settings
+```
+
+- **Feature organization:** Sections and snippets are named by feature or type (e.g. `product--main`, `cart--drawer`, `s--hero-banner`, `m--product-card`). Follow existing naming (prefix + `--` + descriptor).
+
+---
+
+## 2. Figma MCP Integration Rules
+
+### 2.1 Required Flow (do not skip)
+
+1. Run **get_design_context** for the exact node(s) to implement.
+2. If the response is too large or truncated, run **get_metadata** to get a high-level map, then **get_design_context** again for only the required node(s).
+3. Run **get_screenshot** for a visual reference of the node/variant.
+4. After you have both design context and screenshot, download any assets needed (use MCP asset/localhost sources when provided), then implement.
+5. Implement in **this stack:** Liquid sections/snippets + Tailwind (and _styles tokens) + native JS if needed. Do not ship React/Vue or arbitrary new frameworks.
+6. Validate against the Figma screenshot for 1:1 look and behavior before marking complete.
+
+### 2.2 Implementation Rules
+
+- Treat Figma MCP output (e.g. React + Tailwind) as **design and behavior reference**, not as final code. Translate to Liquid + Tailwind + this theme’s tokens and components.
+- **Reuse existing snippets/sections** from `snippets/` and `sections/` instead of duplicating (e.g. buttons → `a--button`, icons → `a--icon`, cards → `m--*` cards, modals → `m--modal` / electric-modal).
+- Use the project’s **color system** (semantic tokens from `02.02_colors.css`), **typography** (`02.03_typography.css`, utilities), and **spacing/sizes** (`02.01_sizes.css`, Tailwind utilities that use them).
+- **Tailwind:** Only static class names; map Figma colors to semantic tokens (e.g. `bg-surface`, `text-primary`); use project breakpoints and spacing scale.
+- Respect **accessibility** (WCAG 2.1 AA): semantic HTML, ARIA where needed, keyboard and screen reader support; see `.cursor/rules/accessibility-rules.mdc`.
+- Respect **JS standards**: no new dependencies; if adding behavior, use native JS/web components per `.cursor/rules/javascript-standards.mdc`.
+- Aim for **1:1 visual parity** with the Figma design and validate with the screenshot.
+
+### 2.3 Asset Handling
+
+- The Figma MCP server can serve image and SVG assets. When it returns a **localhost (or other) source** for an image or SVG, use that source directly.
+- IMPORTANT: Do not add or rely on new icon libraries; use `snippets/a--icon.liquid` or assets provided by Figma MCP.
+- IMPORTANT: Do not use or create placeholders when a real asset URL is provided by the MCP.
+- Store downloaded assets in `assets/` and reference them via `{{ 'filename' | asset_url }}` in Liquid.
+
+---
+
+## 3. Project-Specific Conventions
+
+### 3.1 Liquid
+
+- Follow `.cursor/rules/liquid.mdc`: e.g. assign computed values before passing to `render`; no inline `append` in `render` parameters; valid tags/filters only.
+- Use `{%- doc -%}` and LiquidDoc for all new snippets; document params and examples per `.cursor/rules/liquid-doc-rules.mdc` and `.cursor/rules/snippets.mdc`.
+
+### 3.2 Sections
+
+- Every section: valid `{% schema %}`, semantic HTML, section-scoped classes. Follow `.cursor/rules/sections.mdc` and `.cursor/rules/schemas.mdc` for schema definitions.
+
+### 3.3 Accessibility
+
+- Semantic structure, ARIA where needed, keyboard and focus behavior, WCAG 2.1 AA. See `.cursor/rules/accessibility-rules.mdc`. Use the accessibility-pass skill when asked for an a11y audit.
+
+### 3.4 Performance
+
+- No layout thrashing; batch reads/writes; use requestAnimationFrame for animations; lazy-load images where appropriate. JS: AbortController, cleanup in disconnectedCallback, performance targets from project-overview (e.g. init < 16ms).
+
+### 3.5 Code Quality
+
+- JS: JSDoc for public APIs, private `#` fields, try/catch around critical work. Liquid: LiquidDoc and parameter defaults/validation. Tailwind: static classes and semantic tokens only.
+
+---
+
+## 4. Quick Reference: Mapping Figma to This Theme
+
+| Figma / MCP output     | This theme |
+|------------------------|------------|
+| React component        | Liquid section or snippet(s) |
+| Tailwind arbitrary colors | Semantic tokens: `bg-surface`, `text-primary`, `border-secondary`, etc. |
+| Tailwind spacing       | Project scale: `px-s-inner`, `gap-x-b-base`, `py-s-base`, etc. |
+| Icon component         | `{% render 'a--icon', icon: 'name', size: 'base' %}` |
+| Button                 | `{% render 'a--button', ... %}` or `a--button-tw` as per project |
+| Modal / overlay        | `m--modal` snippet + `_scripts/electric-modal.js` pattern |
+| Images                 | `{{ image \| image_url: width: N }}`; responsive with `srcset` |
+| New SVG icon           | Add in `snippets/a--icon.liquid` as new `when 'icon-name'` |
+| New color/size token   | Add in `_styles/02_base/` or `01_theme/` and use via Tailwind/utilities |
+
+Use this document together with the Figma MCP flow (get_design_context → get_screenshot → implement → validate) so that every Figma-driven change stays consistent with this design system and stack.