為什麼需要命名規範?
- 降低認知負荷:一眼看出元素用途與關係
- 避免命名衝突:大型專案、多人協作、第三方庫共存
- 便於維護重構:搜尋、替換、刪除無殘留
- 支援自動化工具:Stylelint、CSS Modules、Tailwind JIT
業界主流命名方法論對比
BEM (Block Element Modifier) — 最廣泛採用
/* 區塊 */
.card { }
/* 元素:區塊內的組成部分 */
.card__title { }
.card__image { }
.card__footer { }
/* 修飾符:狀態或變體 */
.card--featured { }
.card__title--large { }
.card__image--rounded { }
/* HTML 結構 */
<article class="card card--featured">
<h2 class="card__title card__title--large">標題</h2>
<img class="card__image card__image--rounded" src="..." alt="">
<footer class="card__footer">底部</footer>
</article>
SMACSS (Scalable and Modular Architecture for CSS)
/* 五大類別前綴 */
.layout- /* 版面佈局:.l-container, .l-grid, .l-sidebar */
.module- /* 模組/元件:.module-card, .module-nav, .module-btn */
.state- /* 狀態:.is-active, .is-hidden, .is-loading, .has-error */
.theme- /* 主題:.theme-dark, .theme-high-contrast */
.util- /* 工具類:.u-clearfix, .u-visually-hidden, .u-text-center */
ITCSS (Inverted Triangle CSS) — 架構層級
/* 由寬泛到具體,優先權遞增 */
1. Settings /* 變數、配置:$color-primary, $breakpoint-md */
2. Tools /* 函數、Mixin:@mixin media-query() */
3. Generic /* Reset、Normalize、box-sizing */
4. Elements /* 裸標籤:h1, ul, a, table */
5. Objects /* 設計模式/佈局物件:.o-container, .o-grid, .o-media */
6. Components /* 具體 UI 元件:.c-card, .c-button, .c-modal */
7. Utilities /* 高優先權工具類:.u-hidden, .u-mt-4, .u-text-center */
語意化命名原則
✅ 好命名:描述「是什麼」,而非「長什麼樣」
| ❌ 表現型命名 | ✅ 語意型命名 | 理由 |
.red-btn | .btn-danger / .btn-primary | 顏色可能變,語意不變 |
.left-sidebar | .sidebar / .sidebar--secondary | 位置可能調換 |
.big-title | .heading--hero / .page-title | 尺寸會調整 |
.clearfix | .flow-root (現代 CSS) | 描述行為而非 Hack |
.col-4 | .grid__item--span-4 | 語意化網格系統 |
常見語意化命名詞彙表
| 類別 | 推薦詞彙 |
| 版面區塊 | header, footer, main, aside, section, container, wrapper, inner |
| 導航 | nav, menu, breadcrumb, pagination, tabs, steps |
| 內容元件 | card, article, post, entry, item, tile, panel, block |
| 表單 | form, field, input, label, select, checkbox, radio, button, group |
| 媒體 | media, image, video, audio, avatar, thumbnail, gallery, slider |
| 互動狀態 | active, hover, focus, disabled, loading, error, success, warning |
| 變體修飾 | primary, secondary, tertiary, outline, ghost, link, subtle, bold |
| 尺寸 | xs, sm, md, lg, xl, xxl / compact, comfortable, spacious |
CSS Modules / CSS-in-JS 時代的命名
/* CSS Modules: 自動生成哈希類名,源碼可用語意化命名 */
import styles from './Card.module.css';
<article class={styles.card}>
<h2 class={styles.title}>標題</h2>
</article>
/* 編譯後:.Card_card__a1b2c { } — 完全隔離,無衝突風險 */
自動化檢查配置
/* .stylelintrc.js */
module.exports = {
extends: ['stylelint-config-standard', 'stylelint-config-bem'],
rules: {
'selector-class-pattern': '^[a-z][a-z0-9]*(-[a-z0-9]+)*(__[a-z0-9]+(-[a-z0-9]+)*)?(--[a-z0-9]+(-[a-z0-9]+)*)?$',
'selector-id-pattern': '^[a-z][a-z0-9]*(-[a-z0-9]+)*$',
'custom-property-pattern': '^[a-z][a-z0-9]*(-[a-z0-9]+)*$',
}
};
遷移策略:舊專案漸進式改善
- 新增代碼嚴格遵循新規範
- 修改舊代碼時順手重命名 (Boy Scout Rule)
- 高風險/高頻修改模組優先重構
- 建立命名字典文檔,團隊共享
- 配置 CI 攔截不合規命名