unslop v2.1.1

unslop v2.1.1

⭐ If this tool helps your AI coding workflow, please give this repository a Star! It helps more developers discover the project.

VibeFoundry Agent Suite: 🎨 unslop — UI Design DNA & Anti-Slop Engine (npx -y unslop-mcp@latest init) · 🛡️ vibe-shield — Security Scanner for AI Code (npx -y @vibefoundry/vibe-shield@latest scan .) · 👻 ghost-qa — Autonomous Headless Browser QA (npx -y ghost-qa@latest test http://localhost:3000)

npx -y unslop-mcp@latest init

Your agent can write the code. unslop gives it a measurable design engineering protocol.

unslop is a zero-runtime-dependency UI/UX Design Engineering CLI, native MCP Server, and AI Agent Skill. It audits 72 rules across seven design craft pillars, installs ten studio-grade archetypes, extracts Design DNA, exports four token formats, and turns every finding into an exact, prioritized transformation blueprint for JSX/TSX, HTML, Vue, Svelte, CSS, and Tailwind codebases.

Works natively with Claude Code, OpenCode, OpenAI Codex, Cursor, Windsurf, GitHub Copilot, Cline/Roo Code, Zed, and universal Agent Skills.

Human-readable CLI audits and refactor plans include a copyable badge for the calculated grade and a GitHub star link. Commands that do not calculate a score show a clearly labeled example badge. JSON and MCP stdio are never decorated.

npx -y unslop-mcp init --preset linear-precision
npx -y unslop-mcp audit .
npx -y unslop-mcp refactor-plan . --report UNSLOP-REPORT.md

Supported Coding Agents (Claude Code, OpenCode, Codex, Cursor, Windsurf, Copilot, Cline, Zed)

Install the latest universal integrations directly from GitHub in any project (the published npm version may lag behind main):

npx -y github:avivgerz-hue/unslop#main init --preset linear-precision

Restart or reload the agent after installation so it discovers the new MCP server and Skill. Existing instructions outside Unslop's managed block, unrelated MCP servers, settings, inputs, and custom fields are preserved. Running init again is byte-for-byte idempotent.

This repository itself includes root AGENTS.md, CLAUDE.md, opencode.json, .claude-plugin/plugin.json, and both Claude/Codex Skill paths for immediate auto-discovery.

The result is not a generic prompt. It is a versioned token contract, a Design Craft Score from 0–100, a seven-pillar scorecard, exact before/after translations, and file-level steps your agent can execute in one coherent pass.

v2 at a glance

The 7-Pillar Design Craft Engine

Run a deterministic baseline before letting an agent rewrite the interface:

npx -y unslop-mcp audit . --json

Design Craft Score: 78/100 (C)
7-Pillar Scorecard:
  Color & Contrast: 82/100 (B) · 3 findings
  Typography & Hierarchy: 76/100 (C) · 4 findings
  Layout & Spatial Rhythm: 70/100 (C) · 5 findings
  Surface & Elevation: 88/100 (B) · 2 findings
  Copy & Microcopy: 82/100 (B) · 3 findings
  Interaction & Motion: 58/100 (F) · 7 findings
  Theme & Token Architecture: 90/100 (A) · 2 findings

Legacy slop/* IDs remain in output for compatibility. Canonical SLOP-* findings drive the v2 seven-pillar score, with location-level deduplication so compatibility output does not double-penalize a finding.

Scores with an action attached

Every audit includes exact file:line:column diagnostics and refactoring instructions. The overall score is the rounded mean of seven independently capped pillar scores; 95–100 is A+. Use --fail-under in CI or agent loops:

npx -y unslop-mcp audit . --fail-under 95
npx -y unslop-mcp audit . --prompt
npx -y unslop-mcp audit src --json --no-fail

Static analysis never replaces rendered verification. Keyboard operation, responsive behavior, actual contrast, content overflow, and reduced motion still need explicit inspection.

Design Transformation Blueprint

unslop_refactor_plan turns the audit into an executable Design Transformation Blueprint instead of a list of vague taste suggestions:

npx -y unslop-mcp refactor-plan . --preset linear-precision --report UNSLOP-REPORT.md

The report contains:

1. Design Craft Score and 7-Pillar Scorecard.
2. Before → After Class & Token Translation Table mapping detected classes, hex/RGB literals, off-grid values, and cliché copy to exact replacements from the selected archetype.
3. Prioritized P0/P1/P2 file:line steps covering the entire interface transformation.
4. Acceptance criteria for reaching 95–100 without suppressing rules or losing accessible states.

Example translations:

Use --json for the complete machine-readable blueprint:

npx -y unslop-mcp refactor-plan src --preset swiss-editorial --report reports/DESIGN.md --json

10 Studio-Grade Design Archetypes

Inspect and install a complete token and agent-rule contract:

npx -y unslop-mcp presets
npx -y unslop-mcp presets anthropic-warm-editorial
npx -y unslop-mcp init --preset anthropic-warm-editorial

Each archetype includes full surface hierarchy, explicit light/dark companions, typography scale and weights, spacing rhythm, radii, shadow/border elevation, layout contract, motion curve and spring values, plus ten archetype-specific design laws.

The v1 IDs linear-dark, swiss-grid, stripe-minimal, apple-glass, and neo-brutalist remain loadable for existing installations; the canonical v2 gallery contains the ten systems above.

Four token formats — presets or extracted DNA

Use the same deterministic exporter for a built-in archetype or extracted Design DNA.

Tailwind v4 @theme

npx -y unslop-mcp export-tokens --preset linear-precision --format tailwind-v4 --out tokens.css

Produces @theme, :root, and .dark contracts with semantic colors, fonts, fluid type, tracking, weights, radii, shadows, spacing, motion, and layout values.

Tailwind v3 configuration fragment

npx -y unslop-mcp export-tokens --preset linear-precision --format tailwind-v3 --out tailwind.config.js

Emits a mergeable theme.extend fragment with semantic utilities.

Pure CSS custom properties

npx -y unslop-mcp export-tokens --preset linear-precision --format css --out tokens.css

Emits standalone :root and .dark variables without requiring Tailwind.

W3C Design Tokens JSON

npx -y unslop-mcp export-tokens --preset linear-precision --format w3c-json --out tokens.json

Emits typed $type / $value groups for light and dark colors, typography, dimensions, radii, spacing, shadows, motion, and layout. A .json output path infers this format automatically.

Extract Design DNA from CSS or a URL

npx -y unslop-mcp extract https://example.com --name reference --json -o design-dna.json
npx -y unslop-mcp export-tokens --source https://example.com --name reference --format w3c-json --out tokens.json

The extractor reads local CSS or live HTML, inline styles, linked stylesheets, and @import graphs with explicit byte, request, and stylesheet budgets. Extraction warnings remain visible rather than silently inventing missing tokens.

Native MCP Server

Start the zero-dependency JSON-RPC 2.0 stdio server:

npx -y unslop-mcp --mcp

init merge-safely creates or updates .mcp.json without replacing unrelated servers, top-level settings, or custom fields on the unslop entry:

{
  "mcpServers": {
    "unslop": {
      "command": "npx",
      "args": ["-y", "unslop-mcp", "--mcp"]
    }
  }
}

Claude Code can register it explicitly:

claude mcp add --scope project unslop -- npx -y unslop-mcp --mcp

Positional mcp remains a backward-compatible alias for --mcp.

Principal UI/UX Design Engineer Skill

The rewritten SKILL.md is a five-step execution protocol for Claude Code, Cursor, Windsurf, and other coding agents:

1. Anti-Slop Diagnostic: baseline all seven pillars with unslop_audit.
2. Aesthetic Direction & Token Foundation: choose one archetype or extract Design DNA; install tokens before editing components.
3. Structural & Layout Transformation: use unslop_refactor_plan to replace clone layouts, enforce rhythm, and apply exact translations.
4. Surface, Typography & Copy Polish: implement semantic colors, WCAG contrast, fluid type, tabular numbers, and concrete product copy.
5. Interactive Ergonomics & Verification: complete focus and state behavior, then re-audit to 95–100/100 (A+) and inspect the rendered result.

init installs the selected contract into all native paths in the agent matrix above, including Claude/Codex Skills, Cursor and Copilot rules, and merge-safe MCP configuration for Claude Code, OpenCode, Cursor, VS Code, and Zed. Existing content outside managed blocks and unrelated JSON fields are preserved; repeated installs are byte-for-byte idempotent.

Alternative: zero-build GitHub execution

The npm package is the primary installation path. To execute the committed distribution directly from GitHub:

npx -y github:avivgerz-hue/unslop --version
npx -y github:avivgerz-hue/unslop init --preset linear-precision
npx -y github:avivgerz-hue/unslop --mcp

The repository includes dist/. During a GitHub install, prepare uses TypeScript when available and otherwise validates and reuses the committed runtime and all fifteen canonical-plus-legacy preset JSON files. No production dependency or local compilation step is required.

Docker MCP

docker build --tag unslop:mcp .
docker run --rm -i unslop:mcp

The image entrypoint is node dist/bin/unslop.js mcp. CI builds the image and verifies initialize, silent handling of notifications/initialized, and all four tools in tools/list over stdio with networking disabled.

Registry and citation metadata

• server.json follows the official MCP Registry schema and declares unslop-mcp 2.1.1 with the npx -y unslop-mcp mcp startup contract and four tool summaries.
• glama.json mirrors the exact MCP tool schemas and canonical archetype enum.
• smithery.yaml starts the native stdio server without additional configuration.
• CITATION.cff provides software citation metadata for VibeFoundry.

The npm package is published as unslop-mcp. These files support registry indexing but do not claim that a registry listing has occurred.

Development and verification

npm ci
npm run typecheck
npm test
npm run build

CI verifies Node.js 20 and 22, a production install without TypeScript, reproducible committed dist/, real CLI/MCP stdio negotiation, and the Docker MCP handshake. The v2 suite covers all seven pillars, all ten archetypes, every token format, extracted DNA, refactor blueprints, and manifest-driven 2.1.1 version output.

License

MIT · VibeFoundry