CSS 無變量、無函數、無邏輯控制,註釋是**唯一**能傳達設計意圖、架構決策、副作用警告的載體。好的註釋能:
問題:想告訴開發者 `.product-page` 應用於 `
`,但不想寫 `body.product-page` 升高特定度。/*html*/.product-page { } /* 預期掛在 或 */
/*body*/.product-page { }
/*ol*/.breadcrumb { } /* 預期 */
/*p*/.intro { } /* 預期 */
/*ul*/.image-thumbs { } /* 預期
*/
原理:CSS 註釋 `/* */` 可出現在選擇器中間,被解析器忽略。瀏覽器看到的是 `.product-page`,開發者看到的是「預期掛在 html/body 上」。
優勢:零特定度成本、零運行時開銷、文檔與代碼同步。
在模塊/區塊頂部加入標籤,支援「搜索跳轉」導航:
/**
* ^navigation ^header ^global
*/
.site-header { }
/**
* ^grid ^layout ^sidebar
*/
.layout-sidebar { }
/**
* ^form ^input ^validation ^error
*/
.form-error { }
場景:基礎樣式在 `base.css`,主題擴展在 `theme.css`,物理位置分離但邏輯緊密關聯。
/* base.css */
/**
* @extends .btn--primary in theme.css
*/
.btn {
padding: 0.5rem 1rem;
border-radius: 4px;
font-weight: 600;
}
/* theme.css */
/**
* @extends .btn in base.css
*/
.btn--primary {
background: var(--color-primary);
color: white;
}
.complex-component {
/* @state: hover/focus/active/disabled/loading/error/success */
/* @side-effect: triggers reflow on .sidebar due to width change */
/* @todo: replace with container query when browser support > 95% */
/* @hack: fix Safari 15 flex gap bug, remove after v16 */
/* @deprecated: since v2.3, use .new-component instead */
}
標準化前綴讓工具可解析:
/* ===================================================================
Module: Media Object (媒體對象)
Desc: 圖文混排通用模式,支援圖片左/右/上/下、響應式堆疊
Author: @designer @frontend-lead
Date: 2024-01-15
Dependencies: utilities/spacing, utilities/typography
Variants: .media--reverse, .media--stack, .media--center
States: .media--loading, .media--error
Accessibility: img 必須有 alt,裝飾性圖片 alt=""
Performance: 圖片建議用 srcset + sizes,避免 layout shift
=================================================================== */
.media {
display: flex;
gap: var(--space-md);
align-items: flex-start;
}
.media__figure {
flex-shrink: 0;
}
.media__body {
flex: 1;
min-width: 0; /* 防止長內容撐破 flex 佈局 */
}
/* Variants */
.media--reverse { flex-direction: row-reverse; }
.media--stack { flex-direction: column; }
.media--center { align-items: center; }
/* States */
.media--loading .media__figure::after {
content: ""; display: block;
width: 100%; height: 100%;
background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
background-size: 200% 100%;
animation: shimmer 1.5s infinite;
}
CSS 註釋不是裝飾品,而是**架構文檔的第一現場**。準修飾選擇器文檔結構、代碼標籤構建索引、繼承標記連接分離邏輯、標準化標記可視化技術債、區塊文檔頭充當模塊 README。將這些技巧融入日常編碼,配合 Lint 強制,讓 CSS 代碼庫成為可讀、可維、可傳承的知識資產。