隨著專案規模增長,CSS 檔案動輒數千行。良好的註釋不只是「說明」,更是:
問題:.product-page 看不出適用於哪個元素(html? body? div?)
解法:在選擇器前加上**被註釋的類型選擇器**
/*html*/.product-page { }
/*ol*/.breadcrumb { }
/*p*/.intro { }
/*ul*/.image-thumbs { }
優點:不影響實際選擇器優先級、不增加特異性、可搜尋、可維護。
為樣式區塊打上可搜尋的功能標籤:
/**
* ^navigation ^lists
*/
.nav { }
/**
* ^grids ^lists ^tables
*/
.matrix { }
使用場景:
^lists 可定位所有列表相關樣式建立基礎樣式與擴充樣式的明確關聯:
/* base.css */
/**
* Extend `.foo` in theme.css
*/
.foo { color: #333; padding: 1rem; }
/* theme.css */
/**
* Extends `.foo` in base.css
*/
.bar { background: #f5f5f5; border-radius: 4px; }
價值:跨檔案追蹤樣式關係,重構時不易遺漏依賴。
/* ========================================
* Layout - Grid System
* ======================================== */
.card {
padding: 1rem; /* 內距對應 design token --space-md */
}
/* TODO: 統一斷點命名規範 */
/* HACK: 修正 Safari flex 最小寬度 bug */
/* FIXME: IE11 下 z-index 層疊異常 */
cssnano)/*
* @module Button
* @description 基礎按鈕元件,支援多種變體與狀態
* @author Team Frontend
* @version 2.1.0
* @tags ^buttons ^forms ^interactive
*/
.btn { /* ... */ }
/* @extend .btn in components/button/base.css */
.btn--primary { /* ... */ }