優秀的 CSS 註釋不僅是說明,更是架構文檔,幫助團隊理解設計意圖、快速定位、維護擴展。
問題:避免過度限定選擇器(ul.nav),但想文檔化預期 HTML 結構。
解決:將類型選擇器註釋化,保留 class 選擇器:
/*html*/.page-header { } /* 預期用於 html 標籤 */
/*ol*/.breadcrumb { } /* 預期用於 ol 列表 */
/*p*/.lead { } /* 預期用於段落 */
/*ul*/.media-list { } /* 預期用於 ul 列表 */
.page-header)為組件/模塊打標籤,支援全局搜索跳轉:
/**
* ^navigation ^header ^global
*/
.site-header { }
/**
* ^grid ^layout ^responsive
*/
.grid { }
^,編輯器可直接搜索 ^navigation 定位所有導航相關代碼^component、^layout、^utility、^theme、^vendor解決基礎樣式與擴展樣式分離維護的關聯追蹤問題:
/**
* @extend .btn-primary in theme.css
*/
.btn {
padding: 8px 16px;
border-radius: 4px;
font-weight: 500;
}
/**
* @extends .btn in base.css
*/
.btn-primary {
background: #007bff;
color: #fff;
}
/* ===================================
Layout / Grid System
=================================== */
.btn {
/* @state hover - 背景亮化 10% */
/* @state active - 內陰影 + 下沉 1px */
/* @state disabled - opacity 0.6, not-allowed */
}
.fix-ie-flex {
display: flex;
/* [IE10-] 使用舊語法 */
display: -ms-flexbox;
}
/* TODO: 支援 RTL 佈局 */
/* FIXME: Safari 下 flex-gap 渲染異常 */
/* REVIEW: 此處 z-index 可能衝突 */
postcss-doc)// @ts-check 風格的 JSDoc 註釋支援 CSSCSS 編碼規範指南:避免過度約束、後代選擇器、合併聲明、格式化