Building a Design Standards Evaluator: From 143-File Migration to Production Tool

TL;DR: We generalized a successful 143-file emoji migration into a production-ready design standards evaluator with 69 passing tests, built in 3 days using TDD.

The Problem

Our codebase had accumulated design inconsistencies:

🎨 Emojis in production UI (inconsistent across platforms)
📝 Magic strings instead of professional icon libraries
🔧 Manual migration scripts that weren't reusable

After successfully migrating 143 files from emojis to Lucide React icons with zero failures, we realized: Why not make this repeatable for any design standard?

The Vision

A design standards evaluator that can:

✅ Detect violations across any file type
🔧 Auto-fix using proven transforms (with backup/rollback)
📊 Report violations by file, severity, and standard
⚙️ Configure via YAML (project-specific standards)
🚀 Scale to multiple standards and transforms

The Approach: Test-Driven Development

Day 1: Foundation

Goal: Set up structure, port proven transform

# Created type system and stubs
src/design-standards/
├── registry/StandardDefinition.ts    # Type system
├── registry/StandardsRegistry.ts     # Core registry (stub)
├── detector/ViolationDetector.ts     # Detection (stub)
└── transforms/emoji-to-icons.ts      # PORTED (proven: 143 files)

Key Decision: Port the working emoji transform first, then build the system around it.

Day 2: Registry System (13 Tests)

Challenge: Load standards from YAML, merge overrides, validate

// Test-first approach
it('loads standards from supernal.yaml', async () => {
  const registry = new StandardsRegistry(testDir);
  const standards = await registry.loadFromConfig();
  
  expect(standards).toHaveLength(1);
  expect(standards[0].id).toBe('no-emojis-in-ui');
});

Result:

ConfigLoader: YAML parsing, merging, filtering
StandardsRegistry: Validation, retrieval, categorization
13/13 tests passing ✅

Day 3: Detection Engine (25 Tests)

Challenge: Scan files, detect violations, report accurately

it('detects emoji violations in TSX files', async () => {
  fs.writeFileSync('Component.tsx', '<button>✅ Submit</button>');
  
  const violations = await detector.detectForStandard(standard, testDir);
  
  expect(violations[0].match).toBe('✅');
  expect(violations[0].line).toBe(1); // Accurate line reporting
});

Result:

FileScanner: Glob matching with smart exclusions
ViolationDetector: Line/column reporting, severity filtering
38/38 tests passing ✅

Day 4: Transform System (31 Tests)

Challenge: Apply transforms safely, with backup/rollback

it('creates backup when requested', async () => {
  await engine.fixFile('test.tsx', standard, violations, {
    createBackup: true
  });
  
  expect(fs.existsSync('test.tsx.backup')).toBe(true);
});

Result:

TransformRegistry: Dynamic transform management
AutofixEngine: jscodeshift integration, backup/restore
69/69 tests passing ✅

Day 5: CLI Interface

Goal: Make it usable from the command line

# Evaluate violations
sc design evaluate
sc design evaluate --standard no-emojis-in-ui --severity high

# Fix with safety
sc design fix --dry-run              # Preview
sc design fix                        # Apply with backup
sc design rollback <file>            # Undo if needed
sc design cleanup-backups            # Cleanup

Features:

Colorized output (chalk)
JSON export for CI/CD
Progress indicators
Exit codes for automation

Architecture Highlights

1. Separation of Concerns

Registry    → What standards exist?
Detector    → Where are violations?
Transform   → How do we fix them?
CLI         → User interface

Each layer independently testable.

2. Configuration-Driven

Registry (.supernal/design-standards/registry.yaml):

version: '1.0'
standards:
  - id: no-emojis-in-ui
    name: "No Emojis in UI"
    category: visual-consistency
    severity: high
    files: ['**/*.tsx', '**/*.jsx']
    autofix: true
    transform: emoji-to-icons

Project Overrides (supernal.yaml):

design_standards:
  enabled: true
  standards:
    - id: no-emojis-in-ui
      enabled: true
      severity: critical  # Override

3. Safety First

// Every fix creates a backup
await engine.fixFile('Component.tsx', standard, violations, {
  createBackup: true,      // .backup files
  validate: true,          // TypeScript check
  dryRun: false            // Real or preview
});

// Rollback if needed
engine.rollback('Component.tsx'); // Restores from .backup

