## Liquid Rules

### Valid Filters
* **Cart**
* `item_count_for_variant`: `cart | item_count_for_variant: {variant_id}`
* `line_items_for`: `cart | line_items_for: object`
* **HTML**
* `class_list`: `settings.layout | class_list`
* `time_tag`: `string | time_tag: string`
* `inline_asset_content`: `asset_name | inline_asset_content`
* `highlight`: `string | highlight: string`
* `link_to`: `string | link_to: string`
* `placeholder_svg_tag`: `string | placeholder_svg_tag`
* `preload_tag`: `string | preload_tag: as: string`
* `script_tag`: `string | script_tag`
* `stylesheet_tag`: `string | stylesheet_tag`
* **Collection**
* `link_to_type`: `string | link_to_type`
* `link_to_vendor`: `string | link_to_vendor`
* `sort_by`: `string | sort_by: string`
* `url_for_type`: `string | url_for_type`
* `url_for_vendor`: `string | url_for_vendor`
* `within`: `string | within: collection`
* `highlight_active_tag`: `string | highlight_active_tag`
* **Color**
* `brightness_difference`: `string | brightness_difference: string`
* `color_brightness`: `string | color_brightness`
* `color_contrast`: `string | color_contrast: string`
* `color_darken`: `string | color_darken: number`
* `color_desaturate`: `string | color_desaturate: number`
* `color_difference`: `string | color_difference: string`
* `color_extract`: `string | color_extract: string`
* `color_lighten`: `string | color_lighten: number`
* `color_mix`: `string | color_mix: string, number`
* `color_modify`: `string | color_modify: string, number`
* `color_saturate`: `string | color_saturate: number`
* `color_to_hex`: `string | color_to_hex`
* `color_to_hsl`: `string | color_to_hsl`
* `color_to_rgb`: `string | color_to_rgb`
* `hex_to_rgba`: `string | hex_to_rgba`
* **String**
* `hmac_sha1`: `string | hmac_sha1: string`
* `hmac_sha256`: `string | hmac_sha256: string`
* `md5`: `string | md5`
* `sha1`: `string | sha1: string`
* `sha256`: `string | sha256: string`
* `append`: `string | append: string`
* `base64_decode`: `string | base64_decode`
* `base64_encode`: `string | base64_encode`
* `base64_url_safe_decode`: `string | base64_url_safe_decode`
* `base64_url_safe_encode`: `string | base64_url_safe_encode`
* `capitalize`: `string | capitalize`
* `downcase`: `string | downcase`
* `escape`: `string | escape`
* `escape_once`: `string | escape_once`
* `lstrip`: `string | lstrip`
* `newline_to_br`: `string | newline_to_br`
* `prepend`: `string | prepend: string`
* `remove`: `string | remove: string`
* `remove_first`: `string | remove_first: string`
* `remove_last`: `string | remove_last: string`
* `replace`: `string | replace: string, string`
* `replace_first`: `string | replace_first: string, string`
* `replace_last`: `string | replace_last: string, string`
* `rstrip`: `string | rstrip`
* `slice`: `string | slice`
* `split`: `string | split: string`
* `strip`: `string | strip`
* `strip_html`: `string | strip_html`
* `strip_newlines`: `string | strip_newlines`
* `truncate`: `string | truncate: number`
* `truncatewords`: `string | truncatewords: number`
* `upcase`: `string | upcase`
* `url_decode`: `string | url_decode`
* `url_encode`: `string | url_encode`
* `camelize`: `string | camelize`
* `handleize`: `string | handleize`
* `url_escape`: `string | url_escape`
* `url_param_escape`: `string | url_param_escape`
* `pluralize`: `number | pluralize: string, string`
* **Localization**
* `currency_selector`: `form | currency_selector`
* `translate`: `string | t`
* `format_address`: `address | format_address`
* **Customer**
* `customer_login_link`: `string | customer_login_link`
* `customer_logout_link`: `string | customer_logout_link`
* `customer_register_link`: `string | customer_register_link`
* `avatar`: `customer | avatar`
* `login_button`: `shop | login_button`
* **Format**
* `date`: `string | date: string`
* `json`: `variable | json`
* `structured_data`: `variable | structured_data`
* `weight_with_unit`: `number | weight_with_unit`
* **Font**
* `font_face`: `font | font_face`
* `font_modify`: `font | font_modify: string, string`
* `font_url`: `font | font_url`
* **Default**
* `default_errors`: `string | default_errors`
* `default`: `variable | default: variable`
* `default_pagination`: `paginate | default_pagination`
* **Payment**
* `payment_button`: `form | payment_button`
* `payment_terms`: `form | payment_terms`
* `payment_type_img_url`: `string | payment_type_img_url`
* `payment_type_svg_tag`: `string | payment_type_svg_tag`
* **Math**
* `abs`: `number | abs`
* `at_least`: `number | at_least`
* `at_most`: `number | at_most`
* `ceil`: `number | ceil`
* `divided_by`: `number | divided_by: number`
* `floor`: `number | floor`
* `minus`: `number | minus: number`
* `modulo`: `number | modulo: number`
* `plus`: `number | plus: number`
* `round`: `number | round`
* `times`: `number | times: number`
* **Array**
* `compact`: `array | compact`
* `concat`: `array | concat: array`
* `find`: `array | find: string, string`
* `find_index`: `array | find_index: string, string`
* `first`: `array | first`
* `has`: `array | has: string, string`
* `join`: `array | join`
* `last`: `array | last`
* `map`: `array | map: string`
* `reject`: `array | reject: string, string`
* `reverse`: `array | reverse`
* `size`: `variable | size`
* `sort`: `array | sort`
* `sort_natural`: `array | sort_natural`
* `sum`: `array | sum`
* `uniq`: `array | uniq`
* `where`: `array | where: string, string`
* **Media**
* `external_video_tag`: `variable | external_video_tag`
* `external_video_url`: `media | external_video_url: attribute: string`
* `image_tag`: `string | image_tag`
* `media_tag`: `media | media_tag`
* `model_viewer_tag`: `media | model_viewer_tag`
* `video_tag`: `media | video_tag`
* `article_img_url`: `variable | article_img_url`
* `collection_img_url`: `variable | collection_img_url`
* `image_url`: `variable | image_url: width: number, height: number`
* `img_tag`: `string | img_tag`
* `img_url`: `variable | img_url`
* `product_img_url`: `variable | product_img_url`
* **Metafield**
* `metafield_tag`: `metafield | metafield_tag`
* `metafield_text`: `metafield | metafield_text`
* **Money**
* `money`: `number | money`
* `money_with_currency`: `number | money_with_currency`
* `money_without_currency`: `number | money_without_currency`
* `money_without_trailing_zeros`: `number | money_without_trailing_zeros`
* **Tag**
* `link_to_add_tag`: `string | link_to_add_tag`
* `link_to_remove_tag`: `string | link_to_remove_tag`
* `link_to_tag`: `string | link_to_tag`
* **Hosted_file**
* `asset_img_url`: `string | asset_img_url`
* `asset_url`: `string | asset_url`
* `file_img_url`: `string | file_img_url`
* `file_url`: `string | file_url`
* `global_asset_url`: `string | global_asset_url`
* `shopify_asset_url`: `string | shopify_asset_url`

