coastdigitalgroup/coastai-skills

數值輸入與步進系統

目的

數值輸入與步進系統提供一個標準化框架，用於設計、結構化和實作用於選取、調整或輸入離散數值的控制項。精確的數值輸入——例如購物車商品數量、SaaS 座位分配、定價層級單位、預算範圍或尺寸規格——需要在快速微調與直接文字編輯、明確的最小/最大邊界狀態、適合觸控的點擊目標以及完整的鍵盤/螢幕閱讀器無障礙性之間取得平衡。

標準的 HTML <input type="number"> 控制項在不同瀏覽器間渲染不一致，通常帶有微小且無法自訂的原生微調箭頭，這違反了觸控目標準則 (WCAG 2.2 SC 2.5.8)，並可能觸發意外的滾動調整。此技能定義了明確的 UI 模式、空間佈局規則、互動狀態以及自訂數值步進器和單位限定欄位的無障礙標準。

使用案例

• 電子商務購物車數量選擇器： 讓購物者能夠輕鬆地在產品頁面、購物車抽屜和結帳摘要表格中增加、減少或輸入商品數量。
• SaaS 方案座位與授權控制項： 在定價頁面或訂閱管理設定中配置使用者席位、伺服器實例或儲存空間 GB。
• 表單限定單位輸入： 擷取受限的度量值，例如百分比值 (0–100%)、年齡限制、項目尺寸 (長/寬/高) 或貨幣金額。
• 金融與計算器控制項： 在互動式計算器中選擇貸款期限、存款金額或投資增量。
• 儀表板與篩選器控制項： 在資料密集的桌面環境中調整數值閾值、分頁行數或指標範圍篩選器。

何時不應使用

• 連續範圍選擇： 對於廣泛、非特定數值範圍的探索（精確值次於相對位置），請改用 accessible-range-slider-implementation 或雙拇指滑桿。
• 大型任意數字： 對於輸入信用卡號碼、電話號碼、郵遞區號或社會安全號碼等增/減操作無意義的場景，請搭配 form-design-system 使用標準的 <input type="text" inputmode="numeric">。
• 日期與時間選取： 對於選取日曆日期、月份或時鐘時間，請使用 calendar-and-date-system。
• 大型離散選項集合： 當需從預先配置的大量數量中選取（例如 25、50、100、500），請使用 segmented-control-system 或 custom-select-and-combobox-system。

輸入

1. 數值邊界： 最小值 (min)、最大值 (max) 和步進增量 (step) 約束。
2. 上下文與密度： 可用佈局空間（緊湊的內聯表格行 vs. 顯眼的產品購買區塊）。
3. 輸入格式與單位： 相關的物理或貨幣單位（例如 $、%、items、kg、seats）。
4. 互動模式： 是否允許直接手動文字輸入，或調整僅限於步進按鈕。
5. 品牌與表面 Token： 用於表面背景、活動邊框、禁用狀態、焦點環和圖示字形的調色板 Token。

輸出

1. 步進器元件規格： 定義遞減按鈕、數值顯示/輸入、遞增按鈕和單位標籤的視覺解剖結構。
2. 邊界與狀態矩陣： 預設、懸停、焦點、禁用（在最小/最大限制時）、載入和錯誤狀態的視覺處理。
3. 響應式空間佈局規格： 跨斷點的觸控目標尺寸（觸控至少 44x44px，緊湊桌面為 24x24px）、間距和字體度量。
4. 無障礙與鍵盤映射： ARIA 屬性 (role="spinbutton"、aria-valuenow、aria-valuemin、aria-valuemax)、即時區域配置和鍵盤快捷鍵處理器規格。

---

工作流程

1. 選擇步進器變體

根據上下文和互動意圖選擇合適的結構變體：

• 標準水平步進器（3 段式分割）： 左側為遞減按鈕 (-)，中央為文字輸入，右側為遞增按鈕 (+)。最適合電子商務產品頁面、購物車項目和 SaaS 座位計數器。
• 緊湊內聯步進器（堆疊箭頭）： 文字輸入，尾側帶有垂直堆疊的微型按鈕。最適合高密度桌面資料表格、工具列和 SaaS 設定側邊欄面板。
• 單位前綴輸入框： 帶有固定前綴/後綴單位標籤（例如 $、USD、px、%）和可選步進按鈕的文字欄位。最適合金融輸入和系統配置表單。
• 獨立按鈕計數器： 完全可點擊的藥丸形狀，點擊後會開啟內聯模態/彈出視窗，或在聚焦時轉變為活動步進器。

