component-architecture
Component Architecture
Concept of the skill
Component architecture is the discipline of structuring a library of UI components so their APIs outlive any single product, framework, or visual language. Every component is settled by four interlocking questions: layer — primitive, composite, or product-specific assembly, with dependencies flowing strictly downward; API surface — which props, slots, refs, callbacks, and render functions are open for extension versus closed for modification; state contract — controlled (the consumer owns the value), uncontrolled (the component owns it), or hybrid; and theming — the headless/styled split that lets behavior and visual treatment evolve independently. A component's API is the public contract between its author and every future consumer: once it ships, every prop, slot, event, and exposed ref becomes a thing future versions must keep supporting or break. The discipline replaces "a design system is a pile of components" with "components designed so their contracts survive multiple products and multiple visual languages."
Coverage
The architectural discipline of structuring a library of UI components so they can be reused across products, themes, and teams. Covers the layering of primitives, composites, and product-specific assemblies; the composition-over-configuration principle and its trade-offs; the headless/styled split as the mechanism for behavior reuse across visual languages; controlled / uncontrolled / hybrid state contracts; the open-closed principle adapted to component evolution; polymorphism via as and asChild; extension mechanisms (props, children, slots, render props, compound components, ref forwarding); and the API-as-contract framing that makes component libraries survive multi-product, multi-year reuse.
Philosophy of the skill
The component's API is the contract between its author and every future consumer. Every prop, every slot, every event is a public surface that becomes a thing future versions must continue to support — or break consumers. Component architecture is the discipline of designing those contracts with the knowledge that you cannot predict every consumer and that the contract will be inhabited by integrations you didn't anticipate.
The discipline is upstream of any specific library, framework, or visual language. Layering, composition, the headless/styled split, the controlled/uncontrolled distinction, and the open-closed principle are properties of how components are structured — independent of which framework implements them and which design tokens style them. A team that internalizes these properties produces libraries that survive a decade of framework changes, brand refreshes, and product evolution. A team that does not produces libraries that work for the first product and require a rewrite for the second.
For agents working in component-heavy codebases, the discipline is the framework that lets the agent reason locally. Pick up a component, classify it by layer (primitive / composite / product-specific), inspect its API surface (props, slots, events), identify its state contract (controlled / uncontrolled / hybrid), and use it correctly without internalizing every idiosyncrasy. Without the framework, the agent pattern-matches against whatever the codebase already does — which means proliferating the codebase's existing architectural mistakes.