benjaminsehl/liquid-skills

Overview

This skill documents CSS, JavaScript, and HTML coding standards for Shopify Liquid themes. It focuses on progressive enhancement, design tokens, BEM naming, defensive CSS, and Web Components to keep theme code reliable and maintainable. Use it as a checklist and reference when authoring .liquid templates and theme asset files.

How this skill works

The guide explains where to place styles and scripts in Liquid (inline style attributes, {% stylesheet %}, assets), and prescribes patterns for class naming, CSS variable scoping, property ordering, and specificity. It also describes a lightweight Web Component pattern, fetch handling with AbortController, and HTML-first progressive enhancement practices for accessible, JS-enhanced components.

When to use it

• When writing CSS or SCSS for .liquid component and section files
• When adding JavaScript for component behavior or defining Web Components in assets
• When defining design tokens and CSS custom properties for theme-wide scales
• When implementing progressive enhancement or replacing brittle DOM-driven patterns
• When editing theme JSON templates or settings via scripted tools like jq

Best practices

• Prefer semantic HTML and progressive enhancement: HTML first, CSS second, JS only to enhance
• Never hardcode colors/spacings — define and use design tokens (CSS custom properties) with rem-based scales
• Follow BEM with single element level and pair modifiers with base classes (e.g., .block .block--modifier)
• Keep selector specificity low (single class preferred), avoid IDs and !important
• Use native browser APIs for JS, Web Components for encapsulation, and AbortController for safe fetches

Example use cases

• Create a product-card Web Component that dispatches custom events when items are added to cart
• Scope component tokens on the component root and override via inline style attributes from section settings
• Implement responsive components using container queries and clamp() for fluid spacing
• Build accessible accordions with <details>/<summary> and optionally enhance them with small JS for animations
• Edit templates/*.json or config/settings_data.json safely using jq to add or update sections