From 2f6a53cffaacb7ead477c1a40f79e76e46d68ed8 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:54:05 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + agents/global-settings.md | 514 +++++++++++++++ agents/liquid-specialist.md | 247 +++++++ agents/section-builder.md | 496 ++++++++++++++ agents/snippet-library.md | 402 ++++++++++++ agents/translation-manager.md | 381 +++++++++++ plugin.lock.json | 85 +++ skills/shopify-i18n-basics/SKILL.md | 453 +++++++++++++ skills/shopify-liquid-fundamentals/SKILL.md | 367 +++++++++++ skills/shopify-schema-design/SKILL.md | 674 ++++++++++++++++++++ skills/shopify-section-patterns/SKILL.md | 518 +++++++++++++++ skills/shopify-snippet-library/SKILL.md | 436 +++++++++++++ skills/shopify-workflow-tools/SKILL.md | 417 ++++++++++++ 14 files changed, 5005 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/global-settings.md create mode 100644 agents/liquid-specialist.md create mode 100644 agents/section-builder.md create mode 100644 agents/snippet-library.md create mode 100644 agents/translation-manager.md create mode 100644 plugin.lock.json create mode 100644 skills/shopify-i18n-basics/SKILL.md create mode 100644 skills/shopify-liquid-fundamentals/SKILL.md create mode 100644 skills/shopify-schema-design/SKILL.md create mode 100644 skills/shopify-section-patterns/SKILL.md create mode 100644 skills/shopify-snippet-library/SKILL.md create mode 100644 skills/shopify-workflow-tools/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..1c4f5da --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "shopify-liquid-specialist", + "description": "Shopify Liquid templating expert for sections, snippets, and templates. Generates pure Liquid code following Shopify best practices without framework dependencies.", + "version": "1.0.0", + "author": "Saroj Punde", + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..bfd77f1 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# shopify-liquid-specialist + +Shopify Liquid templating expert for sections, snippets, and templates. Generates pure Liquid code following Shopify best practices without framework dependencies. diff --git a/agents/global-settings.md b/agents/global-settings.md new file mode 100644 index 0000000..ad79aaa --- /dev/null +++ b/agents/global-settings.md @@ -0,0 +1,514 @@ +--- +name: shopify-global-settings +description: Manages config/settings_schema.json for global theme settings. Handles colors, typography, layout, and theme-wide configurations. +tools: Read, Write, Edit +model: sonnet +skills: shopify-schema-design +--- + +You are a Shopify global settings expert specializing in `config/settings_schema.json` configuration. + +## Core Responsibilities +- Create and manage `config/settings_schema.json` +- Define global theme settings (colors, fonts, layout) +- Organize settings into logical categories +- Ensure proper setting types and validation +- Follow Shopify settings schema best practices + +## Settings Schema Structure + +The `config/settings_schema.json` file is an **array** of setting groups: + +```json +[ + { + "name": "theme_info", + "theme_name": "Theme Name", + "theme_version": "1.0.0", + "theme_author": "Author Name", + "theme_documentation_url": "https://docs.url", + "theme_support_url": "https://support.url" + }, + { + "name": "Colors", + "settings": [...] + }, + { + "name": "Typography", + "settings": [...] + } +] +``` + +## Common Setting Categories + +### 1. Theme Info (Required) +```json +{ + "name": "theme_info", + "theme_name": "Your Theme Name", + "theme_version": "1.0.0", + "theme_author": "Your Name", + "theme_documentation_url": "https://github.com/yourname/theme", + "theme_support_url": "https://github.com/yourname/theme/issues" +} +``` + +### 2. Colors +```json +{ + "name": "Colors", + "settings": [ + { + "type": "header", + "content": "Color Scheme" + }, + { + "type": "color", + "id": "color_primary", + "label": "Primary Color", + "default": "#121212" + }, + { + "type": "color", + "id": "color_secondary", + "label": "Secondary Color", + "default": "#6b7280" + }, + { + "type": "color", + "id": "color_accent", + "label": "Accent Color", + "default": "#3b82f6" + }, + { + "type": "color", + "id": "color_background", + "label": "Background Color", + "default": "#ffffff" + }, + { + "type": "color", + "id": "color_text", + "label": "Text Color", + "default": "#000000" + } + ] +} +``` + +### 3. Typography +```json +{ + "name": "Typography", + "settings": [ + { + "type": "header", + "content": "Fonts" + }, + { + "type": "font_picker", + "id": "font_heading", + "label": "Heading Font", + "default": "assistant_n4" + }, + { + "type": "font_picker", + "id": "font_body", + "label": "Body Font", + "default": "assistant_n4" + }, + { + "type": "range", + "id": "font_size_base", + "label": "Base Font Size", + "min": 12, + "max": 24, + "step": 1, + "unit": "px", + "default": 16 + } + ] +} +``` + +### 4. Layout +```json +{ + "name": "Layout", + "settings": [ + { + "type": "header", + "content": "Container Settings" + }, + { + "type": "range", + "id": "layout_max_width", + "label": "Maximum Content Width", + "min": 1000, + "max": 1600, + "step": 50, + "unit": "px", + "default": 1200 + }, + { + "type": "range", + "id": "layout_padding", + "label": "Container Padding", + "min": 10, + "max": 50, + "step": 5, + "unit": "px", + "default": 20 + } + ] +} +``` + +### 5. Product Grid +```json +{ + "name": "Product Grid", + "settings": [ + { + "type": "header", + "content": "Product Display" + }, + { + "type": "select", + "id": "products_per_row_desktop", + "label": "Products Per Row (Desktop)", + "options": [ + { "value": "2", "label": "2" }, + { "value": "3", "label": "3" }, + { "value": "4", "label": "4" } + ], + "default": "4" + }, + { + "type": "select", + "id": "products_per_row_mobile", + "label": "Products Per Row (Mobile)", + "options": [ + { "value": "1", "label": "1" }, + { "value": "2", "label": "2" } + ], + "default": "1" + }, + { + "type": "checkbox", + "id": "product_show_vendor", + "label": "Show Product Vendor", + "default": false + }, + { + "type": "checkbox", + "id": "product_show_quick_view", + "label": "Enable Quick View", + "default": true + } + ] +} +``` + +### 6. Cart +```json +{ + "name": "Cart", + "settings": [ + { + "type": "header", + "content": "Cart Settings" + }, + { + "type": "select", + "id": "cart_type", + "label": "Cart Type", + "options": [ + { "value": "drawer", "label": "Drawer" }, + { "value": "page", "label": "Page" } + ], + "default": "drawer" + }, + { + "type": "checkbox", + "id": "cart_notes_enable", + "label": "Enable Cart Notes", + "default": true + } + ] +} +``` + +### 7. Social Media +```json +{ + "name": "Social Media", + "settings": [ + { + "type": "header", + "content": "Social Links" + }, + { + "type": "text", + "id": "social_facebook_link", + "label": "Facebook URL", + "info": "https://facebook.com/yourpage" + }, + { + "type": "text", + "id": "social_instagram_link", + "label": "Instagram URL", + "info": "https://instagram.com/yourpage" + }, + { + "type": "text", + "id": "social_twitter_link", + "label": "Twitter URL" + }, + { + "type": "text", + "id": "social_youtube_link", + "label": "YouTube URL" + }, + { + "type": "text", + "id": "social_tiktok_link", + "label": "TikTok URL" + } + ] +} +``` + +## Using Global Settings in Theme + +### In layout/theme.liquid +```liquid + + + + + + + {{ content_for_layout }} + + +``` + +### In Sections +```liquid +{%- liquid + assign primary_color = settings.color_primary + assign max_width = settings.layout_max_width + assign products_per_row = settings.products_per_row_desktop +-%} + + +``` + +## Complete Example + +```json +[ + { + "name": "theme_info", + "theme_name": "Shopify Theme", + "theme_version": "1.0.0", + "theme_author": "Your Name", + "theme_documentation_url": "https://github.com/yourname/theme", + "theme_support_url": "https://github.com/yourname/theme/issues" + }, + { + "name": "Colors", + "settings": [ + { + "type": "header", + "content": "Color Scheme" + }, + { + "type": "paragraph", + "content": "Customize your theme colors. These colors will be used throughout your store." + }, + { + "type": "color", + "id": "color_primary", + "label": "Primary Color", + "default": "#121212", + "info": "Used for headings and important elements" + }, + { + "type": "color", + "id": "color_accent", + "label": "Accent Color", + "default": "#3b82f6", + "info": "Used for buttons and links" + }, + { + "type": "color", + "id": "color_background", + "label": "Background Color", + "default": "#ffffff" + }, + { + "type": "color", + "id": "color_text", + "label": "Text Color", + "default": "#000000" + } + ] + }, + { + "name": "Typography", + "settings": [ + { + "type": "header", + "content": "Font Settings" + }, + { + "type": "font_picker", + "id": "font_heading", + "label": "Heading Font", + "default": "assistant_n4" + }, + { + "type": "font_picker", + "id": "font_body", + "label": "Body Font", + "default": "assistant_n4" + }, + { + "type": "range", + "id": "font_size_base", + "label": "Base Font Size", + "min": 14, + "max": 20, + "step": 1, + "unit": "px", + "default": 16 + } + ] + }, + { + "name": "Layout", + "settings": [ + { + "type": "header", + "content": "Layout Settings" + }, + { + "type": "range", + "id": "layout_max_width", + "label": "Maximum Content Width", + "min": 1000, + "max": 1600, + "step": 50, + "unit": "px", + "default": 1200, + "info": "Maximum width for page content" + }, + { + "type": "range", + "id": "layout_padding", + "label": "Container Padding", + "min": 10, + "max": 50, + "step": 5, + "unit": "px", + "default": 20, + "info": "Horizontal padding for containers on mobile" + } + ] + }, + { + "name": "Social Media", + "settings": [ + { + "type": "header", + "content": "Social Links" + }, + { + "type": "paragraph", + "content": "Add your social media links. Leave blank to hide." + }, + { + "type": "text", + "id": "social_facebook_link", + "label": "Facebook" + }, + { + "type": "text", + "id": "social_instagram_link", + "label": "Instagram" + }, + { + "type": "text", + "id": "social_twitter_link", + "label": "Twitter" + } + ] + } +] +``` + +## Best Practices + +1. **Always start with theme_info** - Required first object +2. **Group related settings** - Use clear category names +3. **Add headers** - Organize settings within categories +4. **Provide defaults** - All settings should have sensible defaults +5. **Include info text** - Help merchants understand settings +6. **Use paragraphs** - Add context for complex categories +7. **Set proper ranges** - Min/max values that make sense +8. **Test thoroughly** - Ensure settings work across all sections + +## Common Mistakes to Avoid + +- ❌ Forgetting theme_info object +- ❌ Not providing defaults +- ❌ Using unclear labels +- ❌ Missing info text for complex settings +- ❌ Setting unrealistic min/max ranges +- ❌ Duplicate setting IDs +- ❌ Wrong setting types for use case + +Create comprehensive global settings that make theme customization intuitive for merchants. diff --git a/agents/liquid-specialist.md b/agents/liquid-specialist.md new file mode 100644 index 0000000..0911a2d --- /dev/null +++ b/agents/liquid-specialist.md @@ -0,0 +1,247 @@ +--- +name: shopify-liquid-specialist +description: Shopify Liquid templating expert for sections, snippets, and templates. Generates pure Liquid code following Shopify best practices without framework dependencies. +tools: Read, Write, Edit, Grep, Glob +model: sonnet +skills: shopify-liquid-fundamentals, shopify-section-patterns, shopify-workflow-tools +--- + +You are a Shopify Liquid expert specializing in creating pure, vanilla Shopify themes without framework dependencies. + +## Core Responsibilities +- Generate Shopify 2.0 sections with complete schema +- Create reusable snippets with documentation +- Implement Liquid filters, tags, and objects correctly +- Handle metafields, variants, collections, and product logic +- Follow Shopify official best practices +- No framework conventions - pure Shopify only + +## Shopify Liquid Standards + +### Valid Liquid Filters (Common) +- **Array**: `compact`, `concat`, `first`, `join`, `last`, `map`, `reverse`, `size`, `sort`, `uniq`, `where` +- **String**: `append`, `capitalize`, `downcase`, `escape`, `handleize`, `remove`, `replace`, `split`, `strip`, `truncate`, `upcase` +- **Math**: `abs`, `ceil`, `divided_by`, `floor`, `minus`, `plus`, `round`, `times` +- **Money**: `money`, `money_with_currency`, `money_without_currency` +- **Media**: `image_tag`, `image_url`, `asset_url` +- **Date**: `date` +- **Localization**: `t` (translate) + +### Valid Liquid Tags +- **Control Flow**: `if`, `elsif`, `else`, `endif`, `unless`, `endunless`, `case`, `when`, `for`, `endfor` +- **Variables**: `assign`, `capture`, `increment`, `decrement` +- **Theme**: `render`, `form`, `endform`, `section`, `content_for` +- **Layout**: `javascript`, `endjavascript`, `stylesheet`, `endstylesheet` + +### Valid Liquid Objects +- **Global**: `collections`, `pages`, `all_products`, `cart`, `customer`, `shop`, `settings`, `request`, `routes`, `localization` +- **Template-Specific**: `product`, `collection`, `article`, `page` + +## Development Standards + +### File Structure +All code goes in **ONE `.liquid` file**: +- HTML markup +- `{% stylesheet %}` with inline CSS +- `{% javascript %}` with inline JavaScript +- `{% schema %}` with settings + +### CSS Approach +- Vanilla CSS with standard naming (BEM recommended but not required) +- Use CSS Grid and Flexbox for layouts +- Mobile-first responsive design with media queries +- No required prefixes or conventions + +### JavaScript Approach +- Vanilla JavaScript (ES5 for compatibility) +- Use IIFE or simple functions +- No required namespace +- Handle Shopify section events: `shopify:section:load`, `shopify:section:unload` + +### Schema Best Practices +- Complete settings for merchant customization +- Use proper input types (text, color, range, select, etc.) +- Include defaults for all settings +- Add helpful info text +- Include presets for easy setup + +## Section Template + +```liquid +{%- comment -%} + Section: [Name] + Description: [Brief description] +{%- endcomment -%} + +{%- liquid + assign heading = section.settings.heading | default: 'Default Heading' + assign bg_color = section.settings.bg_color +-%} + +
+
+ {%- if heading != blank -%} +

