Cursor rule

1---
2description:
3globs: blocks/*.liquid,sections/*.liquid,schemas/*
4alwaysApply: false
5---
6 
7# Schema Standards
8 
9Every section and block must include a `{% schema %}` tag with valid JSON structure.
10 
11We write our schemas in the schemas folder and then run `pnpm run build:schemas` to push them to the `.liquid` files. This allows us to take advantage of Typescript for validation and reuse parts of schemas to avoid re-writing them many times.
12 
13## Schema Structure
14 
15```json
16{
17  "$schema": "http://json-schema.org/draft-07/schema#",
18  "type": "object",
19  "required": ["name", "settings"],
20  "properties": {
21    "name": {
22      "type": "string",
23      "maxLength": 50
24    },
25    "tag": {
26      "type": "string",
27      "enum": ["div", "section", "aside", "header", "footer", "main"]
28    },
29    "class": {
30      "type": "string"
31    },
32    "settings": {
33      "type": "array",
34      "items": {
35        "type": "object",
36        "required": ["type", "id", "label"],
37        "properties": {
38          "type": {
39            "enum": [
40              "text",
41              "textarea",
42              "number",
43              "range",
44              "color",
45              "checkbox",
46              "select",
47              "radio",
48              "collection",
49              "product",
50              "blog",
51              "page",
52              "header",
53              "paragraph",
54              "image_picker",
55              "font_picker",
56              "video",
57              "richtext"
58            ]
59          },
60          "id": {
61            "type": "string",
62            "pattern": "^[a-z][a-z0-9_]*$"
63          },
64          "label": {
65            "type": "string",
66            "maxLength": 30
67          },
68          "visible_if": {
69            "type": "string",
70            "pattern": "\\{\\{\\s+[a-zA-Z_][a-zA-Z0-9_]*\\s+\\}\\}"
71          }
72        }
73      }
74    },
75    "blocks": {
76      "type": "array",
77      "maxItems": 20,
78      "items": {
79        "type": "object",
80        "required": ["type", "name", "settings"],
81        "properties": {
82          "type": {
83            "type": "string",
84            "pattern": "^(@theme|@app|[a-z][a-z0-9_]*)$"
85          },
86          "name": {
87            "type": "string",
88            "maxLength": 30
89          },
90          "settings": {
91            "type": "array"
92          }
93        }
94      }
95    },
96    "presets": {
97      "type": "array",
98      "items": {
99        "type": "object",
100        "required": ["name"],
101        "properties": {
102          "name": {
103            "type": "string"
104          },
105          "settings": {
106            "type": "object"
107          }
108        }
109      }
110    }
111  }
112}
113```
114 
115## Setting Types and Usage
116 
117### Input settings
118 
119These are the bulk of the settings with which the merchant will interact.
120 
121See [input settings documentation](mdc:https:/shopify.dev/docs/storefronts/themes/architecture/settings/input-settings)
122 
123### Sidebar settings
124 
125These are informative settings to guide the merchant.
126 
127See [sidebar settings documentation](mdc:https:/shopify.dev/docs/storefronts/themes/architecture/settings/sidebar-settings)
128 
129## Best practices
130 
131### Label Guidelines
132 
133- Keep labels concise (under 30 characters)
134- Setting type provides context - "Columns" not "Number of columns"
135- No verb-based labels for checkboxes
136- Use title case: "Show Vendor" not "show vendor"
137 
138### Translation Keys
139 
140- Schema names must use valid translation keys: `'t:names.keyname'`
141- Keys must exist in `locales/en.default.schema.json` under the `names` section
142- **If a key doesn't exist, add it to the `names` section** (e.g., `"carousel": "Carousel"`)
143- Run `pnpm run build:schemas` after making changes
144 
145### Setting Organization Rules
146 
147**1. Resource Pickers First**
148 
149- Collection, product, blog, page pickers come first
150- These are required for section functionality
151 
152**2. Visual Impact Order**
153 
154- Layout settings (columns, spacing)
155- Typography settings (fonts, sizes)
156- Color settings (background, text)
157- Padding/margin last
158 
159**3. Group settings using Headers**
160 
161```json
162{
163  "type": "header",
164  "content": "Layout"
165}
166```
167 
168### Schema Structure
169 
170**Minimal schema:**
171 
172```javascript
173export default {
174  name: 't:names.section',
175  settings: [
176    /* settings array */
177  ],
178};
179```
180 
181**With presets (optional):**
182 
183```javascript
184export default {
185  name: 't:names.section',
186  settings: [
187    /* settings array */
188  ],
189  presets: [{ name: 't:names.section', settings: {} }],
190};
191```
192 
193## Nested Blocks in Presets
194 
195When a block has nested `blocks`, you must include a `block_order` array.
196 
197```javascript
198blocks: {
199  'product-details': {
200    type: '_product-details',
201    static: true,
202    blocks: {
203      header: {
204        type: 'group',
205        blocks: {
206          title: { type: 'product-title' },
207          price: { type: 'price' },
208        },
209        block_order: ['title', 'price'],
210      },
211    },
212    block_order: ['header'],
213  },
214}
215```
216