Shopify Liquid 主题无障碍访问指南：提升网站可访问性与SEO

liquid-theme-a11y by benjaminsehl/liquid-skills

799 周安装量

97 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/benjaminsehl/liquid-skills --skill liquid-theme-a11y

开发 SEO

🇨🇳中文介绍

Shopify Liquid 主题的无障碍访问

核心原则

每个交互组件都必须仅通过键盘、屏幕阅读器和减少动画偏好设置正常工作。从语义化 HTML 开始——仅在原生语义不足时添加 ARIA。

决策表：使用哪种模式？

组件	HTML 元素	ARIA 模式	参考
可展开内容	`<details>/<summary>`	无需	手风琴
模态框/对话框	`<dialog>`	`aria-modal="true"`	模态框
工具提示/弹出框	`[popover]` 属性

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

749,400 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

255,700 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

205,600 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

136,300 周安装

<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">
    <!-- 所有页面内容放在 main 内 -->
  </main>
  <footer role="contentinfo">
    <nav aria-label="{{ 'accessibility.footer_navigation' | t }}">...</nav>
  </footer>
</body>

每页一个 <header>、<main>、<footer>
多个 <nav> 元素必须有不同的 aria-label
所有内容必须位于地标区域内

<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>

每张卡片一个 Tab 键停留点（主链接）
仅鼠标操作的快捷方式（快速添加）使用 tabindex="-1"
<article> 上的 aria-labelledby 指向标题
图像使用描述性 alt 文本；装饰性图像使用空 alt=""

<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>

自动轮播至少 5 秒，悬停/聚焦时暂停
自动轮播的轮播图需要播放/暂停按钮
幻灯片容器使用 aria-live="polite"（自动轮播期间设置为 "off"）
非活动幻灯片使用 aria-hidden="true"
每张幻灯片：role="group" + aria-roledescription="slide"

<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">
    <!-- 内容 -->
  </div>
</dialog>

<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>

每个输入框都有可见的 <label>，且 for/id 匹配
单选按钮/复选框组使用 <fieldset>/<legend>
错误信息：role="alert" + aria-describedby 链接到输入框
无效输入使用 aria-invalid="true"
常见字段使用 autocomplete 属性
必填字段：required + aria-required="true" + 视觉指示器

<form class="facets">
  <div class="facets__group">
    <button
      type="button"
      aria-expanded="false"
      aria-controls="FilterColor-{{ section.id }}"
    >{{ 'filters.color' | t }}</button>
    <fieldset id="FilterColor-{{ section.id }}" hidden>
      <legend class="visually-hidden">{{ 'filters.filter_by_color' | t }}</legend>
      {% for color in colors %}
        <label>
          <input type="checkbox" name="filter.color" value="{{ color }}">
          {{ color }}
        </label>
      {% endfor %}
    </fieldset>
  </div>
  <div aria-live="polite" aria-atomic="true">
    {{ 'filters.results_count' | t: count: results.size }}
  </div>
</form>

{% if product.compare_at_price > product.price %}
  <div class="price" aria-label="{{ 'products.sale_price_label' | t: sale_price: product.price | money, original_price: product.compare_at_price | money }}">
    <s aria-hidden="true">{{ product.compare_at_price | money }}</s>
    <span>{{ product.price | money }}</span>
  </div>
{% else %}
  <div class="price">{{ product.price | money }}</div>
{% endif %}

<div role="tablist" aria-label="{{ 'accessibility.product_tabs' | t }}">
  {% for tab in tabs %}
    <button
      role="tab"
      id="Tab-{{ tab.id }}"
      aria-selected="{% if forloop.first %}true{% else %}false{% endif %}"
      aria-controls="Panel-{{ tab.id }}"
      tabindex="{% if forloop.first %}0{% else %}-1{% endif %}"
    >{{ tab.title }}</button>
  {% endfor %}
</div>
{% for tab in tabs %}
  <div
    role="tabpanel"
    id="Panel-{{ tab.id }}"
    aria-labelledby="Tab-{{ tab.id }}"
    {% unless forloop.first %}hidden{% endunless %}
    tabindex="0"
  >{{ tab.content }}</div>
{% endfor %}

<nav aria-label="{{ 'accessibility.main_navigation' | t }}">
  <ul role="list">
    {% for link in linklists.main-menu.links %}
      <li>
        {% if link.links.size > 0 %}
          <button aria-expanded="false" aria-controls="Submenu-{{ forloop.index }}">
            {{ link.title }}
          </button>
          <ul id="Submenu-{{ forloop.index }}" hidden role="list">
            {% for child in link.links %}
              <li><a href="{{ child.url }}">{{ child.title }}</a></li>
            {% endfor %}
          </ul>
        {% else %}
          <a href="{{ link.url }}">{{ link.title }}</a>
        {% endif %}
      </li>
    {% endfor %}
  </ul>
</nav>

元素	最小比率
普通文本（<18px / <14px 粗体）	4.5:1
大文本（≥18px / ≥14px 粗体）	3:1
UI 组件和图形	3:1
焦点指示器	3:1

🇺🇸English

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?

