skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
payloadcms/payload88 installs

ui4-review

Review UI4 CSS migrations for proper token usage. Checks that CSS variables are used instead of hardcoded values.

How do I install this agent skill?

npx skills add https://github.com/payloadcms/payload --skill ui4-review
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is a design system migration utility that automates the transition from hardcoded CSS values to UI4 tokens. It uses standard shell tools like git and grep to identify patterns and performs local string replacements. No malicious behaviors or security risks were identified.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

UI4 Review

Reviews CSS changes and auto-fixes token violations.


Important: Palette vs Semantic Tokens

--ramp-* tokens are the raw color palette (e.g., --ramp-white-1000, --ramp-blue-500). These are used only in colors.css to define semantic tokens.

--color-* tokens are context-aware semantic tokens (e.g., --color-bg, --color-text-brand). These handle light/dark theming automatically.

Components and elements should ALWAYS use --color-* semantic tokens, never --ramp-* palette tokens directly.

/* ❌ BAD - using raw palette */
background: var(--ramp-white-1000);

/* ✅ GOOD - using semantic token */
background: var(--color-bg);

Process

Step 1: Get Changed CSS Files

git status --porcelain | grep '\.css$'

Or if a specific file is provided, use that directly.

Step 2: Parallel Violation Detection

Run these grep searches IN PARALLEL to detect all violation types at once:

# 1. SCSS Nesting Violations (BEM patterns that don't work in CSS)
grep -n '&__\|&--' "$FILE"

# 2. Hardcoded Spacing (px/rem values that should be tokens)
grep -nE ':\s*[0-9]+px|:\s*[0-9.]+rem' "$FILE"

# 3. Hardcoded Colors (hex, rgb, rgba - includes box-shadow)
grep -nE '#[0-9a-fA-F]{3,8}|rgba?\(' "$FILE"

# 4. Legacy Theme Variables
grep -nE 'var\(--theme-|var\(--style-|var\(--base\)' "$FILE"

# 5. Old Token Names (pre-UI4 naming)
grep -nE '\-\-bg-default|\-\-bg-secondary|\-\-text-default|\-\-text-secondary|\-\-icon-default|\-\-icon-secondary|\-\-border-default|\-\-border-strong' "$FILE"

# 6. Raw Palette Usage (should use semantic tokens instead)
# Skip this check for colors.css which defines the semantic tokens
grep -nE 'var\(--ramp-' "$FILE"

Invoke all 6 grep commands in a single parallel batch, then analyze results.

Note: Raw --ramp-* violations are only flagged in component CSS files, not in colors.css where they're used to define semantic tokens.

Step 3: Auto-Fix by Priority

  1. SCSS Nesting (breaks CSS entirely) — Fix first
  2. Legacy Variables (deprecated) — Replace with new tokens
  3. Old Token Names (pre-UI4) — Convert to --color-* naming
  4. Raw Palette Usage (--ramp-* in components) — Replace with semantic --color-* tokens
  5. Hardcoded Values (spacing, colors, radius) — Replace with tokens

Step 4: Report

After fixing, report:

  • Total violations found
  • Violations auto-fixed
  • Violations that need manual review (no clear token match)

Violation Reference

SCSS Nesting (BREAKS CSS)

PatternIssueFix
&__elementBEM element concatUse flat .block__element selector
&--modifierBEM modifier concatUse flat .block--modifier selector
.child { .parent--mod & }Parent referenceMove to .parent--mod .child

What DOES work: &:hover, &:focus, &::before, & .child


Spacing Tokens

ValueToken
4px / 0.25rem--spacer-1
8px / 0.5rem--spacer-2
12px / 0.75rem--spacer-2-5
16px / 1rem--spacer-3
24px / 1.5rem--spacer-4
32px / 2rem--spacer-5
40px / 2.5rem--spacer-6

Rounding rules — ALWAYS round to nearest token:

Pixel RangeTokenNotes
0-2px--spacer-0Use 0
3-6px--spacer-1 (4px)5-6px rounds to 4px
7-10px--spacer-2 (8px)10px rounds DOWN to 8px
11-14px--spacer-2-5 (12px)13.33px rounds to 12px
15-20px--spacer-3 (16px)15px, 20px both round to 16px
21-28px--spacer-4 (24px)
29-36px--spacer-5 (32px)30px rounds to 32px
37-48px--spacer-6 (40px)

