@zohofinance/commerce 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (127) hide show
  1. package/README.md +61 -0
  2. package/package.json +2 -2
  3. package/ts-dist/mocks/init-theme/.claude/CLAUDE.md +6 -0
  4. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/SKILL.md +242 -0
  5. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/inputs/figma.md +81 -0
  6. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/inputs/screenshot.md +54 -0
  7. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/inputs/url.md +88 -0
  8. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/spec-table.md +102 -0
  9. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/verification/accessibility.md +110 -0
  10. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/verification/performance.md +127 -0
  11. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/verification/tokens.md +87 -0
  12. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-section-from-design.20260528/verification/visual-diff.md +123 -0
  13. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/SKILL.md +605 -0
  14. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/design-tokens.md +105 -0
  15. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/page-json-contract.md +58 -0
  16. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/qa-accessibility.md +35 -0
  17. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/reference-lookup.md +94 -0
  18. package/ts-dist/mocks/init-theme/.claude/skills/.archive/zcommerce-theme-builder.20260528/section-anatomy.md +109 -0
  19. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/SKILL.md +313 -0
  20. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/agent-hierarchy.md +142 -0
  21. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/ask-developer.md +113 -0
  22. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/bootstrap.md +260 -0
  23. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/build-metrics.md +89 -0
  24. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/code-quality.md +186 -0
  25. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/common-pages-agent.md +97 -0
  26. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/dev-server-and-urls.md +127 -0
  27. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/exemplars.md +79 -0
  28. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/figma-discovery.md +138 -0
  29. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/figma-extraction.md +132 -0
  30. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/image-sources.md +84 -0
  31. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/inputs/guidelines-frame.md +178 -0
  32. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/page-builder.md +322 -0
  33. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/page-orchestrator.md +199 -0
  34. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/parallel-fanout.md +152 -0
  35. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/a11y.mjs +129 -0
  36. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/lint-section.mjs +502 -0
  37. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/perf.mjs +134 -0
  38. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/pixel-diff.mjs +206 -0
  39. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/scripts/record-build-metrics.mjs +118 -0
  40. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/section-builder.md +131 -0
  41. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/subagent-escalation.md +75 -0
  42. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/transcription-rules.md +98 -0
  43. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/verification.md +227 -0
  44. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/visual-verify-loop.md +117 -0
  45. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/_index.md +4 -0
  46. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/assets.md +105 -0
  47. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/best-practices.md +212 -0
  48. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/custom-scripts.md +294 -0
  49. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/i18n.md +155 -0
  50. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/introduction.md +91 -0
  51. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/layouts.md +158 -0
  52. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/pages.md +156 -0
  53. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/reference/_index.md +4 -0
  54. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/reference/filters.md +419 -0
  55. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/reference/global-objects.md +415 -0
  56. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/reference/schema-types.md +926 -0
  57. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/reference/tags.md +259 -0
  58. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/sections.md +203 -0
  59. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/setup-guide.md +424 -0
  60. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/snippets.md +70 -0
  61. package/ts-dist/mocks/init-theme/.claude/skills/theme-from-figma/zcommerce-docs/theme-structure.md +252 -0
  62. package/ts-dist/mocks/init-theme/.cursor/PLAYBOOK.md +144 -0
  63. package/ts-dist/mocks/init-theme/.cursor/README.md +6 -0
  64. package/ts-dist/mocks/init-theme/.cursor/agents/figma-desktop-mobile-parallel.md +48 -0
  65. package/ts-dist/mocks/init-theme/.cursor/agents/visual-compare.md +221 -0
  66. package/ts-dist/mocks/init-theme/.cursor/commands/add-field.md +83 -0
  67. package/ts-dist/mocks/init-theme/.cursor/commands/add-theme-setting.md +200 -0
  68. package/ts-dist/mocks/init-theme/.cursor/commands/assemble-page.md +72 -0
  69. package/ts-dist/mocks/init-theme/.cursor/commands/audit-page.md +57 -0
  70. package/ts-dist/mocks/init-theme/.cursor/commands/build-page-sections.md +110 -0
  71. package/ts-dist/mocks/init-theme/.cursor/commands/build-section.md +418 -0
  72. package/ts-dist/mocks/init-theme/.cursor/commands/build-theme.md +307 -0
  73. package/ts-dist/mocks/init-theme/.cursor/commands/compare-section.md +358 -0
  74. package/ts-dist/mocks/init-theme/.cursor/commands/create-theme.md +77 -0
  75. package/ts-dist/mocks/init-theme/.cursor/commands/extract-tokens.md +43 -0
  76. package/ts-dist/mocks/init-theme/.cursor/commands/fix-section.md +92 -0
  77. package/ts-dist/mocks/init-theme/.cursor/commands/impact.md +50 -0
  78. package/ts-dist/mocks/init-theme/.cursor/commands/qa-a11y.md +66 -0
  79. package/ts-dist/mocks/init-theme/.cursor/commands/qa-i18n.md +110 -0
  80. package/ts-dist/mocks/init-theme/.cursor/commands/qa-layout.md +127 -0
  81. package/ts-dist/mocks/init-theme/.cursor/commands/qa-performance.md +72 -0
  82. package/ts-dist/mocks/init-theme/.cursor/commands/qa-section.md +84 -0
  83. package/ts-dist/mocks/init-theme/.cursor/commands/qa-sections.md +48 -0
  84. package/ts-dist/mocks/init-theme/.cursor/commands/qa-theme.md +85 -0
  85. package/ts-dist/mocks/init-theme/.cursor/commands/redesign-section.md +177 -0
  86. package/ts-dist/mocks/init-theme/.cursor/commands/refactor-section.md +185 -0
  87. package/ts-dist/mocks/init-theme/.cursor/commands/sync-theme-settings.md +132 -0
  88. package/ts-dist/mocks/init-theme/.cursor/commands/validate-page.md +60 -0
  89. package/ts-dist/mocks/init-theme/.cursor/commands/validate-section-group.md +88 -0
  90. package/ts-dist/mocks/init-theme/.cursor/commands/validate-theme-settings.md +119 -0
  91. package/ts-dist/mocks/init-theme/.cursor/examples/design-instructions-template.md +151 -0
  92. package/ts-dist/mocks/init-theme/.cursor/mcp.json +18 -0
  93. package/ts-dist/mocks/init-theme/.cursor/rules/README.md +160 -0
  94. package/ts-dist/mocks/init-theme/.cursor/rules/accessibility.mdc +24 -0
  95. package/ts-dist/mocks/init-theme/.cursor/rules/add-field.mdc +222 -0
  96. package/ts-dist/mocks/init-theme/.cursor/rules/add-theme-setting.mdc +39 -0
  97. package/ts-dist/mocks/init-theme/.cursor/rules/assemble-page.mdc +130 -0
  98. package/ts-dist/mocks/init-theme/.cursor/rules/audit-page.mdc +92 -0
  99. package/ts-dist/mocks/init-theme/.cursor/rules/build-section.mdc +178 -0
  100. package/ts-dist/mocks/init-theme/.cursor/rules/build-theme.mdc +47 -0
  101. package/ts-dist/mocks/init-theme/.cursor/rules/compare-section.mdc +94 -0
  102. package/ts-dist/mocks/init-theme/.cursor/rules/create-theme.mdc +78 -0
  103. package/ts-dist/mocks/init-theme/.cursor/rules/css.mdc +137 -0
  104. package/ts-dist/mocks/init-theme/.cursor/rules/design-spec-extraction.mdc +255 -0
  105. package/ts-dist/mocks/init-theme/.cursor/rules/extract-tokens.mdc +43 -0
  106. package/ts-dist/mocks/init-theme/.cursor/rules/figma-mcp-resolution.mdc +40 -0
  107. package/ts-dist/mocks/init-theme/.cursor/rules/fix-section.mdc +154 -0
  108. package/ts-dist/mocks/init-theme/.cursor/rules/general.mdc +30 -0
  109. package/ts-dist/mocks/init-theme/.cursor/rules/i18n.mdc +85 -0
  110. package/ts-dist/mocks/init-theme/.cursor/rules/javascript.mdc +85 -0
  111. package/ts-dist/mocks/init-theme/.cursor/rules/liquid-no-hardcoded-strings.mdc +42 -0
  112. package/ts-dist/mocks/init-theme/.cursor/rules/liquid.mdc +171 -0
  113. package/ts-dist/mocks/init-theme/.cursor/rules/mobile-desktop-setting-meta.mdc +34 -0
  114. package/ts-dist/mocks/init-theme/.cursor/rules/naming-convention.mdc +64 -0
  115. package/ts-dist/mocks/init-theme/.cursor/rules/pages.mdc +120 -0
  116. package/ts-dist/mocks/init-theme/.cursor/rules/performance.mdc +51 -0
  117. package/ts-dist/mocks/init-theme/.cursor/rules/qa-section.mdc +134 -0
  118. package/ts-dist/mocks/init-theme/.cursor/rules/redesign-section.mdc +147 -0
  119. package/ts-dist/mocks/init-theme/.cursor/rules/schema-sync.mdc +110 -0
  120. package/ts-dist/mocks/init-theme/.cursor/rules/schema.mdc +360 -0
  121. package/ts-dist/mocks/init-theme/.cursor/rules/share-urls.mdc +68 -0
  122. package/ts-dist/mocks/init-theme/.cursor/skills/browser-verify.md +128 -0
  123. package/ts-dist/mocks/init-theme/.cursor/skills/design-tokens.md +105 -0
  124. package/ts-dist/mocks/init-theme/.cursor/skills/page-json-contract.md +87 -0
  125. package/ts-dist/mocks/init-theme/.cursor/skills/qa-accessibility.md +35 -0
  126. package/ts-dist/mocks/init-theme/.cursor/skills/reference-lookup.md +88 -0
  127. package/ts-dist/mocks/init-theme/.cursor/skills/section-anatomy.md +173 -0
