SHOPIFY INTEGRATION

Who this guide is for

• Theme editors who use Shopify Admin → Online Store → Themes → Edit code and are comfortable pasting files into Assets, Snippets, and Sections.
• Developers who will wire the same tokens and CSS into a custom theme.

You do not need to know React. The design system’s reference implementation is in React; on Shopify you use CSS + Liquid that your team ships to match those specs.

When you finish this guide

You will be able to:

• Load design tokens (CSS variables) across the whole theme.
• Load component styles and optional JavaScript for interactive patterns.
• Copy Liquid snippets for common UI pieces and drop them into sections.
• Turn brand and dark mode on or off from theme settings (optional).

How this page relates to the main components

• Source of truth for behavior and variants is the React components in this repo (e.g. packages/ui) and the component documentation on this site.
• The Liquid examples on component pages are hand-written to teach the pattern. They do not auto-update when React code changes.
• The coverage table at the end is generated at docs build time from the same source as the component docs (component-api.json). If a table row and a code snippet disagree, trust the table / component page and ask your team to refresh the snippet text.
• Release checklist (internal): When you change public variant names, sizes, or CSS class conventions for a component that appears on this page, update this MDX file (English and Chinese) and any shipped ds-components.css package together.

Terminology (quick)

Overview

This guide walks you through integrating the ELFBAR Design System into a Shopify Liquid theme. After completing these steps, you will have:

• Design tokens — consistent colors, spacing, fonts, and radii across your theme
• CSS components — pre-styled UI elements matching the design system
• Liquid snippets — reusable template fragments you can render in any section

Final file structure

Prerequisites

Check that you have:

• Theme code access — Shopify Admin → Online Store → Themes → ⋮ → Edit code
• ds-tokens.css — from your design system team (or built from the monorepo packages/tokens if you are a developer)
• ds-components.css — component CSS that uses those tokens (not generated in this repo for Shopify; supplied by your team)
• ds-components.min.js (optional) — for accordions, tabs, etc., if your team provides it

Developers: Token CSS is produced by the Style Dictionary pipeline under packages/tokens. Shopify-specific bundles (ds-components.css / .js) are a separate deliverable—coordinate with your team for file names and versions.

Step 1: Add the design token file

Purpose: Make design system CSS variables available everywhere in the theme.

Design tokens define colors, spacing, fonts, and radii. They ship as CSS variables (e.g. var(--ds-color-…)).

1.1 Create the token file

1. In the theme editor, open Assets
2. Click Add a new asset
3. Choose Create a blank file, name it ds-tokens, extension .css
4. Paste the full contents of ds-tokens.css from your design system team
5. Click Save

1.2 Include it in your layout

Open layout/theme.liquid. Before </head>, add:

{{ 'ds-tokens.css' | asset_url | stylesheet_tag }}

Place it after your theme’s main stylesheet so tokens are available to later rules.

Step 2: Add component styles

Purpose: Apply the design system’s look (buttons, cards, etc.) using classes such as .ds-button.

2.1 Create the stylesheet

1. In Assets, Add a new asset
2. Create a blank .css file named ds-components
3. Paste ds-components.css
4. Save

2.2 Include it in your layout

Right after the token line in layout/theme.liquid:

{{ 'ds-components.css' | asset_url | stylesheet_tag }}

Example </head> tail:

  {{ 'ds-tokens.css' | asset_url | stylesheet_tag }}
  {{ 'ds-components.css' | asset_url | stylesheet_tag }}
</head>

Step 3: Add the interaction script (optional)

Purpose: Enable expand/collapse, tabs, and other patterns that need JavaScript.

If you only need static pieces (e.g. buttons and cards), you can skip this.

3.1 Create the script asset

1. In Assets, Add a new asset
2. Create ds-components.min.js
3. Paste the file from your team
4. Save

3.2 Include it before </body>

In layout/theme.liquid:

{{ 'ds-components.min.js' | asset_url | script_tag }}

Step 4: Create Liquid snippets

Purpose: Add reusable snippets under Snippets and call them with {% render 'ds-…' %} from sections or templates.

How to create a snippet

1. Open Snippets
2. Add a new snippet
3. Name the file exactly as referenced (e.g. ds-button → ds-button.liquid)
4. Open that component’s documentation → Dev tab → Shopify (Liquid) and paste the Liquid there
5. Save

If Shopify (Liquid) shows two fenced blocks, use the Two Liquid examples note on that page: the first block is the snippet file; the second is usage in a section or template — do not save the second block as a snippet.

Copy-paste parameters and {% render %} examples live on each component page next to Props API and Specs. This step is the checklist; use the table to open the right page.

Component → documentation (Shopify section)

Storefront-only notes

If a page states the pattern is not a 1:1 Liquid port, follow its link to Storefront gaps and workarounds in this guide.

Step 5: Use components in sections and templates

Purpose: Show real products and FAQ content using the snippets above.

