Communitygithub.com

coastdigitalgroup/coastai-skills

設計並實作系統化的實體店面發現框架,包含空間分割佈局、地圖與列表的互動同步,以及無障礙鍵盤導航的備援機制。

coastai-skills 是什麼?

這項技能提供了一個完整的「店面定位系統」方法論,專注於設計實體位置發現介面(例如分行查詢、零售商點、經銷商網路或醫療診所查詢)。它定義了空間組成、響應式適應、互動同步以及無障礙護欄等四大核心要素,幫助開發者在搜尋與實體地點之間建立流暢的橋樑。此技能支援支援桌面與行動裝置,透過分割面板或可切換頁籤的佈局來最佳化空間使用,並確保所有互動(點選地圖標記、滑過列表卡片)都能雙向同步。此外,它還強調無障礙友善,例如鍵盤導航、螢幕閱讀器宣告與觸控目標大小,並提供了常見的失敗模式與驗證準則,幫助團隊避免行動裝置滾動陷阱或雙向同步中斷等問題。

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

在你喜歡的 AI 中提問

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

說明文件

店面定位系統

目的

店面定位系統提供了一套設計實體位置發現介面(例如分行查詢、零售商點、經銷商網路或醫療診所查詢)的方法論。此系統定義了空間組成、響應式適應、互動同步以及無障礙護欄,以橋接數位搜尋與實體目的地。它確保使用者能夠找到附近的地點、評估商店詳細資訊,並順利導航前往,不會造成認知負擔、佈局不穩定或無障礙障礙。

使用案例

  • 零售與經銷商網路: 引導顧客前往實體店面、合作零售商或授權服務中心。
  • 醫療保健與診所: 幫助患者尋找附近的緊急護理機構、醫院或專科診所。
  • 金融機構: 顯示ATM網路與分行地點,並附帶特定服務功能(例如得來速、公證服務)。
  • 餐廳與連鎖餐飲: 協助顧客尋找附近的餐廳、查看即時營業狀態,並發起外帶或外送訂單。

何時不該使用

  • 單一地點商家: 如果公司只有一兩個實體辦公室,完整的定位介面就顯得大材小用。一個簡單的聯絡頁面加上嵌入的靜態地圖就已足夠(請參閱 site-navigation-system 或聯絡頁面指南)。
  • 純數位/電子商務品牌: 沒有實體據點或實體取貨點的企業。
  • 動態物流與路徑規劃: 進階的共乘或即時配送追蹤應用程式需要持續的GPS追蹤與動態路線規劃,這屬於專業地理資訊系統/即時交通系統的範疇。

輸入

  1. 位置元數據庫存: 座標集(緯度/經度)、實體地址、聯絡方式(電話、電子郵件)、營業時間以及特定地點的特色或服務(條件篩選)。
  2. 使用者位置訊號: 地理定位API可用性、使用者輸入的郵遞區號或城市/州文字輸入。
  3. 地圖平台能力: 底層地圖提供者(例如 Google Maps API、Mapbox GL JS、Leaflet)的限制與自訂樣式參數。
  4. 主要使用者目標: 使用者主要是想立即前往(需要路線與營業時間)、聯絡該地點(需要電話)還是確認庫存(需要連結到庫存系統)?

輸出

  1. 空間佈局藍圖: 響應式空間佈局規格(桌面的分割面板比例 vs. 行動裝置的堆疊式頁籤面板)。
  2. 構成規範: 地點卡片、搜尋/篩選標題與地圖標記的詳細設計。
  3. 互動與狀態對應圖: 定義標記點擊同步、懸停狀態、列表載入指示器以及卡片/標記對應的行為。
  4. 無障礙地標與鍵盤對應圖: 定義詳細檢視的焦點陷阱機制、螢幕閱讀器的即時區域宣告以及非視覺地圖導航路徑。

工作流程

1. 建立空間組成

