Valentino Engine

Antifragile Open Source UI Design Engine — part of the HALE-BOPP family.

What is Valentino Engine?

Valentino Engine is a CSS/HTML audit tool and UI design engine that:

• Audits CSS and HTML for hardcoded values (px, hex, rgba, named colors) and enforces design token usage
• Runs visual audits via Playwright on files or live URLs (overflow, collisions, contrast)
• Validates PageSpec JSON — the contract that drives UI rendering
• Checks WCAG accessibility (contrast ratios AA/AAA)
• Provides 22 MCP tools for AI-agent integration
• Works as CLI, MCP server, or TypeScript library

Zero framework lock-in. No React, no Tailwind. Pure TypeScript.

When to use Valentino

| Situation | What to use | Example | |-----------|-------------|---------| | Audit a CSS/HTML file for design token violations | CLI valentino audit or valentino report | valentino report index.html --json | | Check a live running site for visual issues | CLI valentino visual-audit with URL | valentino visual-audit http://localhost:8765 --responsive | | AI agent needs to audit CSS during code review | MCP valentino_audit_css or valentino_report | Agent calls tool with CSS content | | AI agent needs visual audit on rendered page | MCP valentino_visual_audit | Agent passes URL, gets overflow/contrast results | | Validate a PageSpec before rendering | API validatePageSpec() | Import and call from TypeScript | | CI pipeline guardrail gate | CLI with exit codes | Exit 0=pass, 1=violations, 2=error, 3=no browser |

Quickstart

npm install @hale-bopp/valentino-engine

# Unified report: CSS guardrails + tokens + security in one command
valentino report ./styles/theme.css

# Same, but skip :root token definitions (avoid false positives)
valentino report index.html --allow-token-definitions

# Machine-readable JSON output
valentino report index.html --json --allow-token-definitions

# Visual audit on a live URL
valentino visual-audit http://localhost:8765

# Responsive visual audit (desktop 1440 + tablet 768 + mobile 390)
valentino visual-audit http://localhost:8765 --responsive --json

# Audit CSS only
valentino audit ./styles/theme.css --allow-token-definitions

# Audit HTML (inline styles + <style> tags)
valentino audit-html index.html --allow-token-definitions

# WCAG contrast check
valentino contrast "#333333" "#ffffff" AA

# Start MCP server (22 tools, stdio)
valentino mcp

CLI Commands (24)

Audit & Report

| Command | Description | |---------|-------------| | valentino audit <file.css> [--fix] [--no-backup] [--allow-token-definitions] | Audit CSS for guardrail violations | | valentino audit-html <file.html> [--fix] [--no-backup] [--allow-token-definitions] | Audit HTML (inline styles + <style> tags) | | valentino report <file> [--json] [--allow-token-definitions] | Unified report: audit + tokens + security | | valentino visual-audit <file\|URL> [--responsive] [--json] | Playwright visual audit (overflow, collision, contrast) | | valentino certify --security <file> | Security audit: inline styles, event handlers, token overrides |

Validation & Probes

| Command | Description | |---------|-------------| | valentino validate <spec.json> | Validate PageSpec V1 contract | | valentino validate-tokens <file.css> [--fix] | Detect circular/self-referencing CSS tokens | | valentino probe <rhythm\|hero\|integrity\|all> <spec.json> | Structural validation probes | | valentino contrast <fg> <bg> [AA\|AAA] | WCAG 2.1 contrast ratio | | valentino guardrails | List the 10 Sovereign Guardrails |

Design Tools

| Command | Description | |---------|-------------| | valentino figma import --file <json> [--template id] | Figma JSON -> PageSpec V1 | | valentino image generate --prompt "..." [--endpoint url] | Image generation (placeholder SVG or external) | | valentino spool <directory> [--out file] | Analyze site CSS -> token mapping | | valentino theme-audit <pack.json> [--level AA\|AAA] | Theme-pack WCAG contrast audit | | valentino template-audit <file> [--template jinja2\|twig\|ejs] | Template engine conflict detection | | valentino grid-contract init\|verify <file.html> | Grid layout contract | | valentino refactor <file> [--dry-run] [--apply] | CSS refactor with self-ref guard |

