Skip to content

Commit 8df97e2

Browse files
claudeclaude
committed
Add CLAUDE.md documentation for AI assistants
Comprehensive guide covering: - Project overview and core philosophy (web-native, performance-first) - Directory structure and file organization - Development commands (Shopify CLI) - Key conventions for Liquid, CSS, and JavaScript - Web Components patterns and pub/sub system - Accessibility requirements - Translation key usage - CI/CD workflow overview - Common tasks and anti-patterns to avoid
1 parent 8eded48 commit 8df97e2

File tree

1 file changed

+226
-0
lines changed

1 file changed

+226
-0
lines changed

‎CLAUDE.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# CLAUDE.md - Dawn Theme Development Guide
2+
3+
This document provides guidance for AI assistants working with the Shopify Dawn theme codebase.
4+
5+
## Project Overview
6+
7+
**Dawn** is Shopify's official reference theme for Online Store 2.0. It follows a "HTML-first, JavaScript-only-as-needed" approach emphasizing performance, accessibility, and progressive enhancement.
8+
9+
**Version:** 8.0.0-rc
10+
**Theme Type:** Shopify Online Store 2.0 Theme
11+
**Primary Technologies:** Liquid, CSS, Vanilla JavaScript
12+
13+
## Core Philosophy
14+
15+
Dawn adheres to these principles - understand them before making changes:
16+
17+
1. **Web-native in its purest form** - No frameworks, libraries, or dependencies. Use native browser APIs.
18+
2. **Lean, fast, and reliable** - Zero CLS, no render-blocking JS, no long tasks, no DOM manipulation before user input.
19+
3. **JavaScript not required** - JS is only for progressive enhancement. Core functionality must work without JS.
20+
4. **Server-rendered** - HTML is rendered by Shopify servers using Liquid. Business logic stays server-side.
21+
5. **Functional, not pixel-perfect** - Progressive enhancement over polyfills; semantic markup over visual precision.
22+
23+
## Directory Structure
24+
25+
```
26+
dawn/
27+
├── assets/ # CSS and JavaScript files
28+
│ ├── base.css # Core styles and CSS custom properties
29+
│ ├── global.js # Core JavaScript and Web Components
30+
│ ├── pubsub.js # Simple pub/sub event system
31+
│ └── component-*.css # Component-specific styles
32+
├── config/
33+
│ ├── settings_schema.json # Theme settings schema (editor UI)
34+
│ └── settings_data.json # Default theme settings values
35+
├── layout/
36+
│ ├── theme.liquid # Main layout template
37+
│ └── password.liquid # Password page layout
38+
├── locales/ # Translation files (en.default.json is the source)
39+
│ ├── en.default.json # English translations
40+
│ └── *.schema.json # Theme editor translations
41+
├── sections/ # Reusable page sections
42+
│ ├── header.liquid # Site header
43+
│ ├── footer.liquid # Site footer
44+
│ ├── main-*.liquid # Main content sections
45+
│ └── *.json # Section groups
46+
├── snippets/ # Reusable Liquid components
47+
│ ├── card-product.liquid # Product card component
48+
│ ├── icon-*.liquid # SVG icons
49+
│ └── facets.liquid # Collection filters
50+
├── templates/ # Page templates (JSON format for OS 2.0)
51+
│ ├── index.json # Homepage
52+
│ ├── product.json # Product page
53+
│ ├── collection.json # Collection page
54+
│ └── customers/ # Customer account templates
55+
└── .theme-check.yml # Theme Check linting configuration
56+
```
57+
58+
## Development Commands
59+
60+
```bash
61+
# Install Shopify CLI (required)
62+
npm install -g @shopify/cli @shopify/theme
63+
64+
# Start development server
65+
shopify theme dev
66+
67+
# Run linting (Theme Check)
68+
shopify theme check
69+
70+
# Push theme to store
71+
shopify theme push
72+
73+
# Pull theme from store
74+
shopify theme pull
75+
```
76+
77+
## Key Conventions
78+
79+
### Liquid Templates
80+
81+
- **Sections** (`sections/*.liquid`): Self-contained, reusable modules with their own settings schema
82+
- **Snippets** (`snippets/*.liquid`): Reusable components without settings; document parameters in comments
83+
- **Templates** (`templates/*.json`): JSON files defining section order and default settings
84+
85+
Section files must include a `{% schema %}` block at the end defining:
86+
- `name`: Display name in theme editor
87+
- `settings`: Configurable options
88+
- `blocks`: Optional nested content blocks
89+
- `presets`: Optional default configurations
90+
91+
### CSS Patterns
92+
93+
1. **CSS Custom Properties**: Defined in `theme.liquid` and `base.css`
94+
```css
95+
--color-foreground: var(--color-base-text);
96+
--font-body-family: {{ settings.type_body_font.family }};
97+
```
98+
99+
2. **Component CSS**: Each component has its own CSS file (e.g., `component-card.css`)
100+
101+
3. **Color Schemes**: Use `.color-background-1`, `.color-accent-1`, etc. classes
102+
103+
4. **Responsive**: Mobile-first with breakpoint at 750px and 990px
104+
```css
105+
@media screen and (min-width: 750px) { }
106+
@media screen and (min-width: 990px) { }
107+
```
108+
109+
5. **CSS Loading**: Non-critical CSS uses media="print" with onload swap:
110+
```liquid
111+
<link rel="stylesheet" href="{{ 'component.css' | asset_url }}" media="print" onload="this.media='all'">
112+
```
113+
114+
### JavaScript Patterns
115+
116+
1. **Web Components**: Custom elements extend HTMLElement
117+
```javascript
118+
class QuantityInput extends HTMLElement {
119+
constructor() {
120+
super();
121+
// Initialize
122+
}
123+
connectedCallback() { }
124+
disconnectedCallback() { }
125+
}
126+
customElements.define('quantity-input', QuantityInput);
127+
```
128+
129+
2. **Pub/Sub System** (`pubsub.js`): For cross-component communication
130+
```javascript
131+
subscribe(PUB_SUB_EVENTS.cartUpdate, callback);
132+
publish(PUB_SUB_EVENTS.cartUpdate, data);
133+
```
134+
135+
3. **Deferred Loading**: All JS uses `defer="defer"` attribute
136+
137+
4. **Progressive Enhancement**: Features work without JS; JS enhances the experience
138+
139+
5. **Event Constants** (`constants.js`): Define event names centrally
140+
141+
### Accessibility Requirements
142+
143+
- All interactive elements must be keyboard accessible
144+
- Use proper ARIA attributes (`aria-expanded`, `aria-controls`, `aria-label`)
145+
- Focus trapping for modals/drawers (see `trapFocus()` in `global.js`)
146+
- `prefers-reduced-motion` media query support
147+
- Skip links for keyboard navigation
148+
149+
### Translation Keys
150+
151+
Use translation keys instead of hardcoded strings:
152+
```liquid
153+
{{ 'products.product.add_to_cart' | t }}
154+
```
155+
156+
Translations are in `locales/en.default.json` for storefront and `locales/en.default.schema.json` for theme editor.
157+
158+
## Important Files
159+
160+
| File | Purpose |
161+
|------|---------|
162+
| `layout/theme.liquid` | Main layout wrapper with CSS variables and global scripts |
163+
| `assets/global.js` | Core Web Components (MenuDrawer, ModalDialog, SliderComponent, etc.) |
164+
| `assets/pubsub.js` | Event pub/sub system |
165+
| `assets/base.css` | Core CSS including color schemes and utility classes |
166+
| `config/settings_schema.json` | Theme-wide settings for the editor |
167+
| `snippets/card-product.liquid` | Product card with documented parameters |
168+
| `sections/header.liquid` | Site header with navigation |
169+
| `sections/main-product.liquid` | Product page main section |
170+
171+
## Quality Checks
172+
173+
Before submitting changes:
174+
175+
1. **Theme Check**: Run `shopify theme check` - all checks must pass
176+
2. **No console errors**: Test in browser DevTools
177+
3. **Keyboard navigation**: Test all interactive elements
178+
4. **Performance**: No layout shifts, no render-blocking resources
179+
5. **NoJS fallback**: Test with JavaScript disabled
180+
6. **Responsive**: Test at 375px, 750px, 990px, and 1440px widths
181+
182+
## CI/CD
183+
184+
The repository uses GitHub Actions (`.github/workflows/ci.yml`):
185+
- **Theme Check**: Validates Liquid code quality
186+
- **Lighthouse CI**: Performance audits on home, product, and collection pages
187+
188+
## Common Tasks
189+
190+
### Adding a new section
191+
192+
1. Create `sections/your-section.liquid`
193+
2. Add HTML structure with Liquid
194+
3. Include `{% schema %}` block with settings
195+
4. Create `assets/section-your-section.css` for styles
196+
5. Add translations to `locales/en.default.json` and schema translations
197+
198+
### Adding a new snippet
199+
200+
1. Create `snippets/your-snippet.liquid`
201+
2. Document accepted parameters in a `{% comment %}` block at the top
202+
3. Use `{% render 'your-snippet', param: value %}` to include
203+
204+
### Modifying JavaScript
205+
206+
1. Edit the relevant file in `assets/`
207+
2. For new components, define a Web Component extending HTMLElement
208+
3. Register with `customElements.define('component-name', ComponentClass)`
209+
4. Never add external dependencies
210+
211+
### Adding theme settings
212+
213+
1. Edit `config/settings_schema.json` to add setting definitions
214+
2. Access in Liquid via `{{ settings.your_setting }}`
215+
3. Add translation keys in `locales/*.schema.json`
216+
217+
## Anti-patterns to Avoid
218+
219+
- Adding external JavaScript libraries or frameworks
220+
- Using JavaScript for functionality that can be done with HTML/CSS
221+
- Render-blocking resources
222+
- DOM manipulation on page load (only on user interaction)
223+
- Inline styles (use CSS custom properties)
224+
- Hardcoded strings (use translation keys)
225+
- Breaking existing accessibility features
226+
- Adding polyfills (use progressive enhancement instead)

0 commit comments

Comments
 (0)