設計地圖與地點列表之間的空間關係:

  • 桌面佈局(分割面板): 使用分割螢幕設計。
    • 側邊欄面板(35% 至 40% 寬度): 放置在左側(針對從左到右的語言),以建立閱讀層級的起點。它必須獨立於主頁面滾動,保持搜尋輸入與地點列表的可及性。
    • 地圖面板(60% 至 65% 寬度): 設定為固定在右側的持久元素。
  • 行動裝置佈局(可切換頁籤): 由於地圖與列表無法在狹窄的視口中並排顯示,因此在螢幕頂部或底部實作一個切換列:
    • 「列表檢視」頁籤: 顯示搜尋輸入與垂直卡片列表。建議作為預設頁籤。
    • 「地圖檢視」頁籤: 顯示全螢幕地圖。
    • 操作層: 確保浮動控制項(例如「搜尋此區域」按鈕或地理定位圖釘)能舒適地置於地圖上方,而不會遮蔽導航。

2. 定義地點卡片的構成

地點卡片是主要的資訊單元。依認知掃描優先順序排列其元素:

+-------------------------------------------------------------+
|  [類別標籤]                               [距離:0.8 英里] |
|  **地點標題 / 分行名稱**                                   |
|  [星級評分 / 評論(選填)]                                 |
|                                                             |
|  123 街道地址, 城市, 州 郵遞區號                           |
|  狀態指示燈:[營業中 / 關閉](晚上 8:00 關門)              |
|                                                             |
|  [按鈕:路線]     [按鈕:致電]    [連結:詳細資訊]         |
+-------------------------------------------------------------+
  • 主要層級: 地點名稱與距離搜尋中心的距離。距離必須即時計算並高度可見(右上角)。
  • 次要層級: 街道地址與即時營業/關閉狀態(使用顏色編碼搭配文字,例如綠色代表營業中,紅色代表關閉)。
  • 第三層級: 主要動作以易於觸控的行動呼籲按鈕呈現(例如「路線」、「致電」、「檢視詳細資訊」)。

3. 設計搜尋與條件篩選

在側邊欄的標題區段提供高度直覺的查詢與篩選工具:

  • 搜尋輸入框: 一個結合郵遞區號、城市名稱與街道地址的輸入框,並附有自動完成選單。
  • 我的位置觸發器: 一個顯眼且無障礙的地理定位按鈕,以標準的「十字準線」圖示表示,並為螢幕閱讀器適當標記(aria-label="尋找靠近我目前位置的據點")。
  • 半徑篩選器: 一個下拉選單,允許使用者調整搜尋半徑(例如 5、10、25、50 英里)。
  • 條件下拉選單: 針對商店特定功能的快速篩選器(例如「得來速」、「輪椅無障礙」、「24 小時營業」)。在篩選按鈕上使用徽章來顯示已選取的數量。

4. 實作雙向互動同步

地圖標記與列表卡片必須表現為一個統一的系統。建立明確的互動關係:

  • 列表卡片懸停/聚焦 -> 地圖標記: 懸停或聚焦列表卡片時,必須觸發其對應地圖標記的視覺狀態變更(例如放大、變色、或使用 z-index 調整移到前方)。
  • 地圖標記點擊 -> 列表卡片: 點擊地圖標記時,必須:
    • 自動滾動側邊欄列表,將對應的卡片帶入視野。
    • 使用簡短的轉場動畫(例如輕微的背景脈衝)來凸顯該卡片。
    • 在標記上方開啟一個地圖「資訊視窗」(彈出視窗),其中包含商店名稱、距離以及「路線」連結。
  • 搜尋此區域(地圖拖曳): 提供一個「搜尋此區域」的浮動按鈕,僅在使用者將地圖平移或縮放至初始搜尋中心之外時,才會出現在地圖面板的頂部中央。

5. 建立行動觸控與地圖適應

管理行動裝置上的互動,以防止挫折感:

  • 避免滾動劫持: 預設停用行動地圖上的手勢縮放(需要雙指拖曳才能平移或縮放)。這可以防止使用者在嘗試向下滾動頁面時「卡在」地圖中。
  • 浮動控制項: 將浮動的放大/縮小控制項與地理定位按鈕放置在地圖的右下角,並使用高對比度的陰影樣式,且最小觸控目標為 44x44px。
  • 卡片輪播疊加層: 在行動裝置的地圖檢視中,在視口底部提供一個可水平滑動的卡片輪播,顯示單一啟用中或最近的地點,將地圖探索與詳細資訊整合在一起。