2. 建立視覺解剖結構與觸控目標規則

使用清晰的幾何參數來構建元件：

• 觸控目標尺寸： 確保所有互動式遞增/遞減按鈕在行動/觸控介面上具有至少 44x44px 的最小點擊目標 (WCAG 2.5.5 / 2.5.8)。在僅桌面的緊湊 UI 上，保持至少 24x24px 並搭配足夠的點擊內邊距。
• 輸入欄位尺寸： 使用 CSS ch 單位根據預期最大位數動態設定寬度（例如，對於 2 位數數量，設定為 width: calc(3ch + 2rem)）。
• 排版與對齊： 將數值在輸入欄位內水平置中對齊。使用等寬表格數字 (font-variant-numeric: tabular-nums;) 以防止在快速數值轉換期間發生佈局偏移。
• 視覺分組： 將按鈕和輸入框封裝在共享邊框容器或連續的分割藥丸形狀內，以表示統一的功能。

3. 定義邊界行為與禁用狀態

清楚溝通最小和最大限制，以避免使用者挫折感：

• 在最小邊界 (value <= min) 時：
  • 禁用遞減按鈕（disabled 屬性和 aria-disabled="true"）。
  • 套用低對比度的禁用樣式（例如 opacity: 0.4; cursor: not-allowed;）。
  • 如果在電子商務購物車上下文中 min === 1，可選擇性地在值為 1 時將遞減按鈕轉變為「垃圾桶/刪除」圖示，以允許移除單項商品。
• 在最大邊界 (value >= max) 時：
  • 禁用遞增按鈕（disabled 屬性和 aria-disabled="true"）。
  • 如果使用者嘗試進一步遞增，提供內聯輔助文字（例如「每個訂單最多 10 件商品」）或一個不明顯的工具提示。
• 直接輸入驗證：
  • 在輸入 blur（失去焦點）時，自動將超出範圍的輸入值限制到最近的有效限制（例如，在最大值為 10 的欄位中輸入 99 會被限制為 10）。
  • 如果步進增量為非整數（例如 step="0.5"），則在失去焦點時將輸入值四捨五入到最近的有效步進增量。

4. 實作鍵盤導航與觸控回饋

確保跨輸入裝置的無縫控制：

• 按鍵綁定：
  • ArrowUp / ArrowRight：按 step 遞增數值。
  • ArrowDown / ArrowLeft：按 step 遞減數值。
  • PageUp：按 step * 10（或更大的步進增量）遞增數值。
  • PageDown：按 step * 10 遞減數值。
  • Home：將值設為 min（如果已定義）。
  • End：將值設為 max（如果已定義）。
• 按住自動重複： 當使用者按住遞增/遞減按鈕（透過指標或鍵盤）時，在初始 500ms 延遲後啟動數值自動重複，每 100ms 循環一次。
• 觸控/行動鍵盤： 在 <input> 元素上設定 inputmode="numeric" 或 inputmode="decimal" 以及 pattern="[0-9]*"，以在行動裝置上觸發數字鍵盤，同時避免強制使用標準的原生瀏覽器微調按鈕。

5. 配置無障礙與螢幕閱讀器語意

提供符合 WCAG 2.1 / 2.2 AA 的體驗：

• 語意 HTML 選項：
  • 選項 A（帶步進按鈕的原生輸入）： 使用與明確 <label> 關聯的 <input type="text" inputmode="numeric">。為遞減/遞增按鈕添加 <button type="button" aria-label="減少數量"> 和 aria-controls="input-id"。
  • 選項 B（ARIA Spinbutton 角色）： 在容器或輸入上應用 role="spinbutton"、aria-valuenow="3"、aria-valuemin="1"、aria-valuemax="10"、aria-valuetext="3 個座位" 和 aria-label="選擇座位數量"。
