CSS Design System TDD

CSS设计系统测试驱动开发（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

将测试驱动开发（TDD）原则应用于CSS设计系统工作：

RED（红）：运行检查以暴露当前问题
GREEN（绿）：修复CSS以通过检查
REFACTOR（重构）：验证无回归问题，清理代码

Available Checks

可用检查项

1. Undefined Variable Check

1. 未定义变量检查

Find CSS variables used but never defined:

bash

undefined

查找已使用但从未定义的CSS变量：

bash

undefined

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

undefined

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

undefined

2. Missing Fallback Check

2. 缺失回退检查

Find

var(--name)

without fallbacks in container blocks:

bash

undefined

查找容器块中没有回退值的

var(--name)

：

bash

undefined

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)

undefined

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

undefined

3. Hardcoded Color Check

3. 硬编码颜色检查

Find hex/rgba colors that should be tokens:

bash

undefined

查找应使用令牌表示的十六进制/rgba颜色：

bash

undefined

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'

undefined

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

undefined

4. Container Consistency Check

4. 容器一致性检查

Verify container blocks use consistent values:

bash

undefined

验证容器块使用一致的值：

bash

undefined

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

undefined

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

undefined

5. Focus Indicator Check

5. 焦点指示器检查

Find interactive elements without focus styles:

bash

undefined

查找没有焦点样式的交互元素：

bash

undefined

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

undefined

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

undefined

6. Token Usage Audit

6. 令牌使用审计

Check if specific tokens are used consistently:

bash

undefined

检查特定令牌是否被一致使用：

bash

undefined

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'

undefined

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

undefined

TDD Workflow

TDD工作流程

Phase 1: RED (Establish Baseline)

阶段1：RED（建立基准）

bash

undefined

bash

undefined

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

undefined

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

undefined

Phase 2: GREEN (Fix Issues)

阶段2：GREEN（修复问题）

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:

bash

undefined

针对每个问题类别：

阅读目标文件以理解上下文
进行最小化修复（添加回退、使用令牌等）
重新运行特定检查以验证修复效果

示例修复流程：

bash

undefined

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

undefined

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

undefined

Phase 3: REFACTOR (Verify No Regressions)

阶段3：REFACTOR（验证无回归）

bash

undefined

bash

undefined

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

undefined

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

undefined

Check Scripts

检查脚本

Quick Check (run before/after changes)

快速检查（变更前后运行）

bash

#!/bin/bash

bash

#!/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."

undefined

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."

undefined

Full Audit (run before major changes)

全面审计（重大变更前运行）

bash

#!/bin/bash

bash

#!/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."

undefined

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."

undefined

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)

修改容器块（blockquote、alert、details）时：

外边距使用
```
1em 0
```
（保持一致）
内边距使用令牌或
```
0.75em 1em
```
模式
所有
```
var()
```
调用都有回退值
为交互元素定义了
```
:focus-visible
```
存在嵌套内容规则（p、ul、ol、code、table）
圆角使用
```
--radius-md
```
颜色使用令牌（应用CSS中无硬编码十六进制值）

Integration with pnpm check:all

与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.

上述CSS检查脚本是内联示例——可直接在终端运行或本地保存。它们并非已提交的项目脚本。

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)

令牌定义：
```
src/styles/index.css
```
设计系统规则：
```
.claude/rules/31-design-tokens.md
```
组件模式：
```
.claude/rules/32-component-patterns.md
```
容器审计：
```
dev-docs/audit-reports/
```
（本地文件，不在仓库中）

css-design-tdd

Original

Translation

CSS Design System TDD

CSS设计系统测试驱动开发（TDD）

Overview

概述

Available Checks

可用检查项

1. Undefined Variable Check

1. 未定义变量检查

Extract all var(--name) usages

Extract all var(--name) usages

Extract all --name: definitions

Extract all --name: definitions

Find undefined (used but not defined)

Find undefined (used but not defined)

2. Missing Fallback Check

2. 缺失回退检查

Blockquote variables without fallback

Blockquote variables without fallback

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

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

3. Hardcoded Color Check

3. 硬编码颜色检查

Hex colors outside :root definitions

Hex colors outside :root definitions

Hardcoded rgba (should be tokens in dark mode)

Hardcoded rgba (should be tokens in dark mode)

4. Container Consistency Check

4. 容器一致性检查

Check margins across containers

Check margins across containers

Check padding

Check padding

Check list multipliers

Check list multipliers

5. Focus Indicator Check

5. 焦点指示器检查

Find elements with hover but no focus-visible

Find elements with hover but no focus-visible

6. Token Usage Audit

6. 令牌使用审计

Radius token usage

Radius token usage

Shadow token usage

Shadow token usage

TDD Workflow

TDD工作流程

Phase 1: RED (Establish Baseline)

阶段1：RED（建立基准）

Run all checks, save baseline

Run all checks, save baseline

Run each check category

Run each check category

... run check 1 ...

... run check 1 ...

... run check 2 ...

... run check 2 ...

Count issues

Count issues

Phase 2: GREEN (Fix Issues)

阶段2：GREEN（修复问题）

Before: verify issue exists

Before: verify issue exists

Make fix in editor.css (add fallback)

Make fix in editor.css (add fallback)

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

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

After: verify issue resolved

After: verify issue resolved

Phase 3: REFACTOR (Verify No Regressions)

阶段3：REFACTOR（验证无回归）

Run full check suite again

Run full check suite again

Compare to baseline - issues should decrease, not increase

Compare to baseline - issues should decrease, not increase

Visual verification

Visual verification

Check Scripts