Component Instance

A component instance is a copy of a component that stays connected to its source. The main component holds the definition; every instance is a use of it, and a change to the definition reaches all of them.

That connection is the whole reason a component library is worth maintaining. Without it, a library is a folder of things to copy, and copies drift — which is how a product accumulates nine versions of one button, each reasonable when it was made.

Main, instance, override

The main component is where the definition lives: structure, states, defaults, the rules about what may change.

An instance is a use of it. It inherits everything by default and points back at the source.

An override is a local change to one instance — a different label, a swapped icon, a hidden element — that survives updates from the main.

Overrides are what let one component serve fifty cases instead of requiring fifty components. They are also where control leaks away, because every override is an exception that nobody reviewed. A system with no overrides is too rigid to use; a system where every instance is overridden has stopped being a system.

The practical line: overrides for content, not for structure. Changing the text is content. Changing the padding, the colour or the layout is a request for a variant that does not exist yet, and it should be raised rather than applied locally.

Detaching is a signal, not a fix

Detaching breaks the connection and leaves a one-off copy. It is instant and it is permanent: that copy will never receive a fix, a token update or an accessibility correction again.

Almost every detach is a symptom. Somebody needed a variant the component does not offer, the contribution route was slower than the deadline allowed, and they took the fast path. See component library, where the same dynamic produces local button variants in the codebase.

Two useful habits. Treat a detached instance as a bug report against the library rather than as a solved problem. And count them — a rising number is the earliest reliable warning that a design system is losing its grip, usually two quarters before anybody says so out loud.

Nesting, and where it stops helping

Components inside components is what makes composition work: a button inside a card inside a section. A change to the button reaches everything above it.

That compounding is the point and it has a limit. Three or four levels is manageable. Past that, nobody can predict what a change will affect, overrides become hard to reach, and the person using the component cannot tell which level a problem lives on.

The signal that the nesting is wrong is usually a prop or an override that has to be passed down several layers to reach the thing it controls. That is the same smell as an eleven-prop component: the abstraction was drawn in the wrong place.

Keeping design and code describing one thing

The model is identical on both sides and the words differ. Main component and definition. Instance and usage. Override and prop. Detach and copy-paste-into-a-local-file.

Keeping the two vocabularies aligned is most of what makes a handover work. When a designer says "this is an instance of the compact card with the footer hidden" and an engineer hears a component name and two props, nothing has to be translated. When the design file has a component the codebase does not, or the codebase accepts a prop the design file cannot express, every screen using it becomes a negotiation.

This is also why the coded component should be treated as the source of truth for behaviour: it is the one users experience. The design file is the source of truth for intent.

In practice

A team audits its design file before a redesign and finds four hundred and twelve instances of the primary button, of which sixty-one are detached.

Reading the sixty-one explains the whole problem. Fifty-three are the same thing: a button with an icon on the right rather than the left. The library offered icon-left only, contributing a variant took a fortnight, and fifty-three times somebody detached and moved the icon.

Adding one variant takes an afternoon and removes the reason for fifty-three exceptions. The remaining eight are genuine one-offs, and knowing that they are only eight is itself the useful outcome.

The number nobody was watching — detached instances — had been describing a missing variant for a year.

Where teams get it wrong

• Overriding structure, not content. Every layout override is an unrequested variant.
• Detaching to hit a deadline. A permanent copy that no fix will ever reach.
• No count of detached instances. The earliest warning signal, unmonitored.
• Nesting past what anyone can predict. Changes with unknowable blast radius.
• Design and code naming the same thing differently. Every handover becomes translation.