按鈕到底叫 Btn、Button 還是 Action？開發維護的隱形痛點
「這顆按鈕在 Figma 叫 PrimaryAction，程式碼裡卻寫著 .btn-blue-v2，到底要改哪一個？」這是我們團隊在輔導企業官網改版與程式碼審查時，最常聽到的工程師嘆氣。許多團隊在專案初期為了求快，大家各寫各的，直到網站上線半年、功能持續疊加後才發現：改一個結帳按鈕的間距，竟然影響了全站五個不同頁面的表單排版。
UI 元件命名看起來只是寫程式碼時的小細節，但從商業營運的角度來看，它直接決定了跨部門溝通的摩擦成本與改版維護的報價高低。當設計師、行銷人員與前端工程師對同一個介面物件沒有共識，每次小幅度的 UI 調整就會演變成來回確認的災難，甚至因為命名重複污染全域樣式，導致線上轉換率無端受損。
在探索介面架構時，Smashing Magazine 創辦人 Vitaly Friedman 也曾深入探討介面語意化的結構問題。
延伸閱讀：A Practical Guide To Naming Things
為什麼隨性命名會讓專案後期成本翻倍
我們實測多個中大型企業專案的維護紀錄後發現，程式碼缺乏一致的 UI 元件命名規範，主要會引發三大營運痛點：
- 樣式覆蓋與命名衝突：命名太過寬鬆（例如直接使用
.card或.title），新功能一上線就意外覆蓋了舊有元件的樣式，造成排版跑版。 - 認知負擔與協作脫鉤：新加入的工程師無法從名稱判斷該元件的「功能」是什麼，只能不斷重複造輪子，寫出功能一模一樣但名稱略異的重複元件。
- 自動化與分析埋點混亂：當行銷團隊想要透過代碼追蹤使用者行為時，難以從混亂的 DOM 結構中精準定位目標元件。若想避免追蹤數據失真，可以參考伺服器端代碼閘道如何拯救行銷追蹤漏失的架構思維，從底層梳理數據流向。
[插入圖片：展示混亂命名的 CSS 程式碼與具備清晰語意結構的元件代碼對比畫面]
三層式語意架構：從意圖出發而非視覺外觀
許多人在命名元件時最常踩的坑，就是「以視覺外觀命名」。例如將警示方塊命名為 .red-box，結果三個月後品牌主視覺調性更新，警示顏色改為深橘色，這時工程師就陷入了要大費周章全域取代名稱、還是容忍程式碼指鹿為馬的兩難。
我們建議採用「意圖導向（Intent-driven）」的三層式命名架構：
1. 區塊層（Block / Scope）
定義元件所屬的獨立功能情境或介面區塊，表達「它是什麼」。例如：card（卡片）、navbar（導覽列）、modal（彈窗）。這個層級應該具備完全的獨立性，不依賴外部父層環境。
2. 元素層（Element）
定義區塊內部的組成部分，表達「它在區塊中的角色」。例如：card__header（卡片標頭）、card__content（卡片內文）、card__action（卡片操作區）。元素層必須依附於區塊，不能脫離區塊單獨存在。
3. 修飾層（Modifier / State）
定義區塊或元素的狀態、外觀變體或行為差異，表達「它目前的狀態或特徵」。例如：card--highlighted（高亮卡片）、button--loading（載入中按鈕）、is-active（啟用狀態）。
常見 UI 元件命名風格與適用情境對照表
實務開發中沒有單一放諸四海皆準的完美規則，關鍵在於團隊規模與維護成本的權衡。以下是我們在不同專案型態中最常評估的四種命名架構比較：
| 命名方法論 | 核心特點 | 主要優點 | 潛在限制與缺點 | 適用專案規模 |
|---|---|---|---|---|
| 標準 BEM（區塊__元素–修飾符） | 使用雙底線與雙連字號嚴格劃分層級 | 結構極其清晰，完全避免樣式污染，易於團隊理解 | class 名稱較長，對於小型靜態頁面稍微繁瑣 | 中大型企業官網、長期維運專案 |
| 語意化實用優先（Tailwind / Utility） | 透過預設 class 直接組合樣式 | 開發速度極快，不用為每個小樣式想名稱 | HTML 結構冗長，若無封裝元件維護成本高 | 敏捷新創、SaaS 儀表板、短檔期活動頁 |
| 模組化 CSS（CSS Modules） | 自動編譯出雜湊（Hash）後綴名稱 | 本質上根除命名衝突，完全封裝元件 | 除錯時樣式名稱可讀性較低，跨框架共用門檻高 | React / Vue 單頁應用與微前端架構 |
| 設計權杖對齊（Design Tokens） | 以功能意圖與層級作為變數名稱（如 color-action-primary） | 設計系統與程式碼命名完全同步，跨平台共用 | 初期架構規劃成本高，需要跨部門高度配合 | 多品牌跨國集團、成熟設計系統元件庫 |
[插入圖片：設計系統中 Figma 元件名稱與前端程式碼變數對應架構圖]
落地執行：建立團隊命名規範的四個實戰步驟
想讓設計與工程團隊真正落實一致的命名，光發布一份文件通常成效不彰。我們歸納出四個具體可執行的推動步驟：
步驟一：建立通用介面詞彙表（Ubiquitous Language）
在專案啟動時，先由設計主管與前端工程師開會，共同制定常用名詞清單。約定好全站所有「彈出式訊息」統一叫 Toast 還是 Snackbar；分頁按鈕統一叫 Pagination 還是 Pager。一旦詞彙確定，就嚴禁在 Figma 或程式碼中任意替換同義詞。
步驟二：定義布林值與狀態前綴詞
針對互動元件的動態狀態，強烈建議統一採用以 is- 或 has- 開頭的語意類名：
is-active：表示當前處於啟動或選中狀態。is-disabled：表示目前無法點擊或互動。is-loading：表示正在背景發送 API 請求。has-error：表示表單欄位驗證未通過。
當團隊需要針對表單進行轉換漏斗分析與驗證防呆時，規範化的狀態類名能大幅降低資料埋點難度。關於表單體驗的細節優化，可進一步參考WordPress表單流失率分析與轉換率優化全攻略中的實務檢測指標。
步驟三：規範修飾詞（Modifiers）的層級順序
當元件同時具備多種屬性時，團隊必須約定屬性的先後順序，例如：[元件名稱]--[尺寸]--[功能色彩]。這樣寫出來的 class 永遠會是 btn--lg--primary，而不會在另一個頁面變成 btn--primary--large，保持搜尋與全域替換時的高度一致性。
步驟四：透過 Linting 工具自動化檢驗
不要依賴人肉審查命名。在前端構建流程中加入 stylelint 與命名驗證外掛，只要有人提交了未遵循規範的 class 名稱（例如包含駝峰式大小寫或未定義的隨意縮寫），CI/CD 流程自動中斷並發出提醒，從工具面守護程式碼品質。
前端 UI 元件命名健康度自我檢查清單
在提交新頁面或審查現有網站程式碼時，請使用這份檢查清單快速掃描：
- 意圖檢驗：類名是否包含了具體顏色、具體像素尺寸（例如
.blue-button、.font-14）？若有，請改為功能性名稱（例如.btn--primary、.text-sm）。 - 階層深度：BEM 命名是否出現超過兩層的巢狀結構（例如
.card__header__title__link）？過深的命名代表元件職責過於龐大，應拆解為獨立的次元件。 - 共用詞彙：該元件的 class 名稱是否與 Figma 中的元件命名完全對應？
- 縮寫限制：是否使用了未在團隊文件中定義的縮寫（例如
.cnt代表 content、.nav-itm代表 item）？除非通用，否則優先使用完整單字。 - 狀態解耦：狀態類名是否獨立於樣式實現，只負責描述互動狀態？
常見問答集
為什麼不乾脆用自動生成的隨機雜湊名稱來避免命名爭議？
現代前端工具（如 CSS Modules 或 Styled Components）確實會自動編譯雜湊名稱，這能百分之百防止命名污染。但它並不能免除團隊的命名工作。工程師在寫原始碼檔案、React 元件名稱、Design Tokens 變數時，依然需要清晰的命名，否則新進成員打開專案依然看不懂架構，除錯時更會增加搜尋難度。
如果目前網站已經累積了大量舊程式碼，該如何著手重構？
千萬不要嘗試一次性全站大重構，那通常會演變成災難。合理的做法是「劃定新舊邊界」：先為新功能或即將大改版的獨立模組制定新規範；舊有模組維持現狀，只在日常維護修改到該模組時，依據「童子軍法則（離開時比抵達時更乾淨）」逐步遷移。
設計系統（Design System）中的命名該由設計師主導還是工程師決定？
命名必須是跨職能共識的產物。設計師通常對「介面視覺階層與使用情境」有直覺理解，而工程師更關注「可擴充性、程式碼重複使用率與繼承關係」。最佳做法是由資深設計師與前端架構師共同制定詞彙表，確保 Figma 與代碼庫雙向同步。
打造結構清晰的高效能企業官網
介面元件命名的嚴謹度，往往直接反映了企業數位資產的維護品質。雜亂的程式碼不僅拖慢團隊的新功能上線節奏，更會因為載入冗餘樣式而犧牲 Core Web Vitals 效能表現。如果您正在規劃企業官網改版，或發現現有網站架構難以擴充維護，歡迎與我們的技術專家聯繫，為您的網站進行全面的架構健檢與前端程式碼體檢，打造既具備良好使用者體驗又易於長期維護的高品質官網。
