How clear names express intent,
guide AI, and
keep components stable

_{—Part of CSS Primer for the AI Era — Structure}

This page explains how naming is not a cosmetic choice but a structural tool —
the way humans express intent so AI can style components safely and predictably.

A quiet mental model:

'Names' describe the shape.
'The shape' determines how style can flow.

• Good names make components predictable.
• Weak names make components fragile.

This page explores:

• how naming expresses structure,
• how structure supports style,
• and how humans guide AI by naming things
  with clarity and intent.

A name should describe:

• what something is
• what role it plays
• how it fits into the component
• what purpose it serves

A name should not describe:

• color
• size
• layout
• temporary hacks
• visual quirks

Examples of meaningful names:

• card_header
• nav_item
• form-field_label
• modal_footer

Examples of misleading names:

• blue-text
• left-box
• big-button
• rounded-div

A quiet principle:

Name things for their purpose,
not their appearance.

This keeps structure stable even when style changes.

A component is a shape —
a set of parts arranged with intention.

Naming makes that shape visible:

• card_header
• card_body
• card_footer

This tells AI:

• what belongs inside the card
• what parts exist
• how they relate
• what should be styled together
• what should not be touched

Without naming,
AI sees only a pile of divs.

A quiet truth:

AI cannot infer structure.
Humans must express it.

Clear names create 'boundaries'.
Examples:

• the card styles stay inside the card
• the nav styles stay inside the nav
• the modal styles stay inside the modal

Boundaries prevent:

• accidental overrides
• global leaks
• brittle selectors
• tangled dependencies

Boundaries make components:

• portable
• predictable
• maintainable
• safe to modify

A quiet rule:

If the boundary is clear,
the styles will be calm.

When names are clear:

• selectors become simple
• specificity stays low
• overrides become rare
• !important becomes unnecessary
• styles become predictable

When names are unclear:

• selectors become long
• specificity escalates
• overrides pile up
• !important becomes tempting
• styles become fragile

A quiet reminder:

Good names
prevent bad selectors.

AI does not “see” the whole codebase.
It only sees what we show it.

Clear naming helps AI:

• understand the component
• understand its parts
• understand variations
• propose safe changes
• avoid touching unrelated elements
• generate consistent CSS
• maintain architectural clarity

For example:

If we show AI:

<div class="card__header">

AI understands:

• this is part of a card
• this is the header
• this is not a global header
• styles should stay inside the card

Naming
gives AI the map.

When asking AI for help,
naming becomes a language.

Compare:

Weak request:

“Make the top part of the box bigger.”

Clear request:

“Increase the padding on .card__header.”

Or:

Weak request:

“Highlight the selected item.”

Clear request:

“Add a modifier class like nav__item--active 
and style it accordingly.”

A quiet truth:

Clear names
make clear prompts.

Naming is not about syntax.
It is about:

• clarity
• intent
• structure
• communication
• maintainability
• collaboration

Good naming:

• reduces cognitive load
• makes components self‑explanatory
• makes CSS predictable
• makes AI more reliable
• makes the system feel calm and coherent

Naming
is part of the design.

However, we do not need to follow 'strict naming conventions'
unless there is a reason for them.
But we always need to express structure clearly.

We can use:

• card-header
• card_header
• CardHeader
• data-part=“header”

The model remains the same:

• blocks
• elements
• modifiers
• variations
• boundaries

A quiet reminder:

The names can change.
The clarity must remain.

Naming is the foundation of style.
It tells CSS where to go.
It tells AI what belongs together.
It tells humans how the component is shaped.

A quiet closing thought:

'Structure' gives style its shape.
'Naming' gives structure its voice.
And when the names are clear,
the styles become effortless.

• Suggested Next Reading: Nested Components — When Structure Helps and When It Hurts

_{Tony de Araujo —New York | Lisbon}

• Top↑
• Back to Topic ↔
• Home←