# 開始使用

安裝 Master Icons 並呈現第一個圖示。

<a id="install"></a>

## 安裝

安裝對應框架的套件。每個框架套件都會一併安裝共用的 `@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 以上。

<a id="first-icon"></a>

## 呈現圖示

以名稱匯入每個圖示。圖示元件名稱以 `Icon` 結尾。

```tsx
import { SearchIcon } from '@master/icons-react';

<SearchIcon size={20} label="Search" />
```

圖示以 `currentColor` 繪製，因此會採用周圍文字的顏色。未指定選項時，圖示呈現微圓角的 24 px 圖稿。在[圖庫](https://icons.master.co/tw/icons)可瀏覽所有名稱、複製匯入用法並下載 SVG 檔案。

<a id="entries"></a>

## 選擇入口

每個套件都有兩種入口，圖示名稱相同：

- **動態入口**，例如 `@master/icons-react`：每個圖示包含全部九份圖稿（三種光學尺寸乘以三種圓角），並接受 `size`、`corner` 與 `strokeWidth`。
- **固定入口**，例如 `@master/icons-react/20/soft`：每個圖示只包含一份圖稿。整個介面使用同一種尺寸與圓角時使用，體積更小。

```tsx
import { SearchIcon } from '@master/icons-react/20/soft';

<button aria-label="Search"><SearchIcon /></button>
```

支援 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)。

<a id="set-up-with-an-ai-agent"></a>

## 以 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。

完成後摘要：變更的檔案、安裝的套件、選定的預設值、替換或刻意保留的圖示、驗證結果，以及未在瀏覽器驗證的項目。
````

<a id="ai-agents"></a>

## 給 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)。

<a id="next"></a>

## 下一步

- 在[尺寸與圓角](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 與其他圖示庫的差異。