• 焦點環管理： 在活動按鈕和文字輸入周圍保持可見、高對比度的焦點環 (outline: 2px solid var(--focus-ring); outline-offset: 2px;)。焦點環絕不能被父容器邊界隱藏或裁剪。
• 即時區域通知： 使用 aria-live="polite" 或動態更新 aria-valuenow，以便輔助技術在按下按鈕時立即宣告數值變更。

---

決策規則

元件模式矩陣

使用案例	建議變體	按鈕放置	最小/最大策略
電子商務產品頁面	標準水平	兩側（- 左，+ 右）	最小值 = 1（或 1 時變為垃圾桶），最大值 = 庫存限制
購物車明細項目	緊湊水平 / 垃圾桶混合	兩側（-/垃圾桶 左，+ 右）	最小值 = 0（移除項目），最大值 = 可用庫存
SaaS 帳務座位	帶單位後綴的水平	兩側（- 左，+ 右）	最小值 = 最低方案層級，最大值 = 帳戶上限
桌面資料表格	堆疊內聯步進器	尾側堆疊（▲ 上，▼ 下）	失去焦點時限制在最小/最大
金融金額	單位前綴輸入框 ($)	可選兩側或僅手動	最小值 = 0，最大值 = 帶驗證訊息的限制

直接輸入 vs. 僅按鈕規則

• 允許直接輸入（預設）： 對於數量 > 5 或使用者可能直接輸入大數字的情況（例如訂購 50 件商品或設定 $500 預算）。
• 限制為僅按鈕 (readonly 輸入)： 僅在數值範圍非常小（例如 1 到 5）且自由文字輸入會在小型觸控裝置上引入不必要的驗證負擔時使用。

---

約束條件

• 無障礙性 (WCAG 2.1 / 2.2 AA)：
  • 按鈕必須提供明確的 aria-label 屬性來描述動作（例如「減少商品數量」）。
  • 遞增和遞減按鈕在觸控視口上必須保持最小 44x44px 的觸控目標 (SC 2.5.8)。
  • 活動焦點指示器必須滿足 WCAG 2.4.11（焦點未被遮蔽）和 SC 2.4.13（焦點外觀）。
• 數字格式化：
  • 絕不允許在失去焦點時輸入中保留空白或 NaN 值。應回退到 min 或先前的有效值。
  • 數字必須使用 font-variant-numeric: tabular-nums; 渲染，以防止在遞增過程中發生佈局回流。
• 行動軟體鍵盤：
  • 始終設定 inputmode="numeric"（或 decimal）以在 iOS/Android 上開啟標準數字鍵盤。透過 CSS (::-webkit-inner-spin-button) 禁用原生微調按鈕樣式，避免使用原生 <input type="number"> 的預設箭頭樣式。

---

常見失敗模式

• 過小的非標準觸控目標： 在行動裝置上使用 18x18px 的 chevron 按鈕，導致誤觸和使用者挫折感。
• 依賴原生瀏覽器 <input type="number">： 允許瀏覽器預設微調按鈕渲染不一致、與自訂文字內邊距重疊或觸發意外的滾動調整。
• 缺少邊界禁用提示： 當 value === min 時，遞減按鈕在視覺上仍保持活動狀態，導致使用者點擊後沒有回饋。
• 未限制的自由形式輸入： 允許使用者輸入無效值（例如 -5 或 999999），卻未在失去焦點時進行限制或提供錯誤回饋。
• 缺少鍵盤支援： 設計自訂的 <div> 按鈕，但缺乏 Tab 聚焦能力和 ArrowUp/ArrowDown 事件處理。

---

驗證標準

• 遞減和遞增按鈕在觸控視口上滿足最小 44x44px 的觸控目標。
• 使用等寬表格數字排版 (tabular-nums) 以防止更新期間的佈局抖動。
• 在最小和最大限制時，各自的按鈕轉換為禁用狀態 (aria-disabled="true")。
• 行動輸入使用 inputmode="numeric" 或 inputmode="decimal"。
• 元件正確處理 ArrowUp、ArrowDown、PageUp、PageDown、Home 和 End 按鍵。
• 已配置程式化標籤（aria-label 或 <label>）和 ARIA 角色（role="spinbutton" 或明確的 aria-controls 按鈕）。
• 超出範圍的輸入值在 blur 時會自動限制或觸發驗證錯誤訊息。
• 高對比度的焦點指示器可見且未被遮蔽。