Copy-Paste UI Needs a Shared Component Contract

·https://www.components.build/
articleuicomponentsreactdesign-systemsfrontendaccessibilitycomponent-registries

Maps to joelclaw UI work by turning reusable React components into source-owned, documented, accessible primitives.

components.build is Vercel putting a stake in the ground for modern UI components: composable, accessible, customizable, documented, and boring enough to move between projects without a pile of weird hidden assumptions.

The useful part is that it’s not a React course and it’s not another component library pitch. It’s a shared vocabulary for people building components in JavaScript, TypeScript, and the broader React ecosystem, co-authored by Hayden Bleasel and shadcn. It also explicitly nods toward Vue, Svelte, and Angular as places the underlying philosophy should still apply.

The clever bit is how it treats the shadcn/ui copy-the-source model as a real distribution pattern, not a cute hack. If components are going to land inside your repo instead of hiding behind an NPM package, then the source needs a contract: clear composition, sane state boundaries, WAI-ARIA defaults, theming hooks, data attributes, docs, registry metadata, and a CLI path for install.

For joelclaw, this is a good checklist for when a UI primitive stops being a one-screen hack and becomes shared infrastructure. That’s where design systems usually get mushy as hell: half convention, half memory, half “ask whoever wrote it.” This spec turns that into pages you can point an agent, maintainer, or future-you at.

Key Ideas

  • components.build defines an open-source standard for modern UI components instead of shipping another closed component library.
  • The spec centers component quality around composition, accessibility, customization, performance, transparency, and documentation.
  • The Composition section argues against mega-components with dozens of props and for smaller compound components like Root, Item, Trigger, and Content.
  • The Core Principles section makes accessibility a baseline feature, including semantic HTML, keyboard navigation, focus management, and WAI-ARIA when needed.
  • The Registry section frames shadcn/ui style registries as source-code distribution: users copy code into their project, inspect it, modify it, and own it.
  • The publishing model needs registry metadata, previews, docs, examples, and a CLI, not just a random JSON blob sitting on the internet.
  • The spec lines up with Radix UI and shadcn/ui conventions that have become common in the React design-system world.

Links

← All discoveries