Components, Variants and Component Properties

A component is a maintained source of truth; an instance is a contextual use of that source. The value is not the diamond icon itself but the update path it creates. If a change to padding or focus treatment must be repeated across screens, the system is already paying a maintenance penalty.

Variants describe a bounded set of meaningful options such as size, hierarchy, and interaction state. Properties expose what an instance owner should change without detaching: label text, optional icon visibility, or which icon instance is used. The best API is small and legible. Hundreds of combinations usually signal that separate responsibilities have been forced into one component.

Detach only when the instance truly stops belonging to the system. Normal content changes, icon choices, or state changes are not reasons to detach. Test the component by placing instances in real contexts and changing the main component. If the update propagates without destroying intentional overrides, the architecture is doing useful work.

Interactive states are an accessibility surface, not just a hover flourish. A keyboard user never sees hover — they see focus. If your variant set stops at default/hover/pressed/disabled, you have designed for a mouse only. Add a Focus variant with a visible outline or ring distinct from hover, and design disabled so it reads as disabled without relying on colour alone (add reduced opacity plus a cursor or label cue). Loading and error variants matter wherever a component can genuinely be waiting or wrong — a submit button, a data card — not on every component by default.