# Master Icons
> 依光學尺寸繪製的介面圖示,支援 React、Vue、Svelte、Preact、Astro 與純 SVG。
# 開始使用
安裝 Master Icons 並呈現第一個圖示。
## 安裝
安裝對應框架的套件。每個框架套件都會一併安裝共用的 `@master/icons` 核心,並使用應用程式中既有的框架。
| 框架 | 套件 |
| --- | --- |
| React 18 或 19 | `@master/icons-react` |
| Vue 3.5 以上 | `@master/icons-vue` |
| Svelte 5 | `@master/icons-svelte` |
| Preact 11 | `@master/icons-preact` |
| Astro 7 | `@master/icons-astro` |
| 不使用框架 | `@master/icons` |
```sh
npm install @master/icons-react
```
使用其他套件管理工具時,以相同名稱執行 `bun add`、`pnpm add` 或 `yarn add`。只需安裝所用框架的套件,不需要其他框架套件。套件支援 Node.js 22 以上,Astro 套件則需要 Node.js 24 以上。
## 呈現圖示
以名稱匯入每個圖示。圖示元件名稱以 `Icon` 結尾。
```tsx
import { SearchIcon } from '@master/icons-react';
```
圖示以 `currentColor` 繪製,因此會採用周圍文字的顏色。未指定選項時,圖示呈現微圓角的 24 px 圖稿。在[圖庫](https://icons.master.co/tw/icons)可瀏覽所有名稱、複製匯入用法並下載 SVG 檔案。
## 選擇入口
每個套件都有兩種入口,圖示名稱相同:
- **動態入口**,例如 `@master/icons-react`:每個圖示包含全部九份圖稿(三種光學尺寸乘以三種圓角),並接受 `size`、`corner` 與 `strokeWidth`。
- **固定入口**,例如 `@master/icons-react/20/soft`:每個圖示只包含一份圖稿。整個介面使用同一種尺寸與圓角時使用,體積更小。
```tsx
import { SearchIcon } from '@master/icons-react/20/soft';
```
支援 tree shaking 的打包工具會移除未使用的圖示。接著請閱讀所用框架的頁面:[SVG 與 JavaScript](https://icons.master.co/tw/guide/svg.md)、[React](https://icons.master.co/tw/guide/react.md)、[Vue](https://icons.master.co/tw/guide/vue.md)、[Svelte](https://icons.master.co/tw/guide/svelte.md)、[Preact](https://icons.master.co/tw/guide/preact.md) 或 [Astro](https://icons.master.co/tw/guide/astro.md)。
## 以 AI agent 設定
Coding agent 可以替你完成設定。在應用程式根目錄啟動 agent,再貼上下方提示詞:它會先檢查專案,並在修改檔案前詢問框架套件、預設尺寸、圓角與線寬,以及既有圖示庫的處理方式。接著安裝套件、呈現第一個圖示並執行專案檢查。
**Set up Master Icons**
````text
你正在一個既有的 web 應用程式中工作。請完整設定 Master Icons。
文件:https://icons.master.co/tw/llms.txt,其中以 Markdown 連結每篇指南(請閱讀 getting-started、所選框架的頁面、optical-sizes、stroke-width 與 accessibility),以及已安裝套件的 README。安裝後依照 node_modules/@master/icons/skills/master-icons/SKILL.md 操作。
Master Icons 已發布至 npm:核心為 @master/icons,每個框架各有一個套件:@master/icons-react、@master/icons-vue、@master/icons-svelte、@master/icons-preact 與 @master/icons-astro。只安裝這些名稱,不要安裝名稱相似的套件。
修改前先檢查專案:套件管理工具與 lockfile、Node.js 版本、框架與建置工具(React、Vue、Svelte、Preact、Astro 或無框架)、目前使用的圖示庫及其匯入方式、dev/lint/build/test 指令,以及 AGENTS.md 等 agent 指引檔案。
修改前先問我以下問題並等待回答,不要自行決定:
- 接入方式:依偵測到的框架選擇套件,純 SVG 與 JavaScript 則用 @master/icons。只安裝一個套件。
- 預設值:光學尺寸(16、20 或 24;一般介面用 24,密集介面用 16 或 20)、圓角(sharp、soft 或 rounded;預設 soft),以及保留各母版的原生線寬或指定單一線寬(16 px 為 0.75–1.5、20 px 為 1–2、24 px 為 1.25–2.5,以 0.25 為級距)。
- 既有圖示:若專案已使用其他圖示庫,要保留它(預設)並只在新介面使用 Master Icons,還是替換我指名的圖示。絕不替換我未指名的圖示。
接著保守地導入 Master Icons:
1. 每個指令都在應用程式根目錄(package.json 所在處)以專案的套件管理工具執行,並從 npm 安裝選定的套件。
2. 以名稱匯入每個圖示。動態入口(import { SearchIcon } from '@master/icons-react')接受 size、corner 與 strokeWidth;固定入口如 '@master/icons-react/20/soft' 只含一個母版、體積更小。整個應用程式使用同一設定時優先使用固定入口。
3. 以原生尺寸呈現圖示。傳入 size 以選擇最接近的光學母版,不要用 CSS width 與 height 縮放圖示。strokeWidth 會選擇預先計算的幾何,因此絕不在 CSS 覆寫 stroke-width。
4. 保持無障礙:位於可見文字旁的圖示維持裝飾性;純圖示按鈕的無障礙名稱放在按鈕上;具意義的獨立圖示加上 label。
5. 若我選擇替換指名的圖示,將每個圖示對應到 node_modules/@master/icons/dist/catalog.json 中最接近的名稱,修改前先給我看對照表,保留每個控制項的無障礙名稱,並在已無任何程式碼匯入舊依賴後才移除它。
6. 保留既有架構與樣式,避免無關的重構。
7. 驗證:在可見頁面呈現 size 20 的 SearchIcon,確認它在淺色與深色模式下都以文字色繪製、呈微圓角。之後除非我要保留,否則移除它,並執行專案的 lint、build 與 tests。
完成後摘要:變更的檔案、安裝的套件、選定的預設值、替換或刻意保留的圖示、驗證結果,以及未在瀏覽器驗證的項目。
````
## 給 AI agent
有兩項資源能讓 coding agent 使用真實的圖示名稱,並遵守上述規則:
- **Agent skill。** `@master/icons` 內附 skill:`node_modules/@master/icons/skills/master-icons/SKILL.md`。將 `master-icons` 資料夾複製到 agent 的 skills 資料夾,例如 `.claude/skills` 或 `.agents/skills`。內容涵蓋套件、入口、尺寸、線寬與無障礙,並附有搜尋已安裝 catalog 的腳本,讓 agent 不會編造圖示名稱:`node node_modules/@master/icons/skills/master-icons/scripts/search.mjs search`。
- **llms.txt。** [/tw/llms.txt](https://icons.master.co/tw/llms.txt) 以 Markdown 列出每篇指南,[/tw/llms-full.txt](https://icons.master.co/tw/llms-full.txt) 則將全文合為一個檔案。每篇指南的網址加上 `.md` 即可取得 Markdown 版,例如 [/tw/guide/getting-started.md](https://icons.master.co/tw/guide/getting-started.md)。
## 下一步
- 在[尺寸與圓角](https://icons.master.co/tw/guide/optical-sizes.md)依可用空間選擇圖稿。
- 以[線寬](https://icons.master.co/tw/guide/stroke-width.md)調整線條粗細。
- 在[無障礙](https://icons.master.co/tw/guide/accessibility.md)為圖示與周圍控制項命名。
- 在[比較](https://icons.master.co/tw/guide/comparison.md)了解 Master Icons 與其他圖示庫的差異。
Source: https://icons.master.co/tw/guide/getting-started.md
---
# 下載
下載整組 SVG、安裝套件,或從 CDN 引用單一檔案。
## 套件
從 npm 安裝所用框架的套件,每個套件都會一併安裝共用的 `@master/icons` 核心。
| 用途 | 安裝 | 指南 |
| --- | --- | --- |
| SVG 與 JavaScript | `npm install @master/icons` | [SVG 與 JavaScript](https://icons.master.co/tw/guide/svg.md) |
| React | `npm install @master/icons-react` | [React](https://icons.master.co/tw/guide/react.md) |
| Vue | `npm install @master/icons-vue` | [Vue](https://icons.master.co/tw/guide/vue.md) |
| Svelte | `npm install @master/icons-svelte` | [Svelte](https://icons.master.co/tw/guide/svelte.md) |
| Preact | `npm install @master/icons-preact` | [Preact](https://icons.master.co/tw/guide/preact.md) |
| Astro | `npm install @master/icons-astro` | [Astro](https://icons.master.co/tw/guide/astro.md) |
## SVG 整組
每一組都是 ZIP 壓縮檔,收錄某一光學尺寸與圓角的全部圖示,採原生線寬。請選擇介面使用的尺寸與圓角:
| 尺寸 | 直角 | 微圓 | 圓潤 |
| --- | --- | --- | --- |
| 16 px | [sharp](https://github.com/master-co/icons/releases/latest/download/master-icons-16-sharp.zip) | [soft](https://github.com/master-co/icons/releases/latest/download/master-icons-16-soft.zip) | [rounded](https://github.com/master-co/icons/releases/latest/download/master-icons-16-rounded.zip) |
| 20 px | [sharp](https://github.com/master-co/icons/releases/latest/download/master-icons-20-sharp.zip) | [soft](https://github.com/master-co/icons/releases/latest/download/master-icons-20-soft.zip) | [rounded](https://github.com/master-co/icons/releases/latest/download/master-icons-20-rounded.zip) |
| 24 px | [sharp](https://github.com/master-co/icons/releases/latest/download/master-icons-24-sharp.zip) | [soft](https://github.com/master-co/icons/releases/latest/download/master-icons-24-soft.zip) | [rounded](https://github.com/master-co/icons/releases/latest/download/master-icons-24-rounded.zip) |
若要使用其他線寬,請下載該光學尺寸的壓縮檔。其中每種圓角與線寬各有一個資料夾,例如 `soft/stroke-2/search.svg`:
- [`master-icons-16-strokes.zip`](https://github.com/master-co/icons/releases/latest/download/master-icons-16-strokes.zip):16 px,線寬 0.75–1.5,含全部圓角
- [`master-icons-20-strokes.zip`](https://github.com/master-co/icons/releases/latest/download/master-icons-20-strokes.zip):20 px,線寬 1–2,含全部圓角
- [`master-icons-24-strokes.zip`](https://github.com/master-co/icons/releases/latest/download/master-icons-24-strokes.zip):24 px,線寬 1.25–2.5,含全部圓角
這些壓縮檔附在每次 [GitHub release](https://github.com/master-co/icons/releases) 中,以上連結一律提供最新版本。任何尺寸與線寬的單一檔案,可從[圖庫](https://icons.master.co/tw/icons)中各圖示的詳細資訊下載。
## 從 CDN 取得檔案
`@master/icons` 套件收錄所有原生 SVG 檔案,因此任何 npm CDN 都能依路徑提供:
```html
```
路徑為 `icons/{size}/{corner}/{name}.svg`。放在 `
` 中的 SVG 無法以 `currentColor` 採用文字顏色;需要時請內嵌標記,或改用元件。
## 授權
每個壓縮檔都附有 `LICENSE`、`THIRD_PARTY_NOTICES.md` 與 `licenses/` 資料夾,每個 SVG 檔案開頭也有各自的聲明。重新散布圖示時請保留這些檔案。品牌圖示仍是各自所有者的商標,僅供指稱其產品使用。請見[授權與來源聲明](https://icons.master.co/tw/guide/license.md)。
Source: https://icons.master.co/tw/guide/download.md
---
# 比較
Master Icons 與其他圖示庫的差異。
## 一覽
多數圖示庫只為每個圖示繪製一份圖稿再加以縮放。Master Icons 則為每個圖示繪製三種光學尺寸與三種圓角,並為每種支援的線寬重新繪製。它的圖示數量少於最大型的圖示庫,專注於儀表板、App 與網站等介面需求。
| 圖示庫 | 圖示數 | 繪製尺寸 | 風格 | 線條粗細 | 官方元件 | 授權 |
| --- | --- | --- | --- | --- | --- | --- |
| **Master Icons** | 946,含 107 個品牌項目 | 16、20 與 24 px | 直角、微圓與圓潤三種圓角 | 0.75–2.5,以 0.25 為級距重新繪製 | React、Vue、Svelte、Preact、Astro | MIT;部分圖稿保留各自聲明 |
| Lucide | 2,091 | 24 px | 線條 | `strokeWidth` 設定 SVG 線寬 | React、Vue、Svelte、Preact、Solid、Angular 等 | ISC |
| Heroicons | 324 | 24 px;實心另有 20 與 16 px | 線條與實心 | — | React、Vue | MIT |
| Phosphor | 1,512 | 單一圖稿 | 六種字重,含實心與雙色 | 六種固定字重 | React、Vue、Web Components 等 | MIT |
| Tabler Icons | 線條 5,491、實心 1,054 | 24 px | 線條與實心 | `stroke` 設定 SVG 線寬 | React、Vue、Svelte、Preact、Solid 等 | MIT |
| Material Symbols | 每種風格 7,890 | 光學尺寸軸 20–48 | Outlined、Rounded、Sharp;填色軸 | 字重軸 100–700 | —(字型與 SVG 檔案) | Apache 2.0 |
| Fluent UI System Icons | 約 3,000 | 最多八種尺寸,10–48 px | 一般與實心 | — | React | MIT |
| Font Awesome Free | 實心 2,001、一般 273、品牌 609 | 單一圖稿 | Solid、Regular 與 Brands | — | React、Vue、Angular | 圖示 CC BY 4.0、程式碼 MIT |
數量取自 2026 年 11 月已發布的 npm 套件:`lucide-static` 1.75、`heroicons` 2.2、`@phosphor-icons/core` 2.1、`@tabler/icons` 3.52、`@material-symbols/svg-400` 0.49、`@fluentui/svg-icons` 1.1.346 與 `@fortawesome/fontawesome-free` 7.3。這些數字會隨每次發布改變,最新數字請以各專案為準。
## 光學尺寸
把 24 px 圖稿縮小到 16 px,仍保有 24 px 的細節,這些細節會擠在一起而變得模糊。Master Icons 另行繪製 16 與 20 px 母版,在小尺寸需要時簡化或重新安排細節,並由 `size` 自動選擇最接近的母版。Fluent UI 與 Heroicons 也會重繪小尺寸,Material Symbols 則透過可變字型的光學尺寸軸調整;其他多數圖示庫只縮放單一圖稿。請見[尺寸與圓角](https://icons.master.co/tw/guide/optical-sizes.md)。
## 圓角
三種圓角風格會改變幾何與內部空間,而不只是 SVG 的線條接合方式,因此整個介面可以在精確與親和的外觀之間切換,而不必更改圖示名稱。Material Symbols 也以 Outlined、Rounded 與 Sharp 三個獨立系列提供類似的選擇。
## 線條粗細
提供線寬設定的圖示庫,通常只修改 SVG 的 `stroke-width` 屬性。線條因此原地加粗,填滿縫隙、挖空與細節之間的空間。Master Icons 預先重新繪製每種支援的線寬,並重新計算挖空與遮罩,因此較粗的圖示仍保有間距。Phosphor 與 Material Symbols 也刻意繪製各自的字重,分別以固定字重或字型軸提供。請見[線寬](https://icons.master.co/tw/guide/stroke-width.md)。
## 體積
從固定入口匯入的元件,例如 `@master/icons-react/24/soft` 的 `SearchIcon`,在經 minify 與 gzip 處理後的 bundle 中約增加 1.5 KB,已包含共用渲染器。動態入口因包含全部九組母版與其線寬,每個圖示約增加 2 KB。十個固定圖示約增加 3 KB。未使用的圖示會被 tree-shaking 移除。
安裝後的核心套件比多數圖示套件大:它包含全部九組母版的 SVG 檔案與預先計算的線寬,壓縮後約 20 MB。這只影響 `node_modules`,不影響應用程式的 bundle。
## 如何選擇
若介面經常使用小尺寸、需要在所有圖示間保持一致的圓角或線條粗細,或要在 React、Vue、Svelte、Preact 與 Astro 之間共用同一套圖示,請選擇 Master Icons。
以下情況可能更適合其他圖示庫:
- 需要涵蓋最多概念:Material Symbols 與 Tabler Icons 都有數千個圖示。
- 需要雙色等字重,或圖示字型:Phosphor 與 Material Symbols。
- 介面遵循 Microsoft Fluent 或 Material Design。
- 使用 Angular、Solid、React Native 或 Flutter:Lucide、Tabler Icons 與 Phosphor 有官方支援。
Master Icons 可以與其他圖示庫並存。先在新介面使用,再逐一替換既有圖示;[設定提示詞](https://icons.master.co/tw/guide/getting-started.md#set-up-with-an-ai-agent)會在修改前,先把既有圖示對應到最接近的名稱。
Source: https://icons.master.co/tw/guide/comparison.md
---
# SVG 與 JavaScript
不依賴框架即可使用圖示。
## SVG 檔案
可從[圖庫](https://icons.master.co/tw/icons)下載單一 SVG 檔案,或下載某一尺寸與圓角的全部圖示 ZIP 壓縮檔,內含授權文件。[安裝 `@master/icons`](https://icons.master.co/tw/guide/getting-started.md#install) 後,同樣的檔案位於套件子路徑 `@master/icons/svg/{size}/{corner}/{name}.svg`,例如 `@master/icons/svg/20/soft/search.svg`。
Inline SVG 使用 `currentColor`。透過 `
` 載入的外部 SVG 不會繼承周圍文字的顏色。
## JavaScript 渲染器
```js
import { Search, renderSvg } from '@master/icons';
const svg = renderSvg(Search, { size: 20, corner: 'soft', label: 'Search' });
```
`renderSvg` 回傳 SVG 標記,請搭配本套件可信任的圖示定義使用。圖示定義的名稱不含元件使用的 `Icon` 字尾。`size` 控制顯示尺寸;`opticalSize` 可明確指定 16、20 或 24,預設選擇最接近的光學圖稿。
| 選項 | 預設 | 行為 |
| --- | --- | --- |
| `size` | `24` | 顯示尺寸,須為有限正數 |
| `opticalSize` | `'auto'` | 16、20 或 24 母版;`auto` 取最接近者,18 與 22 取較大者 |
| `corner` | `'soft'` | `'sharp'`、`'soft'` 或 `'rounded'` |
| `strokeWidth` | 原生 | [線寬](https://icons.master.co/tw/guide/stroke-width.md),以原生單位與 0.25 為級距 |
| `color` | `'currentColor'` | 圖稿的顏色 |
| `label` | 無 | 未提供時 SVG 為 `aria-hidden`;提供時 SVG 加上 `role="img"` 與標籤 |
| `direction` | `'ltr'` | `'rtl'` 會鏡像具方向性的圖示 |
設定 `direction` 為 `rtl` 時,只有 `arrow-left`、`arrow-right`、`chevron-left`、`chevron-right`、`chevrons-left`、`chevrons-right`、`undo` 與 `redo` 會鏡像。
Source: https://icons.master.co/tw/guide/svg.md
---
# React
在 React 呈現動態或固定的光學圖稿。
## 動態圖示
React 是必要的 peer dependency。請在應用程式安裝 React 18 或 19,並[安裝 `@master/icons-react`](https://icons.master.co/tw/guide/getting-started.md#install)。
```tsx
import { SearchIcon } from '@master/icons-react';
```
動態入口會為每個匯入的圖示包含九種光學尺寸與圓角組合,以及各組合支援的線寬圖稿,與其他框架及 SVG 共用相同幾何。`size` 會選擇最接近的光學圖稿;`corner` 預設為 `soft`。
## 固定圖示
```tsx
import { SearchIcon } from '@master/icons-react/16/soft';
```
固定入口只包含一種光學尺寸與圓角。可將 `16/soft` 換成 `16`、`20`、`24` 與 `sharp`、`soft`、`rounded` 的任意組合。固定元件不接受 `corner` 或 `opticalSize`;`size` 只會縮放所選圖稿。在介面中使用一致的固定入口,即可統一視覺語言。
## 框架行為
元件接受標準 SVG props 與事件,並透過 `forwardRef` 將 ref 傳遞至 SVG 元素。元件可在伺服器與瀏覽器渲染,不需要僅限用戶端的包裝。
沒有標籤的圖示會視為裝飾。對有意義的圖示使用 `label`、`aria-label` 或 `aria-labelledby`,或替外層按鈕命名,詳見[無障礙](https://icons.master.co/tw/guide/accessibility.md)。
## 自訂線寬
動態與固定入口都接受 `strokeWidth`,以原生單位與 0.25 為級距。它會選用重新繪製的幾何,而非修改 SVG 的線寬屬性。
```tsx
import { SearchIcon } from '@master/icons-react/24/soft';
```
各光學尺寸支援的範圍與繪製方式,請見[線寬](https://icons.master.co/tw/guide/stroke-width.md)。
Source: https://icons.master.co/tw/guide/react.md
---
# Vue
在 Vue 呈現動態或固定的光學圖稿。
## 動態圖示
Vue 是必要的 peer dependency。請在應用程式安裝 Vue 3.5 以上的 3.x 版本,並[安裝 `@master/icons-vue`](https://icons.master.co/tw/guide/getting-started.md#install)。
```vue
```
動態入口會為每個匯入的圖示包含九種光學尺寸與圓角組合,以及各組合支援的線寬圖稿,與其他框架及 SVG 共用相同幾何。`size` 會選擇最接近的光學圖稿;`corner` 預設為 `soft`。
## 固定圖示
```vue
```
固定入口只包含一種光學尺寸與圓角。可將 `16/soft` 換成 `16`、`20`、`24` 與 `sharp`、`soft`、`rounded` 的任意組合。固定元件不接受 `corner` 或 `opticalSize`;`size` 只會縮放所選圖稿。
## 框架行為
在 template 中使用 `optical-size`,例如 `:optical-size="16"`。SVG 屬性與事件監聽器會傳給 SVG 根元素。圖示為函式元件,元件 ref 並不是 SVG 元素 ref。
沒有標籤的圖示會視為裝飾。對有意義的圖示使用 `label`、`aria-label` 或 `aria-labelledby`,或替外層按鈕命名,詳見[無障礙](https://icons.master.co/tw/guide/accessibility.md)。
## 自訂線寬
動態與固定入口都接受 `strokeWidth`,以原生單位與 0.25 為級距。它會選用重新繪製的幾何,而非修改 SVG 的線寬屬性。
```vue
```
各光學尺寸支援的範圍與繪製方式,請見[線寬](https://icons.master.co/tw/guide/stroke-width.md)。
Source: https://icons.master.co/tw/guide/vue.md
---
# Svelte
在 Svelte 呈現動態或固定的光學圖稿。
## 動態圖示
Svelte 是必要的 peer dependency。請在應用程式安裝 Svelte 5,並[安裝 `@master/icons-svelte`](https://icons.master.co/tw/guide/getting-started.md#install)。
```svelte
```
動態入口會為每個匯入的圖示包含九種光學尺寸與圓角組合,以及各組合支援的線寬圖稿,與其他框架及 SVG 共用相同幾何。`size` 會選擇最接近的光學圖稿;`corner` 預設為 `soft`。
## 固定圖示
```svelte
```
固定入口只包含一種光學尺寸與圓角。可將 `16/soft` 換成 `16`、`20`、`24` 與 `sharp`、`soft`、`rounded` 的任意組合。固定元件不接受 `corner` 或 `opticalSize`;`size` 只會縮放所選圖稿。
## 框架行為
原生 `.svelte` 原始碼由應用程式編譯為伺服器與瀏覽器版本。事件使用 Svelte 5 的 `onclick` 等 props;`bind:ref` 可取得 SVG 元素。修改 `size` 或 `corner` 會更新圖稿。
沒有標籤的圖示會視為裝飾。對有意義的圖示使用 `label`、`aria-label` 或 `aria-labelledby`,或替外層按鈕命名,詳見[無障礙](https://icons.master.co/tw/guide/accessibility.md)。
## 自訂線寬
動態與固定入口都接受 `strokeWidth`,以原生單位與 0.25 為級距。它會選用重新繪製的幾何,而非修改 SVG 的線寬屬性。
```svelte
```
各光學尺寸支援的範圍與繪製方式,請見[線寬](https://icons.master.co/tw/guide/stroke-width.md)。
Source: https://icons.master.co/tw/guide/svelte.md
---
# Preact
在 Preact 呈現動態或固定的光學圖稿。
## 動態圖示
Preact 是必要的 peer dependency。請在應用程式安裝 Preact 11,並[安裝 `@master/icons-preact`](https://icons.master.co/tw/guide/getting-started.md#install)。
```tsx
import { SearchIcon } from '@master/icons-preact';
```
動態入口會為每個匯入的圖示包含九種光學尺寸與圓角組合,以及各組合支援的線寬圖稿,與其他框架及 SVG 共用相同幾何。`size` 會選擇最接近的光學圖稿;`corner` 預設為 `soft`。
## 固定圖示
```tsx
import { SearchIcon } from '@master/icons-preact/16/soft';
```
固定入口只包含一種光學尺寸與圓角。可將 `16/soft` 換成 `16`、`20`、`24` 與 `sharp`、`soft`、`rounded` 的任意組合。固定元件不接受 `corner` 或 `opticalSize`;`size` 只會縮放所選圖稿。
## 框架行為
請使用應用程式的 Preact JSX 設定。元件接受 SVG props、事件處理函式與 SVG ref。此入口直接使用 Preact,不需要安裝 React。
沒有標籤的圖示會視為裝飾。對有意義的圖示使用 `label`、`aria-label` 或 `aria-labelledby`,或替外層按鈕命名,詳見[無障礙](https://icons.master.co/tw/guide/accessibility.md)。
## 自訂線寬
動態與固定入口都接受 `strokeWidth`,以原生單位與 0.25 為級距。它會選用重新繪製的幾何,而非修改 SVG 的線寬屬性。
```tsx
import { SearchIcon } from '@master/icons-preact/24/soft';
```
各光學尺寸支援的範圍與繪製方式,請見[線寬](https://icons.master.co/tw/guide/stroke-width.md)。
Source: https://icons.master.co/tw/guide/preact.md
---
# Astro
在 Astro 呈現動態或固定的光學圖稿。
## 動態圖示
Astro 是必要的 peer dependency。請在應用程式安裝 Astro 7,並[安裝 `@master/icons-astro`](https://icons.master.co/tw/guide/getting-started.md#install)。
```astro
---
import { SearchIcon } from '@master/icons-astro';
---
```
動態入口會為每個匯入的圖示包含九種光學尺寸與圓角組合,以及各組合支援的線寬圖稿,與其他框架及 SVG 共用相同幾何。`size` 會選擇最接近的光學圖稿;`corner` 預設為 `soft`。
## 固定圖示
```astro
---
import { SearchIcon } from '@master/icons-astro/16/soft';
---
```
固定入口只包含一種光學尺寸與圓角。可將 `16/soft` 換成 `16`、`20`、`24` 與 `sharp`、`soft`、`rounded` 的任意組合。固定元件不接受 `corner` 或 `opticalSize`;`size` 只會縮放所選圖稿。
## 框架行為
原生 `.astro` 元件會輸出 inline SVG,不需要瀏覽器端圖示 JavaScript,也不需要框架整合或 `client:*` 指令。支援 SVG 屬性、`class:list` 與預設 slot。Node.js 版本須符合 Astro 的要求。
沒有標籤的圖示會視為裝飾。對有意義的圖示使用 `label`、`aria-label` 或 `aria-labelledby`,或替外層按鈕命名,詳見[無障礙](https://icons.master.co/tw/guide/accessibility.md)。
## 自訂線寬
動態與固定入口都接受 `strokeWidth`,以原生單位與 0.25 為級距。它會選用重新繪製的幾何,而非修改 SVG 的線寬屬性。
```astro
---
import { SearchIcon } from '@master/icons-astro/24/soft';
---
```
各光學尺寸支援的範圍與繪製方式,請見[線寬](https://icons.master.co/tw/guide/stroke-width.md)。
Source: https://icons.master.co/tw/guide/astro.md
---
# 尺寸與圓角
依照可用空間選擇圖稿。
## 光學尺寸
每個圖示都有 16、20 與 24 像素的圖稿。小尺寸可簡化密集細節,並非只是縮小最大尺寸的圖稿。
預設顯示尺寸為 24。自動光學選擇會取最接近的母版;在 18 與 22 的邊界選擇較大的母版。CSS 寬高不會觸發光學選擇,建議使用原生 16、20 或 24 像素以呈現預期效果。
一般介面從 24 px 開始;工具列或表格等密集介面則選擇 16 或 20 px。更大的顯示尺寸會縮放 24 px 圖稿。
## 圓角風格
可選 `sharp`、`soft` 或 `rounded`,預設為 `soft`。這些風格會調整幾何與內部空間,而非只改變 SVG 的線條接合方式。自然曲線與刻意保留的平直細節,在不同風格間可能維持不變。
在[圖庫](https://icons.master.co/tw/icons)開啟圖示詳細資訊,即可比較全部九組母版。若也要調整線條粗細,請見[線寬](https://icons.master.co/tw/guide/stroke-width.md)。
Source: https://icons.master.co/tw/guide/optical-sizes.md
---
# 線寬
調整線條粗細,同時保留挖空與間距。
## 設定線寬
每個圖示都接受 `strokeWidth`:各框架套件的動態與固定入口,以及 JavaScript 渲染器皆可使用。
```tsx
import { SearchIcon } from '@master/icons-react/24/soft';
```
```js
import { Search, renderSvg } from '@master/icons';
const svg = renderSvg(Search, { size: 20, strokeWidth: 1.75 });
```
省略此選項即保留圖稿的原生線寬。在[圖庫](https://icons.master.co/tw/icons)中,線寬滑桿會在每個圖示上預覽所選線寬,複製的程式碼與下載檔案也會套用它。
## 範圍
線寬採用光學母版 viewBox 的原生單位,以 0.25 為級距。每個母版各有支援範圍:
| 光學尺寸 | 原生線寬 | 範圍 |
| --- | --- | --- |
| 16 px | 1.25 | 0.75–1.5 |
| 20 px | 1.5 | 1–2 |
| 24 px | 1.75 | 1.25–2.5 |
超出所選母版範圍的值會限制在上下限。非正數、非有限數,以及不是 0.25 倍數的值會拋出錯誤。
## 重新繪製的幾何
修改 SVG 的 `stroke-width` 屬性只會原地加粗線條,使縫隙、挖空與細節之間的空間被填滿。Master Icons 則預先繪製每種支援的線寬:挖空、遮罩與間隙都會依線寬重新計算,因此較粗的圖示仍保有間距。請勿以 CSS 覆寫 `stroke-width`。
顯示尺寸 `size` 會縮放整個圖稿,包括線寬。品牌標誌維持原始形狀,不受線寬影響;`brand-github-outline` 等線條版則支援線寬。
## 整組下載
每個光學尺寸各有一個 ZIP 壓縮檔,收錄全部圓角的每種支援線寬,例如 `master-icons-24-strokes.zip`,內含 `soft/stroke-2/` 等資料夾。其中的檔案附有與原生線寬整組相同的授權聲明。請見[下載](https://icons.master.co/tw/guide/download.md#sets)。
Source: https://icons.master.co/tw/guide/stroke-width.md
---
# 無障礙
讓圖示與周圍控制項具備清楚語意。
## 命名控制項
可見文字旁的圖示屬於裝飾。省略 `label`,渲染器便會設定 `aria-hidden="true"`。只有圖示的按鈕應在按鈕本身提供無障礙名稱。
```tsx
```
## 命名獨立圖示
圖示獨自傳達資訊時,請提供 `label`。渲染器會加入 `role="img"` 與無障礙標籤。
```tsx
```
不要只靠顏色傳達狀態。保留清楚的鍵盤焦點、足夠大的操作範圍,並以文字提供必要說明。
Source: https://icons.master.co/tw/guide/accessibility.md
---
# 授權與來源聲明
保留隨圖示交付的授權聲明。
## Master Icons
Master Icons 採用 [MIT 授權](https://icons.master.co/LICENSE.txt)開源。重新散布圖示時,請保留適用的著作權與授權聲明。
## 品牌圖示
`brand-` 系列包含 Simple Icons、官方品牌素材、Master 標誌與有紀錄的 Dcard 點陣轉向量稿。圖稿授權與程式碼授權分開記載:Vue 保留 CC-BY-NC-SA-4.0 與額外許可;JavaScript 和 GitHub Copilot 保留上游 MIT 聲明;Microsoft 與 OpenAI 素材保留各自條款。套件及下載的壓縮檔保留個別來源聲明,包括 `licenses/brand-additions.txt`。Dcard 使用已封存的 App 標誌;原規範列出 48 px 最小尺寸,因此較小的輸出是光學預覽,不宣稱符合該規範。品牌名稱與標誌屬於各自所有者;程式碼授權不授予商標權利。逐項來源與版本請見[第三方聲明](https://icons.master.co/THIRD_PARTY_NOTICES.md)。
## 改作來源
部分圖稿改作自其他開源圖示集的構造,包括 Lucide、Tabler、Phosphor、Hugeicons Free、Iconoir 與 Material Design Icons。每個改作圖示的上游 MIT、ISC 或 Apache 2.0 聲明都保留在其 SVG 檔案、套件與下載的壓縮檔中。每個圖示的確切來源請見[第三方聲明](https://icons.master.co/THIRD_PARTY_NOTICES.md)。
`teapot` 圖稿改作自 OpenMoji 表情符號的壺蓋。該圖稿及其修改採 CC BY-SA 4.0 授權,不適用 MIT 授權;其 SVG 與套件附有完整聲明。
獨立審稿工具另含上游比較圖稿。這些研究素材與 Master Icons 套件、正式網站分開,其原始授權隨研究檔案保留。
Source: https://icons.master.co/tw/guide/license.md