Component architecture
Semantics before surface
How Gummy UI keeps native HTML or Base UI behavior in charge while adding editable React source, forwarded refs, and Gel Pop visual anatomy.
By Gummy UI · Published
Choose the behavior owner first
A visual component begins with a behavior decision. When HTML already provides the required interaction, Gummy UI keeps the native element: buttons submit, inputs participate in forms, labels connect to controls, and links navigate. When an interaction needs coordinated focus, roving navigation, collision positioning, or modal behavior, the implementation uses the corresponding Base UI primitive instead of rebuilding that behavior in decorative markup.
This decision is visible in the catalogue’s semantics and keyboard fields. A component detail page does not merely show a picture; it identifies the element or primitive that owns the interaction. That record helps reviewers distinguish a visual variant from a behavioral change and keeps styling work from quietly replacing a proven input model.
Keep public refs and native props useful
Canonical components forward their public refs to the element or primitive root that a consumer needs to focus, measure, or integrate with a form. Props are composed from the underlying React or Base UI types where practical. This preserves familiar attributes such as names, values, disabled state, event handlers, and accessible names instead of hiding them behind an unrelated configuration object.
The release verifier copies committed Next.js and Vite templates into fresh temporary projects, installs independent dependencies, and runs the real shadcn command against a local HTTP registry. npm, pnpm, Yarn, and Bun paths each type-check and production-build without importing from the website repository. The source viewer still lets a reader inspect the actual component before installation rather than relying on a generated prop table alone.
Make decoration silent
Gel shells, glints, pools, and SVG frame paths do not communicate the control’s name or state. They are marked as decorative so assistive technology follows the real input, button, heading, status, or relationship. Visible validation is paired with text and accessible state; a colour change or exclamation mark is not expected to carry the message on its own.
The same rule applies to composition. An article card remains an article until it is intentionally rendered as an anchor or button. A clickable-looking surface is not implemented as a generic div with keyboard behavior bolted on later. Separate passive, link, and button roots make the interaction contract explicit in both the markup and TypeScript types.
Test behavior where it lives
Testing Library exercises the public components through roles, labels, focus, keyboard input, and state changes. Representative axe checks inspect rendered states in a DOM environment, while token-level checks cover selected stable colour pairs. These automated checks support the contract, but they do not replace browser, zoom, touch, or screen-reader review.
The practical outcome is a review order: confirm the element, name, relationship, keyboard model, focus path, and form behavior first; then inspect theme, motion, and material. Surface work becomes safer when the behavioral foundation has an identified owner and an executable test.