# Color Icon Button

`btn-color-icon` 是 daisyUI 5 `btn` 的彩色 SVG 呈現 modifier。它不定義按鈕功能，也不將圖示檔名綁定到 CSS class。

## 基本使用

純圖示按鈕使用 daisyUI `btn-square`：

```html
<button type="button" class="btn btn-square btn-color-icon" aria-label="儲存">
   <img src="/icons/color/save.svg" alt="" aria-hidden="true">
</button>
```

有可見文字時直接使用一般 `btn`：

```html
<button type="button" class="btn btn-color-icon">
   <img src="/icons/color/save.svg" alt="" aria-hidden="true">
   <span>儲存</span>
</button>
```

SVG 可以使用外部 `<img>`，也可以使用 inline `<svg>`。元件只規範其尺寸、陰影、互動與 disabled 呈現。

## daisyUI 組合

所有按鈕能力仍由 daisyUI 提供：

```html
<button class="btn btn-sm btn-square btn-color-icon">...</button>
<button class="btn btn-lg btn-circle btn-color-icon">...</button>
<button class="btn btn-soft btn-color-icon">...</button>
<button class="btn btn-ghost btn-color-icon">...</button>
```

按鈕群組使用 `join`：

```html
<div class="join" role="group" aria-label="檔案操作">
   <button class="btn btn-square btn-color-icon join-item" aria-label="編輯">
      <img src="/icons/color/edit.svg" alt="" aria-hidden="true">
   </button>
   <button class="btn btn-square btn-color-icon join-item" aria-label="儲存">
      <img src="/icons/color/save.svg" alt="" aria-hidden="true">
   </button>
</div>
```

排列使用 Tailwind 的 `justify-start`、`justify-center`、`justify-end`，不另外建立 LeftBar、CenterBar 或 RightBar class。

## 展開標籤

`btn-color-icon-reveal` 保留舊元件的互動展開特色：

```html
<button
   type="button"
   class="btn btn-color-icon btn-color-icon-reveal"
   aria-label="上傳圖片"
>
   <img src="/icons/color/gallery.svg" alt="" aria-hidden="true">
   <span class="btn-color-icon-label">選擇圖片</span>
</button>
```

- 支援 hover、`:focus-visible` 與 `.btn-active`。
- 收合時，圖示以按鈕的幾何中心定位，不受隱藏標籤寬度影響。
- 展開寬度與標籤透明度使用 `linear 200ms`，俐落顯示完整標籤。
- 圖示與標籤使用 daisyUI 一般按鈕相同的 `0.375rem` 間距。
- 觸控裝置沒有 hover 時，標籤預設顯示。
- `prefers-reduced-motion: reduce` 會停用可感知的展開動畫。
- `aria-label` 讓標籤收合時仍有穩定的可存取名稱。

## Disabled

disabled 行為仍由 daisyUI 控制；`btn-color-icon` 只將彩色圖示轉為灰階並降低透明度：

```html
<button class="btn btn-square btn-color-icon" aria-label="儲存" disabled>
   <img src="/icons/color/save.svg" alt="" aria-hidden="true">
</button>
```

## CSS 變數

| 變數 | 預設值 | 用途 |
| --- | --- | --- |
| `--uic-btn-color-icon-size` | `calc(var(--size) * 0.6)` | 圖示尺寸，隨 daisyUI 按鈕高度縮放 |
| `--uic-btn-color-icon-shadow` | Theme-aware drop shadow | 彩色圖示在亮／暗背景上的邊緣分離效果 |

```html
<button
   class="btn btn-color-icon"
   style="--uic-btn-color-icon-size: 2rem"
>
   ...
</button>
```

## SVG 資產

將自訂 SVG 放入 `src/icons/color/`，執行 `npm run build` 後會複製到 `dist/icons/color/`。檔案名稱只供 HTML `src` 使用，不會產生同名 CSS class。

建議規則：

- 主要使用同一個圖示家族與一致 view box；
- 使用 kebab-case 檔名；
- 清除 script、外部資源、XML declaration 與編輯器 metadata；
- 確認每個圖示的商用與再散布授權；
- 同時檢查亮色與深色 theme。

目前元件庫收錄專案原先準備的 12 個彩色 SVG；建置只同步這些專案資產，不再產生第三方範例圖示。

## 可存取性

- 純圖示按鈕必須有 `aria-label`；不要只依賴 `title`。
- 裝飾性 `<img>` 使用 `alt=""` 及 `aria-hidden="true"`。
- 有可見文字時，文字本身可作為按鈕名稱。
- 使用原生 `<button type="button">`，保留 daisyUI 的鍵盤 focus outline。