Once snippets exist, call them from sections/*.liquid, templates/*.liquid, or other snippets.

Example: product card grid section

Create sections/ds-product-grid.liquid:

<div class="ds-product-grid">
  <div class="ds-product-grid__header">
    {% if section.settings.title != blank %}
      <h2>{{ section.settings.title }}</h2>
    {% endif %}
  </div>
  <div class="ds-product-grid__items">
    {% for product in collections[section.settings.collection].products limit: section.settings.limit %}
      {% render 'ds-card',
        image_url: product.featured_image | image_url: width: 600,
        image_alt: product.featured_image.alt,
        title: product.title,
        price: product.price | money,
        href: product.url
      %}
    {% endfor %}
  </div>
</div>
 
{% schema %}
{
  "name": "Product Grid",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Section Title",
      "default": "Featured Products"
    },
    {
      "type": "collection",
      "id": "collection",
      "label": "Collection"
    },
    {
      "type": "range",
      "id": "limit",
      "label": "Number of products",
      "min": 2,
      "max": 12,
      "step": 1,
      "default": 4
    }
  ],
  "presets": [
    {
      "name": "Product Grid"
    }
  ]
}
{% endschema %}

Example: FAQ section with accordion

Create sections/ds-faq.liquid:

<div class="ds-faq-section">
  {% if section.settings.title != blank %}
    <h2>{{ section.settings.title }}</h2>
  {% endif %}
 
  {% render 'ds-accordion', type: 'single' %}
</div>
 
{% schema %}
{
  "name": "FAQ",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Section Title",
      "default": "Frequently Asked Questions"
    }
  ],
  "blocks": [
    {
      "type": "accordion_item",
      "name": "Question",
      "settings": [
        {
          "type": "text",
          "id": "title",
          "label": "Question",
          "default": "What is your return policy?"
        },
        {
          "type": "richtext",
          "id": "content",
          "label": "Answer",
          "default": "<p>We offer a 30-day return policy for all unused products.</p>"
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "FAQ",
      "blocks": [
        { "type": "accordion_item" },
        { "type": "accordion_item" },
        { "type": "accordion_item" }
      ]
    }
  ]
}
{% endschema %}

Step 6: Brand and theme configuration

Purpose: Switch ELFBAR / Lost Mary and optional dark mode using data-brand and data-theme on <html>, matching how tokens are scoped in the design system.

6.1 Add settings to the theme schema array

Open config/settings_schema.json. It is a JSON array [ … ] of blocks. Do not delete existing entries.

1. Find the closing } of the last setting group in the array.
2. Add a comma after that }.
3. Paste the new object below (or merge equivalent settings your theme already has).

Example fragment (your file will have more objects before and/or after):

[
  {
    "name": "Design System",
    "settings": [
      {
        "type": "select",
        "id": "ds_brand",
        "label": "Brand",
        "options": [
          { "value": "elfbar", "label": "ELFBAR" },
          { "value": "lostmary", "label": "Lost Mary" }
        ],
        "default": "elfbar"
      },
      {
        "type": "checkbox",
        "id": "ds_dark_mode",
        "label": "Enable dark mode",
        "default": false
      }
    ]
  }
]

If your file already contains other groups, the result should look like: [ { …existing… }, { "name": "Design System", … } ].

6.2 Apply attributes on <html>

In layout/theme.liquid:

<html
  lang="{{ request.locale.iso_code }}"
  {% if settings.ds_brand != 'elfbar' %}data-brand="{{ settings.ds_brand }}"{% endif %}
  {% if settings.ds_dark_mode %}data-theme="dark"{% endif %}
>

Components that read CSS variables from your token bundle will follow the selected brand and theme.

Using the component documentation while building sections

The interactive docs on this site describe spacing, variants, states, accessibility, and tokens for each component. Use them as the spec while you write Liquid and classes in Shopify.

URL pattern

• English: /en/components/...
• Chinese: /zh/components/...

(If your deployment hides the default locale in the path, use your site’s actual prefix.)

Handy links (same paths as the docs sidebar)

Suggested workflow

1. Open the component page → Guide and Specs for sizes and tokens.
2. Open the Dev tab → Shopify (Liquid) for snippet copy-paste (parameters align with Props API on the same tab).
3. In the theme editor, add or edit a section; mirror the HTML structure and class names your team’s ds-components.css expects.
4. Expose merchant-editable text, links, and images in the section {% schema %} so content stays out of code.

Storefront gaps and workarounds

Some React components rely on portals, app-level state, or patterns that do not map 1:1 to a Liquid storefront. Use the ideas below when you still need a similar experience.

Dialog / modal

• Storefront: Prefer a section with a hidden panel (CSS + a small script) or Shopify patterns such as cart drawer / drawers provided by the theme.
• Design: Reuse tokens and typography from the Dialog doc for overlay, padding, and focus styles—even if the DOM is simpler than React.

Menu / dropdown

• Storefront: Implement header sections, mobile drawers, and disclosure blocks instead of a single React Menu.
• Design: Match spacing, hover, and focus using token-backed CSS classes.

Toast

• Storefront: Use theme settings, announcement bars, or a lightweight section for short messages. Behavior will differ from the React Toast stack.
• Design: Align colors and radius with the Toast spec where it makes sense.

Date picker, FAB, complex Options

• Date picker: Often unnecessary on the storefront; if needed, prefer native HTML or send users to account / checkout flows.
• FAB: Usually an admin or app pattern; on the storefront use a fixed section or theme-supported quick action if required.
• Options: Prefer Radio, Selector, or variant picker patterns documented in this system, implemented as Liquid + CSS.

For Dialog, Toast, Menu, Datepicker, Fab, Options, see also the “Not available for storefront” table below for the short rationale.

Component reference

The tables are generated from this repository when the docs site is built. They show planned CSS / snippet naming and variants from source.

Please note:

• Only the snippets printed earlier on this page are fully worked examples. Other rows assume your team will provide matching ds-*.liquid and CSS when they are ready.
• Tier 2 items usually need ds-components.min.js (or equivalent) and must align with your team’s script.
• If anything disagrees with a component documentation page or this table, treat the docs + table as correct and update Liquid or CSS in the theme.