payloadcms/payload

Never commit a baseline PNG from any other source — a manual screenshot, a screenshot tool, an editor extension, an AI agent's screenshot capability, or a browser's own "save image" — even if it looks identical to you. Only a PNG written by the commands above is guaranteed to match what CI renders; anything else reads as a match locally and then fails every time on CI.

Colors: use semantic --color-* tokens from colors.css (e.g. --color-bg, --color-text-brand, --color-border). Never reference raw --ramp-* palette tokens directly outside of colors.css as they aren't theme-aware.

Baselines must be generated or updated inside the pinned Playwright Docker image, never on a bare host. Font rendering differs enough between operating systems that a baseline captured on macOS or Windows will fail the comparison on CI even when nothing visually changed.

Never use !important (plugin/no-important). Refactor selector specificity instead. Exceptions to this rule are when it's not possible to do so when dealing with external libraries.

Baselines must be generated/updated inside the pinned Playwright Docker image, never on a bare host — font rendering differs enough between operating systems to fail the comparison on CI even when nothing visually changed. Use pnpm test:visual:update.

Memoize arrays/objects passed to hooks: Never pass inline array/object literals to custom hooks - they create new references on every render, breaking memoization and causing unnecessary re-renders or remounts.

When a .server.tsx file needs to render a client component, it must import from the client exports bundle, not via relative path. Relative imports don't respect 'use client' boundaries in production builds.

If you come across an issue related to security, or a potential attack vector within Payload or one of its dependencies, please DO NOT create a publicly viewable issue. Instead, please contact us directly at dev@payloadcms.com. We will do everything we can to respond to the issue as soon as possible.

Only the four canonical breakpoints are allowed in a media query (plugin/no-non-standard-breakpoints): 400px, 768px, 1024px, 1440px. Don't invent one-off breakpoint values.

Do not initialize Payload manually or add database reset/seed hooks; the fixture initializes Payload once per file, resets and seeds before each test that uses it, and destroys it afterward

Translation/Label handling: Always use getTranslation from @payloadcms/translations when you need to render labels defined in the config - it already handles functions, strings, and translation objects correctly. Don't write custom if/else logic to handle different label types.