Communitygithub.com

coastdigitalgroup/coastai-skills

設計並構建互動式、並排的視覺比較介面(前/後對照),支援鍵盤控制、觸控最佳化與版面佈局保留規則。

coastai-skills 是什麼?

這個技能(Image Comparison Slider System)提供了一套完整的設計與空間方法論,用於建立互動式的「前後對照」視覺比較元件。它能讓使用者透過動態滑動、揭露與對比的方式,清晰呈現兩張影像(如照片修復、色彩調整、設計稿、環境變遷或醫療結果)的差異,同時避免視覺混亂、確保版面穩定、最佳化行動裝置的觸控目標,並滿足 WCAG AA 無障礙標準(含鍵盤導航與螢幕報讀支援)。此技能支援多種平台(如 Claude Code、Cursor、Codex 等 AI 代理工具),其核心運作方式是利用 CSS `clip-path` 進行裁剪而非雙圖縮放,避免影像變形;並透過原生 `<input type="range">` 元素與 ARIA 屬性整合鍵盤事件(如方向鍵、Home、End)與狀態回報。此外,技能提供了三種滑動模式(點擊拖曳、懸停跟隨、雙圖切換)、清晰的決策規則與常見失敗模式預防建議,確保開發者能快速產出高品質、無障礙的比較元件。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/coastdigitalgroup/coastai-skills/tree/HEAD/website-design/image-comparison-slider-system

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

圖片比較滑動系統

目的

圖片比較滑動系統提供了一套系統化的設計與空間方法論,用於建構互動式的「前後對照」視覺比較元件。此系統旨在解決呈現兩張重疊影像(例如:照片修復、色彩調整、設計稿、環境變遷或醫療結果)的設計挑戰,讓使用者能動態滑動、揭露並對比細節。它能防止視覺混淆、確保版面穩定性、最佳化行動裝置的觸控目標,並透過結構化的鍵盤互動與螢幕報讀公告,滿足 WCAG AA 無障礙標準。


使用案例

  • 創意與編輯軟體展示: 比較未經編輯的 RAW 檔與最終修飾的照片、色彩調校預設或修圖成果。
  • 建築與設計作品集: 展示施工前後的階段、翻新專案、室內裝潢或網站設計系統改版。
  • 電子商務與產品展示: 呈現產品在不同條件下的比較(例如:防水布料測試、螢幕保護貼、清潔用品或磨損比較)。
  • 環境與科學視覺化: 呈現隨時間變化的現象,如冰川退縮的衛星地圖、城市擴張或造林計畫。
  • 化妝品與醫學案例研究: 在相同光線與空間條件下,呈現高保真的治療結果。

何時不該使用

  • 多項目探索: 若需要比較 2-5 個不同產品的離散屬性,請使用 comparison-matrix-system。
  • 一般圖片網格: 標準圖片顯示、媒體輪播或圖庫,請使用 imagery-and-media-system 或 carousel-and-slider-system。
  • 文字密集型比較: 若主要內容為文字或表格資料(如軟體版本功能),請使用 data-table-ui-system 或 <dl> 列表元素。
  • 低對比度細微變化: 若兩張圖片的視覺差異極小且不易察覺,並排或上下堆疊佈局並搭配清晰標題會更有幫助。

輸入

  1. 雙核心素材: 兩張高品質圖片(「前」與「後」),需從完全相同的空間視角、畫格和解析度拍攝。
  2. 元件尺寸: 寬高比(例如 16:9、4:3 或 1:1)與視口邊界(來自 imagery-and-media-system)。
  3. 字體與品牌標記: 標籤、手柄與操作說明的字體大小與顏色(來自 fluid-typography-system)。
  4. 觸控與動態偏好: 使用者對觸控手勢與系統層級減少動畫狀態的偏好。

輸出

  1. 滑桿解剖藍圖: 定義容器、背景軌道、裁剪路徑疊層、手柄條、抓取拇指與狀態標籤的版面配置。
  2. 鍵盤控制規範: 可存取的座標追蹤對應,將 ArrowLeft、ArrowRight、Home 和 End 等按鍵對應至相對的裁剪路徑百分比。
  3. 行動裝置與觸控行為指南: 觸控目標尺寸、手勢拖曳閾值與拇指間距的明確規格。
  4. 佈局保留規則: 防止版面位移(CLS)的結構性規則(如寬高比保留與絕對尺寸設定)。

工作流程

1. 建立空間軌道與容器

保留寬高比與結構對齊:

  • 寬高比鎖定: 容器必須有明確的寬高比(例如 aspect-ratio: 16 / 9 或 aspect-ratio: 1 / 1),以預留版面空間並防止累計版面位移(CLS)。
  • 絕對定位疊層: 將容器設為 position: relative; overflow: hidden;。將「後」圖片作為標準背景圖片區塊(width: 100%; height: 100%; object-fit: cover;)。
  • 裁剪疊層區塊: 將「前」圖片置於絕對定位的疊層包裝器內(position: absolute; top: 0; left: 0; width: 100%; height: 100%; object-fit: cover;)。
  • 圖片同步: 確保背景圖片與疊層圖片具有完全相同的尺寸、縮放屬性(object-fit: cover)和對齊方式(object-position: center),使其精確重疊。

