Liquid Theme A11y

Accessibility for Shopify Liquid Themes

Core Principle

Every interactive component must work with keyboard only, screen readers, and reduced-motion preferences. Start with semantic HTML — add ARIA only when native semantics are insufficient.

Decision Table: Which Pattern?

Page Structure

Landmarks

<body>
  <a href="#main-content" class="skip-link">{{ 'accessibility.skip_to_content' | t }}</a>
  <header role="banner">
    <nav aria-label="{{ 'accessibility.main_navigation' | t }}">...</nav>
  </header>
  <main id="main-content">
    <!-- All page content inside main -->
  </main>
  <footer role="contentinfo">
    <nav aria-label="{{ 'accessibility.footer_navigation' | t }}">...</nav>
  </footer>
</body>

• Single <header>, <main>, <footer> per page
• Multiple <nav> elements must have distinct aria-label
• All content must live inside a landmark

Skip Link

.skip-link {
  position: absolute;
  inset-inline-start: -999px;
  z-index: 999;
}
.skip-link:focus {
  position: fixed;
  inset-block-start: 0;
  inset-inline-start: 0;
  padding: 1rem;
  background: var(--color-background);
  color: var(--color-foreground);
}

Headings

• One <h1> per page, never skip levels (h1 → h3)
• Use real heading elements, not styled divs
• Template: <h1> is typically the page/product title

Focus Management

Focus Indicators

/* All interactive elements */
:focus-visible {
  outline: 2px solid rgb(var(--color-focus));
  outline-offset: 2px;
}

/* High contrast mode */
@media (forced-colors: active) {
  :focus-visible {
    outline: 3px solid LinkText;
  }
}

• Minimum 3:1 contrast ratio for focus indicators
• Use :focus-visible (not :focus) to avoid showing on click
• Never outline: none without a visible replacement

Focus Trapping (Modals/Drawers)

• Trap focus inside modals, drawers, and dialogs
• Return focus to trigger element on close
• First focusable element gets focus on open
• Query all focusable elements: a[href], button:not([disabled]), input:not([disabled]), select, textarea, [tabindex]:not([tabindex="-1"])

See focus and keyboard patterns for full FocusTrap implementation.

Component Patterns

Product Card

<article class="product-card" aria-labelledby="ProductTitle-{{ product.id }}">
  <a href="{{ product.url }}" class="product-card__link" aria-labelledby="ProductTitle-{{ product.id }}">
    <img
      src="{{ product.featured_image | image_url: width: 400 }}"
      alt="{{ product.featured_image.alt | escape }}"
      loading="lazy"
      width="{{ product.featured_image.width }}"
      height="{{ product.featured_image.height }}"
    >
  </a>
  <h3 id="ProductTitle-{{ product.id }}">
    <a href="{{ product.url }}">{{ product.title }}</a>
  </h3>
  <div class="product-card__price" aria-label="{{ 'products.price_label' | t: price: product.price | money }}">
    {{ product.price | money }}
  </div>
  <button
    class="product-card__quick-add"
    tabindex="-1"
    aria-label="{{ 'products.quick_add' | t: title: product.title }}"
  >
    {{ 'products.add_to_cart' | t }}
  </button>
</article>

Rules:

• Single tab stop per card (the main link)
• tabindex="-1" on mouse-only shortcuts (quick add)
• aria-labelledby on <article> pointing to the title
• Descriptive alt text on images; empty alt="" if decorative

Carousel

<div
  role="region"
  aria-roledescription="carousel"
  aria-label="{{ section.settings.heading | escape }}"
>
  <div class="carousel__controls">
    <button
      aria-label="{{ 'accessibility.previous_slide' | t }}"
      aria-controls="CarouselSlides-{{ section.id }}"
    >{% render 'icon-chevron-left' %}</button>
    <button
      aria-label="{{ 'accessibility.next_slide' | t }}"
      aria-controls="CarouselSlides-{{ section.id }}"
    >{% render 'icon-chevron-right' %}</button>
    <button
      aria-label="{{ 'accessibility.pause_slideshow' | t }}"
      aria-pressed="false"
    >{% render 'icon-pause' %}</button>
  </div>

  <div id="CarouselSlides-{{ section.id }}" aria-live="polite">
    {% for slide in section.blocks %}
      <div
        role="group"
        aria-roledescription="slide"
        aria-label="{{ 'accessibility.slide_n_of_total' | t: n: forloop.index, total: forloop.length }}"
        {% unless forloop.first %}aria-hidden="true"{% endunless %}
      >
        {{ slide.settings.content }}
      </div>
    {% endfor %}
  </div>
</div>

Rules:

• Auto-rotation minimum 5 seconds, pause on hover/focus
• Play/pause button required for auto-rotating carousels
• aria-live="polite" on slide container (set to "off" during auto-rotation)
• aria-hidden="true" on inactive slides
• Each slide: role="group" + aria-roledescription="slide"

Modal

<dialog
  id="Modal-{{ section.id }}"
  aria-labelledby="ModalTitle-{{ section.id }}"
  aria-modal="true"
>
  <div class="modal__header">
    <h2 id="ModalTitle-{{ section.id }}">{{ title }}</h2>
    <button
      type="button"
      aria-label="{{ 'accessibility.close' | t }}"
      on:click="/closeModal"
    >{% render 'icon-close' %}</button>
  </div>
  <div class="modal__content">
    <!-- Content -->
  </div>
</dialog>

Rules:

• Use native <dialog> element
• aria-labelledby pointing to the title
• Close on Escape key (native with <dialog>)
• Focus first interactive element on open
• Return focus to trigger on close

Cart Drawer

Same as modal pattern but with additional:

• Live region for cart count updates: <span aria-live="polite" aria-atomic="true">
• Clear "remove item" buttons with aria-label="{{ 'cart.remove_item' | t: title: item.title }}"
• Quantity inputs with associated labels

Forms

<form action="{{ routes.cart_url }}" method="post">
  <div class="form__field">
    <label for="Email-{{ section.id }}">{{ 'forms.email' | t }}</label>
    <input
      type="email"
      id="Email-{{ section.id }}"
      name="email"
      required
      aria-required="true"
      autocomplete="email"
      aria-describedby="EmailError-{{ section.id }}"
    >
    <p
      id="EmailError-{{ section.id }}"
      class="form__error"
      role="alert"
      hidden
    >{{ 'forms.email_required' | t }}</p>
  </div>
</form>

Rules:

• Every input has a visible <label> with matching for/id
• Use <fieldset>/<legend> for radio/checkbox groups
• Error messages: role="alert" + aria-describedby linking to input
• aria-invalid="true" on invalid inputs
• autocomplete attributes on common fields
• Required fields: required + aria-required="true" + visual indicator

Product Filters

<form class="facets">
  <div class="facets__group">
    <button
      type="button"
      aria-expanded="false"
      aria-controls="FilterColor-{{ section.id }}"
    >{{ 'filters.color' | t }}</button>