Comments and Naming

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/design/references/css/comments-and-naming.md
Description	Not specified

Source Content

Comments and Naming

• File header comment
• Section banners
• Comment the why, not the what
• Semantic class naming
• Semantic HTML pairing

Good comments and honest names are how the next reader (often you) edits CSS in seconds instead of minutes. Model the habit you are teaching: every example in this skill carries a header, banners, and a why-note where a rule bends.

File header comment

Every .css file opens with a block comment stating what the file owns and any load notes. This is the first thing a reader sees, so it answers “am I in the right file?” before they scroll.

/* ============================================================
 * card.css — Card component (BEM block: .card)
 * Owns: card surface, padding, header/body/footer slots.
 * Does NOT own: outer margins (layout's job), color values
 *   (tokens flip these — see tokens-and-theming).
 * Load: imported by the Card component only; not global.
 * ============================================================ */

State what the file owns and, just as usefully, what it does not own — that line stops people adding margins or hardcoded colors here. Note how the file is loaded (component-scoped vs global) so no one assumes global reach it does not have.

Section banners

Inside a file, separate concerns with banner comments. They give the eye a stopping point and make a long file scannable. Use one consistent banner style across the repo.

/* --- Block ---------------------------------------------- */
.card { padding: var(--space-4); }

/* --- Elements ------------------------------------------- */
.card__header { font-weight: var(--weight-bold); }
.card__body { color: var(--color-fg-muted); }

/* --- Modifiers ------------------------------------------ */
.card--compact { padding: var(--space-2); }

For BEM files, banner by Block / Elements / Modifiers — it mirrors the naming and the mental model. Keep banners short; they are signposts, not paragraphs.

Comment the why, not the what

The code already says what it does. A comment earns its place by explaining the why — and it becomes mandatory the moment a rule breaks a default rule of this skill. A justified asymmetric padding, a necessary !important, or a magic number with no obvious source each need a note saying why the exception is correct, or the next reader will “fix” it back.

Good versus noise

Good comment (explains the why)

/* Optical centering: the glyph sits high in its box, so we
 * pad bottom > top to make it look vertically centered.
 * Intentional asymmetry — do not normalize. */
.badge { padding-block: var(--space-1) calc(var(--space-1) + 1px); }

/* !important needed: third-party widget injects an inline
 * style we cannot reach any other way. Remove if the vendor
 * exposes a class hook (tracked: ISSUE-1421). */
.embed iframe { border: 0 !important; }

Noise comment (just restates the code)

/* set padding to space-4 */
.card { padding: var(--space-4); } /* <- adds nothing; delete it */

/* make text bold */
.title { font-weight: var(--weight-bold); } /* <- delete */

If a comment would read aloud the same as the line below it, delete the comment. If the line surprises a reader, write the why.

Semantic class naming

Name by role and meaning, never by appearance. A class named for what a thing is survives redesigns and theme changes; a class named for how it looks lies the moment the look changes.

Avoid (appearance)	Prefer (role)	Why
.red-box	.alert--danger	Color flips per theme; the role stays danger.
.mt-20	layout gap / stack primitive	Margins belong to layout — see spacing.
.float-left	.media__figure	Float is a technique, not a meaning.
.big-blue-button	.button--primary	Size and color are owned by the variant token.

Role names also read as a component API: .card, .site-nav__link, .alert--danger tell you the block, the part, and the state at a glance. This naming is BEM — the block/element/modifier structure and the rule that a variant is owned by exactly one system live in BEM and Tailwind.

Semantic HTML pairing

CSS rides on correct elements. Style the right element (or its role) and accessibility, keyboard support, and your selectors all come for free; reach for a styled <div> and you rebuild those by hand and usually miss some.

• <button> for actions, <a href> for navigation — never <div onClick> or <span onClick>.
• Landmarks for structure: <nav>, <main>, <header>, <footer>, <aside>.
• Lists for lists: <ul>/<ol> + <li>. Figures for media: <figure> + <figcaption>.
• Forms and labels: every input has a <label>; group with <fieldset>/<legend>.
• Headings (<h1>–<h6>) in order, no skipped levels.

Prefer styling the element or role over inventing a class when the element already carries the meaning. This keeps the markup honest and the stylesheet small.

/* Style the semantic element directly — no class needed. */
.site-nav a { color: var(--color-fg); }
.site-nav a[aria-current="page"] { color: var(--color-accent); }

/* Style by ARIA state, so visual and accessible state never drift. */
.accordion__trigger[aria-expanded="true"] { color: var(--color-accent); }

When a role-based selector already does the job, do not add a class to carry the same meaning twice — that is the same single-owner discipline as variants.