- 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)
- 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 " \n 1. Missing Fallbacks:" grep -rn 'var(--list-indent)[^,]' src/*/.css 2
/dev/null | grep -v '1em)' || echo " ✓ All fallbacks present" echo -e " \n 2. 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 " \n 3. 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 " \n 4. 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 " \n Done." 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 " \n Audit 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)