2. 實作揭露裁剪路徑

使用現代 CSS 裁剪而非雙圖縮放,以防止視覺歪斜:

  • 裁剪路徑值: 對疊層包裝器應用 clip-path: inset(0 calc(100% - var(--exposure-ratio)) 0 0);,其中 --exposure-ratio 是一個 CSS 自訂屬性(例如 50%),代表滑桿位置。
  • 動態變數綁定: 透過滑鼠、觸控或鍵盤輸入動態更新 --exposure-ratio。
  • 避免圖片變形: 滑動時不要調整圖片本身的大小,僅裁剪包裝容器。圖片必須彼此保持靜止相對位置。

3. 設計手柄與觸控拇指

手柄是互動的主要視覺提示:

  • 垂直分隔線: 一條垂直條,絕對定位於 left: var(--exposure-ratio);。將寬度設為高對比度的細線(例如 2px 到 4px),並加上陰影以在各種圖片背景中凸顯。
  • 抓取拇指目標: 在垂直線中央放置一個圓形或圓角的抓取拇指。
  • 視覺指示器: 在抓取拇指內部嵌入雙向水平箭頭(← →)或對比紋理,以指示水平拖曳能力。
  • 觸控目標大小(WCAG 2.2 SC 2.5.8): 在行動裝置/觸控介面上,互動抓取拇指的實體觸控目標必須至少為 44px x 44px,無論其視覺大小為何。可透過透明偽元素(::after)或內邊距達成。

4. 建構可存取的文字標籤

維持使用者情境與方向:

  • 文字標籤位置: 將標籤(例如「BEFORE」和「AFTER」)置於容器的對角(例如「前」在左上角,「後」在右上角)。
  • 高對比度設計: 使用半透明深色背景(遮罩)搭配白色文字標籤,確保與相鄰表面的對比度至少為 4.5:1(WCAG AA),無論圖片內容為何。
  • 互動狀態回饋: 可選項:滑桿啟用時淡出文字標籤以減少視覺干擾,互動結束後恢復。

5. 定義鍵盤導航與 ARIA 整合

介面必須可完全單獨透過鍵盤導航:

  • 範圍滑桿後端: 以一個原生、視覺隱藏的 <input type="range"> 元素支援視覺比較。這提供了原生的範圍處理、焦點狀態與 aria 角色。
  • ARIA 屬性關聯: 指派 aria-label(例如「前後圖片比較」)、aria-valuemin="0"、aria-valuemax="100" 以及代表百分比的動態 aria-valuenow。
  • 鍵盤事件對應:
    • ArrowLeft / ArrowDown:將位置減少 1%(或快速移動時為 5%)。
    • ArrowRight / ArrowUp:將位置增加 1%(或 5%)。
    • PageUp / PageDown:以 10% 增量移動滑桿位置。
    • Home:立即移至 0%(完全顯示「後」圖片)。
    • End:立即移至 100%(完全顯示「前」圖片)。
  • 焦點指示器: 滑桿獲得焦點時,在抓取拇指周圍顯示高對比度、清晰的焦點環。絕不要隱藏焦點樣式。

決策規則

滑桿移動模式選擇

互動模式使用案例條件實作方法
主動點擊/點按並拖曳(預設)高精度比較;適合詳細分析。僅在滑鼠/觸控按壓拇指時,於 pointermove 事件更新 --exposure-ratio。
懸停跟隨休閒/探索性比較;低摩擦的登陸頁面功能。當游標在容器任何部分移動時,直接更新 --exposure-ratio。不適合做為唯一方法;行動裝置上需要以點擊/拖曳做為備援。
雙圖切換(任意位置點擊)簡單、快速的比較;最適合螢幕較小且視覺變化非常明顯的情況。在容器任意位置點擊,觸發在 0% 與 100% 之間以平滑的 0.3s 緩動效果進行切換。

限制條件

  • 無障礙性(WCAG AA): 文字標籤必須滿足 4.5:1 的對比度。互動控制器必須支援完整的鍵盤焦點、可見指示器(:focus-visible)以及至少 44px x 44px 的觸控目標。
  • 累計版面位移(CLS): 兩張圖片及其容器必須共享完全相同的預先定義寬高比。絕不要讓容器在圖片載入時崩塌至 0px 高度。使用 CSS aspect-ratio 或內聯 padding 百分比。
  • 響應式流暢性: 元件必須能動態縮放以適應行動裝置視口。在螢幕寬度 < 480px 時,按比例縮放標籤或將其移至圖片正下方,以避免遮擋其他核心視覺功能。
  • 減少動畫: 若使用者偏好減少動畫(@media (prefers-reduced-motion: reduce)),在使用鍵盤導航時停用平滑轉場,並避免使用懸停跟隨觸發,改為明確的點擊/點按動作。