@@ -0,0 +1,605 @@
1
+ # ZCommerce Theme Builder
2
+
3
+ Complete workflow for building, editing, and QA-ing Liquid themes in this theme directory.
4
+
5
+ > **Read CLAUDE.md first** for project context, folder structure, and global conventions.
6
+ > **Read reference sub-skills** in this directory for detailed lookup tables (design-tokens.md, section-anatomy.md, page-json-contract.md, qa-accessibility.md).
7
+
8
+ ---
9
+
10
+ ## Table of Contents
11
+ 1. [Conventions (Always-On Rules)](#1-conventions)
12
+ 2. [Commands](#2-commands)
13
+ 3. [Workflows (Playbook)](#3-workflows)
14
+ 4. [Build-and-Verify Pipeline](#4-build-and-verify-pipeline)
15
+
16
+ ---
17
+
18
+ # 1. Conventions
19
+
20
+ These rules apply to ALL theme work. Internalize them before writing any code.
21
+
22
+ ## 1.1 Custom Schema Syntax (NOT Shopify)
23
+
24
+ Every schema field uses custom default formats. NEVER use plain-string Shopify defaults.
25
+
26
+ | Type | Default format | Liquid access |
27
+ |------|---------------|---------------|
28
+ | text | `"t:sections.<n>.settings.<id>.default"` | `{{ section.settings.<id> }}` |
29
+ | url | `{ "display_name": "t:...", "handle": "/path" }` | `.handle`, `.display_name` |
30
+ | image_picker | `{ "url": "file.webp", "enable_customisation": true }` | `.url` |
31
+ | media_picker | `{ "url": "video.mp4", "is_video": true }` | `.url`, `.is_video` |
32
+ | select | `{ "display_name": "t:...", "value": "opt" }` | `.value`, `.display_name` |
33
+ | menu | `{ "display_name": "t:...", "handle": "" }` | `.handle`, `.display_name` |
34
+ | checkbox | `true` / `false` | `{{ section.settings.<id> }}` |
35
+ | range | number (e.g. `40`) | `{{ section.settings.<id> }}` |
36
+ | color | hex string (e.g. `"#000000"`) | `{{ section.settings.<id> }}` |
37
+ | header | no id, `"content": "t:..."` | UI divider only |
38
+
39
+ All labels: `"t:sections.<section_name>.settings.<field_id>.label"`
40
+ Select options: `"t:sections.<section_name>.settings.<field_id>.option__<n>.label"`
41
+ Block settings: `"t:sections.<section_name>.blocks.<block_type>.settings.<field_id>.label"`
42
+ Video fields must use `media_picker` (not `image_picker`) with default:
43
+ `{ "url": "video.mp4", "is_video": true }`
44
+
45
+ ## 1.2 Liquid Rules
46
+
47
+ - CUSTOM system — not standard Shopify
48
+ - `{% render 'snippet' %}` only — NEVER `{% include %}`
49
+ - Escape output: `{{ value | escape }}`
50
+ - Assets: `{{ 'file.js' | asset_url }}`
51
+ - Internal links: `{{ pageinfo.origin }}/path`
52
+ - All assigns in one `{% liquid %}` block at top
53
+ - Every loop must have empty state (`{% else %}`)
54
+ - Every text/heading: check `!= blank` before rendering
55
+
56
+ ### Global Objects
57
+ ```liquid
58
+ {{ organization.organizationName }} {{ organization.logo.url }}
59
+ {{ organization.email }} {{ organization.phone }}
60
+ {{ pageinfo.origin }} {{ default_menu.menuItems }}
61
+ {{ cart.item_count }} {{ organization.social_media_list }}
62
+ ```
63
+
64
+ ## 1.3 CSS Rules
65
+
66
+ - Tailwind utility classes for layout, spacing, typography
67
+ - CSS variables for ALL colors: `var(--color-primary)`, `var(--color-heading)`, etc.
68
+ - NEVER hardcode hex colors inline
69
+ - Container: `max-w-container-theme mx-auto`
70
+ - Section padding: `style="padding-left: var(--section-padding-x, 16px); padding-right: var(--section-padding-x, 16px);"`
71
+ - Responsive: `hidden md:block` (desktop), `md:hidden` (mobile only)
72
+ - Dynamic CSS via `{% style %}` scoped to `#section-{{ section.id }}`
73
+
74
+ ### Available CSS Variables
75
+ ```
76
+ --color-primary --color-on-primary --color-heading
77
+ --color-background --color-border --color-header-bg
78
+ --section-padding-x
79
+ ```
80
+
81
+ ## 1.4 JavaScript Rules
82
+
83
+ - Vanilla JS only, Web Components extending HTMLElement
84
+ - Custom events for cross-component communication
85
+ - `data-` attributes for JS hooks, not CSS classes
86
+ - Always `defer` scripts
87
+ - Fetch with proper error handling
88
+
89
+ ## 1.5 i18n Rules
90
+
91
+ - ALL user-facing strings use `t:` translation keys
92
+ - Files: `i18n/en.json` (content), `i18n/en.schema.json` (schema labels)
93
+ - Key pattern: `t:sections.{section_name}.settings.{field_id}.label`
94
+ - `display_name` in url/select/menu defaults MUST be a `t:` key
95
+ - NEVER hardcode English strings in schema
96
+
97
+ ## 1.6 Figma Variable Resolution
98
+
99
+ When using Figma MCP or reading Figma output:
100
+ 1. For every `var(--name, fallback)`: strip `--`, split on `/`, traverse `figma-variables.json`
101
+ 2. If path has `$value` → use it (theme-mode-specific)
102
+ 3. If not found → use fallback
103
+ 4. Map resolved value to Tailwind/CSS using design-tokens reference
104
+
105
+ ## 1.7 Cross-Theme Reference Rules
106
+
107
+ When building a new section:
108
+ - **Logic, schema, Liquid patterns** → copy from existing sections in this theme
109
+ - **HTML structure and visual design** → follow the new theme's Figma
110
+ - NEVER discard working Liquid logic for simpler placeholder code
111
+ - If no equivalent section exists → use closest match, build schema from scratch
112
+
113
+ ---
114
+
115
+ # 2. Commands
116
+
117
+ ## create-theme
118
+
119
+ Scaffold a new theme from this theme's existing files.
120
+
121
+ **Usage:** `create-theme <theme_name>`
122
+
123
+ 1. **Validate** — if `` exists, STOP
124
+ 2. **Find reference** — use this theme's current layouts, snippets, settings, and config as the template
125
+ 3. **Create structure:**
126
+ ```
127
+
128
+ assets/
129
+ i18n/en.json, en.schema.json <- copy from ref, keep structure, clear values
130
+ layouts/theme.liquid, accounts.liquid, sitemap.liquid <- copy as-is
131
+ sections/ <- empty
132
+ snippets/ <- copy all from ref (shared infrastructure)
133
+ pages/404.json, blog.json, cart.json, categories.json, checkout.json,
134
+ collection.json, index.json, orders.json, page.json, payment.json,
135
+ product.json, sitemap.json
136
+ settings/schema.json, theme.json <- copy as-is
137
+ favicon.ico, package.json, postcss.config.js, project.json, tailwind.config.js
138
+ ```
139
+ 4. Update `name` field in package.json and project.json
140
+ 5. Report: remind user to get `figma-variables.json` from designer
141
+
142
+ ## build-section
143
+
144
+ Build ONE section at a time. Never build multiple in a single run.
145
+ Includes integrated design verification — matches Figma on the first pass.
146
+
147
+ **Usage:** `build-section <theme_name> <section_name>`
148
+
149
+ ### Pre-flight
150
+ - Verify `figma-variables.json` exists
151
+ - Identify a reference section from this theme's `sections/` folder
152
+ - Confirm Figma frame is available (request BOTH desktop and mobile)
153
+ - Read `.cursor/rules/design-spec-extraction.mdc`
154
+
155
+ ### Stages
156
+ 1. **Read Reference** — extract schema, assigns, conditionals, loops, renders, JS components, style blocks
157
+ 2. **Extract Detailed Design Spec** — THIS IS THE MOST CRITICAL STAGE. Follow the Design Spec Extraction Protocol. Resolve ALL var() from figma-variables.json. Extract EXACT px/hex values for EVERY visible element (text, containers, images, buttons, cards). Produce a Design Spec Table — this is the BUILD CONTRACT
158
+ 3. **Map Tokens** — convert all Figma values to Tailwind classes using figma-variables.json + design-tokens reference. Update spec table's Tailwind/CSS column
159
+ 4. **Build HTML** — Liquid markup with Tailwind classes + CSS vars. **Use the Design Spec Table as blueprint — every row must appear in code**. Mobile-first responsive: base = mobile, `md:` = desktop
160
+ 5. **Add Schema** — using custom syntax. Copy fields from reference, add new fields from Figma. Set padding_top/padding_bottom defaults from Figma spec (not always 40)
161
+ 6. **Add Style/Script** — `{% style %}` for dynamic CSS only, script tags if JS component needed
162
+ 7. **Self-Compare** — For EVERY row in the Design Spec Table, verify the generated code matches exactly. Fix any mismatches before saving. This eliminates the need for separate compare→fix cycles
163
+ 8. **Code QA** — verify: every setting has schema field, no raw hex, no raw px fonts, loops have empty state, images have all attributes, all labels use `t:` keys, responsive classes for all mobile overrides
164
+
165
+ ### Section File Anatomy (required order)
166
+ ```liquid
167
+ {{-- 1. SCRIPT TAGS --}}
168
+ <script src="{{ 'component.js' | asset_url }}" defer></script>
169
+
170
+ {{-- 2. STYLE BLOCK --}}
171
+ {% style %}
172
+ #section-{{ section.id }} {
173
+ padding-top: {{ section.settings.padding_top }}px;
174
+ padding-bottom: {{ section.settings.padding_bottom }}px;
175
+ }
176
+ {% endstyle %}
177
+
178
+ {{-- 3. LIQUID ASSIGNS --}}
179
+ {% liquid
180
+ assign heading = section.settings.heading
181
+ assign show_section = section.settings.show_section
182
+ %}
183
+
184
+ {{-- 4. CONDITIONAL VISIBILITY --}}
185
+ {% if show_section %}
186
+
187
+ {{-- 5. SECTION WRAPPER --}}
188
+ <section id="section-{{ section.id }}" class="section-name w-full">
189
+ <div class="max-w-container-theme mx-auto"
190
+ style="padding-left: var(--section-padding-x, 16px); padding-right: var(--section-padding-x, 16px);">
191
+ {{-- 6. CONTENT --}}
192
+ </div>
193
+ </section>
194
+
195
+ {% endif %}
196
+
197
+ {{-- 7. SCHEMA — always last --}}
198
+ {% schema %}
199
+ { ... }
200
+ {% endschema %}
201
+ ```
202
+
203
+ ### Output
204
+ Save to `sections/<section_name>.liquid`
205
+ Report: what was preserved from reference, what was new from Figma, any unmapped tokens.
206
+
207
+ ## build-page-sections
208
+
209
+ Batch-build all sections for a page from an audit plan.
210
+
211
+ **Usage:** `build-page-sections <theme_name> <page_name>`
212
+
213
+ 1. Read the audit plan (from a previous `audit-page` run or user-provided list)
214
+ 2. For each section in the plan, run the `build-section` workflow
215
+ 3. Build in page order (top to bottom)
216
+ 4. Report consolidated results
217
+
218
+ ## audit-page
219
+
220
+ Plan page sections from Figma before building. No code output.
221
+
222
+ **Usage:** `audit-page <theme_name> <page_name>`
223
+
224
+ 1. Read the Figma page frame
225
+ 2. Identify each distinct section (top to bottom)
226
+ 3. For each section, determine: name, reference section (from this theme's `sections/`), new elements not in reference
227
+ 4. Output an audit plan table:
228
+ ```
229
+ | # | Section Name | Reference | New Elements | Notes |
230
+ ```
231
+ 5. Ask user to approve/edit before building
232
+
233
+ ## assemble-page
234
+
235
+ Generate page JSON after all sections are built and QA'd.
236
+
237
+ **Usage:** `assemble-page <theme_name> <page_name>`
238
+
239
+ 1. List all sections built for this page
240
+ 2. Read each section's schema to get settings, blocks, block types
241
+ 3. Generate page JSON following the page-json-contract (see reference skill)
242
+ 4. Save to `pages/<page_name>.json`
243
+
244
+ ## add-field
245
+
246
+ Add a new setting to an existing section.
247
+
248
+ **Usage:** `add-field <theme_name> <section_name>`
249
+
250
+ 1. **Determine spec** — type, ID, level (section/block), label key, default, placement
251
+ 2. **Update schema** — add field using custom syntax
252
+ 3. **Add Liquid assign** — in the `{% liquid %}` block
253
+ 4. **Wire in HTML** — add rendering where needed
254
+ 5. **Update page JSON** — add default value in correct format
255
+ 6. **Update i18n** — add translation keys
256
+
257
+ ## add-theme-setting
258
+
259
+ Add theme-level customizer settings (global settings like product card style, transitions, etc.).
260
+
261
+ **Usage:** `add-theme-setting <theme_name>`
262
+
263
+ Updates: `settings/schema.json`, every preset in `theme.json`, `i18n/en.schema.json`
264
+
265
+ ## fix-section
266
+
267
+ Fix bugs with minimal blast radius.
268
+
269
+ **Usage:** `fix-section <theme_name> <section_name>`
270
+
271
+ 1. Describe what's broken vs expected
272
+ 2. Diagnose root cause
273
+ 3. Fix with minimal changes — don't refactor unrelated code
274
+ 4. Run self-QA after fix
275
+
276
+ ## redesign-section
277
+
278
+ Replace HTML/CSS design while preserving all Liquid logic.
279
+
280
+ **Usage:** `redesign-section <theme_name> <section_name>`
281
+
282
+ 1. Extract all logic from existing section (schema, assigns, loops, conditions, renders)
283
+ 2. Read new Figma frame for design
284
+ 3. Rebuild HTML/CSS with new design
285
+ 4. Re-wire all preserved logic into new structure
286
+ 5. Self-QA
287
+
288
+ ## compare-section
289
+
290
+ Compare built section against Figma design. Desktop + mobile.
291
+
292
+ **Usage:**
293
+ ```
294
+ compare-section <theme_name> <section_name> → code compare (default)
295
+ compare-section <theme_name> <section_name> --visual → visual browser compare
296
+ compare-section <theme_name> <section_name> --visual --page product --store-url <url>
297
+ ```
298
+
299
+ ### Code Compare (default)
300
+ 1. Fetch both Figma frames (parallel if possible)
301
+ 2. Compare layout, spacing, typography, colors against the built section
302
+ 3. Output consolidated mismatch report tagged: desktop-only, mobile-only, or both
303
+ 4. User chooses: ALL / CRITICAL ONLY / specific issue numbers
304
+
305
+ ### Visual Compare (`--visual`)
306
+ Delegates to the `visual-compare` subagent (`.cursor/agents/visual-compare.md`):
307
+ 1. Ensures dev server is running (`yarn run dev --storeUrl=<url>`)
308
+ 2. Uses Claude in Chrome to navigate to the page and screenshot the rendered section (desktop 1440px + mobile 375px)
309
+ 3. Fetches Figma screenshot via `get_screenshot`
310
+ 4. Visually compares both screenshots — catches CSS cascade bugs, z-index issues, overflow clipping, and rendering quirks that code compare misses
311
+ 5. Checks browser console for JS/Liquid errors
312
+ 6. Produces a visual diff report with CRITICAL / MINOR / SUGGESTION / MOBILE-SPECIFIC categories
313
+
314
+ **Requires:** Claude in Chrome + Figma MCP + dev server (auto-started if not running)
315
+
316
+ ### Recommended: run both modes for final QA
317
+ Code compare finds precise CSS value mismatches; visual compare catches what actually looks wrong in the browser.
318
+
319
+ ## refactor-section
320
+
321
+ Full structural refactoring of a section.
322
+
323
+ **Usage:** `refactor-section <theme_name> <section_name>`
324
+
325
+ ## extract-tokens
326
+
327
+ Validate that `figma-variables.json` exists and is readable.
328
+
329
+ **Usage:** `extract-tokens <theme_name>`
330
+
331
+ ## sync-theme-settings
332
+
333
+ Sync settings from figma-variables.json into theme.json.
334
+
335
+ **Usage:** `sync-theme-settings <theme_name>`
336
+
337
+ ## impact
338
+
339
+ Find all sections that use a given snippet.
340
+
341
+ **Usage:** `impact <theme_name> <snippet_name>`
342
+
343
+ Search all sections for `{% render '<snippet_name>' %}` references.
344
+
345
+ ---
346
+
347
+ ## QA Commands
348
+
349
+ ### qa-section
350
+ Audit a completed section for: schema validity, Liquid correctness, token usage, image attributes, accessibility, performance.
351
+
352
+ ### qa-sections
353
+ Batch QA all sections in a theme.
354
+
355
+ ### qa-theme
356
+ Full theme QA — runs all validation commands and produces consolidated report:
357
+ - qa-sections (all sections)
358
+ - validate-theme-settings
359
+ - qa-layout (all layout files)
360
+ - validate-section-group (per group)
361
+ - validate-page (per page)
362
+ - qa-i18n (translation coverage)
363
+
364
+ ### qa-layout
365
+ Audit layout files for structure, assets, group references, snippet usage, parity.
366
+
367
+ ### qa-i18n
368
+ Audit translation key coverage: missing keys, orphan keys, hardcoded English.
369
+
370
+ ### validate-page
371
+ Verify page JSON: section types match files, block types match schemas, order arrays match keys.
372
+
373
+ ### validate-section-group
374
+ Validate group JSON files (header-group.json, footer-group.json).
375
+
376
+ ### validate-theme-settings
377
+ Cross-check: settings/schema.json <-> settings/theme.json <-> i18n/en.schema.json <-> Liquid consumers.
378
+
379
+ ---
380
+
381
+ # 3. Workflows (Playbook)
382
+
383
+ ## Flow 0 — Full Autopilot (new theme from Figma) ⭐ RECOMMENDED
384
+ 1. `build-theme <name> <figma_file_key>` — orchestrates everything: scaffold, extract tokens, audit pages, build all sections **with design spec verification**, assemble pages, QA
385
+ 2. Review the consolidated audit plan (only manual step)
386
+ 3. Review design accuracy summary — check which sections have <100% spec match
387
+ 4. `compare-section <name> <section>` — **only for sections with unresolved items** (most sections should pass)
388
+ 5. `fix-section <name> <section>` — fix any remaining mismatches
389
+ 6. `qa-theme <name>` — final QA after any manual fixes
390
+
391
+ **Key improvement:** Build now includes self-compare against a Design Spec Table, eliminating most compare→fix iterations.
392
+
393
+ ## Flow 1 — Step-by-Step (manual control)
394
+ 1. `create-theme` -> 2. `extract-tokens` -> 3. `audit-page` -> 4. `build-section` (one at a time) -> 5. `qa-section` -> 6. `compare-section` -> 7. `fix-section` -> 8. `assemble-page` -> 9. `qa-theme`
395
+
396
+ ## Flow 2 — Redesign Existing Section
397
+ 1. `compare-section` (with new Figma URLs) -> 2. `redesign-section` -> 3. `qa-section` -> 4. `compare-section` again
398
+
399
+ ## Flow 3 — Bug Fix
400
+ 1. `compare-section` (if visual bug) -> 2. `fix-section` -> 3. `qa-section`
401
+
402
+ ## Flow 4 — New Theme Setting
403
+ 1. `add-theme-setting` -> 2. Wire in layout/CSS/JS -> 3. `sync-theme-settings` if Figma-driven
404
+
405
+ ## Flow 5 — Pre-Release QA
406
+ Run `qa-theme` or individually: `qa-sections` -> `validate-theme-settings` -> `qa-layout` -> `validate-section-group` -> `validate-page` -> `qa-i18n`
407
+
408
+ ## Quality Gate (every section before ship)
409
+ ```
410
+ qa-section -> code correctness
411
+ compare-section -> design accuracy (use both Figma URLs)
412
+ fix-section -> fix approved issues
413
+ ```
414
+
415
+ ---
416
+
417
+ # 4. Build-and-Verify Pipeline
418
+
419
+ End-to-end automated loop: Figma design → build sections → run dev server → browser test → visual compare → fix → repeat.
420
+
421
+ ## Tools used
422
+ | Step | Tool |
423
+ |------|------|
424
+ | Extract design | Figma MCP (`get_design_context`, `get_screenshot`) |
425
+ | Build/fix sections | `Read`, `Write`, `Edit` |
426
+ | Run dev server | `Bash` (background process) |
427
+ | Browser testing | Claude in Chrome (`navigate`, `get_page_text`, `read_console_messages`) |
428
+ | Visual screenshot | Claude in Chrome (`upload_image`) + Figma MCP (`get_screenshot`) |
429
+ | Loop control | Self-directed iteration until pass |
430
+
431
+ ## Usage
432
+ ```
433
+ build-and-verify <theme_name> <figma_file_url_or_key>
434
+ ```
435
+ Optionally scope to a single page: `build-and-verify <theme_name> <figma_url> --page <page_name>`
436
+
437
+ ---
438
+
439
+ ## Stage 1 — Design Extraction
440
+ 1. Call `get_design_context` on the Figma file/frame
441
+ 2. Call `get_variable_defs` to get the full variable set — save as `figma-variables.json` if not already present
442
+ 3. Call `get_screenshot` on each major page frame — store references for later comparison
443
+ 4. Run `audit-page` flow per page: identify sections top-to-bottom, find reference sections, note new elements
444
+
445
+ Output: audit plan table (user approves before proceeding)
446
+
447
+ ---
448
+
449
+ ## Stage 2 — Build
450
+ For each section in the approved audit plan, run the `build-section` workflow (see Section 2).
451
+ Save all sections to `sections/`.
452
+ Assemble page JSONs via `assemble-page`.
453
+
454
+ ---
455
+
456
+ ## Stage 3 — Start Dev Server
457
+
458
+ **Run in Antigravity terminal:**
459
+ ```bash
460
+ cd <theme_name>
461
+ yarn run dev --storeUrl=<your store url>
462
+ ```
463
+ Wait for "ready" or "compiled" output. Preview opens in Antigravity's browser panel or at the storeUrl.
464
+
465
+ ---
466
+
467
+ ## Stage 4 — Browser Verification Loop
468
+
469
+ Two modes depending on available tools:
470
+
471
+ ### Mode A — Claude in Chrome (preferred when available)
472
+ - Navigate to storefront, take screenshots, read console errors automatically
473
+
474
+ ### Mode B — Antigravity + Cowork (fallback)
475
+ - **Cowork (me):** Pull Figma screenshots via `get_screenshot`, audit section code against design, produce mismatch reports and fixes
476
+ - **Antigravity (you):** Run dev server, preview in browser panel, describe issues or paste/upload screenshots
477
+ - **Loop:** I fix code → you refresh Antigravity preview → feedback → repeat
478
+
479
+ ### 4a. Design-to-Code Comparison (Cowork)
480
+ For each section, I:
481
+ 1. Call `get_screenshot` on the Figma frame for that section
482
+ 2. Call `get_design_context` for exact values (spacing, font sizes, colors)
483
+ 3. Read the section `.liquid` file
484
+ 4. Compare and produce a mismatch report
485
+
486
+ ### 4b. Live Preview Check (Antigravity)
487
+ - Open Antigravity browser panel at the storeUrl
488
+ - Check for: Liquid render errors, layout breaks, missing images, console JS errors
489
+ - Describe issues back to me or share a screenshot (paste or upload) for any visual discrepancy
490
+
491
+ ### 4c. Console Error Resolution
492
+ If Antigravity terminal or browser console shows errors:
493
+ - JS errors → I read the section's asset JS, diagnose, fix
494
+ - Network 404s → check asset_url references, verify file exists in assets/
495
+ - Liquid errors → I check the section file for undefined variables or syntax issues
496
+
497
+ ### 4d. Loop Exit Condition
498
+ A page passes when:
499
+ - [ ] No Liquid render errors
500
+ - [ ] No critical JS console errors
501
+ - [ ] All sections visually match Figma within acceptable tolerance
502
+ - [ ] Mobile viewport (375px) also checked
503
+
504
+ ### 4b. Visual Comparison
505
+ For each section on the page:
506
+ 1. Get Figma screenshot for that section frame
507
+ 2. Compare against the browser screenshot:
508
+ - Layout structure (columns, rows, alignment)
509
+ - Spacing and padding
510
+ - Typography (size hierarchy, weight, line height)
511
+ - Colors (mapped correctly to CSS variables)
512
+ - Images (correct placeholders, aspect ratios)
513
+ - Responsive breakpoints (check mobile viewport too)
514
+ 3. Produce a **mismatch report** for this section:
515
+ ```
516
+ SECTION: <section_name>
517
+ ━━━━━━━━━━━━━━━━━━━━━━━
518
+ ✅ MATCH: layout structure, color tokens
519
+ ❌ MISMATCH:
520
+ [1] Heading font size: Figma=48px, Built=36px — CRITICAL
521
+ [2] Card gap: Figma=24px, Built=16px — MINOR
522
+ [3] CTA button radius: Figma=rounded-full, Built=rounded-md — MINOR
523
+ ```
524
+
525
+ ### 4c. Fix Mismatches
526
+ - Fix CRITICAL issues immediately (wrong layout, broken rendering, missing sections)
527
+ - Fix MINOR issues in batches
528
+ - Apply minimal changes — only touch the CSS/Tailwind classes involved, never refactor schema
529
+ - After fixes, reload the browser page and re-screenshot
530
+
531
+ ### 4d. Console Error Resolution
532
+ If console errors are present:
533
+ - JS errors: read the section's asset JS file, diagnose, fix
534
+ - Network errors: check asset_url references, verify file exists in assets/
535
+ - Liquid errors: check section file for syntax issues, undefined variables
536
+
537
+ ### 4e. Loop Exit Condition
538
+ A page passes when:
539
+ - [ ] No Liquid render errors on page
540
+ - [ ] No critical JS console errors
541
+ - [ ] All sections visually match Figma within acceptable tolerance
542
+ - [ ] Mobile viewport checked and responsive breakpoints correct
543
+
544
+ ---
545
+
546
+ ## Stage 5 — Self Design Review
547
+ After all pages pass the loop, run a final design review:
548
+
549
+ 1. **Consistency check** — across all pages:
550
+ - Same heading hierarchy used consistently
551
+ - Same button styles across CTAs
552
+ - Spacing rhythm consistent between sections
553
+ - Color token usage consistent (no raw hex crept in)
554
+
555
+ 2. **Cross-page navigation** — use Chrome to navigate between pages, check:
556
+ - Header/footer renders correctly on all pages
557
+ - No layout shifts between pages
558
+ - Active states in nav correct per page
559
+
560
+ 3. **Accessibility pass** — using qa-accessibility checklist (see reference skill):
561
+ - All images have alt text
562
+ - Focus indicators visible
563
+ - Heading levels logical
564
+ - Buttons/links have labels
565
+
566
+ 4. **Final report:**
567
+ ```
568
+ THEME: <theme_name> — DESIGN REVIEW COMPLETE
569
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
570
+ Pages reviewed: [list]
571
+ Sections built: [count]
572
+ ✅ PASSED: [list of sections]
573
+ ⚠️ NEEDS ATTENTION: [list with issue descriptions]
574
+ ❌ BLOCKED: [list with blockers]
575
+
576
+ NEXT: Fix ⚠️ items → re-run build-and-verify for affected sections
577
+ ```
578
+
579
+ ---
580
+
581
+ ## Stage 6 — Iteration
582
+ For any remaining issues from Stage 5:
583
+ - Run `fix-section` for visual mismatches
584
+ - Re-run Stage 4 loop for the affected section only
585
+ - Re-run Stage 5 design review for affected pages
586
+
587
+ ---
588
+
589
+ ## Notes
590
+ - **Dev server must stay running** during the entire loop. If it crashes, restart before re-checking.
591
+ - **Always compare both desktop and mobile** — navigate Chrome at 1440px width for desktop, 375px for mobile.
592
+ - **Figma screenshots are the source of truth** — if there's ambiguity, the Figma frame wins.
593
+ - **Don't over-fix** — if a value is within 1-2px/Tailwind-unit of the design, it's acceptable. Only flag true visual deviations.
594
+
595
+ ---
596
+
597
+ # 5. Parallel Agent Strategy
598
+
599
+ When building multiple sections or running QA across a theme, use subagents for parallel work:
600
+ - **Building:** spawn one agent per section (each follows the build-section workflow)
601
+ - **QA:** spawn agents to QA sections in parallel
602
+ - **Compare:** fetch desktop + mobile Figma in parallel (same agent, concurrent tool calls)
603
+ - **Build-and-verify:** spawn one agent per page to run the visual verification loop in parallel
604
+
605
+ Always have each agent read this SKILL.md before starting its work.