Interactive

| Command | Description | |---------|-------------| | valentino cockpit <spec.json> | Conversational REPL | | valentino cockpit <spec.json> --serve [--port N] | Web cockpit (browser UI, default port 3781) | | valentino watch <file\|directory> | File watcher with auto-audit | | valentino review-notes new\|add\|export\|stats | Structured review annotations |

Server

| Command | Description | |---------|-------------| | valentino mcp | Start MCP server (22 tools, stdio transport) |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Pass - no violations | | 1 | Violations found | | 2 | Tool/runtime error (bad args, file not found, etc.) | | 3 | Browser/Playwright not available |

MCP Server (22 Tools)

Connect any MCP-compatible AI agent:

{
  "mcpServers": {
    "valentino-engine": {
      "command": "npx",
      "args": ["@hale-bopp/valentino-engine", "mcp"]
    }
  }
}

Audit & Report Tools

| Tool | Description | |------|-------------| | valentino_audit_css | Audit CSS for hardcoded px, hex/rgba, named colors. Supports allowTokenDefinitions. | | valentino_audit_html | Audit HTML (<style> + inline). Supports allowTokenDefinitions. | | valentino_report | Unified report on a file (CSS guardrails + tokens + security). JSON output. | | valentino_visual_audit | Playwright visual audit on HTML content or live URL. Supports responsive mode. | | valentino_validate_tokens | Detect circular/self-referencing CSS custom properties | | valentino_validate_pagespec | Validate PageSpecV1 contract |

WCAG & Contrast Tools

| Tool | Description | |------|-------------| | valentino_check_contrast | WCAG 2.1 contrast ratio (AA/AAA) | | valentino_theme_audit | Theme-pack contrast audit across all surfaces | | valentino_probe_contrast_usage | Find text/accent variables used without surface remaps |

Probe Tools

| Tool | Description | |------|-------------| | valentino_probe_rhythm | Section sequence rhythm validation | | valentino_probe_hero | Hero section contract (CTA, copy density) | | valentino_probe_integrity | Per-type structural validation | | valentino_probe_all | All probes combined |

Design & Utility Tools

| Tool | Description | |------|-------------| | valentino_resolve_catalog | Resolve PageSpec with catalog blueprints | | valentino_resolve_route | URL route -> page ID | | valentino_get_skill | Design skill rules (premium-design, web-guardrails, design-guidelines) | | valentino_list_guardrails | List 10 Sovereign Guardrails from SSoT | | valentino_self_check | Engine self-diagnostics PASS/FAIL | | valentino_recommend | Guided CSS recommendations (suggestions, not errors) | | valentino_live_check | Real-time CSS check while writing (fragments OK) | | valentino_import_figma | Figma file -> PageSpec V1 | | valentino_generate_image | Image generation (placeholder SVG or external endpoint) |

Library API

import {
  // CSS Guardrails (with allowTokenDefinitions option)
  checkNoHardcodedPx, checkNoHardcodedColor, checkNoNamedColor,
  type GuardrailOptions,

  // HTML Audit
  auditHtml, fixHtml,

  // Unified Report
  generateReport, formatReport,
  type UnifiedReport, type ReportOptions,

  // Visual Audit (URL + responsive)
  runVisualAudit, runResponsiveAudit, formatVisualAudit,
  EXIT_CODES,
  type VisualAuditResult, type ResponsiveAuditResult,

  // Validation
  validatePageSpec, checkWcagContrast,

  // Token Validation
  validateTokens, fixSelfReferences,

  // Security Certification
  certifySecurity, certifySecurityCss,

  // Probes
  probeRhythm, probeHeroContract, probeSectionIntegrity,

  // Catalog & Presentation
  resolvePageSpecWithCatalog, resolvePresentation,

  // Types
  type PageSpecV1, type SectionSpec, type ValentinoCatalogV1,
} from '@hale-bopp/valentino-engine';

