開始使用
安裝 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 |
npm install @master/icons-react使用其他套件管理工具時,以相同名稱執行 bun add、pnpm add 或 yarn add。只需安裝所用框架的套件,不需要其他框架套件。套件支援 Node.js 22 以上,Astro 套件則需要 Node.js 24 以上。
#呈現圖示
以名稱匯入每個圖示。圖示元件名稱以 Icon 結尾。
import { SearchIcon } from '@master/icons-react';<SearchIcon size={20} label="Search" />圖示以 currentColor 繪製,因此會採用周圍文字的顏色。未指定選項時,圖示呈現微圓角的 24 px 圖稿。在圖庫可瀏覽所有名稱、複製匯入用法並下載 SVG 檔案。
#選擇入口
每個套件都有兩種入口,圖示名稱相同:
- 動態入口,例如
@master/icons-react:每個圖示包含全部九份圖稿(三種光學尺寸乘以三種圓角),並接受size、corner與strokeWidth。 - 固定入口,例如
@master/icons-react/20/soft:每個圖示只包含一份圖稿。整個介面使用同一種尺寸與圓角時使用,體積更小。
import { SearchIcon } from '@master/icons-react/20/soft';<button aria-label="Search"><SearchIcon /></button>支援 tree shaking 的打包工具會移除未使用的圖示。接著請閱讀所用框架的頁面:SVG 與 JavaScript、React、Vue、Svelte、Preact 或 Astro。
#以 AI agent 設定
Coding agent 可以替你完成設定。在應用程式根目錄啟動 agent,再貼上下方提示詞:它會先檢查專案,並在修改檔案前詢問框架套件、預設尺寸、圓角與線寬,以及既有圖示庫的處理方式。接著安裝套件、呈現第一個圖示並執行專案檢查。
你正在一個既有的 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 以 Markdown 列出每篇指南,/tw/llms-full.txt 則將全文合為一個檔案。每篇指南的網址加上
.md即可取得 Markdown 版,例如 /tw/guide/getting-started.md。