# Introduction

WebJs UI is a set of beautifully-designed, accessible components and a code distribution platform for WebJs apps. Open Source. Open Code.

Source: https://webjs.dev/ui/docs

**This is not a component library. It is how you build your component library.**

You know how most traditional component libraries work: you install a package from npm, import the components, and use them in your app.

This approach works well until you need to customize a component to fit your design system or require one that isn't included in the library. **Often, you end up wrapping library components, writing workarounds to override styles, or mixing components from different libraries with incompatible APIs.**

This is what WebJs UI aims to solve. It is built around the following principles:

- **Open Code:** The top layer of your component code is open for modification.
- **Composition:** Every component uses a common, composable interface, making them predictable.
- **Distribution:** A flat-file schema and command-line tool make it easy to distribute components.
- **Beautiful Defaults:** Carefully chosen default styles, so you get great design out-of-the-box.
- **AI-Ready:** Open code for LLMs to read, understand, and improve.

## Open Code

WebJs UI hands you the actual component code: `webjs ui add` copies the source into your app's `components/ui/`. You have full control to customize and extend the components to your needs. This means:

- **Full Transparency:** You see exactly how each component is built.
- **Easy Customization:** Modify any part of a component to fit your design and functionality requirements.
- **AI Integration:** Access to the code makes it straightforward for LLMs to read, understand, and even improve your components.

*In a typical library, if you need to change a button's behavior, you have to override styles or wrap the component. With WebJs UI, you simply edit the button code directly.*

**How do I pull upstream updates in an Open Code approach?**

WebJs UI builds on the platform rather than on a headless library: a dialog is a native `<dialog>`, a popover the `popover` attribute, and the few custom elements extend `WebComponent` from `@webjsdev/core`. So the core your components stand on receives fixes when you update `@webjsdev/core` and the browser.

The topmost layer, the code closest to your design system, is yours and is not coupled to the kit. Run `webjs ui diff` to see how your copy differs from the registry, and take the changes you want.

## Composition

Every component in WebJs UI shares a common, composable interface: a class helper you put on a native element (`buttonClass()` on a real `<button>`), or a custom element for each part of a component (`<ui-dialog>`, `<ui-dialog-content>`). **If a component does not exist, we bring it in, make it composable, and adjust its style to match and work with the rest of the design system.**

*A shared, composable interface means it's predictable for both your team and LLMs. You are not learning different APIs for every new component. Variant names, sizes and data attributes follow the same scheme in every component, so what you learn in one carries over to the next.*

## Distribution

WebJs UI is also a code distribution system. It defines a schema for components and a CLI to distribute them.

- **Schema:** A flat-file structure that defines the components, their dependencies, and properties. See [registry-item.json](https://webjs.dev/ui/docs/registry/registry-item-json).
- **CLI:** A command-line tool to distribute and install components, blocks and charts across WebJs apps. See the [CLI](https://webjs.dev/ui/docs/cli).

*You can use the schema to distribute your components to other projects from a [registry of your own](https://webjs.dev/ui/docs/registry), or have AI generate completely new components based on existing schema.*

## Beautiful Defaults

WebJs UI comes with a large collection of components that have carefully chosen default styles. They are designed to look good on their own and to work well together as a consistent system:

- **Good Out-of-the-Box:** Your UI has a clean and minimal look without extra work.
- **Unified Design:** Components naturally fit with one another. Each component is built to match the others, keeping your UI consistent.
- **Easily Customizable:** If you want to change something, it's simple to override and extend the defaults, or pick another of the kit's styles and themes in [Create](https://webjs.dev/ui/create).

## AI-Ready

The design of WebJs UI makes it easy for AI tools to work with your code. Its open code and consistent API allow AI models to read, understand, and even generate new components. Every WebJs app also ships a read-only MCP server whose `ui` tool lists the kit and returns any component's helpers and example, and its `init` brief tells an agent to look for a ready-made [block](https://webjs.dev/ui/docs/skills) before writing a view by hand.

*An AI model can learn how your components work and suggest improvements or even create new components that integrate with your existing design.*