### Valid Tags
* **Theme**
* `content_for`
* `layout`
* `include`
* `render`
* `javascript`
* `section`
* `stylesheet`
* `sections`
* **HTML**
* `form`
* `style`
* **Variable**
* `assign`
* `capture`
* `decrement`
* `increment`
* **Iteration**
* `break`
* `continue`
* `cycle`
* `for`
* `tablerow`
* `paginate`
* `else`
* **Conditional**
* `case`
* `if`
* `unless`
* `else`
* **Syntax**
* `comment`
* `echo`
* `raw`
* `liquid`

### Valid Objects
* `collections`
* `pages`
* `all_products`
* `articles`
* `blogs`
* `cart`
* `closest`
* `content_for_header`
* `customer`
* `images`
* `linklists`
* `localization`
* `metaobjects`
* `request`
* `routes`
* `shop`
* `theme`
* `settings`
* `template`
* `additional_checkout_buttons`
* `all_country_option_tags`
* `canonical_url`
* `content_for_additional_checkout_buttons`
* `content_for_index`
* `content_for_layout`
* `country_option_tags`
* `current_page`
* `handle`
* `page_description`
* `page_image`
* `page_title`
* `powered_by_link`
* `scripts`

### Validation Rules
* **Syntax**
* Use `{% liquid %}` for multiline code.
* Use `{% # comments %}` for inline comments.
* Never invent new filters, tags, or objects.
* Follow proper tag closing order.
* Use proper object dot notation.
* Respect object scope and availability.
* **Theme Structure**
* Place files in appropriate directories.
* Follow naming conventions.
* Respect template hierarchy.
* Maintain proper section/block structure.
* Use appropriate schema settings.

## Theme Architecture

### Folder Structure
* `sections`: Liquid files that define customizable sections of a page. They include blocks and settings defined via a schema, allowing merchants to modify them in the theme editor.
* `blocks`: Configurable elements within sections that can be added, removed, or reordered. They are defined with a schema tag for merchant customization in the theme editor.
* `layout`: Defines the structure for repeated content such as headers and footers, wrapping other template files. It's the frame that holds the page together, but it's not the content.
* `snippets`: Reusable code fragments included in templates, sections, and layouts via the render tag. Ideal for logic that needs to be reused but not directly edited in the theme editor.
* `config`: Holds settings data and schema for theme customization options like typography and colors, accessible through the Admin theme editor.
* `assets`: Contains static files such as CSS, JavaScript, and images. These assets can be referenced in Liquid files using the `asset_url` filter.
* `locales`: Stores translation files for localizing theme editor and storefront content.
* `templates`: JSON files that specify which sections appear on each page type (e.g., product, collection, blog). They are wrapped by layout files for consistent header/footer content. Templates can be Liquid files as well, but JSON is preferred as a good practice.
* `templates/customers`: Templates for customer-related pages such as login and account overview.
* `templates/metaobject`: Templates for rendering custom content types defined as metaobjects.