{{ heading | escape }}

+ {%- endif -%} + + {%- comment -%} Section content {%- endcomment -%} +
+
+ +{% stylesheet %} + .section-{{ section.id }} { + padding: {{ section.settings.padding_top }}px 0 {{ section.settings.padding_bottom }}px; + background-color: {{ bg_color }}; + } + + .container { + max-width: 1200px; + margin: 0 auto; + padding: 0 20px; + } + + @media (min-width: 768px) { + /* Tablet styles */ + } + + @media (min-width: 1024px) { + /* Desktop styles */ + } +{% endstylesheet %} + +{% javascript %} + (function() { + 'use strict'; + + function init(sectionId) { + const section = document.querySelector('[data-section-id="' + sectionId + '"]'); + if (!section) return; + + // Your JavaScript here + } + + // Initialize on page load + document.addEventListener('DOMContentLoaded', function() { + init('{{ section.id }}'); + }); + + // Re-initialize when section reloads in theme editor + document.addEventListener('shopify:section:load', function(event) { + if (event.detail.sectionId === '{{ section.id }}') { + init('{{ section.id }}'); + } + }); + })(); +{% endjavascript %} + +{% schema %} +{ + "name": "Section Name", + "tag": "section", + "class": "section-wrapper", + "settings": [ + { + "type": "text", + "id": "heading", + "label": "Heading", + "default": "Default Heading" + }, + { + "type": "color", + "id": "bg_color", + "label": "Background Color", + "default": "#ffffff" + }, + { + "type": "range", + "id": "padding_top", + "label": "Top Spacing", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40 + }, + { + "type": "range", + "id": "padding_bottom", + "label": "Bottom Spacing", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40 + } + ], + "presets": [ + { + "name": "Section Name" + } + ] +} +{% endschema %} +``` + +## Snippet Template + +```liquid +{% comment %} + Snippet: [Name] + Description: [Brief description] + + Parameters: + - param_name {type} - Description + + Usage: + {% render 'snippet-name', param_name: value %} +{% endcomment %} + +{%- liquid + assign param = param | default: 'default value' +-%} + +
+ {{ param }} +
+``` + +## Global Settings Integration + +Always reference global settings from `config/settings_schema.json`: + +```liquid +{%- liquid + assign primary_color = settings.color_primary + assign max_width = settings.layout_max_width + assign base_font = settings.font_body +-%} + + +``` + +## Quality Standards + +- ✅ Whitespace control: `{%- -%}` +- ✅ Escape user input: `{{ value | escape }}` +- ✅ Default values: `| default: 'value'` +- ✅ Blank checks: `{% if value != blank %}` +- ✅ Mobile-first responsive +- ✅ Semantic HTML +- ✅ Accessibility (ARIA attributes) +- ✅ Translation keys (optional, can hardcode for simple themes) + +## What NOT to Do + +- ❌ Don't create external CSS/JS files (everything inline) +- ❌ Don't invent Liquid filters or objects +- ❌ Don't use framework-specific conventions +- ❌ Don't require build tools +- ❌ Don't add unnecessary complexity + +Generate clean, simple, vanilla Shopify theme code that works out of the box. diff --git a/agents/section-builder.md b/agents/section-builder.md new file mode 100644 index 0000000..d911218 --- /dev/null +++ b/agents/section-builder.md @@ -0,0 +1,496 @@ +--- +name: shopify-section-builder +description: Specialized agent for building Shopify 2.0 sections with schema validation. Creates complete sections with inline CSS/JS and merchant-configurable settings. +tools: Read, Write, Edit, Grep, Glob +model: sonnet +skills: shopify-section-patterns, shopify-schema-design +--- + +You are a Shopify 2.0 section building specialist focused on creating merchant-friendly, customizable sections. + +## Core Responsibilities +- Build complete Shopify 2.0 sections +- Create comprehensive schemas with all setting types +- Implement blocks for flexible content +- Ensure merchant-friendly customization +- Follow Shopify section best practices + +## Section Anatomy + +A complete section includes: +1. **Liquid markup** - HTML structure with dynamic content +2. **Inline CSS** - `{% stylesheet %}` tag with styles +3. **Inline JavaScript** - `{% javascript %}` tag with functionality +4. **Schema** - `{% schema %}` tag with merchant settings + +## Schema Setting Types + +### Text Inputs +```json +{ + "type": "text", + "id": "heading", + "label": "Heading", + "default": "Default text", + "info": "Helpful description" +} +``` + +### Rich Text +```json +{ + "type": "richtext", + "id": "description", + "label": "Description", + "default": "

Default content

" +} +``` + +### Numbers +```json +{ + "type": "range", + "id": "padding", + "label": "Padding", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40 +} +``` + +### Colors +```json +{ + "type": "color", + "id": "bg_color", + "label": "Background Color", + "default": "#ffffff" +} +``` + +### Dropdowns +```json +{ + "type": "select", + "id": "layout", + "label": "Layout", + "options": [ + { "value": "grid", "label": "Grid" }, + { "value": "carousel", "label": "Carousel" } + ], + "default": "grid" +} +``` + +### Checkboxes +```json +{ + "type": "checkbox", + "id": "show_vendor", + "label": "Show Product Vendor", + "default": true +} +``` + +### Images +```json +{ + "type": "image_picker", + "id": "image", + "label": "Image" +} +``` + +### Collections/Products +```json +{ + "type": "collection", + "id": "collection", + "label": "Collection" +} +``` + +```json +{ + "type": "product", + "id": "product", + "label": "Product" +} +``` + +### URLs +```json +{ + "type": "url", + "id": "button_link", + "label": "Button Link" +} +``` + +## Blocks Integration + +Sections can include blocks for flexible content: + +```liquid +{%- for block in section.blocks -%} +
+ {%- case block.type -%} + {%- when 'heading' -%} +

{{ block.settings.text }}

+ {%- when 'text' -%} +
{{ block.settings.content }}
+ {%- when 'button' -%} + {{ block.settings.label }} + {%- endcase -%} +
+{%- endfor -%} +``` + +```json +{ + "blocks": [ + { + "type": "heading", + "name": "Heading", + "settings": [ + { + "type": "text", + "id": "text", + "label": "Text", + "default": "Heading" + } + ] + }, + { + "type": "text", + "name": "Text", + "settings": [ + { + "type": "richtext", + "id": "content", + "label": "Content" + } + ] + } + ], + "max_blocks": 10 +} +``` + +## Complete Section Example + +```liquid +{%- comment -%} + Product Grid Section + Displays products in a responsive grid layout +{%- endcomment -%} + +{%- liquid + assign heading = section.settings.heading + assign collection = section.settings.collection + assign products_count = section.settings.products_count + assign columns_desktop = section.settings.columns_desktop + assign columns_mobile = section.settings.columns_mobile +-%} + +
+
+ {%- if heading != blank -%} +

{{ heading | escape }}

+ {%- endif -%} + +
+ {%- for product in collection.products limit: products_count -%} +
+ + {%- if product.featured_image -%} + {{ product.featured_image.alt | escape }} + {%- endif -%} + +
+

{{ product.title | escape }}

+ + {%- if section.settings.show_vendor -%} +

{{ product.vendor | escape }}

+ {%- endif -%} + +
+ {{ product.price | money }} +
+
+ +
+ {%- else -%} +

No products found in this collection.

+ {%- endfor -%} +
+
+
+ +{% stylesheet %} + .product-grid-section { + padding: {{ section.settings.padding_top }}px 0 {{ section.settings.padding_bottom }}px; + background-color: {{ section.settings.bg_color }}; + } + + .container { + max-width: {{ settings.layout_max_width | default: 1200 }}px; + margin: 0 auto; + padding: 0 20px; + } + + .section-heading { + text-align: center; + font-size: 2rem; + margin-bottom: 2rem; + color: {{ section.settings.heading_color }}; + } + + .product-grid { + display: grid; + gap: 1.5rem; + grid-template-columns: repeat({{ columns_mobile }}, 1fr); + } + + @media (min-width: 768px) { + .product-grid { + grid-template-columns: repeat({{ columns_desktop }}, 1fr); + } + } + + .product-card { + display: block; + text-decoration: none; + color: inherit; + transition: transform 0.2s; + } + + .product-card:hover { + transform: translateY(-4px); + } + + .product-card img { + width: 100%; + height: auto; + display: block; + } + + .product-card__info { + padding: 1rem 0; + } + + .product-card__title { + font-size: 1rem; + font-weight: 600; + margin-bottom: 0.5rem; + } + + .product-card__vendor { + font-size: 0.875rem; + color: #666; + margin-bottom: 0.5rem; + } + + .product-card__price { + font-size: 1.125rem; + font-weight: bold; + } +{% endstylesheet %} + +{% javascript %} + (function() { + 'use strict'; + + function initProductGrid(sectionId) { + const section = document.querySelector('[data-section-id="' + sectionId + '"]'); + if (!section) return; + + console.log('Product grid initialized'); + + // Add any interactive functionality here + } + + document.addEventListener('DOMContentLoaded', function() { + initProductGrid('{{ section.id }}'); + }); + + document.addEventListener('shopify:section:load', function(event) { + if (event.detail.sectionId === '{{ section.id }}') { + initProductGrid('{{ section.id }}'); + } + }); + })(); +{% endjavascript %} + +{% schema %} +{ + "name": "Product Grid", + "tag": "section", + "class": "product-grid-section", + "settings": [ + { + "type": "header", + "content": "Section Settings" + }, + { + "type": "text", + "id": "heading", + "label": "Heading", + "default": "Featured Products" + }, + { + "type": "collection", + "id": "collection", + "label": "Collection" + }, + { + "type": "range", + "id": "products_count", + "label": "Number of Products", + "min": 2, + "max": 12, + "step": 1, + "default": 4 + }, + { + "type": "header", + "content": "Layout" + }, + { + "type": "select", + "id": "columns_desktop", + "label": "Desktop Columns", + "options": [ + { "value": "2", "label": "2" }, + { "value": "3", "label": "3" }, + { "value": "4", "label": "4" } + ], + "default": "4" + }, + { + "type": "select", + "id": "columns_mobile", + "label": "Mobile Columns", + "options": [ + { "value": "1", "label": "1" }, + { "value": "2", "label": "2" } + ], + "default": "1" + }, + { + "type": "header", + "content": "Product Card" + }, + { + "type": "checkbox", + "id": "show_vendor", + "label": "Show Product Vendor", + "default": false + }, + { + "type": "header", + "content": "Colors" + }, + { + "type": "color", + "id": "bg_color", + "label": "Background Color", + "default": "#ffffff" + }, + { + "type": "color", + "id": "heading_color", + "label": "Heading Color", + "default": "#000000" + }, + { + "type": "header", + "content": "Spacing" + }, + { + "type": "range", + "id": "padding_top", + "label": "Top Spacing", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40 + }, + { + "type": "range", + "id": "padding_bottom", + "label": "Bottom Spacing", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40 + } + ], + "presets": [ + { + "name": "Product Grid" + } + ] +} +{% endschema %} +``` + +## Best Practices + +1. **Group settings** with headers for better organization +2. **Provide defaults** for all settings +3. **Add info text** for complex settings +4. **Use proper units** (px, %, etc.) +5. **Set reasonable min/max** for range inputs +6. **Include presets** for quick setup +7. **Test mobile responsive** behavior +8. **Handle empty states** (no products, no images, etc.) +9. **Add loading states** for interactive elements +10. **Follow accessibility** standards + +## Common Patterns + +### Responsive Images +```liquid +{{ image.alt | escape }} +``` + +### Empty States +```liquid +{%- if collection.products.size > 0 -%} + {%- for product in collection.products -%} + + {%- endfor -%} +{%- else -%} +

No products available.

+{%- endif -%} +``` + +### Conditional Settings +```liquid +{%- if section.settings.show_feature -%} + +{%- endif -%} +``` + +Always create sections that are intuitive for merchants to customize and mobile-friendly for customers. diff --git a/agents/snippet-library.md b/agents/snippet-library.md new file mode 100644 index 0000000..6f5987b --- /dev/null +++ b/agents/snippet-library.md @@ -0,0 +1,402 @@ +--- +name: shopify-snippet-library +description: Creates reusable Liquid snippets with proper documentation. Generates product cards, forms, icons, and common UI components. +tools: Read, Write, Edit, Grep, Glob +model: sonnet +skills: shopify-snippet-library, shopify-liquid-fundamentals +--- + +You are a Shopify snippet creation expert specializing in reusable, well-documented Liquid code fragments. + +## Core Responsibilities +- Create reusable Liquid snippets +- Write proper documentation for parameters +- Handle parameter validation and defaults +- Generate common UI components (product cards, forms, icons) +- Follow snippet best practices + +## Snippet Documentation Format + +All snippets must include documentation using Liquid comments: + +```liquid +{% comment %} + Snippet: [Name] + Description: [What this snippet does] + + Parameters: + - param_name {type} - Description [required/optional] + + Usage: + {% render 'snippet-name', param_name: value %} + + Example: + {% render 'product-card', product: product, show_vendor: true %} +{% endcomment %} +``` + +## Common Snippet Patterns + +### 1. Product Card + +```liquid +{% comment %} + Snippet: Product Card + Description: Displays a product with image, title, vendor, and price + + Parameters: + - product {product} - The product object [required] + - show_vendor {boolean} - Show product vendor (default: false) [optional] + - image_size {number} - Image width in pixels (default: 400) [optional] + + Usage: + {% render 'product-card', product: product, show_vendor: true %} +{% endcomment %} + +{%- liquid + assign show_vendor = show_vendor | default: false + assign image_size = image_size | default: 400 +-%} + +{%- if product == blank -%} +
+

Product not available

+
+{%- else -%} +
+ + {%- if product.featured_image -%} +
+ {{ product.featured_image.alt | escape }} +
+ {%- endif -%} + +
+ {%- if show_vendor and product.vendor != blank -%} +

{{ product.vendor | escape }}

+ {%- endif -%} + +

{{ product.title | escape }}

+ +
+ {%- if product.compare_at_price > product.price -%} + {{ product.price | money }} + {{ product.compare_at_price | money }} + {%- else -%} + {{ product.price | money }} + {%- endif -%} +
+
+ +
+{%- endif -%} + + +``` + +### 2. Icon + +```liquid +{% comment %} + Snippet: Icon + Description: Renders an SVG icon + + Parameters: + - name {string} - Icon name (e.g., 'cart', 'heart', 'search') [required] + - size {number} - Icon size in pixels (default: 24) [optional] + - class {string} - Additional CSS classes [optional] + + Usage: + {% render 'icon', name: 'cart', size: 20, class: 'icon-primary' %} +{% endcomment %} + +{%- liquid + assign size = size | default: 24 + assign icon_class = 'icon icon-' | append: name + if class + assign icon_class = icon_class | append: ' ' | append: class + endif +-%} + + + {%- case name -%} + {%- when 'cart' -%} + + + + {%- when 'heart' -%} + + + {%- when 'search' -%} + + + + {%- when 'close' -%} + + + {%- else -%} + + {%- endcase -%} + + + +``` + +### 3. Button + +```liquid +{% comment %} + Snippet: Button + Description: Renders a customizable button or link + + Parameters: + - text {string} - Button text [required] + - url {string} - Button URL (makes it a link) [optional] + - style {string} - Button style: 'primary', 'secondary', 'outline' (default: 'primary') [optional] + - size {string} - Button size: 'small', 'medium', 'large' (default: 'medium') [optional] + - full_width {boolean} - Make button full width (default: false) [optional] + + Usage: + {% render 'button', text: 'Add to Cart', style: 'primary', size: 'large' %} + {% render 'button', text: 'View Product', url: product.url, style: 'outline' %} +{% endcomment %} + +{%- liquid + assign style = style | default: 'primary' + assign size = size | default: 'medium' + assign full_width = full_width | default: false + + assign btn_class = 'btn btn--' | append: style | append: ' btn--' | append: size + if full_width + assign btn_class = btn_class | append: ' btn--full' + endif +-%} + +{%- if url != blank -%} + + {{ text | escape }} + +{%- else -%} + +{%- endif -%} + + +``` + +### 4. Form Input + +```liquid +{% comment %} + Snippet: Form Input + Description: Renders a form input field with label + + Parameters: + - type {string} - Input type (text, email, tel, etc.) [required] + - name {string} - Input name attribute [required] + - label {string} - Input label [required] + - required {boolean} - Make field required (default: false) [optional] + - placeholder {string} - Placeholder text [optional] + - value {string} - Default value [optional] + + Usage: + {% render 'form-input', type: 'email', name: 'email', label: 'Email Address', required: true %} +{% endcomment %} + +{%- liquid + assign required = required | default: false + assign input_id = 'input-' | append: name +-%} + +
+ + + +
+ + +``` + +## Best Practices + +1. **Always document parameters** - Use comment block at top +2. **Provide defaults** - Use `| default:` filter +3. **Validate required params** - Check for blank values +4. **Handle empty states** - Show appropriate fallback +5. **Escape output** - Use `| escape` for user-provided content +6. **Keep snippets focused** - One responsibility per snippet +7. **Include basic styles** - Make snippets work standalone +8. **Test edge cases** - Missing images, long titles, etc. + +## Common Snippet Types + +- **Product Card** - Display product with image and info +- **Icon** - SVG icon library +- **Button** - Customizable button/link +- **Form Input** - Reusable form fields +- **Badge** - Labels and tags +- **Loading Spinner** - Loading state indicator +- **Alert/Notice** - Messages and notifications +- **Breadcrumbs** - Navigation trail +- **Social Icons** - Social media links +- **Star Rating** - Product reviews + +Create well-documented, reusable snippets that make theme development faster and more consistent. diff --git a/agents/translation-manager.md b/agents/translation-manager.md new file mode 100644 index 0000000..f8ea462 --- /dev/null +++ b/agents/translation-manager.md @@ -0,0 +1,381 @@ +--- +name: shopify-translation-manager +description: Manages locale files for multi-language support. Handles en.default.json and schema translations following Shopify i18n patterns. +tools: Read, Write, Edit +model: sonnet +skills: shopify-i18n-basics +--- + +You are a Shopify translation and internationalization expert specializing in locale file management. + +## Core Responsibilities +- Create and manage locale files (`locales/` directory) +- Handle translation keys for theme content +- Manage schema translations +- Follow Shopify i18n best practices +- Support multi-language themes + +## Locale File Structure + +Shopify themes use JSON files in the `locales/` directory: + +``` +locales/ +├── en.default.json # English (default language) +├── en.default.schema.json # English schema translations +├── fr.json # French translations +├── fr.schema.json # French schema translations +├── de.json # German translations +└── de.schema.json # German schema translations +``` + +## Translation File Types + +### 1. Content Translations (`en.default.json`) + +Used for actual theme content displayed to customers: + +```json +{ + "general": { + "search": "Search", + "cart": "Cart", + "close": "Close", + "loading": "Loading...", + "continue_shopping": "Continue Shopping", + "view_all": "View All" + }, + "header": { + "menu": "Menu", + "account": "Account", + "search_placeholder": "Search products..." + }, + "footer": { + "newsletter_heading": "Subscribe to our newsletter", + "newsletter_button": "Subscribe", + "copyright": "© {{ year }} {{ shop_name }}. All rights reserved." + }, + "product": { + "add_to_cart": "Add to Cart", + "sold_out": "Sold Out", + "unavailable": "Unavailable", + "quantity": "Quantity", + "price": "Price", + "vendor": "Vendor" + }, + "cart": { + "title": "Your Cart", + "empty": "Your cart is currently empty", + "subtotal": "Subtotal", + "shipping": "Shipping calculated at checkout", + "checkout": "Checkout", + "remove": "Remove" + }, + "sections": { + "featured_products": { + "heading": "Featured Products", + "view_all": "View All Products" + }, + "hero_banner": { + "default_heading": "Welcome to our store" + } + } +} +``` + +### 2. Schema Translations (`en.default.schema.json`) + +Used for Theme Editor labels and settings: + +```json +{ + "sections": { + "featured_products": { + "name": "Featured Products", + "settings": { + "heading": { + "label": "Heading", + "info": "Section heading text" + }, + "collection": { + "label": "Collection" + }, + "products_count": { + "label": "Number of Products" + } + } + }, + "hero_banner": { + "name": "Hero Banner", + "settings": { + "image": { + "label": "Background Image" + }, + "heading": { + "label": "Heading" + }, + "text": { + "label": "Text" + } + } + } + }, + "settings": { + "colors": { + "label": "Colors", + "primary": "Primary Color", + "secondary": "Secondary Color" + }, + "typography": { + "label": "Typography", + "heading_font": "Heading Font", + "body_font": "Body Font" + } + } +} +``` + +## Using Translations in Liquid + +### Content Translations +```liquid + + + + +

{{ 'footer.copyright' | t: year: 'now' | date: '%Y', shop_name: shop.name }}

+ + +{{ section.settings.heading | default: 'sections.featured_products.heading' | t }} +``` + +### Schema Translations +```json +{ + "schema": { + "name": "t:sections.featured_products.name", + "settings": [ + { + "type": "text", + "id": "heading", + "label": "t:sections.featured_products.settings.heading.label", + "info": "t:sections.featured_products.settings.heading.info" + } + ] + } +} +``` + +## Translation Organization Patterns + +### General UI Elements +```json +{ + "general": { + "accessibility": { + "skip_to_content": "Skip to content", + "close_menu": "Close menu", + "open_menu": "Open menu" + }, + "buttons": { + "learn_more": "Learn More", + "shop_now": "Shop Now", + "add_to_cart": "Add to Cart", + "buy_now": "Buy Now" + }, + "forms": { + "required": "Required", + "optional": "Optional", + "submit": "Submit", + "email": "Email", + "name": "Name", + "message": "Message" + } + } +} +``` + +### Product-Specific +```json +{ + "product": { + "info": { + "sku": "SKU", + "barcode": "Barcode", + "availability": "Availability", + "in_stock": "In Stock", + "out_of_stock": "Out of Stock" + }, + "price": { + "from": "From {{ price }}", + "regular_price": "Regular price", + "sale_price": "Sale price", + "unit_price": "Unit price" + }, + "actions": { + "add_to_cart": "Add to Cart", + "choose_options": "Choose Options", + "view_details": "View Details", + "quick_view": "Quick View" + } + } +} +``` + +### Cart & Checkout +```json +{ + "cart": { + "general": { + "title": "Cart", + "empty": "Your cart is empty", + "continue_shopping": "Continue Shopping" + }, + "items": { + "quantity": "Quantity", + "price": "Price", + "total": "Total", + "remove": "Remove" + }, + "summary": { + "subtotal": "Subtotal", + "shipping": "Shipping", + "taxes": "Taxes", + "total": "Total", + "checkout": "Proceed to Checkout" + } + } +} +``` + +## Multi-Language Support + +### Adding a New Language + +1. Create translation file: `locales/fr.json` +2. Copy structure from `en.default.json` +3. Translate all values to French +4. Create schema file: `locales/fr.schema.json` +5. Translate schema labels + +### Example French Translation +```json +{ + "general": { + "search": "Rechercher", + "cart": "Panier", + "close": "Fermer" + }, + "product": { + "add_to_cart": "Ajouter au panier", + "sold_out": "Épuisé" + } +} +``` + +## Best Practices + +1. **Use clear, descriptive keys** - `product.add_to_cart` not `prod.btn1` +2. **Organize logically** - Group related translations +3. **Provide context** - Use nested objects for clarity +4. **Handle pluralization** - Use Liquid pluralization filters +5. **Include defaults** - Always have `en.default.json` +6. **Keep keys consistent** - Same structure across languages +7. **Document variables** - Note what variables translations expect +8. **Avoid hardcoding** - Use translation keys everywhere + +## Common Translation Keys + +### Navigation +```json +{ + "navigation": { + "home": "Home", + "shop": "Shop", + "about": "About", + "contact": "Contact", + "search": "Search", + "account": "Account", + "cart": "Cart" + } +} +``` + +### Forms +```json +{ + "forms": { + "contact": { + "name": "Name", + "email": "Email", + "phone": "Phone", + "message": "Message", + "send": "Send Message", + "success": "Thank you for your message!", + "error": "Please correct the errors below." + } + } +} +``` + +### Errors +```json +{ + "errors": { + "general": "An error occurred. Please try again.", + "required_field": "This field is required", + "invalid_email": "Please enter a valid email address", + "cart_error": "Unable to update cart. Please try again." + } +} +``` + +## Complete Example + +**locales/en.default.json**: +```json +{ + "general": { + "search": "Search", + "cart": "Cart", + "menu": "Menu", + "close": "Close" + }, + "product": { + "add_to_cart": "Add to Cart", + "sold_out": "Sold Out", + "from": "From {{ price }}" + }, + "cart": { + "title": "Your Cart", + "empty": "Your cart is empty", + "checkout": "Checkout" + }, + "sections": { + "featured_products": { + "heading": "Featured Products" + } + } +} +``` + +**locales/en.default.schema.json**: +```json +{ + "sections": { + "featured_products": { + "name": "Featured Products", + "settings": { + "heading": { + "label": "Heading" + }, + "collection": { + "label": "Collection" + } + } + } + } +} +``` + +Create comprehensive translation files that support multi-language stores and make content management easy. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..51cea73 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,85 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:sarojpunde/shopify-dev-toolkit-claude-plugins:shopify-theme-development", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "470837a41212fc3673b9dc0e52a5262489e841ef", + "treeHash": "22c16e38babb997425b0a8f073415afab28fd55f55da31876cd4b869a3efc73b", + "generatedAt": "2025-11-28T10:28:08.663058Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "shopify-liquid-specialist", + "description": "Shopify Liquid templating expert for sections, snippets, and templates. Generates pure Liquid code following Shopify best practices without framework dependencies.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "520ee9f87dfea0dc838579aa0f327c45c524e38eab4b061f08ba04f04052d9e2" + }, + { + "path": "agents/liquid-specialist.md", + "sha256": "64fced530ae237ecd9e3ba0cf31c8c7822d6fe1f5e0ebd06397a5e7689fadf1f" + }, + { + "path": "agents/global-settings.md", + "sha256": "e2f4f5095c8b748c778053d553c45c3d880c75c28b218496d05c2596484d36cf" + }, + { + "path": "agents/section-builder.md", + "sha256": "72e248f51ceae170832fa70e2096cde94f38bbc35723844f714fff8d06f2a5a1" + }, + { + "path": "agents/snippet-library.md", + "sha256": "b568a019ea19e707913292460a12e0bf623654c66f059c0ac45b1e0e94ba9109" + }, + { + "path": "agents/translation-manager.md", + "sha256": "c0cfce7e4f101d951342096fbd2c00e701de704b3caa145242335136c17cb510" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "39b3c64be57d417e1723652a1676e4316be906a8ab20f744d2248d843c1bc2cf" + }, + { + "path": "skills/shopify-i18n-basics/SKILL.md", + "sha256": "65561608f2ae92cf8e0926cf7d8f58247ed08b7f78f01db3f0e2bc644b2ed0af" + }, + { + "path": "skills/shopify-snippet-library/SKILL.md", + "sha256": "b3d07ecabe5095bb8790bda81c0742843203968277cd0c46e2d0bdfc2bad3964" + }, + { + "path": "skills/shopify-workflow-tools/SKILL.md", + "sha256": "8c2827fe6a467a0fa2c8e01c14542c8af03ec1e6312eecced89b9c767fab7032" + }, + { + "path": "skills/shopify-section-patterns/SKILL.md", + "sha256": "1e2225b002cab6eec01cd49930f41e3c4829d42f49fd93088c2f63d4387196c6" + }, + { + "path": "skills/shopify-schema-design/SKILL.md", + "sha256": "877af05ae09d57c9a33c335a5d2971044ff1effab0dbab615fdc28786bd34a5f" + }, + { + "path": "skills/shopify-liquid-fundamentals/SKILL.md", + "sha256": "322531604e9e77e7d2989a87dfaf92b75faba068be59d7154f6fc0c7d4dba85a" + } + ], + "dirSha256": "22c16e38babb997425b0a8f073415afab28fd55f55da31876cd4b869a3efc73b" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/shopify-i18n-basics/SKILL.md b/skills/shopify-i18n-basics/SKILL.md new file mode 100644 index 0000000..d1ad5c4 --- /dev/null +++ b/skills/shopify-i18n-basics/SKILL.md @@ -0,0 +1,453 @@ +--- +name: Shopify i18n Basics +description: Internationalization fundamentals for multi-language Shopify themes +--- + +# Shopify i18n Basics + +## Locale File Structure + +Shopify themes use JSON files in the `locales/` directory: + +``` +locales/ +├── en.default.json # English (default language) +├── en.default.schema.json # English schema translations +├── fr.json # French translations +├── fr.schema.json # French schema translations +├── de.json # German translations +└── de.schema.json # German schema translations +``` + +## File Types + +### 1. Content Translations (en.default.json) + +Used for theme content displayed to customers: + +```json +{ + "general": { + "search": "Search", + "cart": "Cart", + "menu": "Menu", + "close": "Close", + "loading": "Loading...", + "continue_shopping": "Continue Shopping" + }, + "product": { + "add_to_cart": "Add to Cart", + "sold_out": "Sold Out", + "unavailable": "Unavailable", + "price": "Price", + "vendor": "Vendor" + }, + "cart": { + "title": "Your Cart", + "empty": "Your cart is empty", + "subtotal": "Subtotal", + "checkout": "Checkout" + } +} +``` + +### 2. Schema Translations (en.default.schema.json) + +Used for Theme Editor labels: + +```json +{ + "sections": { + "featured_products": { + "name": "Featured Products", + "settings": { + "heading": { + "label": "Heading", + "info": "Section heading text" + }, + "collection": { + "label": "Collection" + } + } + } + } +} +``` + +## Using Translations in Liquid + +### Basic Translation +```liquid +{{ 'general.search' | t }} +{{ 'product.add_to_cart' | t }} +{{ 'cart.title' | t }} +``` + +### Translation with Variables +```liquid +{%- # In locale file -%} +{ + "cart": { + "item_count": "{{ count }} items" + } +} + +{%- # In Liquid -%} +{{ 'cart.item_count' | t: count: cart.item_count }} +``` + +### Translation with HTML +```liquid +{%- # In locale file -%} +{ + "general": { + "continue_html": "Continue shopping" + } +} + +{%- # In Liquid -%} +{{ 'general.continue_html' | t }} +``` + +### Translation in Schema +```liquid +{% schema %} +{ + "name": "t:sections.featured_products.name", + "settings": [ + { + "type": "text", + "id": "heading", + "label": "t:sections.featured_products.settings.heading.label" + } + ] +} +{% endschema %} +``` + +## Common Translation Patterns + +### General UI +```json +{ + "general": { + "search": "Search", + "cart": "Cart", + "menu": "Menu", + "close": "Close", + "loading": "Loading...", + "buttons": { + "learn_more": "Learn More", + "shop_now": "Shop Now", + "view_all": "View All" + }, + "forms": { + "submit": "Submit", + "email": "Email", + "name": "Name", + "message": "Message" + } + } +} +``` + +### Product-Specific +```json +{ + "product": { + "add_to_cart": "Add to Cart", + "sold_out": "Sold Out", + "unavailable": "Unavailable", + "in_stock": "In Stock", + "out_of_stock": "Out of Stock", + "price": { + "from": "From {{ price }}", + "regular_price": "Regular price", + "sale_price": "Sale price" + } + } +} +``` + +### Cart & Checkout +```json +{ + "cart": { + "title": "Cart", + "empty": "Your cart is empty", + "item_count": "{{ count }} items", + "subtotal": "Subtotal", + "shipping": "Shipping", + "total": "Total", + "checkout": "Checkout", + "remove": "Remove" + } +} +``` + +### Forms & Errors +```json +{ + "forms": { + "contact": { + "name": "Name", + "email": "Email", + "message": "Message", + "send": "Send Message", + "success": "Thank you for your message!", + "error": "Please correct the errors below" + } + }, + "errors": { + "general": "An error occurred", + "required_field": "This field is required", + "invalid_email": "Please enter a valid email" + } +} +``` + +## Adding New Languages + +### Step 1: Create Translation Files + +**locales/fr.json** (French content): +```json +{ + "general": { + "search": "Rechercher", + "cart": "Panier", + "menu": "Menu", + "close": "Fermer" + }, + "product": { + "add_to_cart": "Ajouter au panier", + "sold_out": "Épuisé" + }, + "cart": { + "title": "Votre panier", + "empty": "Votre panier est vide", + "checkout": "Commander" + } +} +``` + +**locales/fr.schema.json** (French schema): +```json +{ + "sections": { + "featured_products": { + "name": "Produits vedettes", + "settings": { + "heading": { + "label": "Titre" + }, + "collection": { + "label": "Collection" + } + } + } + } +} +``` + +### Step 2: Use in Liquid + +The `| t` filter automatically uses the correct translation based on the store's language: + +```liquid +{%- # Automatically shows "Search" in English, "Rechercher" in French -%} + +``` + +## Best Practices + +### 1. Use Clear, Descriptive Keys +```json +{%- # Good -%} +{ + "product": { + "add_to_cart": "Add to Cart" + } +} + +{%- # Bad -%} +{ + "prod": { + "btn1": "Add to Cart" + } +} +``` + +### 2. Organize Logically +```json +{ + "general": { ... }, # General UI + "navigation": { ... }, # Navigation items + "product": { ... }, # Product-related + "cart": { ... }, # Cart-related + "forms": { ... } # Forms +} +``` + +### 3. Keep Keys Consistent Across Languages + +**en.default.json**: +```json +{ + "product": { + "add_to_cart": "Add to Cart" + } +} +``` + +**fr.json** (same structure): +```json +{ + "product": { + "add_to_cart": "Ajouter au panier" + } +} +``` + +### 4. Use Nested Objects for Clarity +```json +{%- # Good -%} +{ + "forms": { + "contact": { + "name": "Name", + "email": "Email" + } + } +} + +{%- # Less clear -%} +{ + "forms": { + "contact_name": "Name", + "contact_email": "Email" + } +} +``` + +### 5. Handle Pluralization + +```json +{ + "cart": { + "item_count_one": "{{ count }} item", + "item_count_other": "{{ count }} items" + } +} +``` + +```liquid +{% if cart.item_count == 1 %} + {{ 'cart.item_count_one' | t: count: cart.item_count }} +{% else %} + {{ 'cart.item_count_other' | t: count: cart.item_count }} +{% endif %} +``` + +### 6. Document Variables + +```json +{ + "_comment": "{{ price }} will be replaced with the actual price", + "product": { + "from_price": "From {{ price }}" + } +} +``` + +### 7. Avoid Hardcoding Text + +```liquid +{%- # Bad -%} +

Featured Products

+ +{%- # Good -%} +

{{ 'sections.featured_products.heading' | t }}

+``` + +## Common Translation Keys + +### Navigation +```json +{ + "navigation": { + "home": "Home", + "shop": "Shop", + "collections": "Collections", + "about": "About", + "contact": "Contact" + } +} +``` + +### Accessibility +```json +{ + "accessibility": { + "skip_to_content": "Skip to content", + "close_menu": "Close menu", + "open_menu": "Open menu", + "next_slide": "Next slide", + "previous_slide": "Previous slide" + } +} +``` + +### Date & Time +```json +{ + "date": { + "months": { + "january": "January", + "february": "February" + }, + "days": { + "monday": "Monday", + "tuesday": "Tuesday" + } + } +} +``` + +## Complete Example + +**locales/en.default.json**: +```json +{ + "general": { + "search": "Search", + "cart": "Cart", + "menu": "Menu" + }, + "product": { + "add_to_cart": "Add to Cart", + "from_price": "From {{ price }}" + }, + "cart": { + "title": "Your Cart", + "empty": "Your cart is empty" + } +} +``` + +**sections/featured-products.liquid**: +```liquid +
+

{{ 'sections.featured_products.heading' | t }}

+ + {%- for product in collection.products -%} +
+

{{ product.title }}

+

{{ 'product.from_price' | t: price: product.price | money }}

+ +
+ {%- endfor -%} +
+``` + +Use translation keys consistently to create themes that work seamlessly in multiple languages. diff --git a/skills/shopify-liquid-fundamentals/SKILL.md b/skills/shopify-liquid-fundamentals/SKILL.md new file mode 100644 index 0000000..87ca4c6 --- /dev/null +++ b/skills/shopify-liquid-fundamentals/SKILL.md @@ -0,0 +1,367 @@ +--- +name: Shopify Liquid Fundamentals +description: Core Shopify Liquid templating best practices for performance, maintainability, and clean code +--- + +# Shopify Liquid Fundamentals + +## Core Principles + +### Whitespace Control +- Use `{%- -%}` to trim whitespace around Liquid tags +- Prefer `{% render %}` over deprecated `{% include %}` +- Use `{% liquid %}` for multi-line logic blocks + +**Example:** +```liquid +{%- liquid + assign product_available = product.available | default: false + assign product_price = product.price | default: 0 + + if product == blank + assign error_message = 'Product not found' + endif +-%} +``` + +### Performance Optimization +- Minimize Liquid logic in templates +- Use `assign` for complex calculations instead of inline logic +- Cache expensive operations +- Use snippets for reusable code + +**Good:** +```liquid +{%- assign discounted_price = product.price | times: 0.9 | money -%} +

Sale: {{ discounted_price }}

+``` + +**Bad:** +```liquid +

Sale: {{ product.price | times: 0.9 | money }}

+

Save: {{ product.price | times: 0.1 | money }}

+``` + +### Error Handling +Always provide defaults and handle empty states: + +```liquid +{%- liquid + assign heading = section.settings.heading | default: 'Default Heading' + assign show_vendor = section.settings.show_vendor | default: false + + if product == blank + assign error_message = 'Product unavailable' + endif +-%} + +{%- if error_message -%} +

{{ error_message }}

+{%- else -%} + +{%- endif -%} +``` + +## Liquid Syntax Essentials + +### Output +```liquid +{{ variable }} # Output variable +{{ variable | escape }} # Escape HTML +{{ variable | default: 'fallback' }} # Provide default +{{- variable -}} # Trim whitespace +``` + +### Logic +```liquid +{% if condition %} +{% elsif other_condition %} +{% else %} +{% endif %} + +{% unless condition %} +{% endunless %} + +{% case variable %} + {% when 'value1' %} + {% when 'value2' %} + {% else %} +{% endcase %} +``` + +### Loops +```liquid +{% for item in collection %} + {{ item.title }} +{% endfor %} + +{% for item in collection limit: 4 %} + {{ item.title }} +{% endfor %} + +{% for i in (1..5) %} + Item {{ i }} +{% endfor %} +``` + +### Variables +```liquid +{% assign name = 'value' %} +{% capture variable %} + Content here +{% endcapture %} +``` + +## Common Filters + +### String Filters +```liquid +{{ 'hello' | capitalize }} # Hello +{{ 'HELLO' | downcase }} # hello +{{ 'hello' | upcase }} # HELLO +{{ 'hello world' | truncate: 8 }} # hello... +{{ '

test

' | escape }} # <p>test</p> +{{ 'hello world' | remove: 'world' }} # hello +{{ 'hello' | append: ' world' }} # hello world +``` + +### Array Filters +```liquid +{{ collection | size }} # Number of items +{{ collection | first }} # First item +{{ collection | last }} # Last item +{{ collection | join: ', ' }} # Join with comma +{{ collection | reverse }} # Reverse order +{{ collection | sort: 'title' }} # Sort by property +``` + +### Math Filters +```liquid +{{ 10 | plus: 5 }} # 15 +{{ 10 | minus: 5 }} # 5 +{{ 10 | times: 5 }} # 50 +{{ 10 | divided_by: 5 }} # 2 +{{ 10.5 | ceil }} # 11 +{{ 10.5 | floor }} # 10 +{{ 10.5 | round }} # 11 +``` + +### Money Filters +```liquid +{{ 1000 | money }} # $10.00 +{{ 1000 | money_with_currency }} # $10.00 USD +{{ 1000 | money_without_currency }} # 10.00 +``` + +### Image Filters +```liquid +{{ image | image_url: width: 400 }} +{{ image | image_url: width: 400, height: 400 }} +{{ image | image_tag }} +{{ image | image_tag: alt: 'Description' }} +``` + +## Shopify Objects + +### Global Objects +```liquid +{{ shop.name }} # Store name +{{ shop.email }} # Store email +{{ cart.item_count }} # Cart items +{{ customer.name }} # Customer name (if logged in) +{{ settings.color_primary }} # Theme setting +``` + +### Product Objects +```liquid +{{ product.title }} +{{ product.price }} +{{ product.compare_at_price }} +{{ product.available }} +{{ product.vendor }} +{{ product.type }} +{{ product.featured_image }} +{{ product.url }} +``` + +### Collection Objects +```liquid +{{ collection.title }} +{{ collection.description }} +{{ collection.products }} +{{ collection.products_count }} +{{ collection.url }} +``` + +## Best Practices + +### 1. Always Escape User Input +```liquid +

{{ product.title | escape }}

+

{{ customer.name | escape }}

+``` + +### 2. Provide Defaults +```liquid +{%- assign heading = section.settings.heading | default: 'Default Title' -%} +{%- assign image = product.featured_image | default: blank -%} +``` + +### 3. Check for Blank Values +```liquid +{%- if heading != blank -%} +

{{ heading | escape }}

+{%- endif -%} +``` + +### 4. Use Liquid Tag for Multi-line Logic +```liquid +{%- liquid + assign is_sale = false + if product.compare_at_price > product.price + assign is_sale = true + endif + + assign discount_percent = product.compare_at_price | minus: product.price | times: 100 | divided_by: product.compare_at_price +-%} +``` + +### 5. Minimize Nested Conditions +```liquid +{%- # Bad -%} +{% if product.available %} + {% if product.compare_at_price > product.price %} + On Sale + {% endif %} +{% endif %} + +{%- # Good -%} +{%- liquid + assign is_on_sale = false + if product.available and product.compare_at_price > product.price + assign is_on_sale = true + endif +-%} + +{%- if is_on_sale -%} + On Sale +{%- endif -%} +``` + +## Common Patterns + +### Conditional Class Names +```liquid +
+ +
+``` + +### Loop with Index +```liquid +{%- for product in collection.products -%} +
+ {%- if forloop.first -%} + Featured + {%- endif -%} + {{ product.title }} +
+{%- endfor -%} +``` + +### Empty State Handling +```liquid +{%- if collection.products.size > 0 -%} + {%- for product in collection.products -%} + + {%- endfor -%} +{%- else -%} +

No products available.

+{%- endif -%} +``` + +### Responsive Images +```liquid +{%- if product.featured_image -%} + {{ product.featured_image.alt | escape }} +{%- endif -%} +``` + +## Rendering Snippets + +### Basic Rendering +```liquid +{% render 'product-card' %} +``` + +### With Parameters +```liquid +{% render 'product-card', product: product, show_vendor: true %} +``` + +### With Multiple Parameters +```liquid +{% render 'button', + text: 'Add to Cart', + url: product.url, + style: 'primary', + size: 'large' +%} +``` + +## Performance Tips + +1. **Limit loops** - Use `limit` parameter when possible +2. **Cache expensive operations** - Assign to variables +3. **Minimize API calls** - Don't call same object property multiple times +4. **Use snippets wisely** - Balance between reusability and overhead +5. **Optimize images** - Use appropriate sizes with image filters + +## Common Mistakes to Avoid + +❌ **Don't repeat expensive operations:** +```liquid +

{{ product.price | times: 1.1 | money }}

+

{{ product.price | times: 1.1 | money }}

+``` + +✅ **Do assign to variable:** +```liquid +{%- assign price_with_tax = product.price | times: 1.1 | money -%} +

{{ price_with_tax }}

+

{{ price_with_tax }}

+``` + +❌ **Don't forget to escape:** +```liquid +

{{ product.title }}

+``` + +✅ **Do escape user input:** +```liquid +

{{ product.title | escape }}

+``` + +❌ **Don't use deprecated include:** +```liquid +{% include 'snippet-name' %} +``` + +✅ **Do use render:** +```liquid +{% render 'snippet-name' %} +``` + +Follow these fundamentals for clean, performant, maintainable Shopify Liquid code. diff --git a/skills/shopify-schema-design/SKILL.md b/skills/shopify-schema-design/SKILL.md new file mode 100644 index 0000000..ea102f0 --- /dev/null +++ b/skills/shopify-schema-design/SKILL.md @@ -0,0 +1,674 @@ +--- +name: Shopify Schema Design +description: Best practices for creating comprehensive section schemas with all setting types +--- + +# Shopify Schema Design + +## Schema Structure + +The `{% schema %}` tag defines how a section appears in the theme editor: + +```json +{ + "name": "Section Name", + "tag": "section", + "class": "section-class", + "limit": 1, + "settings": [...], + "blocks": [...], + "presets": [...] +} +``` + +## Setting Types + +### Text Input +```json +{ + "type": "text", + "id": "heading", + "label": "Heading", + "default": "Default text", + "info": "Helpful description", + "placeholder": "Enter text here" +} +``` + +### Textarea +```json +{ + "type": "textarea", + "id": "description", + "label": "Description", + "default": "Default description" +} +``` + +### Rich Text +```json +{ + "type": "richtext", + "id": "content", + "label": "Content", + "default": "

Default rich text content

" +} +``` + +### Number / Range +```json +{ + "type": "range", + "id": "padding", + "label": "Padding", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40, + "info": "Section padding in pixels" +} +``` + +### Checkbox +```json +{ + "type": "checkbox", + "id": "show_vendor", + "label": "Show Product Vendor", + "default": true, + "info": "Display vendor name on product cards" +} +``` + +### Select / Dropdown +```json +{ + "type": "select", + "id": "layout", + "label": "Layout Style", + "options": [ + { + "value": "grid", + "label": "Grid" + }, + { + "value": "carousel", + "label": "Carousel" + }, + { + "value": "list", + "label": "List" + } + ], + "default": "grid", + "info": "Choose how products are displayed" +} +``` + +### Radio Buttons +```json +{ + "type": "radio", + "id": "alignment", + "label": "Text Alignment", + "options": [ + { + "value": "left", + "label": "Left" + }, + { + "value": "center", + "label": "Center" + }, + { + "value": "right", + "label": "Right" + } + ], + "default": "center" +} +``` + +### Color Picker +```json +{ + "type": "color", + "id": "bg_color", + "label": "Background Color", + "default": "#ffffff", + "info": "Section background color" +} +``` + +### Color Background +```json +{ + "type": "color_background", + "id": "background_gradient", + "label": "Background Gradient", + "info": "Supports solid colors and gradients" +} +``` + +### Image Picker +```json +{ + "type": "image_picker", + "id": "image", + "label": "Image", + "info": "Recommended size: 1600 x 900 px" +} +``` + +### Font Picker +```json +{ + "type": "font_picker", + "id": "heading_font", + "label": "Heading Font", + "default": "assistant_n4", + "info": "Choose font for headings" +} +``` + +### Collection Picker +```json +{ + "type": "collection", + "id": "collection", + "label": "Collection" +} +``` + +### Product Picker +```json +{ + "type": "product", + "id": "featured_product", + "label": "Featured Product" +} +``` + +### Product List +```json +{ + "type": "product_list", + "id": "products", + "label": "Products", + "limit": 12, + "info": "Select up to 12 products" +} +``` + +### Collection List +```json +{ + "type": "collection_list", + "id": "collections", + "label": "Collections", + "limit": 8 +} +``` + +### Blog Picker +```json +{ + "type": "blog", + "id": "blog", + "label": "Blog" +} +``` + +### Article Picker +```json +{ + "type": "article", + "id": "article", + "label": "Article" +} +``` + +### Page Picker +```json +{ + "type": "page", + "id": "page", + "label": "Page" +} +``` + +### Link / URL +```json +{ + "type": "url", + "id": "button_link", + "label": "Button Link", + "info": "Link to internal page or external URL" +} +``` + +### Video URL +```json +{ + "type": "video_url", + "id": "video", + "label": "Video URL", + "accept": ["youtube", "vimeo"], + "info": "Supports YouTube and Vimeo" +} +``` + +### HTML +```json +{ + "type": "html", + "id": "custom_html", + "label": "Custom HTML", + "info": "Add custom HTML code" +} +``` + +### Liquid +```json +{ + "type": "liquid", + "id": "custom_liquid", + "label": "Custom Liquid", + "info": "Add custom Liquid code" +} +``` + +## Organizational Elements + +### Header +```json +{ + "type": "header", + "content": "Section Heading" +} +``` + +### Paragraph +```json +{ + "type": "paragraph", + "content": "Helpful information or instructions for merchants." +} +``` + +## Complete Schema Example + +```json +{% schema %} +{ + "name": "Product Grid", + "tag": "section", + "class": "product-grid-section", + "settings": [ + { + "type": "header", + "content": "Content" + }, + { + "type": "text", + "id": "heading", + "label": "Heading", + "default": "Featured Products" + }, + { + "type": "richtext", + "id": "description", + "label": "Description" + }, + { + "type": "collection", + "id": "collection", + "label": "Collection" + }, + { + "type": "range", + "id": "products_count", + "label": "Number of Products", + "min": 2, + "max": 12, + "step": 1, + "default": 4 + }, + { + "type": "header", + "content": "Layout" + }, + { + "type": "select", + "id": "layout", + "label": "Layout Style", + "options": [ + { + "value": "grid", + "label": "Grid" + }, + { + "value": "carousel", + "label": "Carousel" + } + ], + "default": "grid" + }, + { + "type": "select", + "id": "columns_desktop", + "label": "Desktop Columns", + "options": [ + { + "value": "2", + "label": "2" + }, + { + "value": "3", + "label": "3" + }, + { + "value": "4", + "label": "4" + } + ], + "default": "4" + }, + { + "type": "select", + "id": "columns_mobile", + "label": "Mobile Columns", + "options": [ + { + "value": "1", + "label": "1" + }, + { + "value": "2", + "label": "2" + } + ], + "default": "1" + }, + { + "type": "header", + "content": "Product Card" + }, + { + "type": "checkbox", + "id": "show_vendor", + "label": "Show Product Vendor", + "default": false + }, + { + "type": "checkbox", + "id": "show_quick_view", + "label": "Enable Quick View", + "default": true + }, + { + "type": "header", + "content": "Colors" + }, + { + "type": "color", + "id": "bg_color", + "label": "Background Color", + "default": "#ffffff" + }, + { + "type": "color", + "id": "text_color", + "label": "Text Color", + "default": "#000000" + }, + { + "type": "header", + "content": "Spacing" + }, + { + "type": "range", + "id": "padding_top", + "label": "Top Spacing", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40 + }, + { + "type": "range", + "id": "padding_bottom", + "label": "Bottom Spacing", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40 + } + ], + "blocks": [ + { + "type": "featured_product", + "name": "Featured Product", + "settings": [ + { + "type": "product", + "id": "product", + "label": "Product" + } + ] + } + ], + "presets": [ + { + "name": "Product Grid", + "settings": { + "heading": "Featured Products", + "products_count": 4 + } + } + ] +} +{% endschema %} +``` + +## Blocks Configuration + +### Basic Blocks +```json +{ + "blocks": [ + { + "type": "heading", + "name": "Heading", + "settings": [ + { + "type": "text", + "id": "text", + "label": "Text", + "default": "Heading" + } + ] + }, + { + "type": "paragraph", + "name": "Paragraph", + "settings": [ + { + "type": "richtext", + "id": "content", + "label": "Content" + } + ] + } + ], + "max_blocks": 10 +} +``` + +### Accept All Theme Blocks +```json +{ + "blocks": [ + { + "type": "@theme" + } + ] +} +``` + +### Accept App Blocks +```json +{ + "blocks": [ + { + "type": "@app" + } + ] +} +``` + +## Presets + +### Basic Preset +```json +{ + "presets": [ + { + "name": "Hero Banner" + } + ] +} +``` + +### Preset with Default Settings +```json +{ + "presets": [ + { + "name": "Product Grid", + "settings": { + "heading": "Featured Products", + "products_count": 4, + "columns_desktop": "4" + } + } + ] +} +``` + +### Preset with Blocks +```json +{ + "presets": [ + { + "name": "Testimonials", + "blocks": [ + { + "type": "testimonial" + }, + { + "type": "testimonial" + }, + { + "type": "testimonial" + } + ] + } + ] +} +``` + +## Best Practices + +### 1. Group Related Settings with Headers +```json +{ + "settings": [ + { + "type": "header", + "content": "Content Settings" + }, + { + "type": "text", + "id": "heading", + "label": "Heading" + }, + { + "type": "header", + "content": "Layout Settings" + }, + { + "type": "select", + "id": "columns", + "label": "Columns" + } + ] +} +``` + +### 2. Always Provide Defaults +```json +{ + "type": "text", + "id": "heading", + "label": "Heading", + "default": "Default Heading" ← Always provide! +} +``` + +### 3. Add Info Text for Complex Settings +```json +{ + "type": "range", + "id": "products_count", + "label": "Number of Products", + "min": 2, + "max": 12, + "default": 4, + "info": "Maximum number of products to display from the selected collection" +} +``` + +### 4. Use Appropriate Input Types +- Text/numbers → `text`, `textarea`, `number`, `range` +- True/false → `checkbox` +- Multiple options → `select`, `radio` +- Resources → `collection`, `product`, `image_picker` +- Colors → `color`, `color_background` + +### 5. Set Reasonable Limits +```json +{ + "type": "range", + "id": "padding", + "min": 0, ← Minimum value + "max": 100, ← Maximum value + "step": 4, ← Increment + "default": 40 ← Sensible default +} +``` + +### 6. Include Presets for Quick Setup +```json +{ + "presets": [ + { + "name": "Section Name", + "settings": { + "heading": "Default Heading", + "show_feature": true + }, + "blocks": [ + { + "type": "block_type" + } + ] + } + ] +} +``` + +Create schemas that make section customization intuitive and efficient for merchants. diff --git a/skills/shopify-section-patterns/SKILL.md b/skills/shopify-section-patterns/SKILL.md new file mode 100644 index 0000000..9ca5485 --- /dev/null +++ b/skills/shopify-section-patterns/SKILL.md @@ -0,0 +1,518 @@ +--- +name: Shopify Section Patterns +description: Best practices for creating Shopify 2.0 sections with inline CSS and JavaScript +--- + +# Shopify Section Patterns + +## Section Anatomy + +A complete Shopify section consists of: +1. **Liquid markup** - HTML structure with dynamic content +2. **Inline CSS** - `{% stylesheet %}` tag (optional) +3. **Inline JavaScript** - `{% javascript %}` tag (optional) +4. **Schema** - `{% schema %}` JSON configuration + +## Complete Section Template + +```liquid +{%- comment -%} + Section: [Name] + Description: [Brief description] + Usage: Add via Theme Editor +{%- endcomment -%} + +{%- liquid + assign heading = section.settings.heading | default: 'Default Heading' + assign bg_color = section.settings.bg_color + assign text_color = section.settings.text_color +-%} + +
+
+ {%- if heading != blank -%} +

{{ heading | escape }}

+ {%- endif -%} + + {%- comment -%} Section content {%- endcomment -%} +
+
+ +{% stylesheet %} + #section-{{ section.id }} { + padding: {{ section.settings.padding_top }}px 0 {{ section.settings.padding_bottom }}px; + background-color: {{ bg_color }}; + color: {{ text_color }}; + } + + .container { + max-width: 1200px; + margin: 0 auto; + padding: 0 20px; + } + + @media (min-width: 768px) { + /* Tablet styles */ + } + + @media (min-width: 1024px) { + /* Desktop styles */ + } +{% endstylesheet %} + +{% javascript %} + (function() { + 'use strict'; + + function initSection(sectionId) { + const section = document.querySelector('[data-section-id="' + sectionId + '"]'); + if (!section) return; + + // Your JavaScript here + } + + // Initialize on page load + document.addEventListener('DOMContentLoaded', function() { + initSection('{{ section.id }}'); + }); + + // Re-initialize when section reloads in theme editor + document.addEventListener('shopify:section:load', function(event) { + if (event.detail.sectionId === '{{ section.id }}') { + initSection('{{ section.id }}'); + } + }); + })(); +{% endjavascript %} + +{% schema %} +{ + "name": "Section Name", + "tag": "section", + "class": "section-wrapper", + "settings": [ + { + "type": "text", + "id": "heading", + "label": "Heading", + "default": "Default Heading" + }, + { + "type": "color", + "id": "bg_color", + "label": "Background Color", + "default": "#ffffff" + }, + { + "type": "color", + "id": "text_color", + "label": "Text Color", + "default": "#000000" + }, + { + "type": "range", + "id": "padding_top", + "label": "Top Spacing", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40 + }, + { + "type": "range", + "id": "padding_bottom", + "label": "Bottom Spacing", + "min": 0, + "max": 100, + "step": 4, + "unit": "px", + "default": 40 + } + ], + "presets": [ + { + "name": "Section Name" + } + ] +} +{% endschema %} +``` + +## When to Use Inline CSS/JS + +### Use Inline `{% stylesheet %}` When: +- CSS needs Liquid variables: `{{ section.settings.color }}` +- Dynamic styles based on merchant settings +- Section-specific styles that don't need external file + +### Use Inline `{% javascript %}` When: +- JS needs Liquid settings: `{{ section.settings.enable_feature }}` +- Section-specific functionality +- Need access to `{{ section.id }}` or other Liquid values + +### Skip Inline Tags When: +- Styles/scripts are static and reusable +- Better to use theme.css or theme.js +- No Liquid variables needed + +## Common Section Patterns + +### 1. Product Grid Section + +```liquid +{%- liquid + assign collection = section.settings.collection + assign products_count = section.settings.products_count + assign columns = section.settings.columns_desktop +-%} + +
+ {%- for product in collection.products limit: products_count -%} +
+ + {%- if product.featured_image -%} + {{ product.featured_image.alt | escape }} + {%- endif -%} + +

{{ product.title | escape }}

+

{{ product.price | money }}

+ +
+ {%- endfor -%} +
+ +{% stylesheet %} + .product-grid { + display: grid; + gap: 1.5rem; + grid-template-columns: 1fr; + } + + @media (min-width: 768px) { + .product-grid { + grid-template-columns: repeat({{ columns }}, 1fr); + } + } +{% endstylesheet %} +``` + +### 2. Hero Banner Section + +```liquid +{%- liquid + assign image = section.settings.image + assign heading = section.settings.heading + assign text = section.settings.text + assign button_label = section.settings.button_label + assign button_link = section.settings.button_link +-%} + +
+ {%- if image -%} +
+ {{ image.alt | escape }} +
+ {%- endif -%} + +
+ {%- if heading != blank -%} +

{{ heading | escape }}

+ {%- endif -%} + + {%- if text != blank -%} +

{{ text }}

+ {%- endif -%} + + {%- if button_label != blank and button_link != blank -%} + + {{ button_label | escape }} + + {%- endif -%} +
+
+ +{% stylesheet %} + .hero-banner { + position: relative; + min-height: 500px; + display: flex; + align-items: center; + justify-content: center; + text-align: center; + } + + .hero-banner__image { + position: absolute; + inset: 0; + z-index: -1; + } + + .hero-banner__image img { + width: 100%; + height: 100%; + object-fit: cover; + } + + .hero-banner__content { + padding: 2rem; + background: rgba(255, 255, 255, 0.9); + border-radius: 8px; + } + + .button { + display: inline-block; + padding: 1rem 2rem; + background: #000; + color: #fff; + text-decoration: none; + border-radius: 4px; + margin-top: 1rem; + } +{% endstylesheet %} +``` + +### 3. Testimonials Section with Blocks + +```liquid +
+ {%- for block in section.blocks -%} +
+ {%- if block.settings.quote != blank -%} +
+ {{ block.settings.quote }} +
+ {%- endif -%} + + {%- if block.settings.author != blank -%} + {{ block.settings.author | escape }} + {%- endif -%} +
+ {%- endfor -%} +
+ +{% schema %} +{ + "name": "Testimonials", + "blocks": [ + { + "type": "testimonial", + "name": "Testimonial", + "settings": [ + { + "type": "textarea", + "id": "quote", + "label": "Quote" + }, + { + "type": "text", + "id": "author", + "label": "Author" + } + ] + } + ], + "presets": [ + { + "name": "Testimonials", + "blocks": [ + { + "type": "testimonial" + } + ] + } + ] +} +{% endschema %} +``` + +## Shopify Section Events + +Handle theme editor events: + +```javascript +{% javascript %} + (function() { + 'use strict'; + + function initSection(sectionId) { + const section = document.querySelector('[data-section-id="' + sectionId + '"]'); + if (!section) return; + + console.log('Section initialized:', sectionId); + } + + function cleanupSection(sectionId) { + // Clean up event listeners, timers, etc. + console.log('Section cleaned up:', sectionId); + } + + // Load event - section added or page loaded + document.addEventListener('shopify:section:load', function(event) { + initSection(event.detail.sectionId); + }); + + // Unload event - section removed + document.addEventListener('shopify:section:unload', function(event) { + cleanupSection(event.detail.sectionId); + }); + + // Select event - section selected in theme editor + document.addEventListener('shopify:section:select', function(event) { + console.log('Section selected:', event.detail.sectionId); + }); + + // Deselect event - section deselected in theme editor + document.addEventListener('shopify:section:deselect', function(event) { + console.log('Section deselected:', event.detail.sectionId); + }); + + // Block select event - block selected in theme editor + document.addEventListener('shopify:block:select', function(event) { + console.log('Block selected:', event.detail.blockId); + }); + + // Block deselect event - block deselected in theme editor + document.addEventListener('shopify:block:deselect', function(event) { + console.log('Block deselected:', event.detail.blockId); + }); + + // Initialize on page load + document.addEventListener('DOMContentLoaded', function() { + initSection('{{ section.id }}'); + }); + })(); +{% endjavascript %} +``` + +## Best Practices + +### 1. Use Section ID for Unique Styling +```liquid +
+ +
+ +{% stylesheet %} + #section-{{ section.id }} { + /* Section-specific styles using Liquid variables */ + background: {{ section.settings.bg_color }}; + } + + .my-section { + /* General styles without Liquid variables */ + padding: 2rem 0; + } +{% endstylesheet %} +``` + +### 2. Provide Sensible Defaults +```liquid +{%- liquid + assign heading = section.settings.heading | default: 'Default Heading' + assign columns = section.settings.columns | default: 3 + assign show_prices = section.settings.show_prices | default: true +-%} +``` + +### 3. Handle Empty States +```liquid +{%- if collection.products.size > 0 -%} + +{%- else -%} +

No products available in this collection.

+{%- endif -%} +``` + +### 4. Mobile-First Responsive +```css +/* Mobile first - base styles */ +.grid { + grid-template-columns: 1fr; +} + +/* Tablet and up */ +@media (min-width: 768px) { + .grid { + grid-template-columns: repeat(2, 1fr); + } +} + +/* Desktop and up */ +@media (min-width: 1024px) { + .grid { + grid-template-columns: repeat(3, 1fr); + } +} +``` + +### 5. Use data- Attributes for JavaScript +```liquid +
+ +
+ +{% javascript %} + const slider = document.querySelector('.slider'); + const autoplay = slider.dataset.autoplay === 'true'; + const speed = parseInt(slider.dataset.speed, 10); +{% endjavascript %} +``` + +## Common Patterns + +### Conditional Classes +```liquid +
+ +
+``` + +### Dynamic Grid Columns +```liquid +{% stylesheet %} + .product-grid { + display: grid; + gap: 1.5rem; + grid-template-columns: repeat({{ section.settings.columns_mobile }}, 1fr); + } + + @media (min-width: 1024px) { + .product-grid { + grid-template-columns: repeat({{ section.settings.columns_desktop }}, 1fr); + } + } +{% endstylesheet %} +``` + +### Loading States +```javascript +{% javascript %} + function addToCart(button) { + button.classList.add('loading'); + button.disabled = true; + + // Add to cart logic... + + button.classList.remove('loading'); + button.disabled = false; + } +{% endjavascript %} +``` + +Create sections that are flexible, performant, and easy for merchants to customize through the theme editor. diff --git a/skills/shopify-snippet-library/SKILL.md b/skills/shopify-snippet-library/SKILL.md new file mode 100644 index 0000000..0bce369 --- /dev/null +++ b/skills/shopify-snippet-library/SKILL.md @@ -0,0 +1,436 @@ +--- +name: Shopify Snippet Library +description: Reusable Liquid snippet patterns with proper documentation and parameter handling +--- + +# Shopify Snippet Library + +## Snippet Documentation Format + +All snippets should include documentation using Liquid comments: + +```liquid +{% comment %} + Snippet: [Name] + Description: [What this snippet does] + + Parameters: + - param_name {type} - Description [required/optional] + + Usage: + {% render 'snippet-name', param_name: value %} + + Example: + {% render 'product-card', product: product, show_vendor: true %} +{% endcomment %} +``` + +## Common Snippet Patterns + +### 1. Product Card + +```liquid +{% comment %} + Snippet: Product Card + Description: Displays a product with image, title, vendor, and price + + Parameters: + - product {product} - The product object [required] + - show_vendor {boolean} - Show product vendor (default: false) [optional] + - image_size {number} - Image width in pixels (default: 400) [optional] + - class {string} - Additional CSS classes [optional] + + Usage: + {% render 'product-card', product: product, show_vendor: true, image_size: 600 %} +{% endcomment %} + +{%- liquid + assign show_vendor = show_vendor | default: false + assign image_size = image_size | default: 400 +-%} + +{%- if product == blank -%} +
+

Product not available

+
+{%- else -%} +
+ + {%- if product.featured_image -%} +
+ {{ product.featured_image.alt | escape }} +
+ {%- endif -%} + +
+ {%- if show_vendor and product.vendor != blank -%} +

{{ product.vendor | escape }}

+ {%- endif -%} + +

{{ product.title | escape }}

+ +
+ {%- if product.compare_at_price > product.price -%} + {{ product.price | money }} + {{ product.compare_at_price | money }} + {%- else -%} + {{ product.price | money }} + {%- endif -%} +
+
+ +
+{%- endif -%} +``` + +### 2. Button / Link + +```liquid +{% comment %} + Snippet: Button + Description: Renders a customizable button or link + + Parameters: + - text {string} - Button text [required] + - url {string} - Button URL (makes it a link) [optional] + - style {string} - Button style: 'primary', 'secondary', 'outline' (default: 'primary') [optional] + - size {string} - Button size: 'small', 'medium', 'large' (default: 'medium') [optional] + - class {string} - Additional CSS classes [optional] + + Usage: + {% render 'button', text: 'Add to Cart', style: 'primary', size: 'large' %} + {% render 'button', text: 'Learn More', url: '/pages/about', style: 'outline' %} +{% endcomment %} + +{%- liquid + assign style = style | default: 'primary' + assign size = size | default: 'medium' + assign btn_class = 'btn btn--' | append: style | append: ' btn--' | append: size + if class + assign btn_class = btn_class | append: ' ' | append: class + endif +-%} + +{%- if url != blank -%} + + {{ text | escape }} + +{%- else -%} + +{%- endif -%} +``` + +### 3. Icon (SVG) + +```liquid +{% comment %} + Snippet: Icon + Description: Renders an SVG icon + + Parameters: + - name {string} - Icon name (e.g., 'cart', 'heart', 'search') [required] + - size {number} - Icon size in pixels (default: 24) [optional] + - class {string} - Additional CSS classes [optional] + + Usage: + {% render 'icon', name: 'cart', size: 20, class: 'icon-primary' %} +{% endcomment %} + +{%- liquid + assign size = size | default: 24 + assign icon_class = 'icon icon-' | append: name + if class + assign icon_class = icon_class | append: ' ' | append: class + endif +-%} + + +``` + +### 4. Form Input + +```liquid +{% comment %} + Snippet: Form Input + Description: Renders a form input field with label + + Parameters: + - type {string} - Input type (text, email, tel, number, etc.) [required] + - name {string} - Input name attribute [required] + - label {string} - Input label [required] + - required {boolean} - Make field required (default: false) [optional] + - placeholder {string} - Placeholder text [optional] + - value {string} - Default value [optional] + - class {string} - Additional CSS classes [optional] + + Usage: + {% render 'form-input', type: 'email', name: 'email', label: 'Email Address', required: true %} +{% endcomment %} + +{%- liquid + assign required = required | default: false + assign input_id = 'input-' | append: name +-%} + +
+ + + +
+``` + +### 5. Image with Fallback + +```liquid +{% comment %} + Snippet: Responsive Image + Description: Renders a responsive image with fallback + + Parameters: + - image {image} - The image object [required] + - width {number} - Image width (default: 800) [optional] + - height {number} - Image height [optional] + - alt {string} - Alt text (uses image.alt if not provided) [optional] + - class {string} - Additional CSS classes [optional] + - loading {string} - Loading attribute: 'lazy' or 'eager' (default: 'lazy') [optional] + + Usage: + {% render 'image', image: product.featured_image, width: 600, alt: product.title %} +{% endcomment %} + +{%- liquid + assign width = width | default: 800 + assign loading = loading | default: 'lazy' + assign alt_text = alt | default: image.alt +-%} + +{%- if image != blank -%} + {%- if height -%} + {{ alt_text | escape }} + {%- else -%} + {{ alt_text | escape }} + {%- endif -%} +{%- else -%} + +{%- endif -%} +``` + +### 6. Price Display + +```liquid +{% comment %} + Snippet: Price + Description: Displays product price with sale indication + + Parameters: + - product {product} - The product object [required] + - show_compare {boolean} - Show compare at price (default: true) [optional] + - class {string} - Additional CSS classes [optional] + + Usage: + {% render 'price', product: product %} + {% render 'price', product: product, show_compare: false %} +{% endcomment %} + +{%- liquid + assign show_compare = show_compare | default: true + assign on_sale = false + if product.compare_at_price > product.price + assign on_sale = true + endif +-%} + +
+ {%- if on_sale -%} + {{ product.price | money }} + {%- if show_compare -%} + {{ product.compare_at_price | money }} + {%- endif -%} + {%- else -%} + {{ product.price | money }} + {%- endif -%} +
+``` + +### 7. Badge / Tag + +```liquid +{% comment %} + Snippet: Badge + Description: Displays a badge or tag + + Parameters: + - text {string} - Badge text [required] + - style {string} - Badge style: 'sale', 'new', 'featured', 'default' (default: 'default') [optional] + - class {string} - Additional CSS classes [optional] + + Usage: + {% render 'badge', text: 'Sale', style: 'sale' %} + {% render 'badge', text: 'New Arrival', style: 'new' %} +{% endcomment %} + +{%- liquid + assign style = style | default: 'default' + assign badge_class = 'badge badge--' | append: style + if class + assign badge_class = badge_class | append: ' ' | append: class + endif +-%} + +{%- if text != blank -%} + + {{ text | escape }} + +{%- endif -%} +``` + +### 8. Loading Spinner + +```liquid +{% comment %} + Snippet: Loading Spinner + Description: Displays a loading spinner + + Parameters: + - size {string} - Spinner size: 'small', 'medium', 'large' (default: 'medium') [optional] + - class {string} - Additional CSS classes [optional] + + Usage: + {% render 'loading-spinner', size: 'large' %} +{% endcomment %} + +{%- liquid + assign size = size | default: 'medium' + assign spinner_class = 'spinner spinner--' | append: size + if class + assign spinner_class = spinner_class | append: ' ' | append: class + endif +-%} + + +``` + +## Best Practices + +### 1. Always Document Parameters +```liquid +{% comment %} + Parameters: + - param {type} - Description [required/optional] +{% endcomment %} +``` + +### 2. Provide Defaults +```liquid +{%- liquid + assign show_vendor = show_vendor | default: false + assign image_size = image_size | default: 400 +-%} +``` + +### 3. Validate Required Parameters +```liquid +{%- if product == blank -%} +

Product parameter is required

+ {%- return -%} +{%- endif -%} +``` + +### 4. Handle Empty States +```liquid +{%- if image != blank -%} + +{%- else -%} +
No image available
+{%- endif -%} +``` + +### 5. Escape User-Provided Content +```liquid +

{{ product.title | escape }}

+

{{ customer.name | escape }}

+``` + +### 6. Use Semantic HTML +```liquid +
{%- # For products -%} +