The --allow-token-definitions Flag

By default, Valentino flags ALL hardcoded px/color values, including CSS custom property definitions in :root:

:root {
  --vr-12: 12px;        /* flagged as "hardcoded px" */
  --vc-accent: #0072bc; /* flagged as "hardcoded color" */
}

These are token definitions, not hardcoded application values. Use --allow-token-definitions to skip them:

valentino report index.html --allow-token-definitions
valentino audit theme.css --allow-token-definitions
valentino audit-html index.html --allow-token-definitions

In the MCP tools, pass allowTokenDefinitions: true.

In the API, pass { allowTokenDefinitions: true } to any check function:

const violations = checkNoHardcodedPx(css, { allowTokenDefinitions: true });

Responsive Visual Audit

--responsive runs the audit at 3 viewports:

| Viewport | Width | Height | |----------|-------|--------| | Desktop | 1440 | 900 | | Tablet | 768 | 1024 | | Mobile | 390 | 844 |

valentino visual-audit http://localhost:8765 --responsive --json

Detects per-viewport: horizontal overflow, element collisions, WCAG contrast violations.

Requires Playwright:

npm install --save-dev playwright && npx playwright install chromium

Consumers

Projects that use Valentino Engine:

| Project | How | Purpose | |---------|-----|---------| | easyway-portal | npm dependency, API | PageSpec rendering, design token enforcement | | sn-desk | npm dependency, CLI | CSS/HTML audit, visual audit | | AI agents (via MCP) | MCP server | Automated CSS review, visual regression checks | | CI pipelines | CLI + exit codes | Guardrail gate before merge |

FAQ / Troubleshooting

"70+ violations on my :root token definitions"

Use --allow-token-definitions. Valentino treats --vr-12: 12px as hardcoded px by default. The flag skips lines that are CSS custom property declarations.

"visual-audit treats my URL as a file path"

Make sure the URL starts with http:// or https://. Valentino auto-detects: if it looks like a URL, it uses Playwright page.goto(); otherwise it reads the file.

"Cannot read properties of undefined (reading 'violations')"

This was a bug in pre-2.12.0. The visual audit now returns a structured error with phase field telling you exactly where it failed: browser-launch, page-create, content-load, or audit-script.

"Visual audit skipped: Playwright not installed"

Install Playwright: npm install --save-dev playwright && npx playwright install chromium. The audit gracefully skips (exit code 3) when Playwright is unavailable.

"MCP returns wrong branch strategy for valentino-engine"

The MCP reads factory-vcs.json from canonical paths. If it returns stale data, restart the MCP server. Since v2.12.0, stale bundled copies are no longer used as silent fallback.

"How do I get JSON output?"

Add --json to report or visual-audit commands:

valentino report index.html --json
valentino visual-audit http://localhost:8765 --responsive --json

MCP tools always return JSON.

The 10 Sovereign Guardrails

1. WhatIf di Layout -- Wireframe first, code second
2. Component Boundary & Fallbacks -- Error Boundaries on all API bridges
3. Design Token System -- No hardcoded colors or px values
4. L3 Audit before Commit -- ARIA, performance, and dependency check
5. Architecture Review -- Escalate trade-offs before committing
6. Zero UI-Debt -- Reuse before creating
7. Electrical Socket Pattern -- CSS root variables for all colors
8. Testudo Formation -- No inline padding/margin overrides on containers
9. Tangible Legacy -- No redundant CSS blocks
10. Visual Live Audit -- Playwright or valentino visual-audit

Contributing

PRs welcome! See CONTRIBUTING.md for guidelines.

License

MIT -- EasyWay Platform Team