決策規則

  • 「預設搜尋」規則: 當定位頁面載入時,若沒有搜尋查詢或地理定位權限:
    • 不要顯示空白地圖。
    • 預設根據IP地理定位顯示最近的地點,或依字母順序/優先順序顯示所有地點。
  • 「無結果」恢復規則: 如果使用者在沒有地點的區域進行搜尋:
    • 將地圖縮小以顯示最近的可用地點。
    • 在側邊欄列表中顯示一則有用的訊息(例如「在 [查詢] 方圓 25 英哩內找不到據點。以下是離您最近的據點:」)。
    • 提供「檢視所有據點」連結。
  • 彈出視窗 vs. 詳細資訊面板規則:
    • 如果地點的元數據很少(僅地址與營業時間),請在地圖標記的資訊視窗彈出視窗中顯示所有資訊。
    • 如果地點有大量的元數據(庫存、團隊列表、照片),點擊「檢視詳細資訊」必須在側邊欄內滑出一個全深度的詳細資訊面板,並將鍵盤焦點鎖定在其中,同時提供一個明確的「返回列表」按鈕。

限制條件

  • 無障礙性(鍵盤導航):
    • 鍵盤使用者必須能夠在不直接使用地圖的情況下,導覽整個搜尋流程與地點列表。
    • 地圖標記必須可透過鍵盤聚焦(tabindex="0"),或由一個無障礙的列表替代方案來表示。
    • 當搜尋結果更新時,使用 aria-live="polite" 元素向螢幕閱讀器宣告變更(例如「在西雅圖, WA 附近找到 3 個地點」)。
  • 觸控目標大小: 所有按鈕、地圖標記與篩選控制項必須符合 WCAG 2.2 SC 2.5.8(最小 24x24px,並含周圍間距),且卡片上的主要動作觸發器與浮動控制項應至少為 44x44px,以符合拇指舒適度。
  • 視覺對比度: 偏好使用高對比度的地圖。標準標記與作用中標記標籤相對於地圖背景的對比度至少需達到 3:1。卡片與彈出視窗內文的對比度必須符合 WCAG AA(4.5:1)。
  • 防止佈局位移: 在進行搜尋時,於側邊欄中為載入狀態保留垂直/水平空間(使用骨架卡片),以預防累積佈局位移。

常見失敗模式

  • 行動裝置滾動陷阱: 使用者困在頁面上,因為在行動螢幕上滾動只會平移/縮放地圖,導致他們無法滾過地圖元件。
  • 雙向同步中斷: 點擊地圖標記會開啟彈出視窗,但不會滾動到側邊欄中對應的卡片或將其凸顯,迫使使用者手動比對名稱。
  • 「盲人地圖」(鍵盤排除): 將地圖標記實作為不可聚焦的 SVG 形狀或 Canvas 元素,使得螢幕閱讀器與僅使用鍵盤的使用者完全無法觸及實體地點。
  • 無查詢的空白死胡同: 在頁面首次載入時顯示完全空白的畫面與沉寂的地圖,要求使用者必須先猜測要進行搜尋。
  • 地圖拖曳延遲: 在每次小幅地圖拖曳時嘗試即時擷取並渲染數百個標記,導致介面凍結。應在地圖範圍變更時實作防抖(250–400ms)並聚合靠近的標記。

驗證標準

  • 已定義桌面(分割螢幕側邊欄)與行動裝置(可切換列表/地圖頁籤)的空間佈局。
  • 已指定雙向同步(點擊標記會凸顯/滾動到卡片;懸停/聚焦卡片會凸顯標記)。
  • 行動裝置手勢縮放預設為關閉(需要雙指滾動)以避免行動裝置滾動劫持。
  • 已設計載入狀態(骨架螢幕)以避免在搜尋查詢更新時發生佈局位移。
  • 已定義無障礙替代方案:鍵盤使用者可以瀏覽所有地點、閱讀其詳細資訊並取得路線,無需使用滑鼠懸停在地圖 Canvas 元素上。
  • 當搜尋結果更新時,螢幕閱讀器會收到一個描述性的、禮貌的 aria-live 宣告。
  • 所有互動式卡片元素、標記與縮放按鈕的觸控目標至少符合 WCAG 2.2 24x24px 的最小值(主要行動呼籲按鈕建議為 44x44px)。
  • 地點卡片與地圖彈出視窗內文的文字對比度符合 WCAG AA(4.5:1)。
  • 已為零結果搜尋與位置權限拒絕設計明確的備援流程。

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.

相關技能