Skip to content
Case studyPayload Components · 2026

Payload Components

An open-source registry and CLI that installs Payload CMS blocks — wired, not pasted. This is how it was designed, from the mark down to the last hairline.

Year
2026
Scope
Identity, CLI, docs, components
Stack
Payload v3 · Next.js · shadcn
License
MIT, end to end

Scroll

01The brief

Copying a block is easy. Making it live is the job.

A pasted Payload block does nothing until four more edits land — the schema, the renderer, the types, the import map. On every project, by hand, then proven by hand. The brief was to make all five one step.

02The idea

Wired, not pasted.

Three words carry the whole product. Everything below is those words made visible: blocks that key together, one wire, one accent.

03Identity

Two blocks, keyed.

Two equal squares overlap on the diagonal: separate pieces fitted into one shape, which is what the installer does. It replaced a prompt-and-cursor mark that stopped reading as a prompt at tab size, so candidates were judged at 16 pixels, not at poster size.

192px
96px
48px
24px
16px

RetiredThe prompt-and-cursor mark, at the three sizes where it failed.

Specimen — the shipping mark from 192px to a 16px browser tab, on one baseline. The union has no seam to lose, so the silhouette survives every step down.
actual size
Pixel study — the mark rasterized at 16 × 16. Each cell is the share of that pixel the emerald covers; the outline is the vector it came from.

04Color

One accent.

Zinc builds the structure. Emerald appears only when something means yes — active, installed, linked — so color never has to be decoded.

  • Paper--background
  • Quiet surface--muted
  • Hairline--border
  • Second ink--muted-foreground
  • Ink--foreground
  • The accent--brand
Study after Josef Albers, Homage to the Square (1950–1976): six tokens, nested from paper to the accent.

05Type

Three faces, one voice.

Geist Sans
Does the work: prose, headings, controls.
Instrument Serif
One italic word per heading. Never a paragraph.
Geist Mono
Anything you might copy: commands, paths, versions.

06The system

Five artifacts, one command.

npx payload-components add runs the whole chain in one pass and lands it as a single diff you review like any pull request.

  1. 01 / 05

    Copy the source

    The block config, component, and shared fields land in src/blocks/.

    src/blocks/

  2. 02 / 05

    Register the block

    Added to your Pages collection in src/collections/Pages/index.ts.

    src/collections/Pages/index.ts

  3. 03 / 05

    Map the renderer

    Wired into src/blocks/RenderBlocks.tsx so the page renders it.

    src/blocks/RenderBlocks.tsx

  4. 04 / 05

    Regenerate types

    payload generate:types updates src/payload-types.ts.

    src/payload-types.ts

  5. 05 / 05

    Regenerate the import map

    payload generate:importmap updates the admin import map.

    src/app/(payload)/admin/importMap.js

07The work

82 components, none of them mockups.

Every preview is the real block's demo twin, rendered from the same registry the docs use and held to its source class by class.

Browse the catalog

08Details

The craft is in the small print.

Second ink. --muted-foreground sits at 46% lightness, about 7.1:1 on white — muted, and still well past AA's 4.5.
The one dark surface. The terminal frame keeps its own tokens on every page: it is the product, not a second theme.
A receipt. Every decision in the design philosophy names what it replaced and links the file that enforces it.

09Outcomes

By the numbers.

components in the registry
82
site templates composed from them
15
artifacts wired by every install
5
runtime dependencies in the published CLI
2
accent color, end to end
1
pricing tiers, license keys, or waitlists
0

10Credits

Typefaces
Geist Sans and Geist Mono by Vercel; Instrument Serif
Built with
Next.js, Fumadocs, Tailwind CSS, shadcn/ui
Made for
Payload CMS v3 on Next.js
Color study
After Josef Albers, Homage to the Square
License
MIT — registry, CLI, components, and this site
github.com/Ducksss/payload-components

Next

Read the design philosophy

The principles, the decision ledger with a receipt for every choice, and the rules behind this page.