Quick Start

This page takes you through adding a Shadcn Button to an existing application and rendering it for the first time. You can start here without reading the whitepaper.

Run these commands from an existing React, Vue, or Web Components application. The example below uses a React application that already has react installed.

The CLI installs the selected Adapter and Prototype packages at its own exact version. With the current @latest release, all public @proto.ui/* dependencies added by this flow resolve to 0.2.0, so release trains are not mixed.

You can invoke the CLI with npx; a global installation is not required:

npx @proto.ui/cli@latest --help

Using the explicit @latest tag makes the stable channel policy visible. For a permanently reproducible installation or CI workflow, replace it with @0.2.0.

From the application root, run:

npx @proto.ui/cli@latest init

Accepting the defaults creates the local Proto UI workspace and the Shadcn style preset:

your-project/
├── src/
│   └── styles/
│       ├── proto-ui-style.css
│       ├── proto-ui-tokens.generated.css
│       └── shadcn-theme.css
├── proto-ui/
│   ├── adapters/
│   ├── prototypes/
│   ├── components/
│   └── config.json
├── package.json
└── ...

• proto-ui/config.json records the project configuration used by later CLI commands.
• proto-ui/components/ contains generated host entries that the application imports.
• proto-ui/adapters/ and proto-ui/prototypes/ are CLI-managed areas.
• src/styles/proto-ui-style.css composes the generated theme and token CSS.

The CLI manages generated files; do not edit them by hand. Use --prototypes brutalist when initializing a project that should use the Brutalist preset, or --no-styles when the application will provide the complete semantic token surface itself.

Import the generated stylesheet from the application entry:

import './styles/proto-ui-style.css';

Adjust the relative path if your entry file is elsewhere. When the application has not selected a theme, the generated Shadcn theme follows prefers-color-scheme. Set data-theme="light" / data-theme="dark" on the root element, or use the compatible .light / .dark classes, to override the system preference.

If the application does not use named CSS cascade layers, keep the single import above. If it does, establish the complete order in one CSS entry before any reset, Proto UI, or consumer layer is first declared:

@layer theme, base, proto-ui, components, utilities;

@import './reset.css' layer(base);
@import './styles/proto-ui-style.css';
@import './app-components.css' layer(components);
@import './app-utilities.css' layer(utilities);

Import app.css once from the application entry instead of importing those stylesheets separately. The generated entry places its theme defaults in the theme layer, so values declared by later named consumer layers—or by unlayered consumer CSS—remain authoritative. The complete relationship is theme defaults < reset/base < proto-ui < explicit consumer layers. For Tailwind, preserve its theme < base < components < utilities order while inserting proto-ui after base and before the application’s component and utility layers in the earliest order statement.

Layer order is fixed when a named layer first appears. A generated @layer theme, proto-ui; declaration can reserve only those two slots when that entry loads first; it cannot repair an order that earlier stylesheets already established. The host order statement above remains necessary whenever the application introduces named reset or consumer layers.

Add the official Shadcn Button facade for the host your application uses. The example keeps the CLI command and application entry together for React and Web Components; its initial host follows the site-wide Adapter preference when supported.

npx @proto.ui/cli@latest add wc shadcn-button

import '../proto-ui/components/wc';

document.body.innerHTML = '<proto-ui-shadcn-button variant="outline">Proto UI 0.2.0</proto-ui-shadcn-button>';

npx @proto.ui/cli@latest add react shadcn-button

import { ShadcnButton } from '../proto-ui/components/react';

export function App() {
  return <ShadcnButton variant="outline">Proto UI 0.2.0</ShadcnButton>;
}

The command installs the matching Adapter and @proto.ui/prototypes-shadcn@0.2.0, then generates the host entry under proto-ui/components/. Vue projects use vue in the same command. The relative imports are intentional: applications do not share one path-alias setup or directory depth. Generated facades preserve the Prototype’s declared props, event listeners, and ref/expose surface.

Start the application. You should see an outline Button labeled “Proto UI 0.2.0”. Check that styles load, then try focusing it with Tab and activating it with Enter or Space. If an import fails, check the generated directory and relative path; if styling is missing, check that the application entry imports the generated stylesheet.

Once this works, use the component documentation to connect business state and events.

npx @proto.ui/cli@latest add react shadcn-toggle
npx @proto.ui/cli@latest add react shadcn-dialog

The generated host entry accumulates exports, so the application can keep importing from the same path:

import { ShadcnButton, ShadcnDialogRoot, ShadcnToggle } from '../proto-ui/components/react';

To generate without installing missing packages, add --no-install. The CLI will print exact install commands, but the generated entry will not build until those dependencies are present.

• 0.2.0 is the stable release for the 0.2 line, not a v1 compatibility guarantee.
• Spec entity lifecycle still applies: an active entity is a current guarantee, while a draft entity remains work in progress even when related executable packages are published.
• The CLI installs official Prototype packages and generates local component facades. It does not copy styled Prototype source into the application for direct editing.
• The current Adapter architecture includes a runtime. Compiler output and zero-runtime delivery remain future work.
• Shadcn compatibility is intentional but incomplete; the current model does not expose Radix-style asChild.
• Review component and Adapter coverage for your use case, and validate accessibility, SSR, and bundle behavior in your own application before production adoption.

• Proto UI 0.2.0 release

Once you have integrated your first component, choose where to go next: