# Accesserty UI Kit

為無障礙而做的元件，不綁定單一前端框架。

Accesserty UI Kit 是一套無障礙 Web Components，以 HTML 標籤使用。元件本身不依賴 Vue 或 React 的執行環境，外觀可以直接用 CSS 調整，不需要另學專用的主題工具。

MIT 授權、免費，直接用 HTML 試用。

元件 JavaScript 沒有執行期依賴；純 HTML 範例可以下載後直接試，不需要 npm 或建置工具。

英文版本：https://accesserty.com/en/ai/products/uikit.md

## 什麼時候適合使用 UI Kit？

正在做頁籤、選單或表單，想先用現成元件處理鍵盤操作與狀態，可以從這裡試。資料怎麼帶入、操作後要更新什麼，再接上你自己的程式。

- 少從頭處理無障礙細節：頁籤的方向鍵切換、選單開關、選取狀態與語意結構放在元件裡，讓你有現成的互動基礎。
- 元件不依附單一框架：同一套 Web Components 有純 HTML、Vue／Nuxt 與 React／Next 的使用範例。框架整合仍需設定載入、屬性與事件；升級框架時，也要檢查這些設定。
- 直接用 CSS 調整外觀：顏色、間距與邊框可透過各元件提供的 CSS 變數調整；有開放 CSS Parts 的地方，可依文件細調。不需要為了使用 UI Kit 另接專用主題管理工具。

## 先看有哪些元件

