元件庫是什麼？先釐清它和設計系統、素材庫的差別
元件庫是把可重複使用的 UI 或程式碼元件集中管理，讓團隊能搜尋、引用、更新與維護的共用系統。它不只是放檔案的資料夾，也不等於完整設計系統；重點在於讓元件可以被正確使用，並在跨專案時保持一致。
元件庫的基本定義
對產品團隊來說，元件庫通常包含按鈕、輸入框、卡片、導覽列、表單欄位、提示訊息、彈窗等共用元件。設計端可能以 Figma library 管理 Main Component、Instance 與 Variants，開發端則可能以 React component、Vue component 或 Flutter widget 管理程式碼元件庫。
我會建議先把元件庫視為「共用規格」，再決定工具。工具換了，命名、分類、文件與維護規則仍然會留下來。
元件庫、設計系統、素材庫差在哪
| 項目 | 主要內容 | 團隊用途 |
|---|---|---|
| 元件庫 | 可重複使用的 UI 元件或程式碼元件 | 降低重複製作，維持跨專案一致性 |
| 設計系統 | 品牌、設計原則、design token、元件、內容規範與流程 | 建立產品體驗與協作規則 |
| 素材庫 | 圖示、圖片、插畫、範本、品牌檔案 | 提供可取用的視覺素材 |
UI 元件庫、前端元件庫、低程式碼元件庫的差異
設計元件庫偏向定義畫面規格，例如狀態、尺寸、間距、變體與使用情境。程式碼元件庫偏向可執行與可測試，例如 props、CSS variables、theme config、可及性與版本管理。Power Apps Component Library 這類低程式碼平台元件庫，則偏向在平台內重複使用控制項與邏輯。
三者可以互補，但不能混成同一份文件處理。設計師需要知道元件怎麼用，工程師需要知道 props 怎麼接，PM 需要知道誰能改、何時發布、影響哪些專案。
什麼情況適合建立元件庫？建立前先做盤點
適合做元件庫建立的時機，是同一類元件已經在多個畫面或專案重複出現，且團隊開始因命名、樣式、狀態或維護方式不同而增加溝通成本。還沒有重複使用需求時，先整理規則比急著建庫更實際。
值得抽成元件庫的 5 種訊號
- 同一種按鈕、卡片、表單欄位在多個專案反覆出現。
- 設計稿中有相似元件，但尺寸、色彩、狀態不一致。
- 工程端重複實作相同 UI，且每次都要重新確認規格。
- 新成員找不到該用哪個元件，只能複製舊畫面。
- 產品已有多個頁面或模組，未來會持續擴充。
暫時不該放進元件庫的元件
只出現一次、仍在大量驗證、依賴單一活動頁、規格尚未穩定的元件，不適合太早納入正式元件庫。過早抽象會讓元件庫變成限制，而不是效率工具。
一個實務判斷是：如果團隊還不能說清楚它的用途、變體、狀態與不可使用情境，就先放在候選區，不要直接標成正式元件。
元件成熟度：草稿、候選、正式、棄用
| 成熟度 | 狀態說明 | 建議處理 |
|---|---|---|
| 草稿 | 正在探索，規格未穩定 | 只供特定專案使用 |
| 候選 | 可能重複使用，但還缺文件或測試 | 限制使用範圍，補齊規格 |
| 正式 | 已確認用途、狀態、owner 與版本 | 可跨專案引用 |
| 棄用 | 不再建議新專案使用 | 提供替代元件與 migration guide |
元件庫建立流程：從盤點到發布的 7 個步驟
元件庫建立應從盤點開始，再進入抽取、分類、命名、補狀態、文件化、測試與發布。順序很重要，因為沒有盤點就命名，容易留下個人習慣；沒有文件就發布，團隊仍然會用錯。
Step 1 盤點現有畫面與重複元件
先從已上線產品、設計稿與前端頁面盤點，不要只看最新專案。把重複出現的按鈕、欄位、卡片、導覽、提示、表格列出來，標記它們出現在哪些頁面、有哪些差異、是否有互動狀態。
Step 2 抽出可重複使用的主元件
主元件應該代表穩定規格，而不是某個頁面的複製品。若一個卡片元件只因文案長短不同而變化，可以抽成同一個元件；若資訊架構完全不同，就不該硬合併。
Step 3 設定分類、命名與屬性
分類處理「放在哪裡」，命名處理「叫什麼」，屬性處理「怎麼被搜尋與維護」。這一步要一起做，否則會出現資料夾看似整齊，但搜尋不到元件的問題。
Step 4 補齊狀態、尺寸與變體
常見狀態包含 default、hover、focus、disabled、error、loading。尺寸可能有 small、medium、large。變體則可能對應 primary、secondary、danger、ghost 等語意用途。缺狀態的元件上線後通常會被各專案自行補洞，最後變成多個版本。
Step 5 撰寫元件文件與使用規則
每個正式元件至少要寫用途、適用情境、不適用情境、狀態、內容規則、可及性注意事項、開發對應與變更紀錄。文件不需要一開始就很長，但要足以讓不在原專案的人正確使用。
Step 6 測試可及性、響應式與一致性
元件庫不只要看起來一致，也要在鍵盤操作、螢幕閱讀器、不同裝置寬度與互動狀態下可用。設計端可以檢查狀態是否完整，工程端則應補上可及性與視覺回歸測試。
Step 7 發布、通知與追蹤使用情況
發布時要說明新增了哪些元件、修改了哪些規則、是否有破壞性變更、哪些專案需要跟進。後續可以追蹤 Figma library 使用量、程式碼引用次數、issue 類型與棄用元件殘留情況。
元件命名規範怎麼訂？用階層、語意與狀態命名
元件命名規範應該先描述元件用途，再補上變體、狀態與尺寸。好的命名能讓設計師找得到、工程師接得上、PM 看得懂影響範圍；不要用顏色、個人縮寫或臨時版本當主要名稱。
命名應該先描述用途，而不是視覺外觀
「Primary Button」比「Blue Button」穩定，因為藍色可能因品牌更新而改變，但主要行動的語意不會隨便變。元件命名規範的第一個原則，是把名稱綁在用途與語意上，而不是當下的視覺樣式。
建議格式：類型 / 用途 / 變體 / 狀態 / 尺寸
| 欄位 | 用途 | 範例 |
|---|---|---|
| 類型 | 說明元件大類 | Button、Input、Card、Modal |
| 用途 | 說明使用情境 | Submit、Search、Product、Confirm |
| 變體 | 說明語意層級 | Primary、Secondary、Danger |
| 狀態 | 說明互動狀態 | Default、Hover、Disabled、Error |
| 尺寸 | 說明規格大小 | Small、Medium、Large |
Figma 元件命名範例
Figma 可用階層式命名，例如 Button/Primary/Default/Medium、Input/Search/Error/Large、Card/Product/Default。這種命名方式能讓 library 面板自動形成群組，也方便設計師從大類一路縮小到可用變體。
前端 component 命名範例
前端 component 建議使用語意清楚的 PascalCase，例如 PrimaryButton、SearchInput、ProductCard、ConfirmModal。Props 則對應設計端變體，例如 variant="primary"、size="md"、state="loading"。命名不一定要完全複製 Figma，但語意要能對齊。
常見錯誤：顏色命名、版本命名、個人習慣命名
- 用 BlueButton、RedTag 命名，品牌改版後名稱失準。
- 用 ButtonNew、ButtonFinal、ButtonV3 命名，沒有人知道差異。
- 用 AliceCard、PMBanner 命名，離開原情境後不可維護。
- 同一元件在設計端叫 CTA，在程式碼端叫 MainAction，文件又叫主要按鈕。
元件分類：資料夾、標籤與欄位篩選怎麼搭配
元件分類不能只靠資料夾，因為元件常同時具有平台、狀態、owner、版本與使用情境。比較穩定的做法，是用資料夾管理大類，用標籤與 metadata 管理多重屬性，再用穩定 ID 維持跨工具對應。
資料夾適合放「大類」，標籤適合放「多重屬性」
資料夾適合放 Actions、Forms、Navigation、Feedback、Data Display 這類大分類。標籤適合標記 mobile、desktop、checkout、admin、deprecated、accessibility-reviewed 這類多重屬性。
為每個元件建立穩定識別碼
穩定 ID 是元件在不同工具之間的共同識別。例如 button.primary.submit 可以同時出現在 Figma 文件、Storybook、程式碼元件、設計規範與 changelog。名稱可以微調，ID 則應避免頻繁變更。
很多團隊失控的原因不是元件做太少，而是找不到同一個元件在不同系統中的對應關係。
建議欄位：owner、狀態、平台、版本、可用情境
| 欄位 | 用途 | 範例 |
|---|---|---|
| owner | 確認誰負責維護與審核 | Design System Team、Frontend Chapter |
| 狀態 | 判斷能否正式使用 | draft、candidate、stable、deprecated |
| 平台 | 標記可用範圍 | Web、iOS、Android、Admin |
| 版本 | 追蹤變更 | 1.2.0、2026.05 |
| 可用情境 | 降低誤用 | 表單送出、危險操作確認、商品列表 |
用主元件、實例與變體管理 UI 狀態
設計元件庫應用主元件管理標準，用實例承接頁面使用情境，用變體管理狀態、尺寸與語意用途。這樣能減少重複元件，也能讓設計稿更新時保持一致。
主元件負責標準，實例負責使用場景
Main Component 應該放標準結構，例如按鈕的高度、內距、字級、圓角、icon 位置與互動狀態。Instance 則放在實際畫面中，調整文字、內容或允許的屬性。
變體應該對應狀態、尺寸與語意用途
Variants 適合管理 primary、secondary、danger、disabled、loading、small、medium、large 這類可預期差異。若差異會影響使用語意，就應該寫進變體規則；若只是單一頁面的特殊排版，通常不該升級成正式變體。
不要為每個微小差異建立新元件
元件庫最怕看起來很完整，實際上每個元件只解決一個頁面。若 Button/Primary、Button/Main、Button/CTA 其實是同一用途，就應合併語意。反過來，若兩個卡片承載的資訊決策完全不同，即使外觀接近，也不一定要合併。
從設計元件庫到程式碼元件庫：如何保持同步
設計開發同步要靠共同語意，而不是靠人工口頭提醒。Figma variants 應對應 component props，design token 應對應 CSS variables 或 theme config，Storybook 則作為設計、工程與產品都能檢查的共同文件。
Figma variants 如何對應 component props
| 設計端 | 程式碼端 | 同步重點 |
|---|---|---|
| Variant: primary | variant="primary" | 語意一致，避免只用顏色對應 |
| Size: medium | size="md" | 尺寸命名需有對照表 |
| State: loading | loading=true | 互動狀態需包含可及性行為 |
| Disabled | disabled=true | 需同時處理樣式與不可操作狀態 |
Design tokens 如何對應 CSS variables 或 theme config
Design token 用來描述色彩、字級、間距、陰影、圓角等基礎值。設計端可用 token 命名管理樣式，工程端可轉成 CSS variables、theme config 或平台樣式設定。若 token 名稱不穩定，元件命名規範再漂亮也會被樣式例外拖垮。
Storybook 或文件站作為共同語言
Storybook 不是唯一選擇，但它很適合展示程式碼元件庫的狀態、props、互動與文件。PM 可以確認元件是否符合情境，設計師可以比對設計稿，工程師可以檢查 props 與行為。這種共同檢查點，比單靠設計交付檔可靠。
元件文件應該寫什麼？讓團隊知道何時該用、何時不該用
元件文件至少要說明用途、適用情境、不適用情境、狀態、變體、內容規則、可及性與開發對應。文件的目標不是把元件講得很漂亮，而是讓團隊少問一次、少用錯一次。
每個元件至少要有的 8 個欄位
| 欄位 | 應回答的問題 |
|---|---|
| 元件名稱與穩定 ID | 這是哪一個元件？跨工具怎麼對應？ |
| 用途 | 它解決什麼介面需求？ |
| 適用情境 | 哪些頁面或任務可以使用？ |
| 不適用情境 | 何時應改用其他元件？ |
| 狀態與變體 | 有哪些互動與尺寸規格？ |
| 內容規則 | 文字、icon、錯誤訊息要怎麼放？ |
| 可及性 | 鍵盤、焦點、對比與語意標籤是否完整？ |
| 開發對應 | 對應哪個 component、props 與版本？ |
正確用法與錯誤用法都要寫
只寫正確用法，通常不足以阻止誤用。文件應明確列出「不要把 danger button 用在一般送出」、「不要用 toast 承載需要使用者決策的資訊」、「不要把表格卡片拿去做行銷版位」這類限制。
可及性與互動狀態不可省略
按鈕是否可用鍵盤操作、輸入錯誤是否被螢幕閱讀器讀到、焦點樣式是否清楚、disabled 狀態是否還能被誤點，這些都要進文件。可及性不是最後補的項目，它會影響元件本身的設計與程式碼。
元件庫治理：新增、修改、棄用與版本發布
元件庫治理是規定誰能新增、誰要審核、修改前如何確認影響範圍、棄用時怎麼提供替代方案，以及版本發布如何記錄。沒有治理，元件庫很快會回到各做各的狀態。
誰可以新增元件？誰負責審核？
新增元件不一定只能由設計系統團隊提出，但每個正式元件都應有 owner。小團隊可以用一位設計負責人加一位前端負責人共同審核；成熟團隊則可建立固定 review 節奏。
修改元件前要先確認影響範圍
修改正式元件前，先確認它被哪些畫面、專案或套件版本使用。視覺微調可能影響產品辨識，props 調整可能造成破壞性變更，token 修改則可能牽動大量元件。
棄用元件要提供替代方案與 migration guide
棄用不等於刪除。標記 deprecated 後，要說明替代元件、差異、遷移步驟與建議完成時間。沒有 migration guide 的棄用流程，通常只會讓新舊元件長期並存。
版本發布要附變更紀錄
| 變更類型 | 紀錄內容 | 是否需通知 |
|---|---|---|
| 新增 | 元件用途、狀態、使用方式 | 需要 |
| 修正 | 修正內容與影響範圍 | 視影響程度 |
| 破壞性變更 | 受影響元件、替代方式、遷移步驟 | 必須 |
| 棄用 | 棄用原因、替代元件、期限 | 必須 |
元件庫品質檢查：不要只看畫面像不像
元件庫品質檢查應涵蓋可及性、響應式、互動狀態、視覺回歸測試、單元測試與 token 一致性。只看畫面像不像，很容易漏掉鍵盤操作、狀態缺失與跨裝置問題。
可及性檢查
- 互動元件是否可用鍵盤操作。
- 焦點狀態是否清楚可見。
- 文字與背景對比是否足夠。
- 錯誤訊息是否能被輔助工具辨識。
- icon-only button 是否有可讀名稱。
響應式與互動狀態檢查
元件要在手機、平板、桌機與容器寬度變化下都能維持結構。表單錯誤、loading、hover、focus、disabled、empty state 也要一起檢查。台灣產品團隊常忽略後台與行動版的同一元件差異，這會在維護期放大成本。
視覺回歸與單元測試
視覺回歸測試用來檢查 UI 是否被非預期改動，單元測試則檢查 props、事件、狀態與輸出是否正確。小團隊可以先從高使用量元件開始，例如 Button、Input、Modal、Table，不必一開始追求全部覆蓋。
Token 一致性檢查
Token 一致性檢查要確認元件是否使用正式色彩、字級、間距與圓角，而不是寫死臨時值。若設計元件庫和程式碼元件庫都依賴同一組 design token，後續改版會穩定很多。
元件庫建立能自動化嗎？
元件庫建立可以部分自動化，例如文件產生、changelog、測試、使用量追蹤與欄位同步。但命名原則、抽象邊界、元件是否值得共用，仍需要人做判斷。
可自動化的項目
- 從程式碼註解或 props 產生 component documentation。
- 從版本提交或 PR 產生 changelog 草稿。
- 在 CI 中執行可及性、單元測試與視覺回歸測試。
- 追蹤元件被哪些專案引用。
- 同步 metadata、owner、版本與 deprecated 狀態。
不建議過早自動化的項目
不要太早自動判斷哪些元件應該合併、拆分或棄用。這些決策需要理解產品情境、使用者任務與團隊維護能力。自動化能幫忙發現訊號，但不應取代 owner 的判斷。
小團隊的最低自動化配置
小團隊可先做三件事：用固定模板寫元件文件、用 changelog 記錄每次版本變更、讓重要元件有基本測試。等元件量與跨專案需求增加，再導入 Storybook、使用量追蹤與 token 檢查。
常見失敗原因：為什麼元件庫建完沒人用？
元件庫建完沒人用，通常不是工具問題，而是分類、命名、owner、文件、版本與設計開發同步沒有處理好。元件庫若讓團隊找不到、用不對、改不了，就會被舊習慣取代。
元件太多但沒有分類
元件越多，越不能只靠人記憶。沒有資料夾、標籤、metadata 與穩定 ID，成員會直接複製最近看過的元件。修正方式是先合併重複項，再補上大類與可搜尋欄位。
命名看得懂，但找不到
有些命名在原專案內看得懂，跨團隊就失效。例如 PromoCard、InfoBlock、NewModal 都缺少清楚用途。元件命名規範應和搜尋習慣一起設計，讓使用者能用任務、類型、狀態找到元件。
沒有 owner，沒人敢改
沒有 owner 的元件會出現兩種結果：沒人敢修改，或每個人都自行修改。兩者都會降低信任。正式元件至少要有設計 owner、開發 owner 或共同維護窗口。
設計端和開發端長期不同步
若 Figma 顯示一套狀態，程式碼卻只有部分 props，團隊很快會失去信任。設計開發同步要靠 token、props、Storybook、版本與變更紀錄串起來。元件庫建立的真正成果，是讓元件找得到、用得對、改得動、能維護。
元件庫和設計系統差在哪？
元件庫是設計系統的一部分，主要管理可重複使用的元件。設計系統範圍更大，還包含品牌原則、design token、內容規範、互動原則與治理流程。若團隊規模還小，可以先做元件庫建立，再逐步補成完整設計系統。
小團隊需要建立元件庫嗎？
需要，但不一定要做得很重。小團隊可以先整理最常用的按鈕、表單、卡片與導覽，建立基本元件命名規範、文件模板與 owner。等跨專案使用變多，再擴充治理與自動化。
元件庫要先從 Figma 做，還是先從程式碼做？
如果問題主要在設計稿重複與視覺不一致，可以先從 Figma library 開始。如果問題主要在前端重複實作與版本維護，可以先從程式碼元件庫開始。最理想的做法，是兩邊用相同語意、token 與版本規則逐步對齊。
元件命名可以用中文嗎？
設計文件與團隊說明可以用中文，尤其是使用情境與限制。但 Figma component、React component、Vue component 與 token 名稱通常建議用英文，方便跨工具、跨程式碼與未來維護。重點是建立一致對照，而不是中英文混用到無法搜尋。
什麼元件不適合放進元件庫？
只用一次、仍在驗證、依賴單一活動頁、規格常改、沒有明確用途的元件，不適合直接放入正式元件庫。可以先放在草稿或候選狀態，等重複使用需求與規格穩定後再升級。
元件庫可以管理替代元件或替代版本嗎？
可以，而且建議要管理。當元件被棄用時，文件應標出替代元件、差異、遷移方式與版本期限。這能避免團隊同時使用新舊元件，也能讓專案有時間逐步調整。
元件太多時要怎麼整理？
先找出重複元件與低使用量元件，再用大類、標籤、metadata 與穩定 ID 重新整理。不要只靠改資料夾名稱，因為團隊通常是用用途、狀態、平台與情境來搜尋元件。
如何避免新舊元件混用？
要有清楚的 deprecated 標記、替代元件、migration guide 與版本發布紀錄。設計端可以在元件名稱或文件中標示棄用，工程端則可用警告、lint 規則或文件站提醒減少誤用。
Storybook 是元件庫嗎？
Storybook 本身比較像程式碼元件的展示與文件環境，不等於完整元件庫。它可以展示元件狀態、props、互動與範例，因此常被用來支援程式碼元件庫與設計開發同步。
元件庫多久應該檢查一次？
固定產品團隊可每月檢查候選元件、棄用元件與高使用量元件；大型改版或跨專案發布前，應做額外檢查。檢查重點包含命名、文件、owner、版本、可及性、token 一致性與使用情況。
Power Apps component library 和設計元件庫差在哪？
Power Apps component library 是低程式碼平台中的共用元件機制，偏向在平台內重複使用控制項與邏輯。設計元件庫則偏向管理 UI 規格、狀態、變體與使用規則。兩者都需要命名、分類與維護，但工具範圍不同。
元件庫一定要自己開發平台嗎？
不一定。多數團隊可以用 Figma library、Storybook、文件站、套件管理工具與表格先建立可維護流程。真正需要自建平台的情況，通常是元件量大、跨產品線多、metadata 與權限流程已經超出一般工具能處理的範圍。