In the design file it is “main card”. In the code it is featured-box. In the meeting it is “that big box”. Three names for one thing means a translation step in every exchange. The cost looks small at first, but the real problem is that the translation table lives only in people’s heads — it never reaches the person who joins next, and it does not reach you either, six months later.
What actually breaks when names diverge
Three things collapse, in order. First, requests get longer. What should be “reduce the card padding by 8” becomes “you know that big box on the third row of the listing page”.
Second, it stops being clear whether two things are the same component. If what the designer thinks of as one thing exists twice in the code, one copy gets fixed and the other does not. On screen it looks like “why did this one not change?”, and the cause sits at the point where the names split.
Third, documentation rots. A document bridging two vocabularies is one more thing to maintain, and the moment it is not maintained it becomes a wrong map.
Three rules for naming
1. Name the role, not the look. “Blue box” becomes a lie the day the colour changes. “Notice” survives the repaint. For the same reason “filter panel” outlives “left sidebar”.
2. Split into block, element and variant. There is a card; inside it are elements such as title and summary; and there are variants such as a featured card. That structure maps cleanly onto the layer tree in the design file and onto the class structure in the code.
3. Only create a variant once you have three. Promoting a one-off exception to a named variant just lengthens the list. Let it be an exception twice; when the same shape turns up a third time, name it. That is the moment it became a real pattern.
Where the name tags live
The names should exist in exactly one place. The simplest arrangement is that the component names in the design file are the list. A separate document creates somewhere for the two to disagree, and that disagreement is usually discovered long after it happened.
On the WordPress side those names land directly as class prefixes and template file names. If it is a card, the style file is card and the classes are the card family. The target state is one word that sounds the same in the design file, the stylesheet and the conversation.
Component-level thinking is covered further in the development workflow archive, and structural clean-up including naming falls within the scope of our optimization program.
Next part
With names agreed, the next question is what those components actually encounter. The next part is states and edge cases: empty lists, errors, very long titles and missing images.