Skip to content

Commit 22d8677

Browse files
aswamyaswamy
authored
Merge pull request #1038 from Shopify/bot/liquid-ai-instructions/2025-08-08--15-04-05
🤖 Sync AI Instructions
2 parents c338b71 + 8f5ce09 commit 22d8677

16 files changed

+5033
-0
lines changed

‎ai/claude/CLAUDE.md

Lines changed: 1475 additions & 0 deletions
Large diffs are not rendered by default.

‎ai/cursor/rules/assets.mdc

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
description: Static files (css, js, and images) for theme templates
3+
globs: assets/*
4+
alwaysApply: false
5+
---
6+
# Assets
7+
8+
The `assets` directory contains static files—such as CSS, JavaScript, images, and icons—that need to be referenced in `.liquid` files or included on your theme.
9+
10+
- **No subdirectories:** this directory is flat and cannot contain folders.
11+
- **Usage:** reference files with the [`asset_url`](mdc:https://shopify.dev/docs/api/liquid/filters/asset_url) filter.
12+
- **SVG icons:** use the [`inline_asset_content`](mdc:https://shopify.dev/docs/api/liquid/filters/inline_asset_content) filter to include SVGs inline.
13+
- **Critical static files:** Only include assets (like `critical.css` or global JS) needed on every page. For page or section specific assets, prefer the `{% stylesheet %}` and `{% javascript %}` tags.
14+
15+
Keep all images, scripts, stylesheets, and icons required by your theme in this directory.

‎ai/cursor/rules/blocks.mdc

Lines changed: 339 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,339 @@
1+
---
2+
description: Development standards and best practices for creating, configuring, and styling theme blocks, including static and nested blocks, schema configuration, CSS, and usage examples
3+
globs: blocks/*.liquid
4+
alwaysApply: false
5+
---
6+
# Theme blocks development standards
7+
8+
Follow [Shopify's theme blocks documentation](mdc:https:/shopify.dev/docs/storefronts/themes/architecture/blocks/theme-blocks/quick-start?framework=liquid).
9+
10+
## Theme block fundamentals
11+
12+
Theme blocks are reusable components defined at the theme level that can be:
13+
- Nested under sections and blocks
14+
- Configured using settings in the theme editor
15+
- Given presets and added by merchants
16+
- Used as [static blocks](mdc:https:/shopify.dev/docs/storefronts/themes/architecture/blocks/theme-blocks/static-blocks#statically-vs-dynamically-rendered-theme-blocks) by theme developers
17+
18+
Blocks render in the editor and storefront when they are referenced in [template files](mdc:.cursor/rules/templates.mdc).
19+
20+
### Basic block structure
21+
```liquid
22+
{% doc %}
23+
Block description and usage examples
24+
25+
@example
26+
{% content_for 'block', type: 'block-name', id: 'unique-id' %}
27+
{% enddoc %}
28+
29+
<div {{ block.shopify_attributes }} class="block-name">
30+
<!-- Block content using block.settings -->
31+
</div>
32+
33+
{% stylesheet %}
34+
/*
35+
Scoped CSS for this block
36+
37+
Use BEM structure
38+
CSS written in here should be for components that are exclusively in this block. If the CSS will be used elsewhere, it should instead be written in [assets/base.css](mdc:@assets/base.css)
39+
*/
40+
{% endstylesheet %}
41+
42+
{% schema %}
43+
{
44+
"name": "Block Name",
45+
"settings": [],
46+
"presets": []
47+
}
48+
{% endschema %}
49+
```
50+
51+
### Static block usage
52+
53+
Static blocks are theme blocks that are rendered directly in Liquid templates by developers, rather than being dynamically added through the theme editor. This allows for predetermined block placement with optional default settings.
54+
55+
**Basic static block syntax:**
56+
```liquid
57+
{% content_for 'block', type: 'text', id: 'header-announcement' %}
58+
```
59+
60+
**Example: Product template with mixed static and dynamic blocks**
61+
```liquid
62+
<!-- templates/product.liquid -->
63+
<div class="product-page">
64+
{% comment %} Static breadcrumb block {% endcomment %}
65+
{% content_for 'block', type: 'breadcrumb', id: 'product-breadcrumb' %}
66+
67+
<div class="product-main">
68+
<div class="product-media">
69+
{% comment %} Static product gallery block {% endcomment %}
70+
{% content_for 'block', type: 'product-gallery', id: 'main-gallery', settings: {
71+
enable_zoom: true,
72+
thumbnails_position: "bottom"
73+
} %}
74+
</div>
75+
76+
<div class="product-info">
77+
{% comment %} Static product info blocks {% endcomment %}
78+
{% content_for 'block', type: 'product-title', id: 'product-title' %}
79+
{% content_for 'block', type: 'product-price', id: 'product-price' %}
80+
{% content_for 'block', type: 'product-form', id: 'product-form' %}
81+
82+
{% comment %} Dynamic blocks area for additional content {% endcomment %}
83+
<div class="product-extra-content">
84+
{% content_for 'blocks' %}
85+
</div>
86+
</div>
87+
</div>
88+
89+
{% comment %} Static related products block {% endcomment %}
90+
{% content_for 'block', type: 'related-products', id: 'related-products', settings: {
91+
heading: "You might also like",
92+
limit: 4
93+
} %}
94+
</div>
95+
```
96+
97+
**Key points about static blocks:**
98+
- They have a fixed `id` that makes them identifiable in the theme editor
99+
- Settings can be overridden in the theme editor despite having defaults
100+
- They appear in the theme editor as locked blocks that can't be removed or reordered
101+
- Useful for consistent layout elements that should always be present
102+
- Can be mixed with dynamic block areas using `{% content_for 'blocks' %}`
103+
104+
## Schema configuration
105+
106+
See [schemas.mdc](mdc:.cursor/rules/schemas.mdc) for rules on schemas
107+
108+
### Advanced schema features
109+
110+
#### Exclude wrapper
111+
112+
```json
113+
{
114+
"tag": null // No wrapper - must include {{ block.shopify_attributes }} for proper editor function
115+
}
116+
```
117+
118+
## Block implementation patterns
119+
120+
### Accessing block data
121+
122+
**Block settings:**
123+
```liquid
124+
{{ block.settings.text }}
125+
{{ block.settings.heading | escape }}
126+
{{ block.settings.image | image_url: width: 800 }}
127+
```
128+
129+
**Block properties:**
130+
```liquid
131+
{{ block.id }} // Unique block identifier
132+
{{ block.type }} // Block type name
133+
{{ block.shopify_attributes }} // Required for theme editor
134+
```
135+
136+
**Section context:**
137+
```liquid
138+
{{ section.id }} // Parent section ID
139+
{{ section.settings.heading | escape }}
140+
{{ section.settings.image | image_url: width: 800 }}
141+
```
142+
143+
## Nested blocks implementation
144+
145+
### Rendering nested blocks
146+
```liquid
147+
<div class="block-container" {{ block.shopify_attributes }}>
148+
<h2>{{ block.settings.heading | escape }}</h2>
149+
150+
<div class="nested-blocks">
151+
{% content_for 'blocks' %}
152+
</div>
153+
</div>
154+
```
155+
156+
### Nesting with layout control
157+
```liquid
158+
<div
159+
class="group {{ block.settings.layout_direction }}"
160+
style="--gap: {{ block.settings.gap }}px;"
161+
{{ block.shopify_attributes }}
162+
>
163+
{% content_for 'blocks' %}
164+
</div>
165+
```
166+
167+
### Presets with nested blocks
168+
```json
169+
{
170+
"presets": [
171+
{
172+
"name": "t:names.two_column_layout",
173+
"category": "Layout",
174+
"settings": {
175+
"layout_direction": "horizontal"
176+
},
177+
"blocks": [
178+
{
179+
"type": "text",
180+
"settings": {
181+
"text": "Column 1 content"
182+
}
183+
},
184+
{
185+
"type": "text",
186+
"settings": {
187+
"text": "Column 2 content"
188+
}
189+
}
190+
]
191+
}
192+
]
193+
}
194+
```
195+
196+
## CSS and styling
197+
198+
See [css-standards.mdc](mdc:.cursor/rules/css-standards.mdc) for rules on writing CSS
199+
200+
### Scoped styles
201+
```liquid
202+
{% stylesheet %}
203+
.block-name {
204+
padding: var(--block-padding, 1rem);
205+
background: var(--block-background, transparent);
206+
}
207+
208+
.block-name__title {
209+
font-size: var(--title-size, 1.5rem);
210+
color: var(--title-color, inherit);
211+
}
212+
213+
.block-name--primary {
214+
background-color: var(--color-primary);
215+
}
216+
217+
.block-name--secondary {
218+
background-color: var(--color-secondary);
219+
}
220+
{% endstylesheet %}
221+
```
222+
223+
### Dynamic CSS variables
224+
```liquid
225+
<div
226+
class="custom-block"
227+
style="
228+
--block-padding: {{ block.settings.padding }}px;
229+
--text-align: {{ block.settings.alignment }};
230+
--background: {{ block.settings.background_color }};
231+
"
232+
{{ block.shopify_attributes }}
233+
>
234+
```
235+
236+
## Block targeting
237+
238+
### Section schema for theme blocks
239+
```json
240+
{
241+
"blocks": [
242+
{ "type": "@theme" }, // Accept all theme blocks
243+
{ "type": "@app" } // Accept app blocks
244+
]
245+
}
246+
```
247+
248+
### Restricted block targeting
249+
```json
250+
{
251+
"blocks": [
252+
{
253+
"type": "text",
254+
"name": "Text Content"
255+
},
256+
{
257+
"type": "image",
258+
"name": "Image Content"
259+
}
260+
]
261+
}
262+
```
263+
264+
## Common block patterns
265+
266+
### Content block
267+
```liquid
268+
<div class="content-block {{ block.settings.style }}" {{ block.shopify_attributes }}>
269+
{% if block.settings.heading != blank %}
270+
<h3 class="content-block__heading">{{ block.settings.heading | escape }}</h3>
271+
{% endif %}
272+
273+
{% if block.settings.text != blank %}
274+
<div class="content-block__text">{{ block.settings.text }}</div>
275+
{% endif %}
276+
277+
{% if block.settings.button_text != blank %}
278+
<a href="{{ block.settings.button_url }}" class="content-block__button">
279+
{{ block.settings.button_text | escape }}
280+
</a>
281+
{% endif %}
282+
</div>
283+
```
284+
285+
### Media block
286+
```liquid
287+
<div class="media-block" {{ block.shopify_attributes }}>
288+
{% if block.settings.image %}
289+
<div class="media-block__image">
290+
{{ block.settings.image | image_url: width: 800 | image_tag:
291+
alt: block.settings.image.alt | default: block.settings.alt_text
292+
}}
293+
</div>
294+
{% endif %}
295+
296+
{% if block.settings.video %}
297+
<div class="media-block__video">
298+
{{ block.settings.video | video_tag: controls: true }}
299+
</div>
300+
{% endif %}
301+
</div>
302+
```
303+
304+
### Layout block (container)
305+
```liquid
306+
<div
307+
class="layout-block layout-block--{{ block.settings.layout_type }}"
308+
style="
309+
--columns: {{ block.settings.columns }};
310+
--gap: {{ block.settings.gap }}px;
311+
"
312+
{{ block.shopify_attributes }}
313+
>
314+
{% content_for 'blocks' %}
315+
</div>
316+
```
317+
318+
## Performance best practices
319+
320+
### Conditional rendering
321+
```liquid
322+
{% liquid
323+
assign has_content = false
324+
if block.settings.heading != blank or block.settings.text != blank
325+
assign has_content = true
326+
endif
327+
%}
328+
329+
{% if has_content %}
330+
<div class="block-content" {{ block.shopify_attributes }}>
331+
<!-- Content here -->
332+
</div>
333+
{% endif %}
334+
```
335+
336+
## Examples referenced
337+
338+
[text.liquid](mdc:.cursor/rules/examples/block-example-text.liquid) - Basic content block from existing project
339+
[group.liquid](mdc:.cursor/rules/examples/block-example-group.liquid) - Container with nested blocks from existing project

0 commit comments

Comments
 (0)