Token Reviewer

🔍 Token Reviewer — CSS Compliance Skill

Đảm bảo 100% giá trị CSS đều sử dụng tokens, không hardcode. Mục tiêu: CSS luôn theme-aware, density-aware, và centrally maintained.

How to Use This Skill

This skill is organized in 3 layers:

1. This file (SKILL.md) — Token hierarchy, violation summary, fix workflow, report template. Read this first.
2. references/ — Deep-dive rules, scan commands, mapping tables. Read only what's relevant.
3. Automated scripts — Run lint-css.js and verify-output.js for machine-checkable compliance.

Quick navigation:

• Running a review? → Quick Commands then Fix Process
• Hunting hardcoded values? → Read references/deep-scan-commands.md
• Need the token for a raw value? → Read resources/mapping-tables.md
• Understanding what's a violation? → Violation Summary then references/violation-rules.md
• Writing a compliance report? → Report Template

1. Token Hierarchy

CSS value → var(--component-token) → var(--semantic-token) → var(--primitive) → raw value
            components/*.json        --comp-*, --group-*     --spacing-*, --color-*   primitives/*.json

Why this hierarchy? Each layer serves a purpose:

• Component tokens — scoped to a specific component, swappable per variant
• Semantic tokens — theme-aware (light/dark), density-aware (compact/default)
• Primitives — base scale values, never used directly in CSS

Token Namespaces

Semantic Tokens (theme-aware)

• Colors: --primary, --secondary, --destructive, --warning, --success, --info + -foreground, -muted, -muted-foreground variants
• Base: --background, --foreground, --border, --muted, --card, --surface, --input + variants
• State layers: --state-layer-hover, --state-layer-focused, --state-layer-disable, --state-layer-colored-*
• Density (4-tier): --page-*, --section-*, --group-*, --comp-* (radius, margin, padding variants)

2. Violation Summary

❌ Violations — KHÔNG được phép

The core rule is simple: no raw CSS values for properties that have tokens.

📖 Full violation table with all types + rationale: references/violation-rules.md §1

✅ Exceptions — NOT violations

• 0 — zero value
• CSS keywords: auto, none, inherit, transparent, currentColor
• % in layout/gradient, calc() with tokens inside
• content: '', flex: 1, grid templates, -1px corrections
• @keyframes internals, media query breakpoints, animation 100%
• Demo/preview inline styles, z-index 1-10 (local stacking), :root {} definitions

📖 Full exceptions + warnings: references/violation-rules.md §2-§3

🔴 bg/fg Pairing

Canonical source: component-lifecycle/references/token-naming-states.md §2

Any element with background: var(--X) → color MUST be var(--X-foreground).

Why? Without pairing, theme switches (light → dark) can produce invisible text.

📖 Full mapping table: references/violation-rules.md §4

3. Validation Rules (output-specific)

These are structural errors in the token build output — different from style violations:

📖 Full rules with rationale: references/violation-rules.md §5

4. Deep Scan

Script lint-css.js may not catch all patterns. Use grep-based deep scan for comprehensive coverage:

📖 Full commands per violation type: references/deep-scan-commands.md

Quick start — most impactful scans:

## Font-weight raw numbers
grep -rn "font-weight:\s*[0-9]" showcase/style.css

## Color hex codes
grep -rn "#[0-9a-fA-F]\{3,8\}" showcase/style.css

## Fallback with raw px
grep -rn "var(--.*,\s*[0-9]" showcase/style.css

## rgba() hardcodes
grep -rn "rgba(" showcase/style.css

Specialized scans for dividers (§7) and titles (§8) are also in the reference file.

5. Fix Process

Why this order? Grouping by file minimizes I/O and review cycles. Mapping tables prevent guessing.

1. Nhóm violations theo file — easier to review and batch-fix
2. Tra Mapping Tables → resources/mapping-tables.md — xác định token thay thế chính xác
3. Dùng multi_replace_file_content — nhóm cùng file → 1 lần replace
4. Re-scan: node design-system/scripts/pipeline/lint-css.js --all → PHẢI đạt 0 violations
5. Deep scan: Run grep commands from references/deep-scan-commands.md → PHẢI 0 violations

6. Quick Commands

## Full pipeline (sync → review → verify → drift → audit)
node design-system/scripts/pipeline/run-pipeline.js --all

## Single file review
node design-system/scripts/pipeline/lint-css.js showcase/showcase-default/style.css

## Review-only step (skip sync + build)
node design-system/scripts/pipeline/run-pipeline.js --only=3

7. Compliance Report Template

Mỗi kết quả review PHẢI output theo format sau (phục vụ §4 ds-architect):

COMPLIANCE REPORT:
- File scanned  : showcase/{name}/style.css
- Scan time     : {timestamp}
- Total lines   : {N}

VIOLATIONS:
  🔴 ERRORS ({count}):
    [E1] Line {N}: {property}: {hardcoded-value}
         → Fix: {property}: var(--{token-name})

  🟡 WARNINGS ({count}):
    [W1] Line {N}: var(--{token}, {raw-fallback})
         → Fix: var(--{token}, var(--{primitive-token}))

  ✅ PASSES:
    - No hardcoded colors: ✅
    - No hardcoded spacing: ✅ | ❌ ({count} violations)
    - bg/fg pairs complete: ✅ | ❌ (missing: {list})
    - All var() references defined: ✅ | ❌

VERDICT: ✅ PASS | ❌ FAIL
- Error count   : {N}  (must be 0 to PASS)
- Warning count : {N}  (acceptable, should fix)
- bg/fg pairs   : {N}/{total} complete

Nhóm violations theo loại khi có nhiều lỗi:

GROUP BY TYPE:
1. Hardcoded colors   : {N} violations → lines: {list}
2. Hardcoded spacing  : {N} violations → lines: {list}
3. Hardcoded radius   : {N} violations → lines: {list}
4. Missing bg/fg pair : {N} violations → elements: {list}
5. Raw fallbacks      : {N} violations → lines: {list}
6. Undefined var()    : {N} violations → lines: {list}

PASS condition: Error count = 0. Warnings không block PASS nhưng phải có plan fix.

Anti-patterns (Quick Reference)

Reference Files