Cursor rule

1---
2description:
3globs: *.liquid
4alwaysApply: false
5---
6# Modern HTML Standards
7 
8Use the latest evergreen browser features for better user experience and simpler code.
9All features should be supported in the last two versions of all major browsers.
10All necessary features must be "Baseline widely available".
11Progressive enhancement features may be "Baseline 2024".
12These are strictly for UX improvements that are non-blocking for conversions.
13 
14## Native Interactive Elements
15 
16**Expandable Content:**
17- Use `<details>` and `<summary>` instead of JavaScript toggles
18- Perfect for FAQs, product details, filters
19- See the [accordion component](mdc:assets/accordion-custom.js) for cases where animation is involved
20 
21**Modals and Popups:**
22- Use `<dialog>` for modals instead of custom overlays
23- Built-in focus management and backdrop clicks
24- See the [dialog component](mdc:assets/dialog.js) for how we use these
25 
26**Tooltips and Menus:**
27- Use `popover` attribute for floating content
28- Automatic positioning and dismissal
29 
30**Forms:**
31- Use `<search>` element for search forms
32- Use `<output>` for form calculations and results
33 
34### Input Types (HTML5+)
35```html
36<input type="text">        <!-- Basic text input -->
37<input type="email">       <!-- Email with validation -->
38<input type="tel">         <!-- Telephone numbers -->
39<input type="url">         <!-- URLs with validation -->
40<input type="search">      <!-- Search field with clear button -->
41<input type="password">    <!-- Password field -->
42 
43<!-- Numeric inputs -->
44<input type="number">      <!-- Numeric input with spinner -->
45<input type="range">       <!-- Slider control -->
46 
47<!-- Date/Time inputs -->
48<input type="date">        <!-- Date picker -->
49<input type="time">        <!-- Time picker -->
50<input type="datetime-local"> <!-- Date and time picker -->
51<input type="month">       <!-- Month picker -->
52<input type="week">        <!-- Week picker -->
53 
54<!-- Selection inputs -->
55<input type="checkbox">    <!-- Checkbox -->
56<input type="radio">       <!-- Radio button -->
57<input type="color">       <!-- Color picker -->
58<input type="file">        <!-- File upload -->
59 
60<!-- Action inputs -->
61<input type="submit">      <!-- Submit button -->
62<input type="reset">       <!-- Reset button -->
63<input type="button">      <!-- Generic button -->
64<input type="image">       <!-- Image button -->
65 
66<!-- Hidden -->
67<input type="hidden">      <!-- Hidden data -->
68```
69 
70### Container Elements
71```html
72<!-- Form container -->
73<form>                     <!-- Form wrapper -->
74<fieldset>                 <!-- Group related inputs -->
75<legend>                   <!-- Fieldset label -->
76 
77<!-- Modern semantic containers -->
78<search>                   <!-- Search form container (HTML5.3) -->
79```
80 
81### Text Areas
82```html
83<textarea>                 <!-- Multi-line text input -->
84```
85 
86### Selection Elements
87```html
88<select>                   <!-- Dropdown menu -->
89<option>                   <!-- Option in dropdown -->
90<optgroup>                 <!-- Group options -->
91<datalist>                 <!-- Autocomplete suggestions -->
92```
93 
94### Labels and Output
95```html
96<label>                    <!-- Input label -->
97<output>                   <!-- Calculation/result display -->
98```
99 
100### Buttons
101```html
102<button type="submit">     <!-- Submit form -->
103<button type="reset">      <!-- Reset form -->
104<button type="button">     <!-- Generic button -->
105```
106 
107### Progress and Meters
108```html
109<progress>                 <!-- Progress indicator -->
110<meter>                    <!-- Gauge/measurement display -->
111```
112 
113### Modern Form Attributes
114```html
115<!-- Validation attributes -->
116required                   <!-- Field must be filled -->
117pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}" <!-- Regex validation -->
118minlength="5"              <!-- Minimum character length -->
119maxlength="50"             <!-- Maximum character length -->
120min="1"                    <!-- Minimum numeric value -->
121max="100"                  <!-- Maximum numeric value -->
122step="0.01"                <!-- Numeric increment -->
123 
124<!-- Autocomplete attributes -->
125autocomplete="name"        <!-- Enable specific autocomplete -->
126autocomplete="off"         <!-- Disable autocomplete -->
127list="suggestions"         <!-- Link to datalist -->
128 
129<!-- Input hints -->
130placeholder="Enter email"  <!-- Placeholder text -->
131autofocus                  <!-- Focus on page load -->
132readonly                   <!-- Read-only field -->
133disabled                   <!-- Disabled field -->
134multiple                   <!-- Multiple file/email selection -->
135 
136<!-- Form behavior -->
137formnovalidate            <!-- Skip validation (on submit buttons) -->
138formaction="/alt-submit"  <!-- Alternative submission URL -->
139formmethod="post"         <!-- Override form method -->
140formenctype="multipart/form-data" <!-- Override encoding -->
141```
142 
143Use [client-side form validation](mdc:https:/developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation) to ensure valid date is being sent to the server.
144 
145## Modern CSS Features
146 
147**Layout:**
148- `container-queries` for responsive components
149- `aspect-ratio` for maintaining proportions
150- `scroll-snap` for carousel behavior
151 
152**Styling:**
153- `color-mix()` for dynamic color generation (used for progressive enhancement)
154- `view-transitions` for smooth page transitions
155- `@layer` for CSS cascade control
156 
157**Interactions:**
158- `:has()` selector for parent styling
159- `@media (prefers-reduced-motion)` for accessibility
160 
161## Progressive Enhancement
162 
163Use features that are `Baseline Widely Available`.
164 
1651. **Start with semantic HTML** that works without JavaScript
1662. **Layer on CSS** for visual enhancement
1673. **Add JavaScript** for advanced interactions and accessibility
1684. **Polyfill** for modern browsers if necessary for critical interactions
1695. **Never break core functionality** for older browsers
170 
171## Accessibility Features
172 
173**Focus Management:**
174- Use `tabindex="0"` for custom interactive elements
175- Never use positive tabindex values
176- Ensure keyboard navigation works naturally
177- Ensure focus is trapped in modal contexts
178 
179**Screen Readers:**
180- Use semantic HTML elements
181- Add `aria-label` when visual context isn't enough
182- Use `aria-expanded` for collapsible content
183- Use `aria-role` where appropriate
184 
185**Motion Preferences:**
186 
187Write CSS where animations can be disabled if reduced motion is preferred.
188 
189```css
190@media (prefers-reduced-motion: reduce) {
191  .carousel {
192    scroll-behavior: auto;
193  }
194}
195```
196 
197## ID Naming Convention
198 
199Use `CamelCase` for IDs and append section/block identifiers:
200 
201```html
202<!-- Section IDs -->
203<section id="FeaturedCollection-{{ section.id }}">
204 
205<!-- Block IDs -->
206<div id="ProductCard-{{ block.id }}">
207 
208<!-- Element IDs -->
209<dialog id="ProductModal-{{ product.id }}-{{ section|block.id }}">
210<form id="ProductForm-{{ product.id }}-{{ section|block.id }}">
211```
212 
213Section and block IDs are the only things we can guarantee are unique, and so should always be included in `id`s.
214 
215## Examples
216 
217**Expandable FAQ:**
218```html
219<details class="faq">
220  <summary class="faq__question">
221    {{ 'faq.shipping_question' | t }}
222  </summary>
223  <div class="faq__answer">
224    {{ 'faq.shipping_answer' | t }}
225  </div>
226</details>
227```
228 
229**Modal Dialog:**
230```html
231<button class="product__quick-view" onclick="ProductModal{{ product.id }}.showModal()">
232  {{ 'products.quick_view' | t }}
233</button>
234 
235<dialog id="ProductModal{{ product.id }}" class="product-modal">
236  <form method="dialog">
237    <button type="submit" class="modal__close">
238      {{ 'general.close' | t }}
239    </button>
240  </form>
241  <div class="modal__content">
242    {% render 'product-details', product: product %}
243  </div>
244</dialog>
245```
246 
247**Popover Menu:**
248```html
249<button popovertarget="CartMenu" class="header__cart">
250  {{ 'cart.title' | t }} ({{ cart.item_count }})
251</button>
252 
253<div id="CartMenu" popover class="cart-popover">
254  {% render 'cart-drawer' %}
255</div>
256```
257 
258**Search Form:**
259```html
260<search class="header__search">
261  <form action="{{ routes.search_url }}" method="get">
262    <input
263      type="search"
264      name="q"
265      placeholder="{{ 'general.search_placeholder' | t }}"
266      value="{{ search.terms | escape }}"
267    >
268    <button type="submit">{{ 'general.search' | t }}</button>
269  </form>
270</search>
271```
272 
273**Responsive Product Card:**
274```html
275<div class="product-card" style="container-type: inline-size;">
276  <div class="product-card__media">
277    {{ product.featured_image | image_url: width: 800 | image_tag }}
278  </div>
279  <div class="product-card__info">
280    <h3>{{ product.title | escape }}</h3>
281    <output class="product-card__price">
282      {{ product.price | money }}
283    </output>
284  </div>
285</div>
286```
287 
288## Avoid These Patterns
289 
290**Don't use custom JavaScript for:**
291- Show/hide toggles (use `<details>`)
292- Modal overlays (use `<dialog>`)
293- Tooltips (use `popover`)
294- Form validation (use native HTML5)
295 
296**Don't create:**
297- Custom dropdown menus (use `<select>` or `popover`)
298- Custom accordions (use `<details>`)
299- Custom tabs (use CSS `:target` or native behavior)
300