SwIcon

SwIcon 是一個純粹的尺寸與顏色容器（<span class="sw-icon">），不內嵌任何具體圖示。真正的 SVG 內容透過預設 slot 傳入。在實際專案中，與 AppIcon 元件配合使用，兩層職責分離：

AppIcon（業務層）：透過 inject-icons 建置腳本將 assets/icons/*.svg 注入到元件中，使用 v-if="name === '圖示名'" 決定渲染哪個 SVG，再將其透過 slot 交給 SwIcon。
SwIcon（框架層）：使用 :deep() 將 SVG 內部的 fill 和 stroke 統一改為 currentColor，實現顏色的 CSS 繼承控制。

基本用法

<!-- 業務層建議用法：透過 AppIcon 使用 inject-icons 注入的圖示 -->
<AppIcon name="home" />
<AppIcon name="user" :width="24" color="#3b82f6" />

<!-- 進階用法：直接向 SwIcon 傳入一次性內聯 SVG -->
<SwIcon name="custom" :width="32" color="#f59e0b">
  <svg viewBox="0 0 24 24"><path d="..." /></svg>
</SwIcon>

inject-icons 建置流程

在專案根目錄執行 pnpm inject-icons，腳本會讀取 app/assets/icons/ 下所有 *.svg 檔案，自動注入到 AppIcon.vue 元件的 ICONS:START / ICONS:END 標記區間中。

# 將 app/assets/icons/home.svg 注入為 <AppIcon name="home" />
pnpm inject-icons

# 之後即可在任意元件中使用
<AppIcon name="home" />
<AppIcon name="settings" :width="20" color="var(--primary)" />

尺寸與顏色

加载中...

預設寬高均為 1em，隨父元素字型大小自動縮放，無需額外指定即可與文字等比例排列。顏色預設繼承父元素的 color CSS 屬性。

屬性（Props）

名稱	類型	預設值	說明
`name`	`string`	—	圖示識別碼，原樣落到 `data-icon` 屬性上，方便從 DOM／截圖反查是哪個圖示。不參與渲染——圖示本體由 default slot 提供
`width`	`number \| string`	— （CSS fallback `1em`）	圖示寬度，傳數字時單位為 px，傳字串時為 CSS 值。不傳則不寫行內樣式，尺寸由 `--sw-icon-width` 的 CSS fallback 承擔
`height`	`number \| string`	`'1em'`	圖示高度，傳數字時單位為 px，傳字串時為 CSS 值
`color`	`string`	— （CSS fallback `currentColor`）	圖示顏色，任意 CSS 顏色值。同上，不傳則無行內樣式

插槽（Slots）

名稱	說明
`default`	SVG 內容，通常由 AppIcon 傳入

顏色繼承規則

SwIcon 使用 :deep() 將 SVG 內所有帶 fill 或 stroke 屬性的元素改為 currentColor，但 fill="none" 和 stroke="none"（透明路徑）不會被覆蓋。因此只需設定 color prop 或透過 CSS 設定父元素的 color 屬性即可控制整個圖示顏色。

<!-- 透過父元素 color 控制（繼承） -->
<p style="color: #ef4444;">
  <AppIcon name="warning" />  <!-- 自動繼承紅色 -->
  警告文字
</p>

<!-- 透過 color prop 單獨控制（不影響父元素） -->
<AppIcon name="star" color="#f59e0b" />

樣式訂製 Token

以下 CSS 變數可在業務端覆蓋（fallback 即預設值）：

變數	預設值	說明
`--sw-icon-color`	`currentcolor`	圖示顏色。預設繼承文字色，見「顏色繼承規則」
`--sw-icon-height`	`1em`	圖示高度。預設跟隨字級
`--sw-icon-width`	`1em`	圖示寬度。預設跟隨字級

注意事項

SwIcon 是圖示「容器」，不是圖示庫 —— 它只管尺寸（1em 跟隨字級）與顏色（currentColor），圖示內容由 slot 提供。業務端通常不直接寫 SwIcon：專案自有 SVG 寫 <AppIcon name="x" />（starter 的 AppIcon 內部就是 SwIcon 的封裝），UI 功能圖示直接用圖示庫元件（starter 用 @phosphor-icons/vue，如 <PhX />）——圖示庫元件自帶尺寸 / 顏色 prop，不需要再套 SwIcon。
多色 SVG 會被壓平成單色 —— 顏色繼承規則把所有 fill / stroke（none 除外）改寫為 currentColor，這對單色圖示是便利，但品牌 logo 等多色 SVG 放進來會丟失配色。多色資源改用 SwImage（fit="contain"）或直接內聯 <svg>。
預設 aria-hidden="true" —— 按「裝飾性圖示」處理，螢幕閱讀器會跳過。圖示單獨承載語意時（純圖示按鈕等），需在外層可互動元素上補 aria-label，而不是拿掉 aria-hidden。
算繪為 <span> 而非 <i> —— 避免與 iconfont / Font Awesome 等占用 <i> 的函式庫衝突；寫 CSS 選擇器時按 span.sw-icon 命中。
1em 預設值是 stylelint em 禁用規則的唯一例外 —— framework 全站禁 em 單位（巢狀複合難追蹤），SwIcon 的 1em 跟隨字級模式是明確豁免項，不要據此在別處用 em。