diff --git a/rules-new/shopify-theme-dev-liquid.mdc b/rules-new/shopify-theme-dev-liquid.mdc new file mode 100644 index 00000000..8d89a3d3 --- /dev/null +++ b/rules-new/shopify-theme-dev-liquid.mdc @@ -0,0 +1,79 @@ +--- +description: Best practices for Shopify theme development with Liquid, JavaScript, and CSS +globs:**/*.liquid, assets/*.js, assets/*.css, sections/*.liquid, snippets/*.liquid, templates/**/*.liquid +--- + + +# Shopify Theme Development Best Practices + +## Project Structure +- Adopt a clear **directory structure**, e.g., `sections`, `snippets`, `templates`, `assets`. +- Organize **generic modules** (like JavaScript functionalities) into separate files. +- Keep **Liquid files** concise and focused on single responsibilities, avoiding monolithic files. +- Organize templates and sections by **page or functionality**. +- Implement proper **internationalization (i18n)** file management. +- Utilize **SCSS/CSS Modules** for style organization to prevent global pollution. + +## Liquid Templating +- Prefer the `render` tag over `include`. +- Limit **database queries** within loops to avoid N+1 issues. +- Use **filters** judiciously, especially complex computational ones. +- Leverage Liquid's **caching mechanisms** to reduce redundant calculations. +- Avoid complex **logic handling** directly in Liquid; move intricate logic to JavaScript. +- Use `assign` and `capture` to define and reuse variables effectively. + +## JavaScript Development +- Modularize JS, using **ES Modules** for imports and exports. +- Follow modern JavaScript **best practices**, such as `const`/`let`, arrow functions, etc. +- Avoid direct **DOM manipulation**; prioritize event delegation. +- Optimize **JavaScript performance** to reduce repaints and reflows. +- Consider using **Webpack/Rollup** for bundling and code optimization. +- Write clear **comments** and **JSDoc**. + +## CSS/SCSS Styling +- Adhere to naming conventions like **BEM, OOCSS, or Utility-First CSS**. +- Optimize **CSS selectors** to improve rendering performance. +- Use **CSS variables** to manage theme configurations like colors and fonts. +- Implement **responsive design** to ensure consistent theme appearance across devices. +- Minimize **CSS file size** by removing unused styles. +- Make good use of **SCSS mixins** and **functions**. + +## Sections and Blocks +- Utilize Section **Schema** to define configurable options. +- Maintain **section independence and reusability**. +- Provide clear **presets** for sections. +- Use **Blocks** appropriately to enhance section flexibility. +- Ensure sections provide a good user experience in the **Shopify Customizer**. +- Avoid hardcoding content within sections; use Schema configurations whenever possible. + +## Performance Optimization +- Optimize **image loading** by using Shopify's CDN and the `image_url` filter. +- Minify **JavaScript and CSS files**. +- Leverage **browser caching**. +- Reduce the number of **HTTP requests**. +- Consider **lazy loading**. +- Monitor **theme performance** using Google Lighthouse and Shopify Theme Check. + +## Accessibility (A11y) +- Ensure all interactive elements are **keyboard accessible**. +- Provide meaningful **`alt` text** for images. +- Use correct **HTML semantic tags**. +- Consider **color contrast**. +- Implement clear **focus states**. +- Use **ARIA attributes** to enhance the accessibility of complex components. + +## Maintenance and Scalability +- Write clear **code comments** and documentation. +- Follow **naming conventions** to maintain code consistency. +- Regularly **test** theme functionalities. +- Ensure compatibility across different **browsers and devices**. +- Consider future **extensibility**, avoiding tight coupling. +- Use **Shopify CLI** for local development and deployment. + +## Quality and Testing +- Use **Shopify Theme Check** for static code analysis. +- Write **unit tests** (where applicable). +- Conduct thorough **end-to-end testing**. +- Test in various environments (local, development store, production store). +- Focus on **compatibility testing** (browsers, devices, Shopify versions). +- Test **error handling** and edge cases. \ No newline at end of file