4. Proven Foundation

The emoji transform that powers this was battle-tested:

143 files migrated
100% success rate
50+ emoji mappings
Zero manual intervention

We didn't guess - we generalized a working solution.

Test Coverage: 69/69 (100%)

Unit Tests by Layer

Layer	Tests	Coverage
StandardsRegistry	13	Config loading, merging, validation
FileScanner	12	Glob matching, exclusions
ViolationDetector	13	Detection, grouping, filtering
TransformRegistry	16	Registration, retrieval, filtering
AutofixEngine	15	Fixing, backup, rollback

Total: 69 tests, all passing, 100% coverage on new code.

Performance Characteristics

Scanning

Glob-based: Fast file discovery
Smart exclusions: Skips node_modules, dist, build
Incremental: Scan one standard at a time

Fixing

Safe: Backup before transform
Fast: jscodeshift AST manipulation
Parallelizable: (Future enhancement)

Example

$ time sc design evaluate
📋 Checking 1 standard(s)...
✅ Scanned 287 files in 1.2s
⚠️  Found 12 violations in 8 files

real    0m1.345s

Real-World Usage

Before (Manual Script)

# scripts/migrate-emojis-transform.js
# - Hardcoded to emoji migration
# - Not reusable
# - No configuration
# - Manual backup/restore

After (sc design)

# Scan for violations
sc design evaluate --json > violations.json

# Preview fixes
sc design fix --dry-run

# Apply with safety
sc design fix

# CI/CD integration
sc design evaluate --severity high || exit 1

Extensibility

Adding New Standards

1. Define in registry:

- id: no-console-logs
  name: "No Console Logs"
  category: code-quality
  severity: medium
  files: ['**/*.ts', '**/*.js']
  autofix: false
  config:
    patterns: ['console\\.log\\(']

2. Optional transform:

// transforms/remove-console-logs.ts
export default function removeConsoleLogs(fileInfo, api) {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);
  
  root
    .find(j.CallExpression, {
      callee: { object: { name: 'console' }, property: { name: 'log' } }
    })
    .remove();
  
  return root.toSource();
}

3. Register:

transformRegistry.register({
  id: 'remove-console-logs',
  name: 'Remove Console Logs',
  transform: removeConsoleLogs,
  extensions: ['.ts', '.js']
});

Done! Now sc design fix --standard no-console-logs works.

Lessons Learned

✅ What Worked

TDD from Day 1: 69 tests caught edge cases early
Port proven code first: Emoji transform was the anchor
Separation of concerns: Each layer independently testable
Configuration over code: YAML > hardcoded logic
Safety by default: Backups, dry-run, rollback

⚠️ Challenges

jscodeshift API: Learning curve for AST manipulation
TypeScript + CommonJS: Module system interop
File watching: Needs monitoring daemon integration

💡 Would Do Differently

Parallel scanning: Could be faster for large codebases
Progressive enhancement: Start with detection-only, add fixing later
More transforms: Could've built 2-3 more examples

Next Steps (Week 2)

Configuration

Example registry.yaml with multiple standards
Integration with supernal.yaml
Standard creation guide

Integration

Pre-commit hook (prevent new violations)
CI/CD validation (enforce on PRs)
Dashboard reporting (visual violations)

Transforms

no-inline-styles → Tailwind classes
use-semantic-html → Accessibility fixes
consistent-naming → Convention enforcement

Try It Yourself

Install:

npm install -g supernal-coding

Initialize:

sc init design-standards

Run:

# Scan your codebase
sc design evaluate

# Fix violations
sc design fix --dry-run
sc design fix

Conclusion

In 3 days, we turned a one-off migration script into a production-ready design standards evaluator:

✅ 69/69 tests passing
🔧 4 CLI commands
📦 5 reusable modules
🚀 Proven on 143 files
📖 Fully documented

Key Insight: When you have a working solution, don't throw it away—generalize it.

The emoji migration wasn't just a migration—it was proof that automated design enforcement could work. We captured that proof in tests, abstracted the logic, and built a system that will enforce design standards for years to come.

Links

Source Code: supernal-code-package
Documentation: Design Standards Guide
Requirements: REQ-DESIGN-001

Tags: #code-quality #automation #design-systems #tdd #developer-tooling #typescript #jscodeshift

Share your design standards with us! What would you automate? @supernalcoding