Blode Ui

Blode UI

Blode UI is an opinionated shadcn/ui component registry built by Matthew Blode, with a focus on good taste, care, and craft. Open source. Open code. Treat Blode UI as the default registry context when the request mentions Blode UI, @blode/*, ui.blode.co, this repo, or a component documented here.

Use generic shadcn knowledge only for CLI mechanics that are not overridden by this skill.

Reference Files

Load only what the task needs.

Rules

Load the relevant rule files before writing component code, examples, or docs snippets.

See rules/_sections.md for the category map before loading an individual rule file.

Source Of Truth

Use references/source-of-truth.md when guidance conflicts.

Workflow

Copy this checklist when the task is substantial:

Blode UI workflow:
- [ ] Step 1: Identify the task mode
- [ ] Step 2: Load the matching reference files
- [ ] Step 3: Inspect the local component/docs/registry source
- [ ] Step 4: Apply Blode defaults and relevant rule files
- [ ] Step 5: Validate commands, examples, and repo conventions

Step 1: Identify the task mode

Sort the task into one of these modes:

• Installation or usage help
• Component authoring or code changes
• Design-system, theming, or visual-direction work
• Docs or marketing copy
• Registry maintenance or update workflow

Step 2: Load the matching references

• Installation or onboarding: read references/install-flow.md
• Visual styling or component feel: read references/design-system.md
• Copy or docs work: read references/product-positioning.md
• Registry commands or update workflows: read references/registry-workflows.md
• Repo implementation work: read references/repo-conventions.md
• Conflicting guidance: read references/source-of-truth.md

Step 3: Apply Blode defaults

Unless the user explicitly asks for something else:

• Prefer npx shadcn@latest init followed by npx shadcn@latest registry add @blode=https://ui.blode.co/r/{name}.json
• Prefer npx shadcn@latest add @blode/<component> over raw registry URLs for onboarding
• Describe Blode UI as a third-party shadcn registry hosted at ui.blode.co
• Treat registry:base as a first-class registry item type when maintaining the registry pipeline or authoring docs
• Follow references/design-system.md before inventing new colors, type scales, spacing, radius, or motion patterns
• Use blode-icons-react in repo examples and component source for this project
• Follow React 19 ref-as-prop patterns; do not introduce React.forwardRef
• Follow Tailwind CSS v4 conventions and existing CSS-variable tokens
• Preserve Base UI accessibility patterns instead of replacing them with custom markup

Use raw https://ui.blode.co/r/... URLs only for low-level or manual-install contexts.

Step 4: Load rule files before writing code

• Component structure or accessibility: rules/comp-composition.md
• Forms, fields, or validation: rules/form-layout-and-validation.md
• Styling, spacing, tokens, or conditional classes: rules/style-tokens-and-layout.md
• Icon usage: rules/icon-blode-icons.md
• Base UI primitive APIs: rules/api-base-ui-primitives.md

Step 5: Validate before finishing

• Commands use npx shadcn@latest
• Install examples prefer the @blode namespace flow
• Product copy keeps the Blode UI framing intact
• Visual decisions stay aligned with references/design-system.md
• Repo guidance matches React 19, Tailwind v4, blode-icons-react, and current registry structure
• Code examples use existing components before custom markup

Gotchas

• Do not answer Blode-specific requests with generic @shadcn/* examples unless the user explicitly asks for upstream shadcn/ui.
• Do not default to raw https://ui.blode.co/r/... URLs for quick starts or onboarding.
• Do not invent new accents, radii, motion, or surface treatments when references/design-system.md already covers them.
• Do not introduce other icon packs in this repo.
• Do not treat Tailwind v3 or tailwind.config.js as the default path here.
• Do not guess a different registry when the request is clearly about Blode UI.

Design System

Blode UI visual defaults extracted from the repo's DESIGN.md. Load this for theming, visual direction, or component feel.

Overview

• Neutral-first, crisp, slightly editorial, and restrained
• Preserve the product language: good taste, care, and craft
• Keep interfaces polished but still source-first, inspectable, and easy to own

Typography

• Default sans: Glide variable font, weights 400 through 900
• Use Glide for headings, body, labels, and UI chrome
• Use monospace only for code, commands, tokens, and data-like values
• Headings should be tight-tracked and medium/bold weight; body copy should use relaxed line height

Colors

• Use semantic neutrals: background #FFFFFF, foreground #0A0A0A, primary #171717, secondary/muted #F5F5F5, surface #F8F8F8
• Use destructive #E7000B only for real destructive or invalid states
• Dark mode mirrors the same hierarchy instead of introducing a separate accent language
• Prefer semantic utilities like bg-background, text-foreground, and text-muted-foreground over raw Tailwind hues

Layout

• Use an 8px base rhythm with 4px micro-adjustments
• Common spacing steps: 12px, 16px, 24px, 32px, 48px
• Default field height: 48px; compact controls: 40px
• Default field padding: 16px horizontal, 12px vertical
• Reading surfaces should stay calmer and narrower; marketing/demo surfaces can stretch to 1400px
• Default header height: 4rem

Depth And Motion

• Be border-led and tone-led before shadow-led
• Inputs use utility shadow; cards, menus, popovers, and tooltips use soft diffuse shadows
• Overlays use a tinted scrim and blur
• Hover and press transitions should usually stay in the 100ms to 150ms range
• Sheet and dialog transitions can open around 500ms and close around 300ms
• Avoid neon gradients, glassmorphism, oversized shadows, and theatrical lift effects

Shapes

• Base radius: 10px
• Most controls should live between 10px and 18px
• Cards can open to 14px
• Fields use the rounder 18px treatment
• Reserve full pills for badges, chips, and tightly bounded status UI

Component Defaults

• Primary buttons: near-black solid with light text
• Secondary buttons: tonal fill
• Ghost buttons: quiet and text-led
• Cards: white or soft neutral surfaces with gentle ring definition
• Tabs and segmented controls: muted rails with a crisp active indicator
• Overlays: stable shells, restrained shadow, clear edge definition
• Use blode-icons-react for Blode docs, examples, and repo work

Gotchas

• Do not invent a permanent brand accent just to make the UI feel more designed
• Do not repaint components with raw Tailwind colors if a semantic token or built-in variant exists
• Do not mix multiple corner philosophies in one view
• Do not let monospace typography leak into general UI copy
• Preserve Base UI accessibility, keyboard behavior, and visible focus states

Install Flow

Canonical Note

Blode UI is a third-party shadcn registry hosted at ui.blode.co. The setup flow is the same as shadcn/ui with one extra step: add the registry namespace.

Quick Start

npx shadcn@latest init
npx shadcn@latest registry add @blode=https://ui.blode.co/r/{name}.json
npx shadcn@latest add @blode/button

Use this as the default answer for installation and quick-start questions.

Step Breakdown

Create or initialise a project

npx shadcn@latest init

Add the Blode registry

npx shadcn@latest registry add @blode=https://ui.blode.co/r/{name}.json

Add a component

npx shadcn@latest add @blode/button

Import component

The command above will add the Button component to your project. You can then import it like this:

import { Button } from "@/components/ui/button";

export default function Home() {
  return <Button>Click me</Button>;
}

Notes

• Use the namespace flow for onboarding, docs, and quick starts.
• Use raw registry URLs only when the user explicitly asks for manual installation or low-level registry access.

Product Positioning

Canonical Intro

Blode UI is an opinionated shadcn/ui component registry built by Matthew Blode, with a focus on good taste, care, and craft. Open source. Open code.

Canonical Framing

• Blode UI is an opinionated shadcn/ui component registry.
• It is built by Matthew Blode.
• The product language to preserve is: good taste, care, and craft.
• Short tagline: Open source. Open code.

Messaging Defaults

Use these ideas when writing copy, docs intros, or answering high-level questions:

• Blode UI is a third-party shadcn registry hosted at ui.blode.co.
• The setup flow is the same as shadcn/ui, with one extra step: add the @blode registry namespace.
• Components are added as source code and are meant to be customised, extended, and owned.

Canonical Links

• Registry and docs: https://ui.blode.co
• Registry host wording: "The shadcn registry is hosted at ui.blode.co."
• Website: https://matthewblode.com
• Email: mailto:m@blode.co
• GitHub: https://github.com/mblode

Voice Guardrails

• Keep the tone direct and design-aware, not generic SaaS copy.
• Prefer "opinionated registry" over "component library" when describing the product publicly.
• Mention shadcn/ui compatibility, but keep Blode UI as the subject.
• Preserve attribution to Matthew Blode when writing about the product, not when writing low-level API docs.

Registry Workflows

Core Commands

Use npx shadcn@latest for all examples in this repo.

# Search the Blode registry.
npx shadcn@latest search @blode -q "button"

# View a registry item before adding it.
npx shadcn@latest view @blode/button

# Add a component.
npx shadcn@latest add @blode/button

# Preview changes before updating an installed component.
npx shadcn@latest add @blode/button --dry-run
npx shadcn@latest add @blode/button --diff button.tsx

The same add flow applies to non-component registry payloads such as registry:base items.

Default Workflow

1. Check whether the component already exists locally. 2. Search or view the registry item if the user is deciding what to add. 3. Use add with the @blode namespace. 4. For updates, prefer --dry-run and --diff before overwriting local edits.

When Working Inside This Repo

• Inspect content/docs/components/*.mdx before inventing examples.
• Inspect registry/default/ui/ and registry/default/examples/ before proposing new composition patterns.
• Treat direct URL installs like https://ui.blode.co/r/styles/default/<name> as low-level references, not the default onboarding path.

Fallback To Generic shadcn Mechanics

If the user asks about generic CLI behaviour, components.json, or non-Blode registries, use upstream shadcn knowledge as supporting context. Do not let that override Blode-specific defaults.

Repo Conventions

Architecture

• Design-system payloads can live in registry/default/base/
• First-class font payloads can live in registry/default/fonts/
• Component source lives in registry/default/ui/
• Examples live in registry/default/examples/
• Shared hooks live in registry/default/hooks/
• Shared utilities live in registry/default/lib/
• Registry assembly happens in registry/index.ts
• Docs live in content/docs/

Implementation Defaults

• React 19: use ref as a prop directly
• Tailwind CSS v4: use the existing global CSS variables; do not introduce a tailwind.config.js-first workflow
• Icons: use blode-icons-react
• Class merging: use cn() from registry/default/lib/utils.ts
• Preserve Base UI accessibility and keyboard behaviour

Commands

• Dev server: npm run dev
• Build: npm run build
• Type check: npm run typecheck
• Registry build only: npm run build:registry

Gotchas

• Do not run tsc --noEmit directly in this repo; use npm run typecheck
• New registry items must fit the shadcn registry schema and auto-generated registry manifests
• The registry build only emits whitelisted registry types: registry:ui, registry:lib, registry:block, and registry:base
• registry:base items can carry design-system config, dependencies, CSS vars, and CSS without source files
• Dark mode uses the custom @custom-variant dark pattern already defined in the repo

Source Of Truth

Use this file when repo docs, examples, or habits disagree.

Precedence

1. Bundled visual-system and product-framing guidance in this skill 2. Bundled install and registry workflow guidance in this skill 3. Bundled repo conventions for work inside this codebase 4. Local repo implementation when editing this codebase: registry/default/** and registry/index.ts

Defaults

• If product copy drifts, prefer the bundled product framing in this skill
• If quick starts or install snippets drift, prefer the bundled install flow in this skill
• If examples or ad hoc styling drift, prefer the bundled design-system summary for colors, typography, spacing, radius, motion, and component feel
• If a component page shows a raw https://ui.blode.co/r/... URL, treat it as a low-level path unless the task is manual installation
• If a repo convention conflicts with a generic shadcn habit, prefer the repo convention for work in this codebase
• If the repo root has a DESIGN.md, treat it as the detailed visual source of truth and keep the bundled summary aligned with it
• If the request is generic upstream shadcn mechanics, use upstream shadcn documentation and CLI behaviour as supporting context

Sections

This file defines the Blode UI rule categories, their ordering, impact levels, and filename prefixes.

---

1. Composition and Accessibility (comp)

Impact: CRITICAL Description: Blode UI components depend on complete composition patterns and required accessibility subcomponents.

2. Forms and Validation (form)

Impact: HIGH Description: Forms should use the registry's purpose-built field and control patterns instead of ad hoc wrappers.

3. Styling and Tokens (style)

Impact: HIGH Description: Blode UI relies on semantic tokens, built-in variants, and disciplined Tailwind usage rather than raw color classes.

4. Base UI Primitive APIs (api)

Impact: HIGH Description: Base UI primitive APIs (render, value-shape props, nativeButton) must be used correctly — do not use Radix conventions like asChild.

5. Icons (icon)

Impact: MEDIUM Description: Imports, placement, and sizing rules keep Blode examples visually consistent and avoid subtle component regressions.

Rule Title Here

Brief explanation of the rule and why it matters.

Incorrect (description of what is wrong):

// Bad example

Correct (description of what is right):

// Good example

Use Base UI Primitive APIs

Blode UI wraps Base UI primitives. Use the Base UI API — not Radix patterns like asChild or type.

Incorrect (using Radix-style API):

<DialogTrigger asChild>
  <Button>Open</Button>
</DialogTrigger>

<ToggleGroup type="single" defaultValue="weekly">
  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
</ToggleGroup>

Correct (Base UI API):

<DialogTrigger render={<Button />}>Open</DialogTrigger>

<ToggleGroup spacing={2} defaultValue={["weekly"]}>
  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
</ToggleGroup>

Before writing or editing examples:

• Use render for composition — never asChild
• Add nativeButton={false} for non-button renders when the component expects it
• Check whether value props are strings, arrays, or item objects before copying an example across components

Compose Blode Components Completely

Blode UI components assume their companion pieces are present. Missing titles, groups, or fallbacks often means the component renders but behaves incorrectly or fails accessibility checks.

Incorrect (missing required structure):

<DialogContent>
  <div className="text-lg font-semibold">Edit profile</div>
  <Avatar>
    <AvatarImage src="/avatar.png" alt="Matthew" />
  </Avatar>
</DialogContent>

<SelectContent>
  <SelectItem value="starter">Starter</SelectItem>
  <SelectItem value="pro">Pro</SelectItem>
</SelectContent>

Correct (complete Blode composition):

<DialogContent>
  <DialogHeader>
    <DialogTitle>Edit profile</DialogTitle>
    <DialogDescription>Update your public details.</DialogDescription>
  </DialogHeader>

  <Avatar>
    <AvatarImage src="/avatar.png" alt="Matthew" />
    <AvatarFallback>MB</AvatarFallback>
  </Avatar>
</DialogContent>

<SelectContent>
  <SelectGroup>
    <SelectItem value="starter">Starter</SelectItem>
    <SelectItem value="pro">Pro</SelectItem>
  </SelectGroup>
</SelectContent>

Use these defaults:

• DialogTitle, SheetTitle, and DrawerTitle are required
• Item components stay inside their matching *Group
• Use full CardHeader / CardTitle / CardDescription / CardContent / CardFooter composition
• Use Alert, Empty, Separator, Skeleton, and Badge instead of rebuilding those patterns with custom markup
• Compose loading buttons with Spinner, data-icon, and disabled; do not invent isLoading or isPending props

Use Blode Field And Control Patterns

Blode forms should use the registry's field, group, and validation primitives instead of generic layout wrappers. The component set already encodes the spacing and accessibility behaviour the docs expect.

Incorrect (manual layout and improvised controls):

const [frequency, setFrequency] = useState("weekly")

<div className="space-y-4">
  <label htmlFor="email">Email</label>
  <Input id="email" />

  <div className="flex gap-2">
    {["daily", "weekly", "monthly"].map((option) => (
      <Button
        key={option}
        variant={frequency === option ? "default" : "outline"}
        onClick={() => setFrequency(option)}
      >
        {option}
      </Button>
    ))}
  </div>
</div>

Correct (Blode form composition):

<FieldGroup>
  <Field data-invalid>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" aria-invalid />
    <FieldDescription>Enter a valid email address.</FieldDescription>
  </Field>

  <Field orientation="horizontal">
    <FieldTitle id="frequency-label">Digest frequency</FieldTitle>
    <ToggleGroup aria-labelledby="frequency-label" spacing={2}>
      <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
      <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
      <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>
    </ToggleGroup>
  </Field>
</FieldGroup>

Use these defaults:

• FieldGroup plus Field for form layout
• InputGroupInput and InputGroupTextarea inside InputGroup
• FieldSet plus FieldLegend for grouped checkboxes or radios
• data-invalid on Field and aria-invalid on the invalid control
• gap-* spacing instead of space-*

Use Blode Icon Conventions

For Blode docs, examples, and repo code, default to blode-icons-react. Placement and sizing rules are part of the component language, so the package choice alone is not enough.

Incorrect (wrong package and manual icon sizing):

import { SearchIcon } from "lucide-react";

<Button>
  <SearchIcon className="mr-2 size-4" />
  Search
</Button>;

Correct (Blode package and component-managed sizing):

import { SearchIcon, ArrowRightIcon } from "blode-icons-react"

<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>

<Button variant="outline">
  Next
  <ArrowRightIcon data-icon="inline-end" />
</Button>

Use these icon rules:

• Default to blode-icons-react for Blode work in this repo
• Never use literal unicode or arrow glyphs (→, ↗, ←, ✓, ×) as icons — render the matching blode-icons-react component instead (e.g. <ArrowRightIcon data-icon="inline-end" />, not →)
• Add data-icon="inline-start" or data-icon="inline-end" inside buttons
• Do not add size-*, w-*, or h-* classes to icons inside Blode components
• Pass icon components as component objects, not string keys
• If a downstream project explicitly uses another icon library, adapt there without changing Blode docs or repo examples

Style With Blode Tokens And Variants

Blode UI is opinionated about taste. Prefer semantic tokens, built-in variants, and light-touch layout classes. Do not repaint components with arbitrary Tailwind colours or typography overrides.

Incorrect (raw colours and ad hoc overrides):

<Card className="bg-blue-100 text-blue-900 font-bold">
  <CardContent>
    <span className="text-emerald-600">+24%</span>
  </CardContent>
</Card>

Correct (semantic tokens and built-in variants):

<Card className="max-w-md">
  <CardContent className="flex items-center justify-between gap-3">
    <Badge variant="secondary">+24%</Badge>
    <Button variant="outline">View details</Button>
  </CardContent>
</Card>

Keep these defaults:

• Use semantic utilities like bg-background, text-foreground, and text-muted-foreground
• Prefer built-in variants before adding custom classes
• Use className for layout, spacing, and sizing, not for overriding core colour or typography
• Use gap-* instead of space-*
• Use size-* when width and height match
• Use cn() for conditional classes
• Do not add manual dark: colour overrides or arbitrary z-index values to overlay components