Component	HTML Element	ARIA Pattern	Reference
Expandable content	`<details>/<summary>`	None needed	Accordion
Modal/dialog	`<dialog>`	`aria-modal="true"`	Modal
Tooltip/popup	`[popover]` attribute	`role="tooltip"` fallback	Tooltip
Dropdown menu	`<nav>` + `<ul>`	`aria-expanded` on triggers	Navigation
Tab interface	`<div>`	`role="tablist/tab/tabpanel"`	Tabs
Carousel/slider	`<div>`	`role="region"` + `aria-roledescription`	Carousel
Product card	`<article>`	`aria-labelledby`	Product card
Form	`<form>`	`aria-invalid`, `aria-describedby`	Forms
Cart drawer	`<dialog>`	Focus trap	Cart drawer
Price display	`<span>`	`aria-label` for context	Prices
Filters	`<form>` + `<fieldset>`	`aria-expanded` for disclosures	Filters

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>
    <fieldset id="FilterColor-{{ section.id }}" hidden>
      <legend class="visually-hidden">{{ 'filters.filter_by_color' | t }}</legend>
      {% for color in colors %}
        <label>
          <input type="checkbox" name="filter.color" value="{{ color }}">
          {{ color }}
        </label>
      {% endfor %}
    </fieldset>
  </div>
  <div aria-live="polite" aria-atomic="true">
    {{ 'filters.results_count' | t: count: results.size }}
  </div>
</form>

Price Display

{% if product.compare_at_price > product.price %}
  <div class="price" aria-label="{{ 'products.sale_price_label' | t: sale_price: product.price | money, original_price: product.compare_at_price | money }}">
    <s aria-hidden="true">{{ product.compare_at_price | money }}</s>
    <span>{{ product.price | money }}</span>
  </div>
{% else %}
  <div class="price">{{ product.price | money }}</div>
{% endif %}

Use aria-label to provide full price context (sale vs. original)
aria-hidden="true" on the visual strikethrough to avoid duplicate reading

Accordion

<details>
  <summary>{{ block.settings.heading }}</summary>
  <div class="accordion__content">
    {{ block.settings.content }}
  </div>
</details>

Native <details>/<summary> provides keyboard and screen reader support automatically.

Tabs

<div role="tablist" aria-label="{{ 'accessibility.product_tabs' | t }}">
  {% for tab in tabs %}
    <button
      role="tab"
      id="Tab-{{ tab.id }}"
      aria-selected="{% if forloop.first %}true{% else %}false{% endif %}"
      aria-controls="Panel-{{ tab.id }}"
      tabindex="{% if forloop.first %}0{% else %}-1{% endif %}"
    >{{ tab.title }}</button>
  {% endfor %}
</div>
{% for tab in tabs %}
  <div
    role="tabpanel"
    id="Panel-{{ tab.id }}"
    aria-labelledby="Tab-{{ tab.id }}"
    {% unless forloop.first %}hidden{% endunless %}
    tabindex="0"
  >{{ tab.content }}</div>
{% endfor %}

Arrow keys navigate between tabs (left/right)
Only active tab has tabindex="0", others -1

Dropdown Navigation

<nav aria-label="{{ 'accessibility.main_navigation' | t }}">
  <ul role="list">
    {% for link in linklists.main-menu.links %}
      <li>
        {% if link.links.size > 0 %}
          <button aria-expanded="false" aria-controls="Submenu-{{ forloop.index }}">
            {{ link.title }}
          </button>
          <ul id="Submenu-{{ forloop.index }}" hidden role="list">
            {% for child in link.links %}
              <li><a href="{{ child.url }}">{{ child.title }}</a></li>
            {% endfor %}
          </ul>
        {% else %}
          <a href="{{ link.url }}">{{ link.title }}</a>
        {% endif %}
      </li>
    {% endfor %}
  </ul>
</nav>

Tooltip

<button aria-describedby="Tooltip-{{ block.id }}">
  {{ 'labels.info' | t }}
</button>
<div id="Tooltip-{{ block.id }}" role="tooltip" popover>
  {{ block.settings.tooltip_text }}
</div>

Mobile Accessibility

Touch targets: minimum 44x44px, 8px spacing between targets
No orientation lock: never restrict to portrait/landscape
No hover-only content: everything accessible via tap
Use dvh instead of vh for mobile viewport units

Animation & Motion

/* Always provide reduced motion */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

No flashing above 3 times per second
Auto-playing animations need pause/stop controls
Meaningful animations only — don't animate for decoration

Visually Hidden Utility

.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Use for screen-reader-only content like labels and descriptions.

Color Contrast

Element	Minimum Ratio
Normal text (<18px / <14px bold)	4.5:1
Large text (≥18px / ≥14px bold)	3:1
UI components & graphics	3:1
Focus indicators	3:1

Never rely solely on color to convey information — always pair with text, icons, or patterns.

References

Weekly Installs

327

Repository

benjaminsehl/li…d-skills

GitHub Stars

First Seen

Feb 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

claude-code259

codex242

opencode242

kimi-cli240

gemini-cli240

amp240

Shopify Liquid 主题无障碍访问指南：提升网站可访问性与SEO

🇨🇳中文介绍

Shopify Liquid 主题的无障碍访问

核心原则

决策表：使用哪种模式？

相关 Skills

页面结构

地标区域

跳过链接

标题

焦点管理

焦点指示器

焦点陷阱（模态框/抽屉）

组件模式

产品卡片

轮播图

模态框

购物车抽屉

表单

产品筛选器

价格显示

手风琴

标签页

下拉导航

工具提示

移动端无障碍访问

动画与动效

视觉隐藏工具类

颜色对比度

参考

🇺🇸English

Accessibility for Shopify Liquid Themes

Core Principle

Decision Table: Which Pattern?

Page Structure

Landmarks

Skip Link

Headings

Focus Management

Focus Indicators

Focus Trapping (Modals/Drawers)

Component Patterns

Product Card

Carousel

Modal

Cart Drawer

Forms

Product Filters

Price Display

Accordion

Tabs

Dropdown Navigation

Tooltip

Mobile Accessibility

Animation & Motion

Visually Hidden Utility

Color Contrast

References

最新 Skills