As you work with Liquid files to create Custom Sections, it’s important to follow these best-practice guidelines to ensure your code is well-organized and easy to maintain. For more information about Custom and Standard Sections and how to modify them in PathFactory, read How to Use the Themes Section Library and Add Custom Sections.

Note About Accessibility: To create accessible sections, ensure they follow web accessibility standards. Use semantic HTML tags, provide proper ARIA labels, and ensure keyboard navigability. 

Selector Strategy

When working with Liquid files, adopting a thoughtful selector strategy is key to creating efficient, maintainable code. The following guidelines will help you achieve consistency and avoid common pitfalls in your CSS and JavaScript.

• Class Naming Conventions – Important: 
  • Do not change existing IDs or classes. To do so may cause their associated CSS or javascript to not work.
  • Do not start a class name with a number, as it can lead to unexpected behavior.
  • Consistency in class naming aids in better identification.

• Prefer Classes Over IDs – To enhance accessibility testing and prevent duplicate ID issues, prioritize using classes over IDs as primary selectors. Classes offer more versatility, allowing for multiple instances and varied selections, unlike IDs that are limited to one instance.
• Variable Declaration – Declare all selectors as liquid variables at the top of the file, particularly for selectors composed of multiple variables. This promotes clarity and allows for easy global changes if needed, minimizing the risk of errors due to incorrect event listeners.
• Crafting Unique Selectors – Create unique selectors using a specific format to avoid conflicts. Be mindful of duplicates and account for multiple component instances and different sections using the same component. Format: {{ Component_description }}-{{ node-id }}-{{ component-id }}-{{ specificity }}. These selectors should be in class format.
• Order of Specificity – Arrange selector IDs in a top-down order based on the DOM hierarchy. This ensures a consistent and logical structure for easier identification.
• Selector Construction – Avoid Ancestor Chains. Minimize the use of ancestor chain selectors (e.g., “.parent > .child > .target”) and opt for containment selectors instead (e.g., “.parent .target”). Contain-selectors are more robust, as changes to the hierarchy won’t break the selector’s functionality.

Component Development Tips

In addition to a solid selector strategy, effective component development is essential for creating reusable and scalable code. Here are some best practices to keep in mind when building and managing components within your PathFactory themes.

• Props Declaration – Components accepting props should clearly define the expected props at the beginning of the file and provide example values. This documentation simplifies component usage for others.
• JavaScript Placement – Whenever possible, keep JavaScript code within the files where it is used. For instance, if a button component has a click event listener, place the listener in that component’s file. This approach offers better context and clarity.
• Exceptions – In cases of reusable functions, place them in a suitable common file, like the helpers folder, to ensure organized and manageable code.