theme-shopify-html-data-comments

Shopify の HTML、データ属性、コメント

Shopify テーマにおける HTML 構造、データ属性の使用方法、コードコメントに関するガイドラインです。

使用する場面

• セクション内の HTML マークアップを構成する
• 属性を使って JavaScript にデータを渡す
• Liquid テンプレートにコメントを追加する
• HTML 要素を整理する

HTML とデータ属性

カスタム HTML タグ

• 適切な場合はカスタム HTML タグを使用します
• カスタム要素は JavaScript のカスタム要素と相性が良好です
• セマンティックな構造を改善できます

例

<product-card data-product-id="{{ product.id }}">
  
</product-card>

データ属性

• data-* 属性を使って動的なデータを渡します
• JavaScript では dataset プロパティを使ってアクセスします
• 属性名にはケバブケースを使用します

データ属性の命名

<div 
  data-product-id="{{ product.id }}"
  data-variant-id="{{ variant.id }}"
  data-product-handle="{{ product.handle }}">
</div>


<div data-productId="{{ product.id }}"></div>

JavaScript でのデータへのアクセス

class ProductCard extends HTMLElement {
  constructor() {
    super();
    this.productId = this.dataset.productId;
    this.variantId = this.dataset.variantId;
    this.productHandle = this.dataset.productHandle;
  }
}

設定用のデータ属性

データ属性を使って、Liquid から JavaScript に設定を渡します。

<image-gallery 
  data-autoplay="{{ section.settings.autoplay }}"
  data-interval="{{ section.settings.interval }}"
  data-transition="{{ section.settings.transition }}">
  
</image-gallery>

class ImageGallery extends HTMLElement {
  constructor() {
    super();
    this.autoplay = this.dataset.autoplay === 'true';
    this.interval = parseInt(this.dataset.interval, 10);
    this.transition = this.dataset.transition;
  }
}

コメント

コメントのガイドライン

• コメントは最小限にします
• 自明でないロジックにのみコメントを付けます
• すべての行を説明しないでください
• 「何を」ではなく「なぜ」を説明するコメントを使います

Liquid のコメント

{%- comment -%}
  Calculate discount percentage for products with compare_at_price.
  Only show discount badge if discount is greater than 20%.
{%- endcomment -%}

{% liquid
  if product.compare_at_price > product.price
    assign discount = product.compare_at_price | minus: product.price
    assign discount_percent = discount | times: 100 | divided_by: product.compare_at_price
    if discount_percent > 20
      assign show_badge = true
    endif
  endif
%}

スニペットの使用方法に関するコメント

スニペットには必ず使用方法に関するコメントを含めます。

{%- comment -%}
Usage:
{% render 'product-card', 
  product: product, 
  show_vendor: true, 
  show_price: true %}
{%- endcomment -%}

HTML コメント

セクションの整理には、HTML コメントを必要最小限だけ使用します。

{%- comment -%}
  Product Card Section
  Displays product information with image, title, price, and add to cart button
{%- endcomment -%}

<div class="product-card">
  
  <div class="product-card__image">
    {{ product.featured_image | image_tag: widths: '360, 720', loading: 'lazy' }}
  </div>

  
  <div class="product-card__info">
    <h3 class="product-card__title">{{ product.title }}</h3>
    <p class="product-card__price">{{ product.price | money }}</p>
  </div>
</div>

コメントを付ける場面

コメントを付けるもの：

• 複雑なビジネスロジック
• 自明でない計算
• 回避策やハック
• スニペットの使用方法
• セクションレベルのドキュメント

コメントを付けないもの：

• 明らかなコード（例：{% if product.available %}）
• すべてのコード行
• 名前から用途が明らかな変数
• 標準的な Liquid 構文

例：良いコメントと悪いコメント

{%- comment -%}
  Good: Explains why, not what
  Calculate discount percentage. Shopify doesn't provide this directly,
  so we calculate it from compare_at_price and current price.
{%- endcomment -%}
{% liquid
  assign discount = product.compare_at_price | minus: product.price
  assign discount_percent = discount | times: 100 | divided_by: product.compare_at_price
%}

{%- comment -%}
  Bad: Explains what, which is obvious
  Check if product is available. If available, show add to cart button.
{%- endcomment -%}
{% if product.available %}
  <button>Add to Cart</button>
{% endif %}

HTML 構造のベストプラクティス

セマンティック HTML

セマンティックな HTML 要素を使用します。

<article class="product-card">
  <header class="product-card__header">
    <h2 class="product-card__title">{{ product.title }}</h2>
  </header>
  <div class="product-card__image">
    {{ product.featured_image | image_tag: widths: '360, 720', loading: 'lazy' }}
  </div>
  <footer class="product-card__footer">
    <p class="product-card__price">{{ product.price | money }}</p>
    <button class="product-card__button">Add to Cart</button>
  </footer>
</article>

アクセシビリティ

適切なアクセシビリティ属性を含めます。

<button 
  aria-label="Add {{ product.title }} to cart"
  data-product-id="{{ product.id }}">
  Add to Cart
</button>

Shopify テーマのドキュメント

以下の Shopify 公式リソースを参照してください。

• HTML 要素
• データ属性
• ウェブアクセシビリティ
• Shopify テーマの構造

指示

1. セマンティックな構造に適している場合は、カスタム HTML タグを使用します
2. ケバブケースを使い、data-* 属性でデータを渡します
3. コメントは最小限にし、自明でないロジックにのみ付けます
4. 「何を」ではなく「なぜ」をコメントします。明らかなコードではなく、理由を説明します
5. すべてのスニペットに使用方法に関するコメントを含めます
6. 構造とアクセシビリティを向上させるため、セマンティック HTML を使用します
7. アクセシビリティ属性（aria-label、alt テキストなど）を追加します