agentleFS
textura-agencytextura-agency/next16-claude-starter/.claude/skills/payload-admin/SKILL.md

payload-admin

Skill141 starsChanged 33 days agoUnlicenseView on GitHub

Make a Payload admin feel like part of the site and explain itself — the skin re-tinted from the site's own tokens (calm, light, no added motion), the site's wordmark and favicon, a dashboard welcome card, sidebar groups in reading order, rows named by their own copy, field notes in the editor's words, and an editor's guide inside the admin (/admin/guide) with a screenshot of every screen beside the entry that edits it, plus SEO and Analytics explained. Use after `payload-cms` is in, or when the user says the admin "looks bad", "hurts the eyes", "everything merges", "make it in the site's style", "add documentation / a guide / hints in the admin", "the client won't understand the admin".

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Nothing merges: Every tab a bordered pill, nested groups as soft panels with small headings (not a second big title on a vertical rule), …

    line 19
  2. Distinctive:

    Hover = colour only: No fills, underlines or shadows.

    line 22
  3. Very specific:

    Check contrast: --admin-muted on --admin-surface ≥ 4.5:1.

    line 44
  4. Distinctive:

    After a Payload upgrade: the same tour — class names are not a public API.

    line 97

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

The admin's look and its guide

An owner judges the CMS in the first minute: does it look like their site, and can they find the hero? This skill is how the reference site's admin went from "it hurts the eyes, everything merges" to a quiet, branded tool with its own manual. Kits: admin and guide (bash .claude/skills/payload-cms/scaffold.sh admin guide).

Principles (each was a correction from the owner)

  1. Light only (admin.theme: "light"). One theme done well beats two half-done.
  2. Calm, not loud. The first skin was bold and "hurt the eyes"; the one that stuck: pale ground, one white panel per screen, 13px muted labels, headings that step down by size not weight, the accent only on what can be pressed.
  3. Nothing merges. Every tab a bordered pill, nested groups as soft panels with small headings (not a second big title on a vertical rule), array rows in one rounded clipped frame (Payload's own 4px corners otherwise show through).
  4. Hover = colour only. No fills, underlines or shadows; no transitions or animation added (starter motion rules). Payload's own are kept.
  5. The site's marks: wordmark on the login card, favicon in the nav.
  6. The sidebar is the site: Home page (numbered, scroll order) → Site → Pages & documents → Insights → Help → Settings last.
  7. The editor's words everywhere: labels by what the reader sees ("Accent (highlighted part)"), a one-line note per global with the rule that matters before Save, row labels from the row's own copy ("03 · Design & ID").

§Skin — src/app/(payload)/custom.css

  1. Fill the Tier 1 block at the top (--admin-surface/ground/field/line/ navy/ink/muted/accent/accent-strong/accent-deep/good/bad/live) from the site's --raw-* values in globals.css. Those are the only raw colours in the file; Payload's whole --color-base-* ramp and --color-success-* are mixed from them (color-mix, oklab). --admin-ground is a paler tint of the site's ground — the site's own ground is usually too strong for a full-screen form.
  2. Fonts: add @font-face blocks for the site's self-hosted files (family "Site Sans") — a url() that doesn't resolve fails the build, so the kit ships none and falls back to the system stack.
  3. Unlayered rules beat Payload's @layer — no !important needed.
  4. Settings (users, media) is Payload's first group because collections list before globals; the skin moves it last with flex order. Keep that block.
  5. Check contrast: --admin-muted on --admin-surface ≥ 4.5:1.

Selector map and what each block targets: references/skin-map.md.

§Marks, welcome, rows

  • graphics.tsx — import the wordmark's SVG path from the site's component (export it once; never a second copy). Falls back to the brand name as text.
  • welcome.tsx — above the dashboard: what this admin is for, "Open the site ↗", "Read the guide". Say what stays in code.
  • row-label.tsx — NAME_KEYS (title, name, label, text, lead…): extend with the keys this project's cards use for their name.
  • payload.config.ts: meta.titleSuffix: " — <Brand> Content", the favicon, i18n English only (unless the owner asks otherwise — ask once).

§Guide — /admin/guide

The editor's documentation, inside the admin, read-only, no client code. Build it last: it documents the final sidebar.

  1. guide-content.tsx — plain data:
    • INTRO: how the admin works (sidebar = site; Save shows at once; blank is safe; what stays in code; no version history — retype to undo).
    • CHAPTERS: one entry per sidebar item, in sidebar order — where (the sidebar path), title (what they see), shot, fields (what changes, in the screen's words), notes (rules: a count the layout needs, links set in code, {name} placeholders, "keep it short — it paints with the first screen").
    • SEO (tab by tab, field by field, where each shows), ANALYTICS (number by number, how a visitor is counted, what is not stored), SETTINGS.
  2. Screenshots — the site's own screens, one per entry:
    yarn build && yarn start -p 4500
    node tools/qa/admin-shots.mjs --url http://localhost:4500/ \
      --shots "hero=#hero,header=header,footer=footer,not-found=/404" --save public/admin-guide
    1440 × 900, a person's UA (not the robot form), cookie banner and dev overlays hidden, each section scrolled into view and settled, 1200 px WebP (~40 KB). Look at every shot. Re-shoot when a screen changes — the guide shows whatever is in the folder.
  3. guide-body.tsx imports nothing of Payload's, so it can be rendered alone (that's how it is checked — Payload's template needs a signed-in user). guide-view.tsx wraps it in DefaultTemplate; guide-nav.tsx adds Help → Guide to the nav. yarn generate:importmap after adding them.
  4. next/image serves the WebPs — the admin pays for thumbnails.

Prove it

  • /admin/login, dashboard, a global with arrays + tabs (SEO), Media, Analytics, Guide — at 1440 and at 390 wide. Screenshot each and look.
  • Nothing merges: every tab, group and row has a visible edge.
  • Keyboard: focus ring visible (--accessibility-outline → accent).
  • yarn lint, yarn build.
  • After a Payload upgrade: the same tour — class names are not a public API.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.