CSS Design System TDD

Overview

Apply TDD principles to CSS design system work:

• RED: Run checks that reveal current issues

• GREEN: Fix CSS to pass checks

• REFACTOR: Verify no regressions, clean up

Available Checks

1. Undefined Variable Check

Find CSS variables used but never defined:

Extract all var(--name) usages

grep -rhoE 'var(--[a-zA-Z0-9-]+' src/**/*.css | sort -u | sed 's/var(//' > /tmp/css-vars-used.txt

Extract all --name: definitions

grep -rhoE '^[[:space:]]--[a-zA-Z0-9-]+:' src/**/.css | sed 's/://' | sed 's/^[[:space:]]*//' | sort -u > /tmp/css-vars-defined.txt

Find undefined (used but not defined)

comm -23 /tmp/css-vars-used.txt /tmp/css-vars-defined.txt

2. Missing Fallback Check

Find var(--name) without fallbacks in container blocks:

Blockquote variables without fallback

grep -n 'var(--[^,)]*)[^,]' src/components/Editor/editor.css | grep -E 'blockquote|alert|details'

All containers - should have fallbacks for --list-indent, etc.

grep -rn 'var(--list-indent)' src/**/*.css # Should be var(--list-indent, 1em)

3. Hardcoded Color Check

Find hex/rgba colors that should be tokens:

Hex colors outside :root definitions

grep -rn '#[0-9a-fA-F]{3,6}' src/**/*.css | grep -v ':root' | grep -v 'var(--'

Hardcoded rgba (should be tokens in dark mode)

grep -rn 'rgba(255, 255, 255' src/**/*.css | grep -v ':root'

4. Container Consistency Check

Verify container blocks use consistent values:

Check margins across containers

echo "=== MARGINS ===" grep -rn 'margin:.em' src/components/Editor/editor.css src/plugins/alertBlock/.css src/plugins/detailsBlock/*.css

Check padding

echo "=== PADDING ===" grep -rn 'padding:' src/components/Editor/editor.css src/plugins/alertBlock/.css src/plugins/detailsBlock/.css | head -20

Check list multipliers

echo "=== LIST MULTIPLIERS ===" grep -rn 'list-indent.*' src/**/.css

5. Focus Indicator Check

Find interactive elements without focus styles:

Find elements with hover but no focus-visible

for file in src/**/*.css; do if grep -q ':hover' "$file" && ! grep -q ':focus-visible|:focus' "$file"; then echo "Missing focus: $file" fi done

6. Token Usage Audit

Check if specific tokens are used consistently:

Radius token usage

echo "=== RADIUS ===" grep -rn 'border-radius:' src/**/*.css | grep -v 'var(--radius'

Shadow token usage

echo "=== SHADOWS ===" grep -rn 'box-shadow:' src/**/*.css | grep -v 'var(--shadow|var(--popup-shadow'

TDD Workflow

Phase 1: RED (Establish Baseline)

Run all checks, save baseline

echo "=== CSS TDD BASELINE ===" > /tmp/css-baseline.txt echo "Date: $(date)" >> /tmp/css-baseline.txt

Run each check category

echo -e "\n### Undefined Variables ###" >> /tmp/css-baseline.txt

... run check 1 ...

echo -e "\n### Missing Fallbacks ###" >> /tmp/css-baseline.txt

... run check 2 ...

Count issues

echo -e "\n### Summary ###" >> /tmp/css-baseline.txt wc -l /tmp/css-baseline.txt

Phase 2: GREEN (Fix Issues)

For each issue category:

• Read the target file to understand context

• Make the minimal fix (add fallback, use token, etc.)

• Re-run the specific check to verify fix

Example fix workflow:

Before: verify issue exists

grep -n 'var(--list-indent)' src/components/Editor/editor.css

Make fix in editor.css (add fallback)

var(--list-indent) → var(--list-indent, 1em)

After: verify issue resolved

grep -n 'var(--list-indent)' src/components/Editor/editor.css # Should show fallbacks

Phase 3: REFACTOR (Verify No Regressions)

Run full check suite again

Compare to baseline - issues should decrease, not increase

Visual verification

pnpm dev # Check in browser: light mode, dark mode, all container types

Check Scripts

Quick Check (run before/after changes)

#!/bin/bash

scripts/css-quick-check.sh

echo "=== CSS Quick Check ==="

echo -e "\n1. Missing Fallbacks:" grep -rn 'var(--list-indent)[^,]' src/**/*.css 2>/dev/null | grep -v '1em)' || echo " ✓ All fallbacks present"

echo -e "\n2. Hardcoded Dark Hover:" grep -rn 'rgba(255, 255, 255, 0.08)' src/**/*.css 2>/dev/null | wc -l | xargs -I{} echo " {} occurrences (should be 0)"

echo -e "\n3. Container Margin Consistency:" echo " Blockquote:" && grep -o 'margin:.*em' src/components/Editor/editor.css | grep -A1 blockquote | head -1 echo " Alert:" && grep -o 'margin:.*em' src/plugins/alertBlock/alert-block.css | head -1 echo " Details:" && grep -o 'margin:.*em' src/plugins/detailsBlock/details-block.css | head -1

echo -e "\n4. Focus States:" for f in src/plugins/detailsBlock/.css src/plugins/alertBlock/.css; do if ! grep -q 'focus-visible' "$f" 2>/dev/null; then echo " Missing focus-visible: $f" fi done

echo -e "\nDone."

Full Audit (run before major changes)

#!/bin/bash

scripts/css-full-audit.sh

echo "=== CSS Full Audit ===" echo "Date: $(date)"

echo -e "\n## 1. Undefined Variables" grep -rhoE 'var(--[a-zA-Z0-9-]+' src//.css 2>/dev/null | sort -u | sed 's/var(//' > /tmp/used.txt grep -rhoE '^\s--[a-zA-Z0-9-]+:' src//*.css 2>/dev/null | sed 's/://' | tr -d ' ' | sort -u > /tmp/defined.txt comm -23 /tmp/used.txt /tmp/defined.txt

echo -e "\n## 2. Hardcoded Hex Colors (outside :root)" grep -rn '#[0-9a-fA-F]{3,6}' src/**/*.css 2>/dev/null | grep -v ':root' | grep -v '.svg' | wc -l

echo -e "\n## 3. Hardcoded Z-Index" grep -rn 'z-index: [0-9]' src/**/*.css 2>/dev/null | grep -v 'var(--' | wc -l

echo -e "\n## 4. Border Radius Not Using Tokens" grep -rn 'border-radius:' src/**/*.css 2>/dev/null | grep -v 'var(--radius' | grep -v '0' | wc -l

echo -e "\n## 5. Missing Focus Indicators" for f in $(find src -name "*.css" 2>/dev/null); do if grep -q ':hover' "$f" && ! grep -q ':focus' "$f"; then echo " $f" fi done

echo -e "\nAudit complete."

Container Block Checklist

When modifying container blocks (blockquote, alert, details):

• Margin uses 1em 0 (consistent)

• Padding uses token or 0.75em 1em pattern

• All var() calls have fallbacks

• :focus-visible defined for interactive elements

• Nested content rules exist (p, ul, ol, code, table)

• Border radius uses --radius-md

• Colors use tokens (no hardcoded hex in app CSS)

Integration with pnpm check:all

The CSS check scripts above are inline examples — run them directly in your terminal or save locally. They are not committed project scripts.

Reference Files

• Token definitions: src/styles/index.css

• Design system rules: .claude/rules/31-design-tokens.md

• Component patterns: .claude/rules/32-component-patterns.md

• Container audit: dev-docs/audit-reports/ (local, not in repo)