Cursor rule

1---
2description: Writing CSS, whether inside .css files or in the `{% stylesheet %}…{% endstylesheet %}` or `{% style %}…{% endstyle %}` tags
3globs:
4alwaysApply: false
5---
6 
7# CSS Standards
8 
9## Specificity Rules
10 
11- **Never** use IDs as selectors
12- **Avoid** using elements as selectors
13- **Avoid** using `!important` at all costs - if you must use it, comment why in the code
14- Use a `0 1 0` specificity wherever possible, meaning a single `.class` selector.
15- In cases where you must use higher specificity due to a parent/child relationship, try to keep the specificity to a maximum of `0 4 0`
16  - Note that this can sometimes be impossible due to the `0 1 0` specificity of pseudo-classes like `:hover`. There may be situations where `.parent:hover .child` is the only way to achieve the desired effect.
17- **Avoid** complex selectors. A selector should be easy to understand at a glance. Don't over do it with pseudo selectors (:has, :where, :nth-child, etc).
18 
19See [MDN](mdc:https:/developer.mozilla.org/en-US/docs/Web/CSS/Specificity) for more a comprehensive list of specificity rules.
20 
21### Notes on `:has()` selector and Shopify themes
22 
23The `:has()` selector is incredibly useful, but can impact performance. This is mainly a problem during dynamic DOM updates as the browser engines must re-evaluate `:has()` selectors. This is especially important in Shopify themes where dynamic content updates are common (cart updates, variant selection, filtering, etc.). See [MDN :has performance considerations](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:has#performance_considerations) for more information.
24 
25Performance mitigation strategies:
26 
27#### Minimize Subtree Traversals
28 
29Anchor of an element as close to the children as possible. i.e. `A:has(B)`, where `A` is the anchor.
30 
31Use combinators like `>` or `+` so there is a very clear path for the browser to evaluate. Anything too broad increases the number of leaf nodes to verify.
32 
33```css
34/* ❌ AVOID: May trigger full subtree traversal */
35.ancestor:has(.foo) {
36  /* Any change within .ancestor requires checking ALL descendants */
37}
38 
39/* ✅ GOOD: More constrained - limits traversal */
40.ancestor:has(> .foo) {
41  /* Only checks direct children */
42}
43```
44 
45#### Leverage server-rendered classes when possible
46 
47If the dynamic content is being server rendered, you might be able to write a class higher in the DOM than rely on `:has()`
48 
49Example: With filters, instead of checking based on the state of the inner `input` element, create a disabled class.
50 
51```css
52/* ❌ AVOID: Styling .filter-label based on child */
53.filter-label:has(input[disabled]) {
54  /* Disabled styles */
55}
56 
57/* ✅ GOOD: .disabled set server side */
58.filter-label.disabled {
59  /* Disabled styles */
60}
61```
62 
63This strategy won't work for client-side events, like a `checked`, `selected`, `focus` event.
64 
65## CSS Variables
66 
67CSS variables, a.k.a. custom properties, are a powerful tool for reducing redundancy and making it easier to update values across a component.
68 
69- If you need to hardcode a value, set it to a variable and use that variable in the declaration. Example: a touch target size. `--touch-target-size: 44px;`
70- **Never** hardcode colors, always use the color schemes
71 
72### Global Variables
73 
74Global variables should be scoped to the `:root` selector in `snippets/theme-styles-variables.liquid`.
75 
76Example of global variables:
77 
78```css
79/* in snippets/theme-styles-variables.liquid */
80:root {
81    --page-width: 1400px;
82     --font-body--family: {{ settings.type_body_font.family }}, {{ settings.type_body_font.fallback_families }}; /* Referencing a theme setting */
83     --font-{{ preset_name_dash }}--family: {{ settings[preset_font] | prepend: 'var(--font-' | append: '--family)' }}; /* Using Liquid to set a variable */
84}
85```
86 
87### Scoped Variables
88 
89Be sure to scope your CSS variables to the component they are being used in, if they are not meant to be global. Scoped variables can reference global variables.
90 
91Example of scoped variables:
92 
93```css
94/* in assets/facets.css */
95.facets {
96  --drawer-padding: var(--padding-md); /* Referencing a global variable */
97  --facets-upper-z-index: 3;
98  --facets-open-z-index: 4;
99 
100  --facets-clear-shadow: 0px -4px 14px 0px rgb(var(--color-foreground-rgb) / var(--opacity-10)); /* Referencing a Color Scheme variable */
101}
102```
103 
104### Namespace Your CSS Variables
105 
106Namespace your variables to avoid collisions unless you explicitly want them to bleed through to other components.
107 
108✅ Do this:
109 
110```css
111.component {
112  --component-padding: ...;
113  --component-aspect-ratio: ...;
114}
115```
116 
117❌ Don't do this:
118 
119```css
120.component {
121  --padding: ...;
122  --aspect-ratio: ...;
123}
124```
125 
126### Semantic Color Variables
127 
128Use semantic naming for better maintainability:
129 
130```css
131:root {
132  /* Base colors */
133  --color-primary: {{ settings.colors_accent_1 }};
134  --color-secondary: {{ settings.colors_accent_2 }};
135 
136  /* Semantic colors */
137  --color-foreground-muted: rgb(var(--color-rgb) / 0.6);
138  --color-text-disabled: rgb(var(--color-rgb) / 0.38);
139 
140  /* Interactive states */
141  --hover-color: var(--link-text-color-rgb, var(--color-foreground-rgb));
142  --color-active: var(--color-foreground);
143}
144```
145 
146### Design Token System
147 
148Establish consistent spacing and typography scales:
149 
150```css
151:root {
152  /* Spacing scale */
153  --space-3xs: 0.25rem; /* 4px */
154  --space-2xs: 0.5rem; /* 8px */
155  --space-xs: 0.75rem; /* 12px */
156  --space-sm: 1rem; /* 16px */
157  --space-md: 1.5rem; /* 24px */
158  --space-lg: 2rem; /* 32px */
159  --space-xl: 3rem; /* 48px */
160  --space-2xl: 4rem; /* 64px */
161  --space-3xl: 6rem; /* 96px */
162 
163  /* Typography scale */
164  --font-size-xs: 0.75rem; /* 12px */
165  --font-size-sm: 0.875rem; /* 14px */
166  --font-size-base: 1rem; /* 16px */
167  --font-size-lg: 1.125rem; /* 18px */
168  --font-size-xl: 1.25rem; /* 20px */
169  --font-size-2xl: 1.5rem; /* 24px */
170  --font-size-3xl: 1.875rem; /* 30px */
171}
172```
173 
174## Scoping CSS to Instances of Sections and Blocks
175 
176Reset CSS variable values inline on a `style` attribute with a section/block settings. This has a couple benefits:
177 
178- Less CSS in Liquid which allows us to use the `{% stylesheet %}` tag for all CSS.
179- Reduces redundancy in CSS selectors and number of selectors in the HTML, i.e. `.selector--{{ block.id }}` pattern.
180 
181✅ Do this:
182 
183```html
184<section
185  style="
186    --background-color: {{ settings.background_color }};
187    --padding: {{ settings.padding }}px;
188  "
189>
190  ...
191</section>
192 
193<button style="--button-color: {{ settings.button_color }};">...</button>
194```
195 
196❌ Don't do this:
197 
198```html
199{% style %} .selector--{{ block.id }} { --button-color: {{ settings.button_color }}; } {% endstyle %}
200 
201<button class="selector--{{ block.id }}">...</button>
202```
203 
204### Redundancy
205 
206Use variables to reduce property assignment redundancy.
207 
208```css
209/* Do this */
210.block-name {
211  background: rgb(var(--block-name-color) / 0.75);
212}
213 
214.block-name--secondary {
215  --block-name-color: var(--secondary-color);
216}
217 
218/* Not this */
219.block-name {
220  background: rgb(var(--primary-color) / 0.75);
221}
222 
223.block-name--secondary {
224  background: rgb(var(--secondary-color) / 0.75);
225}
226```
227 
228## BEM Naming Convention
229 
230Use the @BEM CSS convention for class names.
231 
232BEM TL;DR:
233 
234- **Block**: Component name (`.product-card`)
235- **Element**: Block + element (`.product-card__title`)
236- **Modifier**: Block/element + modifier (`.product-card--featured`)
237- **Use dashes** to separate words in names
238 
239```css
240/* Good BEM structure */
241.product-card {
242}
243.product-card__image {
244}
245.product-card__title {
246}
247.product-card__price {
248}
249.product-card--featured {
250}
251.product-card__title--large {
252}
253```
254 
255```css
256.block {
257  ...;
258}
259.block--modifier {
260  ...;
261}
262.block__element {
263  ...;
264}
265.block__multi-word-element {
266  ...;
267}
268.block__element--modifier {
269  ...;
270}
271.block__element--multi-word-modifier {
272  ...;
273}
274```
275 
276Dashes are used to separate words in blocks, elements, and modifiers.
277 
278Exception: We also use global @utility classes that can be applied to block and and elements without following BEM naming convention.
279 
280### Naming a "Block" (component)
281 
282The root "block" namespace must wrap any elements derived from it.
283 
284✅ Do this:
285 
286```html
287<div class="my-component">
288  <div class="my-component__wrapper"></div>
289</div>
290```
291 
292❌ Not this:
293 
294`.my-component__wrapper` is used as a parent to `.my-component`.
295 
296```html
297<div class="my-component__wrapper my-component--page-width">
298  <div class="my-component"></div>
299</div>
300```
301 
302### Naming an "Element" (child)
303 
304There should only be a _single_ "element" in a classname. Only the root "block" name needs to be included in child classnames. If additional naming specificity is necessary, use a "-" to seperate words or consider starting a new BEM scope altogether when an element could make sense as a standalone entity.
305 
306✅ Do this:
307 
308```html
309<div class="my-component my-component--full-width">
310  <div class="my-component__wrapper">
311    <button class="my-component__button">
312      <span class="my-component__button-label">My button</span>
313    </button>
314  </div>
315</div>
316```
317 
318✅ Or this:
319 
320Started new scope with `.button-component`.
321 
322```html
323<div class="my-component my-component--full-width">
324  <div class="my-component__wrapper">
325    <button class="button-component">
326      <span class="button-component__label">My button</span>
327    </button>
328  </div>
329</div>
330```
331 
332❌ Not this:
333 
334Multiple element names are used (`__wrapper__button__label`).
335 
336```html
337<div class="my-component my-component--full-width">
338  <div class="my-component__wrapper">
339    <button class="my-component__wrapper__button">
340      <span class="my-component__wrapper__button__label">My button</span>
341    </button>
342  </div>
343</div>
344```
345 
346### Naming a "Modifier" (variant)
347 
348Any "modifier" classname should always use a "--" and should always correspond to an existing block and element namespace. Never use a modifier class on an element that doesn't also have a base classname.
349 
350✅ Do this:
351 
352The `.button` class is the base classname and modified by `--secondary`.
353 
354```html
355<button class="button button--secondary"></button>
356```
357 
358❌ Not this:
359 
360The `.button` and `.button-secondary` classes are both named as _exclusive_ components and should not used together.
361 
362```html
363<button class="button button-secondary"></button>
364```
365 
366❌ Or this:
367 
368Modifer class is used without corresponding base classname.
369 
370```html
371<button class="button--secondary"></button>
372```
373 
374Also consider keeping modifiers at the highest element that makes sense. This makes the component more extensible and resilient as styling needs are changed or added in the future.
375 
376✅ Do this:
377 
378```html
379<div class="my-component my-component--size-large my-component--page-width">
380  <div class="my-component__wrapper"></div>
381</div>
382```
383 
384### Utility Classes
385 
386Utility classes are intended to act as global overrides for a single styling decision, e.g. alignment, show/hide, etc. BEM conventions are not followed, there is no hierarchy in utility classes and utility classes do not assume they are used with any particular block or element.
387 
388Name multi-word utility classes with hyphens `-`. Append any viewport specifications at the **end**, e.g. `hidden-mobile`.
389 
390✅ This is fine:
391 
392```css
393.align-left {
394  text-align: left;
395}
396```
397 
398```html
399<div class="my-component align-left">
400  <p class="my-component__text"></p>
401</div>
402```
403 
404## Modern CSS Features
405 
406### Container Queries
407 
408Use container queries for truly responsive components:
409 
410```css
411.product-grid {
412  container-type: inline-size;
413}
414 
415@container (min-width: 400px) {
416  .product-card {
417    display: grid;
418    grid-template-columns: 1fr 1fr;
419  }
420}
421```
422 
423### CSS Functions
424 
425Leverage modern CSS functions for better responsiveness:
426 
427```css
428.component {
429  /* Fluid spacing */
430  padding: clamp(1rem, 4vw, 3rem);
431 
432  /* Intrinsic sizing */
433  width: min(100%, 800px);
434 
435  /* Dynamic colors */
436  /* color-mix isn't supported in earlier version of iOS <16.2 so limit its usage */
437  background: color-mix(in srgb, rgb(var(--color-primary)) 90%, white);
438}
439```
440 
441### Cascade Layers
442 
443For better CSS organization in complex themes:
444 
445```css
446@layer reset, base, components, utilities, overrides;
447 
448@layer components {
449  .button {
450    /* Component styles here won't conflict with utilities */
451  }
452}
453```
454 
455### View Transitions
456 
457```css
458@view-transition {
459  navigation: auto;
460}
461 
462.page-content {
463  view-transition-name: main-content;
464}
465```
466 
467## Media Queries
468 
469- Default to mobile first. e.g. `min-width` queries
470- Use `screen` for all media queries
471 
472### Breakpoint System
473 
474Define consistent breakpoints:
475 
476```css
477/* Mobile first breakpoints */
478--breakpoint-sm: 576px; /* Small devices */
479--breakpoint-md: 768px; /* Medium devices */
480--breakpoint-lg: 992px; /* Large devices */
481--breakpoint-xl: 1200px; /* Extra large devices */
482--breakpoint-2xl: 1400px; /* 2X Extra large devices */
483```
484 
485### Context-Aware Queries
486 
487Use feature queries alongside media queries:
488 
489```css
490@supports (display: grid) {
491  .product-grid {
492    display: grid;
493    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
494  }
495}
496 
497@supports not (display: grid) {
498  .product-grid {
499    display: flex;
500    flex-wrap: wrap;
501  }
502}
503```
504 
505### Print Styles
506 
507Always consider print stylesheets:
508 
509```css
510@media print {
511  .no-print {
512    display: none !important;
513  }
514 
515  a[href^='http']:after {
516    content: ' (' attr(href) ')';
517  }
518}
519```
520 
521## CSS Nesting Rules
522 
523Nesting can make styles harder to read. Be responsible with it.
524 
525- **No `&` operator** in nested selectors
526- **Never nest beyond first level** (except media queries/states)
527- **Keep nesting simple** and readable
528- Only use `&` when there is a direct relationship between the two selectors
529  - State based selectors e.g. `&:hover`, `&:focus`, `&:active`
530  - Modifiers that affect each other e.g. `button--integrated { &.button--text }`
531- Never nest beyond the first level
532- See below for exceptions
533 
534### Nesting Media Queries
535 
536Use nesting for media queries
537 
538```css
539.header {
540  width: 100%;
541 
542  @media screen and (min-width: 750px) {
543    width: 100px;
544  }
545}
546```
547 
548This includes when there is nothing to override, e.g.
549 
550```css
551.header {
552  @media screen and (min-width: 750px) {
553    width: 100px;
554  }
555}
556```
557 
558That way, if something needs to be added later, it can just be added without needing to flip the media query to the inside.
559 
560### If-like Parent-Child Relationships
561 
562You may use nesting to help organize parent-child relationship when the parent can have **multiple states or modifiers** that affect children. In the example below, a number of child selectors need to change when the parent is the `--full-width` variant. This saves you from needing to append `parent--full-width` to each css selector.
563 
564```css
565.parent {
566  grid-columns: var(--gap) 1fr var(--gap);
567}
568 
569.child {
570  grid-column: 2;
571}
572 
573.grand-child {
574  ...;
575}
576 
577.parent--full-screen {
578  grid-columns: 1fr;
579 
580  .child {
581    grid-column: 1;
582  }
583 
584  .grand-child {
585    ...;
586  }
587}
588```
589 
590In cases like this, the styles that are being applied are the direct result of the parent's modifier. We can see this as a kind of if-like relationship where the logic is easier to follow if the child styles are nested inside the parent.
591 
592This is not a reason to nest multiple levels. Maintain the single level rule.
593 
594## Logical Properties
595 
596Where appropriate, use logical properties to have baseline support for Right-to-Left (RTL) languages.
597Focusing on these properties:
598 
599- padding
600- margin
601- border
602- text-align
603- top, bottom, left, right
604 
605✅ Do this:
606 
607```css
608.element {
609  padding-inline: 2rem;
610  padding-block: 1rem;
611  margin-inline: auto;
612  margin-block: 0;
613  border-inline-end: 1rem solid var(--color-background);
614  text-align: start;
615  inset: 0;
616}
617```
618 
619❌ Not this:
620 
621```css
622.element {
623  padding: 1rem 2rem;
624  margin: 0 auto;
625  border-bottom: 1rem solid var(--color-background);
626  text-align: left;
627  top: 0;
628  bottom: 0;
629  left: 0;
630  right: 0;
631}
632```
633 
634## Layout Patterns
635 
636### CSS Grid for Layouts
637 
638```css
639.section-content {
640  display: grid;
641  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
642  gap: var(--spacing-lg);
643}
644```
645 
646### Flexbox for Components
647 
648```css
649.product-card {
650  display: flex;
651  flex-direction: column;
652  gap: var(--spacing-sm);
653}
654```
655 
656### Aspect Ratio for Media
657 
658```css
659.product-card__image {
660  aspect-ratio: 4 / 3;
661  object-fit: cover;
662}
663```
664 
665## Fancy Selectors
666 
667### Using `:is()`
668 
669When giving the same styles to multiple selectors, use a comma separated list.
670 
671✅ Do this:
672 
673```css
674.facets__label,
675.facets__clear-all,
676.clear-filter {
677  ...;
678}
679```
680 
681❌ Not this:
682 
683```css
684:is(.facets__label, .facets__clear-all, .clear-filter) {
685  ...;
686}
687```
688 
689However, if you are giving the same styles to a parent-child relationship with different selectors, you may use `:is()`.
690 
691✅ Do this:
692 
693```css
694.parent:is(.child-1, .child-2) {
695  ...;
696}
697```
698 
699❌ Not this:
700 
701```css
702.parent .child-1,
703.parent .child-2 {
704  ...;
705}
706```
707 
708✅ Do this:
709 
710```css
711:is(.parent, .parent-2) .child {
712  ...;
713}
714```
715 
716❌ Not this:
717 
718```css
719.parent .child,
720.parent-2 .child {
721  ...;
722}
723```
724 
725Try to keep the same specificity for all selectors within a single `:is()` to avoid increasing the overall specificity of the selector unintentionally.
726 
727## Accessibility
728 
729### Motion and Animation
730 
731- Always respect user motion preferences
732- Provide fallbacks for users who prefer reduced motion
733 
734```css
735@media (prefers-reduced-motion: reduce) {
736  *,
737  *::before,
738  *::after {
739    animation-duration: 0.01ms !important;
740    animation-iteration-count: 1 !important;
741    transition-duration: 0.01ms !important;
742    scroll-behavior: auto !important;
743  }
744}
745```
746 
747### Focus Management
748 
749- Ensure all interactive elements have visible focus indicators
750- Use `:focus-visible` for better UX
751 
752```css
753.button:focus-visible {
754  outline: 2px solid rgb(var(--color-focus));
755  outline-offset: 2px;
756}
757```
758 
759### Color and Contrast
760 
761- Maintain WCAG AA contrast ratios (4.5:1 for normal text, 3:1 for large text)
762- Test with high contrast mode
763- Never rely solely on color to convey information
764 
765```css
766@media (prefers-color-scheme: dark) {
767  :root {
768    /* Dark theme variables */
769  }
770}
771```
772 
773## Performance Considerations
774 
775### Animation Performance
776 
777- Use `transform` and `opacity` for animations
778- Avoid animating layout properties (`width`, `height`, `margin`, `padding`)
779- Use `will-change` sparingly and remove after animation
780 
781```css
782.product-card {
783  transition: transform 0.2s ease;
784}
785 
786.product-card:hover {
787  transform: translateY(-2px); /* Better than animating top/margin */
788}
789 
790/* Only use will-change during animation */
791.product-card:hover {
792  will-change: transform;
793}
794 
795.product-card:not(:hover) {
796  will-change: auto;
797}
798```
799 
800### Layout Performance
801 
802- Use `contain` property for better rendering performance
803- Prefer CSS Grid and Flexbox over complex positioning
804 
805```css
806.product-grid {
807  contain: content;
808  display: grid;
809  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
810}
811```
812 
813## CSS Organization
814 
815### CSS Property Order
816 
817Maintain consistent property order within declarations:
818 
819```css
820.component {
821  /* 1. Layout & Positioning */
822  position: relative;
823  display: flex;
824  flex-direction: column;
825 
826  /* 2. Box Model */
827  width: 100%;
828  margin: 0;
829  padding: var(--space-md);
830  border: 1px solid rgb(var(--color-border));
831 
832  /* 3. Typography */
833  font-family: var(--font-body-family);
834  font-size: var(--font-size-base);
835 
836  /* 4. Visual */
837  background: rgb(var(--color-surface));
838  color: rgb(var(--color-text));
839 
840  /* 5. Animation & Transforms */
841  transition: transform 0.2s ease;
842}
843```
844 
845## Error Prevention
846 
847### Common Pitfalls
848 
849- **Never** use `position: fixed` without considering mobile keyboards
850- **Always** test with zoom up to 200%
851- **Avoid** magic numbers - use variables or calc() instead
852- **Remember** that `vh` units can be problematic on mobile, use `dvh` to mitage this
853 
854### Defensive CSS
855 
856Write CSS that gracefully handles edge cases:
857 
858```css
859.product-card {
860  /* Prevent content overflow */
861  word-wrap: break-word;
862  overflow-wrap: break-word;
863 
864  /* Handle long content */
865  min-width: 0; /* Allows flex items to shrink below content size */
866 
867  /* Prevent layout shift */
868  aspect-ratio: 1 / 1;
869 
870  /* Fallback for missing images */
871  background: rgb(var(--color-surface-secondary));
872}
873```
874 
875### Browser Support
876 
877- Test in browsers used by your audience
878- Provide fallbacks for newer CSS features
879- Use progressive enhancement approach
880 
881## CSS Documentation
882 
883### Commenting Standards
884 
885Use consistent commenting for better maintainability:
886 
887```css
888/* =============================================================================
889   Component Name
890   ============================================================================= */
891 
892/**
893 * Brief component description
894 *
895 * @example
896 * <div class="component component--modifier">
897 *   <div class="component__element">Content</div>
898 * </div>
899 */
900.component {
901  /* Implementation */
902}
903 
904/* Component modifiers
905   ========================================================================== */
906 
907/**
908 * Modifier description
909 */
910.component--modifier {
911  /* Modifier styles */
912}
913 
914/* Component elements
915   ========================================================================== */
916 
917/**
918 * Element description
919 */
920.component__element {
921  /* Element styles */
922}
923```
924 
925## Example Component Structure
926 
927```liquid
928{% stylesheet %}
929  .featured-collection {
930    --section-padding: {{ section.settings.padding | default: 60 }}px;
931    --bg-color: {{ section.settings.background_color | default: '#ffffff' }};
932    --color: {{ section.settings.text_color | default: '#000000' }};
933 
934    padding: var(--section-padding) 0;
935    background-color: var(--bg-color);
936    color: var(--color);
937    container-type: inline-size;
938  }
939 
940  .featured-collection__grid {
941    display: grid;
942    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
943    gap: var(--spacing-md);
944  }
945 
946  @container (min-width: 768px) {
947    .featured-collection__grid {
948      grid-template-columns: repeat({{ section.settings.columns | default: 4 }}, 1fr);
949    }
950  }
951 
952  @media (prefers-reduced-motion: reduce) {
953    .featured-collection * {
954      transition: none !important;
955    }
956  }
957{% endstylesheet %}
958```
959