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)

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

Spacing Tokens

Rounding rules — ALWAYS round to nearest token:

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

Radius Tokens

Elevation Tokens (Box Shadows)

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

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

/* ❌ 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.

Legacy Variables (Replace Immediately)

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

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: