css-design-tdd

CSS デザインシステムの TDD

概要

TDD の原則を CSS デザインシステムの作業に適用します。

1. RED：現在の問題を明らかにするチェックを実行します
2. GREEN：チェックに合格するよう CSS を修正します
3. REFACTOR：リグレッションがないことを確認し、クリーンアップします

利用可能なチェック

1. 未定義変数のチェック

使用されているものの、定義されていない CSS 変数を見つけます。

# 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. フォールバック不足のチェック

コンテナブロック内で、フォールバックのない var(--name) を見つけます。

# 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. ハードコードされた色のチェック

トークンに置き換えるべき hex／rgba 色を見つけます。

# 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. コンテナの一貫性チェック

コンテナブロックで一貫した値が使用されていることを確認します。

# 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. フォーカスインジケーターのチェック

フォーカススタイルがないインタラクティブ要素を見つけます。

# 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. トークン使用状況の監査

特定のトークンが一貫して使用されているか確認します。

# 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 ワークフロー

フェーズ 1：RED（ベースラインの確立）

# 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

フェーズ 2：GREEN（問題の修正）

問題のカテゴリごとに、次の手順を行います。

1. 対象ファイルを読み、コンテキストを把握します
2. 最小限の修正を行います（フォールバックの追加、トークンの使用など）
3. 該当するチェックを再実行し、修正を確認します

修正ワークフローの例：

# 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

フェーズ 3：REFACTOR（リグレッションがないことを確認）

# 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

チェックスクリプト

クイックチェック（変更の前後に実行）

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

全体監査（大規模な変更の前に実行）

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

コンテナブロックのチェックリスト

コンテナブロック（blockquote、alert、details）を変更する場合：

• マージンに 1em 0 を使用している（一貫性がある）
• パディングにトークンまたは 0.75em 1em パターンを使用している
• すべての var() 呼び出しにフォールバックがある
• インタラクティブ要素に :focus-visible が定義されている
• ネストされたコンテンツのルールがある（p、ul、ol、code、table）
• 角丸に --radius-md を使用している
• 色にトークンを使用している（アプリの CSS にハードコードされた hex がない）

pnpm check:all との統合

上記の CSS チェックスクリプトはインラインの例です。ターミナルで直接実行するか、ローカルに保存してください。プロジェクトのスクリプトとしてコミットされているものではありません。

参照ファイル

• トークン定義：src/styles/index.css
• デザインシステムのルール：.claude/rules/31-design-tokens.md
• コンポーネントのパターン：.claude/rules/32-component-patterns.md
• コンテナ監査：dev-docs/audit/（リポジトリ内）