CSS components that another person can maintain
By Gyata Tabiri · Revised October 30, 2026
A component should make the next piece of work easier to produce. I look for a clear boundary around what stays consistent, what can vary, and what another developer needs to know before making a change.
Find a real pattern
A card, form field, or navigation item is a candidate when its behavior and purpose recur. Begin with a real instance and a second use. Comparing those cases reveals what belongs in the shared component and what is only a page-specific choice.
Make states explicit
Consider focus, hover, error, disabled, and expanded states where they apply. Explain which element owns a state and how it changes. Consistent naming helps a maintainer see the relationship without needing to reconstruct the original page.
Keep exceptions understandable
A variation should describe a need, such as a featured card, rather than encode an unexplained patch. Avoid selectors that depend on an incidental chain of ancestors when a component class can state the intention. Test a shared change in more than one context.
Make the handoff useful
A small example page can show supported variations and realistic content. Include long headings, missing optional content, and a narrow view. That gives the next developer a place to inspect the component before adding another override to the production stylesheet.
The benefit appears in repeated work: another page, a longer title, or a new state should not require someone to rediscover the component’s original intention. Examples are part of the handoff.