#Principle
Elements that look alike are likely to be interpreted as sharing a role, state, or category.
#Why it matters
Color, shape, typography, icon style, size, and treatment establish an interface vocabulary. Once users learn that vocabulary, similarity accelerates scanning. Problems appear when visually identical components behave differently or when equivalent actions receive unrelated styling. Semantic consistency matters more than visual sameness for its own sake.
#Deeper design interpretation
Similarity creates a visual vocabulary. Once users learn that a blue filled control is primary, that a muted pill is a status, or that an underlined label is a link, they begin predicting behavior without rereading every element. That prediction is valuable because it turns repeated interface exposure into faster recognition.
The dangerous case is semantic collision: two things look alike but mean different things, or the same thing looks different without a meaningful reason. Both cases increase interpretation cost. Semantic collision is especially risky for status color, destructive controls, links, selected states, and disabled states because misreading them can lead directly to wrong action.
Layr should treat visual consistency as a mapping problem. The question is not whether every button is identical; it is whether the system maintains a stable mapping between appearance and meaning.
#What the agent should reason about
Compare visual variants against actual roles, states, and event handlers. Identify whether differences are meaningful, responsive, or accidental. When two variants differ, ask what semantic distinction the difference communicates. When two elements match, ask whether users can safely assume equivalent behavior.
Design-system metadata provides strong evidence. If two components share a semantic variant but diverge visually, the agent can report a high-confidence inconsistency. Screenshot-only inference should remain more cautious.
#Common failure patterns
- The same color means success, active, and promotional depending on the page.
- Buttons with identical styling trigger actions with very different risk.
- Selected and disabled states rely on nearly identical muted treatments.
- The same action has different labels and icons across routes.
- A custom component visually imitates a native control while behaving differently.
#Audit questions
- What meaning does each repeated visual treatment teach?
- Are users rewarded for learning the visual vocabulary, or must they re-interpret it on each screen?
- Does any appearance imply the wrong action, state, or category?
- Are intentional exceptions documented or contextually obvious?
#Example agent finding
High — Red is mapped to both “overdue” and “active.” The project table uses red status chips for overdue work, while the adjacent automation panel uses the same chip treatment for enabled automations. Because both states appear in the same workflow, the shared visual mapping is misleading. Reserve red for negative/urgent status and use the existing active-state token for enabled items.
#Agent directive
Use visual similarity to encode shared semantics. Flag cases where similar appearance predicts the wrong behavior or where equivalent behavior is styled inconsistently without a meaningful state distinction.
#Apply this when
- Buttons, badges, links, tabs, status chips, form controls, cards, navigation, table actions, and repeated data displays.
#Observable signals
- Two controls share the same style but have different interaction models.
- The same action appears as a primary button in one place and plain text in another without context explaining the difference.
- Colors are reused for unrelated states.
- Disabled, selected, and read-only states are visually difficult to distinguish.
- Icon families or stroke styles change within the same interaction set.
#Recommended actions
- Map repeated semantics to shared variants and tokens.
- Reserve distinctive treatments for real state or priority differences.
- Keep equivalent components consistent across routes unless platform context requires adaptation.
- Document intentional exceptions in the design system.
#Do not over-apply
Similarity does not require every instance to be visually identical. Size, density, or responsive context can vary while semantic cues remain stable.
#Example
Weak
A red pill means 'overdue' in one list and 'active' in another because both teams independently chose red as an accent.
Stronger
Status colors and shapes follow one semantic mapping across the product, while layout density can change by surface.
#Evaluation notes
- Default severity: Medium to high when users can misread state or action; low for cosmetic inconsistency.
- Typical confidence: High when shared variants and semantics can be compared.
- Primary evidence: Component variants, color/token usage, labels, event handlers, state mapping.
- Related rules: Jakob's Law, Aesthetic-Usability Effect, Law of Uniform Connectedness, Mental Model