## UX Principles

### Translations
* Keep every piece of text in the theme translated.
* Update the locale files with sensible keys and text.
* Just add English text, not other languages, as translators handle other languages.

### Settings

#### General Guidance
* Keep it simple, clear, and non-repetitive.
* The setting type can provide context that the setting label doesn't need to provide. Example: "Number of columns" can simply be "Columns" if the input indicates that it's a number value.
* Assume all settings to be device-agnostic, with graceful scaling between breakpoints. Only mention mobile or desktop if there is a unique setting required.
* Use common shorthand where it makes sense. Example: Max/Min to mean Maximum and Minimum. Caveat: ensure these values are translated/localized correctly.
* Help text: Minimize use as much as possible. If really required, make it short and remove punctuation unless it's more than 1 sentence (but it shouldn't be!).

#### Information Architecture

* **Ordering**
* List settings to reflect the order of elements they control in the preview. Top to bottom, left to right, background to foreground.
* List resource pickers first, if they're needed, followed by customization settings. Focus on what the merchant needs to take action on in order for the section/block to function. Example: a featured collection block needs the merchant to choose a collection before deciding the number of products per row.
* List settings in order of visual impact, example: Number of products per row should come before the product card settings.
* **Groupings**
* Consider grouping settings under a heading if there are more than 1 related setting. List ungrouped settings at the top of the section/block.
* Common groupings:
* Layout
* Typography
* Colors
* Padding
* **Naming**
* Remove word duplication in the heading and nested labels. When a word appears in a heading (e.g., "Color"), it should not be repeated in nested setting labels or help text. The hierarchy of information provides sufficient context.
* **Conditional**
* Use conditional settings when it:
* simplifies decision-making for merchants via progressive disclosure
* avoids duplication of settings
* avoids visual clutter and reduces cognitive load
* Conditional settings should appear in the information architecture wherever they're most relevant. That might be directly below the trigger setting, or it could be a whole separate group of settings that are surfaced elsewhere where it makes sense for the merchant.
* Tradeoffs and considerations of conditional settings:
* They hide functionality/options that help merchants decide how style their website, so be judicious in what concepts you tie together. For example, don't make a Product card's "Swatch display" setting conditional on a "Quick buy" setting. They are both related to variant selection, but they serve different purposes.
* Limit conditions to 2 levels deep to avoid complex logic (up for discussion!).
* Even when not shown, a conditional setting's value is evaluated in the Liquid code. Code defensively, never assume a theme setting's value is nil.
* **Input Type**
* **Checkbox**: Treat checkbox as an on/off switch. Avoid using verb-based labels, example: use "Language selector" and not "Enable language selector". The presence of the verb may inadvertently suggest the direction to toggle to enable or disable it.
* **Select**: Keep select option labels as short as possible so they can be dynamically displayed as segmented controls.

### Server-Side Rendering
* Storefronts are to be rendered server-side with Liquid as a first principle, as opposed to client-side JavaScript.
* When using JavaScript to render part of the page, fetch the new HTML from the server wherever possible.

#### Optimistic UI
* This is the exception to the rule of server-side rendering.
* "Optimistic UI" is the idea that we can update part of the UI before the server response is received in the name of **perceived performance**.
* **Criteria**
* Key factors to consider when deciding whether to use optimistic UI:
1. You are updating a **small** portion of the UI on the client (with JavaScript) before the server response is received.
2. The API request has a high degree of certainty of being successful.
* Examples of appropriate use cases:
* When filtering a collection page, we can update the a list of applied filters client-side as a Buyer chooses them, i.e., "Color: Red" or "Size: Medium". However, we do not know how many products will be returned that match the filters, so we can't update the product grid or a count of products.
* When a Buyer attempts to add an item to their cart, we can update the cart item count client-side. Assuming our product form's "add to cart" button is already checking the item's availability, we can have a reasonably high degree of certainty that the item will be added to the cart (API request is successful). However, we do not know what the new cart total will be, nor do we know what the line items will look like, so we can't update those in a cart drawer without waiting for the server response.

## HTML
* Use semantic HTML.
* Use modern HTML features where appropriate, e.g., use `BITO API Error (403): {"status":1,"response":"Unauthorized Access","created":"2025-12-21T13:39:46.583531673Z"}