Blode UI is an opinionated shadcn/ui component registry built by Matthew Blode, with a focus on good taste, care, and craft. Components install as source you own and edit.
- IS: installing
@blodecomponents into a project and writing code with them. - IS NOT: maintaining the Blode registry itself (that lives in the
mblode/uirepo's own instructions), scaffolding a whole Next.js app (usescaffold-nextjs), or visual direction for a non-Blode product (useui-design).
Before Adding Anything
Two things have to be true, and both fail quietly:
- The CLI can resolve
@blode. shadcn's registry directory has listed it since Aug 2026, so a current CLI needs no setup. Only an older CLI that reports an unknown registry needs the namespace registered incomponents.json. @blode/uiis installed. Grep the project's CSS for--field-radius; if it is absent, the design system was never added and every component will render unstyled.
references/install-flow.md has the commands for both.
Reference Files
Load only what the task needs.
| File | Read when |
|---|---|
references/install-flow.md |
Setting up @blode in a project, or a component renders unstyled |
references/registry-workflows.md |
Searching, viewing, adding, or updating components |
references/design-system.md |
Choosing color, typography, spacing, radius, elevation, or motion |
Rules
Load the matching rule file before writing component code. rules/_sections.md has the category map.
| Priority | Category | Impact | Prefix | Rules |
|---|---|---|---|---|
| 1 | Composition and accessibility | CRITICAL | comp- |
1 |
| 2 | Forms and validation | HIGH | form- |
1 |
| 3 | Styling and tokens | HIGH | style- |
1 |
| 4 | Base UI Primitive APIs | HIGH | api- |
1 |
| 5 | Icons | MEDIUM | icon- |
1 |
Gotchas
- A bare
npx shadcn@latest add @blode/buttonresolves through shadcn's registry directory. Keepnpx shadcn@latest registry add @blode=https://blode.co/ui/r/{name}.jsonas the fallback for an older CLI that cannot resolve@blode, not as a required first step. - An unstyled Blode component is a missing
@blode/uiinstall until proven otherwise. Chasing it as a specificity or class-merge problem produces cosmetic patches on a component that was never styled at all. - Blode wraps Base UI, not Radix.
asChilddoes not exist here; composition goes throughrender. Radix habits are the most common source of broken Blode code. addoverwrites a customised component with no warning. Preview with--difffirst.- The design system already settles accents, radii, motion, and surface treatments. Inventing new ones is how Blode work drifts into generic SaaS styling.
- Compose installed Blode components before hand-rolling markup that duplicates one.
- No icon pack other than
blode-icons-react. - Generic
@shadcn/*examples are the wrong answer to a Blode request unless the user asked about upstream shadcn/ui.
Related Skills
scaffold-nextjsfor standing up a new Next.js repo, which installs Blode UI as one step of a larger flowui-designfor visual direction on products that are not Blodeblode-icons-reactfor the icon package itself rather than its use in components