Blode UI

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 @blode components into a project and writing code with them.
• IS NOT: maintaining the Blode registry itself (that lives in the mblode/ui repo's own instructions), scaffolding a whole Next.js app (use scaffold-nextjs), or visual direction for a non-Blode product (use ui-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 in components.json.
• @blode/ui is 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/button resolves through shadcn's registry directory. Keep npx shadcn@latest registry add @blode=https://blode.co/ui/r/{name}.json as the fallback for an older CLI that cannot resolve @blode, not as a required first step.
• An unstyled Blode component is a missing @blode/ui install 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. asChild does not exist here; composition goes through render. Radix habits are the most common source of broken Blode code.
• add overwrites a customised component with no warning. Preview with --diff first.
• 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-nextjs for standing up a new Next.js repo, which installs Blode UI as one step of a larger flow
• ui-design for visual direction on products that are not Blode
• blode-icons-react for the icon package itself rather than its use in components