Contributing
How contributors should propose and ship new Payload Components.
Payload Components is open-source and community-first — adoption and contributions are the whole point.
Aim every contribution at making the install contract clearer, not just adding more UI. A component that installs cleanly and twice is worth more than a prettier block that drifts.
New component checklist
A component proposal should arrive complete — incomplete components don't ship:
A small, useful Payload block concept — narrow enough to verify, useful enough to install.
A block config with editor-friendly fields.
A frontend component that renders without extra app assumptions.
A manifest with files, fragments, dependencies, and sample content.
Install tests for both first install and repeated install.
Documentation explaining the target use case.
Visual standards
Every block speaks one visual language — light shadcn monochrome with a single emerald accent — defined as tokens in src/app/globals.css. Two checks keep new components on it, and both run in the release gate:
Colours come from tokens, never the raw palette. Reach for bg-card,
text-muted-foreground, border-border/70, text-primary, text-brand —
not bg-blue-500, text-white, or a hardcoded text-[#0a0a0a] /
bg-[oklch(…)]. The keywords transparent / current / inherit and
var(--…)-based values are fine.
Radius and letter-spacing use the named tokens, not arbitrary values:
rounded-frame / rounded-panel / rounded-card / rounded-inset (plus
rounded-lg / rounded-full), and tracking-eyebrow / tracking-display /
tracking-heading — not rounded-[2rem] or tracking-[-0.06em]. Spacing and
font size stay on the default scale.
tests/int/visual-standards.int.spec.ts enforces this statically across payload-components/source (and holds the landing twins to the colour palette), while tests/e2e/components-visual.e2e.spec.ts snapshots every component to catch anything pixels can see. Need a new radius or tracking value? Add a token to globals.css instead of reaching for an arbitrary value — the guard then allows it everywhere.
Pure layout geometry — aspect-[4/3], grid-cols-[auto_1fr_auto],
w-[calc(…)] — is per-component and stays arbitrary by design; only colour,
radius, letter-spacing, spacing, and font-size are token-governed.
Keep the catalog curated
The catalog grows by curation, not volume — every component must stay verifiable no matter how many ship.
A component is ready when it installs cleanly, can be run twice, and has docs good enough for another developer to reason about the target project changes.
Report install drift
If a supported Payload project shape changes, open an issue with enough context for the wrapper to update the support matrix — or reject the target shape clearly:
- Payload version
- Next.js version
- the failing command
- relevant
RenderBlocksandPagescollection snippets - the expected install result