前言

Theme 首頁看起來接近設計稿，不代表轉版已完成。上一篇 談到同一張卡片背後可能是 Article、Product、Collection、Metafield 或 manual block；驗收必須同時覆蓋 code、視覺、Theme Editor 與真實 resource。

這篇用實際 conversion plan 建立一條驗收梯子，並把「這次真的跑過什麼」和「計畫要求、但還沒有公開證據」分開。

原本的做法與問題症狀

最容易出現的驗收方式是只看一張 desktop screenshot。它抓不到：

  • Liquid 或 JSON schema 錯誤。
  • Header、Section、Block 在 Theme Editor 中無法選取或儲存。
  • 390px 手機寬度發生水平 overflow。
  • 820px 平板落在錯誤 breakpoint，卡片數量與間距失衡。
  • 1440px 桌面內容過寬，或大圖沒有合理尺寸。
  • Blog 沒文章、Collection 沒商品、圖片為空時 markup 崩壞。
  • 外部字型、圖片或 JavaScript 造成效能與第三方依賴。

反過來，只跑 Theme Check 也不夠。靜態 analyzer 能找 Liquid、JSON、效能與最佳實務問題，卻不知道實際 preview 是否忠於 source design。

問題是怎麼推敲出來的？

案例的 design handoff 提供多組 viewport，conversion plan 再收斂成三個主要 acceptance widths：390、820、1440。這三個數字不是 Shopify 平台保證的 breakpoint，而是此專案用來代表 mobile、tablet portrait 與 desktop 的抽樣點。

驗收因此分六層：

  1. Source inventory：頁面、素材、互動與 responsive contract 是否都有對應去向。
  2. Static theme validation：Theme Check、Liquid、JSON schema、檔案結構。
  3. Preview rendering：透過 development theme 在測試商店載入真實 Shopify runtime。
  4. Responsive visual comparison：390／820／1440 與 source archive 對照。
  5. Theme Editor operations：新增 section、修改 setting、重排 block、儲存、重開。
  6. Resource edge cases：空 Blog、長標題、缺圖、多 variants、空 Collection 與分頁。

任何一層失敗都應記錄在對應責任，不要用「頁面看得到」把它們合併成一個 pass。

最後採用的架構

驗收矩陣可以這樣保存：

層級 工具／操作 驗收重點 本次狀態
Source inventory source map 每個 surface 與 asset 有去向 有 conversion plan
Theme static shopify theme check error、warning、Liquid／JSON 已執行
Development preview shopify theme dev Shopify runtime 與真實資料 無當日證據
Mobile 390px navigation、單欄、overflow、tap target 計畫項
Tablet 820px grid transition、spacing、media 計畫項
Desktop 1440px max width、比例、large media 計畫項
Theme Editor add/reorder/save/reload schema、定位、持久化 無當日證據
Resource cases Blog/Product/Collection empty/long/missing/pagination 無當日證據

「無當日證據」不是失敗，也不是通過；它表示發布文章時不能宣稱已驗收。

關鍵實作

第一個 gate 是固定 CLI 版本與 path：

shopify version
shopify theme check --path ./theme

視覺驗收則應建立可重現的 checklist：

390px
  □ 無水平捲動
  □ mobile navigation 可開關、可鍵盤操作
  □ heading 不截斷
  □ CTA 不互相覆蓋

820px
  □ grid 在 tablet 寬度不過密
  □ 圖片與文字順序符合 source
  □ section 間距沒有沿用錯誤 desktop 值

1440px
  □ content max-width 與 gutter 正確
  □ hero、卡片與圖片比例接近 source
  □ navigation、hover、focus 狀態完整

Theme Editor 驗收不能只改文字：

新增 section → 修改 settings → 新增 block
→ 重排 block → 隱藏／刪除 → 儲存
→ 重新整理 editor → preview storefront 再確認

若 JSON template 會由 editor 更新，還要確認團隊如何把 store-side configuration 拉回版本控制，或明確決定它不屬於 code artifact。

實際驗證

2026-07-29 的當日結果如下：

  • Shopify CLI：4.5.2。
  • Theme Check：exit code 0。
  • 檢查 44 個 theme files。
  • 0 error。
  • 3 warnings，全部集中在 layout/theme.liquid 的外部字型資源，規則為 RemoteAsset。

Theme source 也有 templates/index.json、多個 custom sections、schema、blocks、header/footer groups，以及 Article、Blog、Product、Collection 等基礎 templates。

本次沒有連接或修改任何正式商店，也沒有公開 development store。沒有執行可被保存的 390／820／1440 screenshot comparison，沒有 live Theme Editor reorder／save／reload 紀錄，也沒有真實 resource fixture。因此本文提供的是「驗收方法＋靜態 gate 的當日結果」，不是完整視覺簽核。

仍然存在的限制

第一，Theme Check exit 0 不代表 warning 可忽略。外部字型會讓頁面依賴第三方 domain，也可能增加 render-blocking request；應建立 owner 與修正決策。

第二，三個 viewport 是代表點，不是完整裝置集合。至少還應檢查兩點之間的流動寬度，以及 200% zoom、長文字與不同語系。

第三，screenshot 只能看視覺，不能證明 keyboard navigation、focus order、screen reader label、reduced motion 或 form error handling。

第四，development theme 使用的 resource 狀態會影響結果。只有 demo content 的 happy path，無法證明 empty state、pagination、unavailable variant 與缺圖。

第五，Theme Editor 的 section reorder 可能改變前景／背景、heading order 或 JavaScript selector。元件能拖曳不等於任意順序都有合理語意。

最後，來源工作區沒有可核對的 theme Git history。驗收結果應另存 timestamp、CLI version、theme commit／artifact identity 與 screenshot；否則日後無法確認通過的是哪一版。

可以延伸到哪些情境？

完整發布前可以把 gate 排成：

Theme Check
  → JSON / Liquid smoke test
  → development preview
  → 390 / 820 / 1440 visual regression
  → Theme Editor CRUD + reorder
  → resource edge cases
  → accessibility / performance
  → controlled publish + rollback check

自動化適合阻擋可重現的錯誤；視覺、內容與商家操作仍需要明確 reviewer。最重要的不是把每格快速標綠，而是讓「已驗證」、「尚未驗證」與「平台之外的限制」各自可追蹤。

本次每日上限到 1039 為止；同一 Theme 批次的下一篇維護文章尚未發布，因此不預先建立正式連結。

參考資料

以上平台文件查核日期：2026-07-29。