Rule: For values ≤ 40px, ALWAYS use a single token (no calc()). For values > 40px, use calc() with a spacer token.

Exceptions: 0, percentages, auto, inherit, -1px (for clip offsets)


Stroke Width Tokens

ValueToken
1px--stroke-width-small

Radius Tokens

ValueToken
2px / 0.125rem--radius-small
5px / 0.3125rem--radius-medium
13px / 0.8125rem--radius-large
9999px--radius-full

Elevation Tokens (Box Shadows)

Defined in packages/ui/src/css/elevations.css.

Never use hardcoded rgba() for box-shadows. Use elevation tokens instead:

TokenUse Case
--elevation-300-tooltipTooltips, small floating elements
--elevation-400-menu-panelMenus, dropdowns, floating panels
--elevation-500-modal-windowModals, dialogs, full overlays
/* ❌ BAD - hardcoded shadow */
box-shadow: 0 -2px 16px -2px rgba(0, 0, 0, 0.2);

/* ✅ GOOD - elevation token */
box-shadow: var(--elevation-400-menu-panel);

Elevations automatically adjust for light/dark themes.


Semantic Color Tokens (UI4 Naming)

All semantic colors use the --color- prefix. The default category and variant are implicit.

Old NameNew Name (UI4)
--bg-default--color-bg
--bg-secondary--color-bg-secondary
--bg-hover--color-bg-hover
--bg-selected--color-bg-selected
--bg-brand--color-bg-brand
--bg-danger--color-bg-danger
--bg-success--color-bg-success
--bg-warning--color-bg-warning
--text-default--color-text
--text-secondary--color-text-secondary
--text-tertiary--color-text-tertiary
--text-brand--color-text-brand
--text-danger--color-text-danger
--text-success--color-text-success
--icon-default--color-icon
--icon-secondary--color-icon-secondary
--icon-tertiary--color-icon-tertiary
--icon-brand--color-icon-brand
--icon-danger--color-icon-danger
--border-default--color-border
--border-strong--color-border-strong
--border-selected--color-border-selected
--border-brand--color-border-brand

Legacy Variables (Replace Immediately)

LegacyReplacement
--theme-elevation-0--color-bg
--theme-elevation-50--color-bg-secondary
--theme-elevation-100--color-border
--theme-text--color-text
--style-radius-m--radius-medium

var(--base) Conversion: Legacy token = 20px. Convert using:

OriginalPixelsReplacement
var(--base) * 0.48pxvar(--spacer-2)
var(--base) * 0.510pxcalc(var(--spacer-1) * 2.5)
var(--base) * 0.612pxvar(--spacer-2-5)
var(--base)20pxcalc(var(--spacer-4) * 0.833)
var(--base) * 240pxvar(--spacer-6)

See ui4 skill Step 1 for full conversion table.


Behavior

DO NOT just report violations. FIX THEM immediately using replace_string_in_file or multi_replace_string_in_file.

When a violation has no clear token match (e.g., 3px or an unusual rem value), flag it for manual review but don't guess.

For each violation:

  1. Identify the exact line and value
  2. Determine the correct token replacement
  3. Use replace_string_in_file to fix it immediately
  4. Report what was fixed

Only flag (don't fix) when:

  • No matching token exists (e.g., 18px badge size)
  • Value is intentional (e.g., 1px border, 0)
  • Ambiguous replacement

Empty CSS files: If a component's CSS file becomes empty after migration (all styles now handled by shared components like Button), delete the CSS file and remove its import from the component.


Output Format

After auto-fixing, report:

## Auto-Fixed

✅ Collapsible/index.css:9 — `height: 2rem` → `height: var(--spacer-5)`
✅ Collapsible/index.css:120 — `width: 2rem` → `width: var(--spacer-5)`

## Flagged (Manual Review)

⚠️ ErrorPill/index.css:15 — `height: 1.125rem` (18px) — no matching token

Summary

After all fixes, provide a simple summary:

FileFixedFlagged
Collapsible/index.css21
ErrorPill/index.css02

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/payloadcms/payload/ui4-review">View ui4-review on skillZs</a>