系統化的註解策略能:生成動態樣式指南、支援 IDE 大綱導航、降低新人認知負載、強制架構思維。
/*!
* components/_button.css
* Button 元件樣式 - 支援多變體、尺寸、狀態
*
* @version 2.1.0
* @author Frontend Team
* @updated 2024-01-15
* @dependencies _variables.css, _mixins.css
* @see https://design-system.example.com/components/button
* @todo 支援 loading 狀態動畫
*/
/* ===================================================================
MAIN STYLESHEET - 目錄導航
===================================================================
1. SETTINGS & TOKENS
1.1 Variables (colors, spacing, typography)
1.2 Mixins & Functions
2. GENERIC & RESET
2.1 Normalize
2.2 Box-sizing
3. ELEMENTS (Base styles)
3.1 Typography
3.2 Forms
3.3 Tables
4. OBJECTS (Layout patterns)
4.1 Container
4.2 Grid
4.3 Media
5. COMPONENTS (UI patterns)
5.1 Button
5.2 Card
5.3 Modal
5.4 Form Fields
6. UTILITIES (High specificity helpers)
6.1 Spacing
6.2 Visibility
6.3 Typography
7. PAGES (Page-specific overrides)
=================================================================== */
/* =BUTTON BASE ================================= */
.btn { ... }
/* =BUTTON VARIANTS ============================= */
.btn--primary { ... }
.btn--secondary { ... }
.btn--outline { ... }
.btn--ghost { ... }
/* =BUTTON SIZES ================================ */
.btn--sm { ... }
.btn--lg { ... }
.btn--xl { ... }
/* =BUTTON STATES =============================== */
.btn:hover { ... }
.btn:focus-visible { ... }
.btn:disabled { ... }
.btn[aria-busy="true"] { ... }
.modal {
/* @hack: iOS Safari fixed 定位在鍵盤彈出時錯位 */
position: fixed;
inset: 0;
/* @fixme: Safari 15.4 backdrop-filter 模糊邊緣 */
backdrop-filter: blur(8px);
/* @see: https://github.com/org/repo/issues/1234 */
z-index: var(--z-modal);
}
/* 狀態註解 */
.btn--primary {
/* @deprecated v3.0 改用 .btn--brand */
background: var(--color-primary);
}
| 標記 | 用途 | 處理方式 |
|---|---|---|
@todo | 計劃功能 | Issue 追蹤、Sprint 規劃 |
@fixme | 已知缺陷 | 優先修復、標註影響範圍 |
@hack | 瀏覽器 Hack | 標註瀏覽器版本、預計移除時間 |
@deprecated | 即將移除 | 版本號、替代方案、遷移指引 |
@see | 外部參考 | 設計稿、規格文檔、StackOverflow、MDN |
@requires | 依賴聲明 | CSS 變數、Mixins、HTML 結構 |
@warning | 副作用提醒 | 全域影響、效能風險、無障礙風險 |
=SECTION 錨點出現在大綱視圖@hack、@fixme 必須關聯 Issue 編號