到[元件與範例](https://accesserty.com/uikit/#components)找你需要的介面，共有 15 種 Web Components。點元件名稱看 GitHub 上的 HTML 範例；想先試操作或調樣式，可以開啟 Playground：[預覽元件與調整樣式](https://accesserty.com/uikit/playground/)。也可以直接查看最新的[範例資料夾](https://github.com/Accesserty/UI-Kit/tree/v3.0.2/demo)。

- 表單與輸入：Input（`au-input`）、Textarea（`au-textarea`）、Checkbox（`au-checkbox`）、Radio group（`au-radio-group`）、Switch（`au-switch`）、Rating（`au-rating`）、File upload（`au-file-upload`）。
- 導覽與選擇：Tabs（`au-tabs`）、Dropdown（`au-dropdown`）、Pagination（`au-pagination`）、Breadcrumbs（`au-breadcrumbs`）、Tree（`au-tree`）。
- 內容呈現：Accordion（`au-accordion`）、Card（`au-card`）、Carousel（`au-carousel`）。

原生 HTML 已能滿足需求時，優先使用原生元素。Button、Select、Dialog 使用原生 HTML 元素，另有可選的樣式，不包含在這 15 種 Web Components 裡。

## 先把一個元件跑起來

到[開始整合](https://accesserty.com/uikit/#plain-html-start)，先操作現有的「服務資訊」頁籤：按 Tab 移到頁籤，用左右方向鍵切換，再按 Tab 進入內容。下方 HTML 是這個例子的寫法。

操作示範、HTML 與下載之後，是預設收起的第一次使用步驟與框架設定。已有 Vue／Nuxt 或 React／Next 專案，就展開對應設定，依[最新框架整合文件](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/README.md#framework-integration)載入元件並接上屬性與事件。

### 純 HTML：最小用法與完整頁面

產品頁提供兩個頁籤的最小用法、JavaScript 下載，以及可展開的完整 HTML。下載[最新版 UI Kit JavaScript](https://accesserty.com/vendors/accesserty-ui-kit.min.js)，保留檔名 `accesserty-ui-kit.min.js`；將完整範例存成 `index.html`，放在同一資料夾，再用瀏覽器開啟。

範例使用一般的 `defer` script 標籤。元件內含基本樣式，這條純 HTML 試跑路徑不需要 npm、建置工具或額外樣式表。這是 HTML 範例；Vue 模板與 React JSX 的載入及綁定方式，請看各自的整合設定。

若開啟後只看到兩段文字、沒有頁籤，先檢查 JavaScript 的檔名、相對路徑與瀏覽器執行設定。

### Vue／Nuxt

Nuxt：把 UI Kit 的 `dist/` 資料夾複製到專案（例如 `vendor/accesserty/`，不要放在 `public/`），再於 `nuxt.config.ts` 加一個 module：`modules: ['./vendor/accesserty/accesserty-ui-kit-nuxt.js']`。不需要自己寫外掛、設定 `isCustomElement` 或包 `<ClientOnly>`。參考 [Nuxt 導入指南](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/README.md#nuxt)。

Vue＋Vite：載入元件、安裝 `AccessertyVue` 外掛，Vite 設定改用 UI Kit 提供的 `isCustomElement`（不要寫 `tag => tag.startsWith('au-')`）。`au-input`、`au-textarea`、`au-checkbox`、`au-switch`、`au-radio-group`、`au-rating`、`au-file-upload` 可以直接寫 `v-model`，規則和 Vue 原生欄位一致，多個 checkbox 也能共用同一個陣列。參考 [Vue 3 導入指南](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/README.md#vue-3)。

### React／Next

React 19：表單元件有對應的 React 元件（`AuInput`、`AuCheckbox` 等），和原生欄位一樣用 `value`／`checked` 與 `onChange` 控制；其他元件直接寫成 `au-*` 標籤。React 整合需要 React 19。參考 [React／Next 導入指南](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/README.md#react-and-nextjs)。

Next：在用戶端元件呼叫一次 `defineElements()`；伺服器會輸出元件標籤與初始值，內部控制項在瀏覽器執行 JavaScript 後建立。使用自架的 Next 伺服器時，可以用 `withDeclarativeShadow` 讓 accordion、tabs、breadcrumbs 在伺服器先畫好（Vercel 不支援自架伺服器）。Nuxt 的 module 預設就會這樣做。

[Next 表單整合範例](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/test/ssr/next-react/app/Form.jsx)從 `vendor/` 載入複製過來的 dist，和實際專案的做法相同；請把路徑換成你放檔案的位置。

兩套框架設定之後提供共用的 [Next／Nuxt 整合範例與測試範圍](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/test/ssr/README.md)，不必展開另一套框架才能查看。

## 接上資料，調整成網站需要的樣子

### 取得資料、回應操作

依元件文件帶入欄位值、讀取使用者輸入，並接上操作後要執行的程式。表單整合時，確認所用元件的事件內容、屬性更新、FormData 支援與重設行為；不是所有元件都能用 FormData 取得資料。可對照[綁定與表單範例](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/test/ssr/README.md)。

File upload 處理檔案選取；上傳要接你自己的程式，伺服器也要驗證收到的檔案。

### 直接用 CSS 調整外觀

把 CSS 寫在自己的樣式表，就能調整元件開放的變數。例如，在 `<au-tabs>` 上加上 `class="example-tabs"`，再用下面的 CSS 調整頁籤背景與選取狀態的顏色：

```css
.example-tabs {
  --au-tabs-bg: #f5f5f5;
  --au-tabs-selected-bg: #222;
  --au-tabs-selected-text-color: #fff;
}
```

這段是供你在專案裡套用的例子，產品頁的操作示範保留原有外觀。各元件可調整的變數與 CSS Parts 見[樣式調整指南](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/README.md#styling)。

也可開啟 Playground：[預覽元件與調整樣式](https://accesserty.com/uikit/playground/)。調整後複製 CSS 到自己的樣式表，將產生的 class 名稱套到對應元素上。Playground 只輸出改過的 CSS 變數，沒有調整時不會產生樣式規則；HTML 與 JavaScript 需另外接入專案。

### 換上自己的文字與翻譯

「服務資訊」示範的「服務內容／聯絡方式」是頁面提供的文字，你可以換成自己網站的頁籤名稱。欄位標籤、提示與狀態文字也由你的產品透過屬性或內容傳入，可接既有的翻譯系統。UI Kit 不會自動翻譯；各元件的文字設定見[翻譯屬性](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/README.md#localization)。

## 可以只用需要的元件嗎？

可以。UI Kit 的 `dist/components/` 有 15 個單一元件檔（各有一般版與 min 版），每個都已包含需要的共用程式，可以只複製需要的元件，詳見[最新 README](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/README.md)。官網的 JavaScript 下載是整套元件；只用部分元件時，升級由你的專案自行管理。

## 可以用在商業專案嗎？

可以。UI Kit 使用 MIT 授權，可免費使用與修改，也能用在公司或接案網站。散布程式碼時須保留版權與授權聲明；完整條件見 [MIT 授權](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/LICENSE)。

## 看得到原始碼，也查得到測試

最新版下載與文件對應同一版本，可查看原始碼、HTML 示範及元件與框架整合測試。整合測試使用 Nuxt 4、Vue＋Vite，以及 Next 16 與 React 19；React 整合需要 React 19。測試範圍不涵蓋所有框架版本、完整應用或輔助科技組合。

### 放進網站後，還要測什麼？

用鍵盤走完實際任務，確認焦點看得見、內容與狀態能正確切換。調整樣式後，檢查文字對比與窄螢幕操作；換文字或語言後，用螢幕閱讀器確認名稱、狀態與內容。表單、路由及操作後的資料更新，也要在自己的專案測試。

元件不能讓整站自動符合 WCAG。Playground 與元件測試提供的是各自涵蓋的檢查，完整網站仍需要人工與輔助科技測試。升級元件或框架前，先在測試環境重跑自己的載入、綁定與完整流程。遇到問題可[查看已知問題或回報問題](https://github.com/Accesserty/UI-Kit/issues)。

### 最新文件、授權與測試

- [最新 README](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/README.md)
- [MIT 授權](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/LICENSE)
- [原始碼](https://github.com/Accesserty/UI-Kit/tree/v3.0.2/src)
- [示範與元件文件](https://github.com/Accesserty/UI-Kit/tree/v3.0.2/demo)
- [測試原始碼](https://github.com/Accesserty/UI-Kit/tree/v3.0.2/test)與[執行說明](https://github.com/Accesserty/UI-Kit/blob/v3.0.2/README.md#development)

## 目前入口

- 產品頁：https://accesserty.com/uikit/
- 元件與範例：https://accesserty.com/uikit/#components
- 開始整合：https://accesserty.com/uikit/#plain-html-start
- 預覽元件與調整樣式：https://accesserty.com/uikit/playground/
- GitHub：https://github.com/Accesserty/UI-Kit