Installation
Set up UI.MD in your project and install your first component.
Setup
Two steps get the full design system into your project.
1. Initialize shadcn
Sets up the shadcn CLI and creates a components.json config in your project root. These components are built on Base UI, the CLI's default style, so no extra flags are needed.
2. Install the base theme
Adds the OKLCH color tokens, custom type scale, and spacing variables to your CSS. All UI.MD components expect these tokens to be present.
Install everything
One command for the whole kit, and the same command to update it later.
Pulls every component, the shared utilities, an app/ui-md-tokens.css file holding the whole token layer, and a docs/ui-md-rules.md file that states the design rules for anyone (or any coding agent) working in the project. It replaces both setup steps above, apart from init.
Re-run it any time to update. -o overwrites, so treat everything under your ui folder as read-only: local edits are lost on the next pull. Wrap a component instead of editing it. Leave -o off and the CLI asks before touching each existing file.
Tokens ship as a file rather than as merged CSS variables on purpose. The CLI only ever ADDS a variable it cannot find, so a project that installed months ago would keep its old palette forever. A file gets overwritten, so a pull is always current. To retune a token, re-declare it in your own global CSS below the import: that file is read after the token file, so your value wins and survives every update.
@import "tailwindcss";
@import "./ui-md-tokens.css";
:root {
--accent: var(--color-accent-600);
}Adding components
Install any component by pointing the CLI at its registry URL.
The CLI downloads the component source into your components/ui/ directory and installs any npm dependencies it needs (Base UI primitives, cva, etc.).
Swap button for any component name to install that one instead. Every component page has a copy-paste install command.
Install by namespace
Register the namespace once, then install any component by name.
Add the registry to the registries field in your components.json:
{
"registries": {
"@uimd": "https://ui.mattdowney.com/r/{name}.json"
}
}Then install any component by name, no URL needed:
What's available
The registry includes components, utilities, and a base theme.
| Item | Description |
|---|---|
| kit.json | Everything below in one install, plus a rules file for the project |
| base.json | OKLCH color tokens, type scale, spacing, shadows, and radii |
| Components | Button, Card, Dialog, Input, Select, Combobox, and more |
| Utilities | cn() class merging, shared layout tokens for cards and modals |
Usage
Import from your local components directory and use like any React component.
import { Button } from "@/components/ui/button"
export function Example() {
return <Button variant="outline">Click me</Button>
}