常見失敗模式

  • 「圖片擠壓」陷阱: 在拖曳互動過程中調整或拉伸圖片而非裁剪,導致視覺變形。
  • 「零 CLS 崩塌」: 未設定容器尺寸,導致圖片下載時版面劇烈跳動。
  • 鍵盤排除: 建立僅能使用滑鼠拖曳的滑桿,使得鍵盤、螢幕報讀器及部分輔助開關使用者完全無法操作。
  • 淺色圖片上的「隱形拇指」: 未為手柄和拇指添加陰影、邊框或高對比度疊層,使其完全融入淺色/複雜的圖片中。
  • 觸控目標陷阱: 將抓取拇指做得極小(例如 10px 寬)且無觸控內邊距,在行動裝置上造成極大的使用者挫敗感。

驗證標準

  • 精確疊層對齊: 「前」與「後」圖片完美對齊,滑動時沒有水平偏移、擠壓或變形。
  • 零累計版面位移: 容器在圖片載入前,使用一致的寬高比或明確尺寸預留版面空間。
  • 行動觸控安全: 在行動/觸控視口上,抓取手柄/拇指的觸控目標至少為 44px x 44px。
  • 完整鍵盤導航能力: 使用者可以使用標準鍵盤按鍵(方向鍵、Home、End)導航、聚焦並調整滑桿位置。
  • 符合 ARIA 標準: 互動控制器使用語義元素(如 <input type="range">)或正確的 ARIA 角色(role="slider"、aria-valuenow、aria-label)。
  • 對比度 AA 合規: 文字標籤(「前」和「後」)與焦點指示器滿足與相鄰表面 4.5:1 的 WCAG 對比度。
  • 動態敏感度: 互動行為尊重使用者對減少動畫的偏好(prefers-reduced-motion: reduce)。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for progressive disclosure using accordions, ensuring structural integrity, visual affordances, and accessibility across different content densities and devices.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for long-form content, managing readability, vertical rhythm, and information density to ensure a superior reading experience.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for informational elements that communicate state (Badges) and categorization (Tags) with clarity and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for non-overlay notifications, managing global announcements and contextual inline alerts to communicate system states without interrupting the user's flow.

coastdigitalgroup/coastai-skills

Design and implement a systematic, asymmetrical bento-grid layout framework to organize diverse content types cohesively while maintaining strict visual hierarchy, logical focus order, and responsive flexibility.

coastdigitalgroup/coastai-skills

Design a responsive, mobile-first bottom navigation bar and persistent action dock system for mobile websites and web applications, establishing spatial anchors, tab bar anatomy, badge indicators, thumb-zone ergonomics, safe area inset handling, active/inactive state contrast, and desktop responsive adaptation rules.

coastdigitalgroup/coastai-skills

Design a mobile-first bottom sheet overlay system with configurable detents, drag affordances, safe area padding, responsive desktop modal/popover adaptation, and WCAG AA accessibility compliance.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for secondary navigation trails that provide orientation, context, and one-click access to parent levels in deep information architectures.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for buttons and interactive triggers, managing visual hierarchy, variant logic, and action grouping to ensure clear intent and accessible interaction.

coastdigitalgroup/coastai-skills

Design a systematic framework for date and time selection, managing calendar grids, range pickers, and scheduling interfaces to ensure precision and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for modular content containers that maintain hierarchy, structural integrity, and action alignment across variable content and responsive viewports.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for horizontal discovery components, managing navigation affordances, scroll behavior, and accessibility to ensure effective content density without compromising usability.

coastdigitalgroup/coastai-skills

Design a systematic, highly accessible, and developer-friendly UI layout framework for code blocks, snippet showcases, multi-file code tabs, line-highlighting, diff views, and syntax token contrast in technical documentation and developer platforms.

coastdigitalgroup/coastai-skills

Design a systematic framework for global command menus (Cmd+K panels) that combines keyboard-driven navigation, command execution, and shortcut discovery into an accessible, responsive overlay.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for threaded conversations, managing nesting depths, action hierarchies, and community signaling to foster engagement and readability.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for side-by-side comparison interfaces, managing high attribute density and responsive complexity to support informed decision-making.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for user privacy, managing consent banners, preference centers, and persistent privacy controls to balance legal compliance with user trust.

coastdigitalgroup/coastai-skills

Design and implement a systematic, highly accessible, and responsive visual layout framework for conversational chat widgets, live chat boxes, and chatbot panels that ensures clear message scannability, native focus flow, and seamless mobile keyboard adaptation.

coastdigitalgroup/coastai-skills

Design a systematic, accessible, and high-conversion framework for custom select dropdowns and comboboxes, defining anatomy, states, search-filtering, and responsive mobile-adaptive patterns.

coastdigitalgroup/coastai-skills

Design and implement a systematic color palette that ensures WCAG 2.2 accessibility compliance. Trigger this skill when asked to define brand colors, create UI themes, or establish a visual system for a website.

相關技能