👁️ Argus — Design Intelligence Runtime

GIVE YOUR AGENT EYES.

Argus is a design intelligence runtime that gives AI coding agents the ability to see, judge, and learn from visual design quality. It runs locally, scores deterministically, and integrates with any agent via MCP.

AI agents can generate code fast but they can't see that your spacing is inconsistent, your contrast fails WCAG, or your heading hierarchy is broken. Argus fixes that. Not with LLM opinions — with measurable, reproducible, principle-based analysis.

Website · Docs · Vision · Getting Started · MCP Setup · Rules Reference · Discord

How it works

Your page / DOM / Screenshot
│
▼
┌─────────────────────────────┐
│ Inspector Layer │ ← See: DOM analysis, CSS extraction, a11y
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ Scorer Layer │ ← Judge: 49 rules, 6 categories, 0–100
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ Memory Layer │ ← Learn: preferences, profiles, export
└──────────────┬──────────────┘
│
▼
MCP Server ← Connect: any AI agent, any IDE

See. Judge. Learn. Connect.

Install

Runtime: Node 20+ (Node 22+ recommended).

npm install -g @argus-design/cli@latest
# or: pnpm add -g @argus-design/cli@latest
argus onboard

Getting started

# First-time setup
argus onboard
# Score a page
argus score https://your-app.com
# Full design + accessibility audit
argus audit https://your-app.com
# Export your taste profile for any AI agent
argus preferences export --format xml
# Check installation health
argus doctor

MCP setup

Add Argus to your AI agent's MCP configuration:

Claude Code / Claude Desktop

{
"mcpServers": {
"argus": {
"command": "argus",
"args": ["mcp"]
}
}
}

Cursor

Add to .cursor/mcp.json:

{
"mcpServers": {
"argus": {
"command": "argus",
"args": ["mcp"]
}
}
}

Windsurf / Copilot

Same pattern — point to argus mcp as the command.

Once connected, your agent has 8 design intelligence tools:

Tool	What it does
design.inspect	Analyze a page's visual structure
design.score	Score design quality (0–100)
design.suggest	Get actionable improvement suggestions
design.apply	Apply a fix and verify improvement
design.compare	Before/after comparison
design.preferences	Read/export your taste profile
design.audit	Full design + accessibility audit
design.doctor	Check Argus health

The four layers

Inspector — See

The inspector walks the DOM and captures everything an agent needs to understand a page visually:

• Element positions, dimensions, computed styles
• Margin, padding, gap values
• Accessibility properties (role, aria-label, contrast ratio, WCAG level)
• Color palette extraction
• Typography scale detection
• Spacing value inventory
• Structural analysis (heading hierarchy, layout patterns, sibling groups, landmarks)

import{walkDOM}from"@argus-design/inspector";constsnapshot=walkDOM({maxElements: 500});// → PageSnapshot with full visual state

Scorer — Judge

24 built-in rules across 6 categories. All deterministic. No LLM. Runs in milliseconds.

import{score,formatReport}from"@argus-design/scorer";constreport=score(snapshot);console.log(formatReport(report));// → Design Score: 82/100 (B+)// → Spacing: 90/100 ████████░░// → Typography: 75/100 ████████░░// → ...

Memory — Learn

Records what you approve and reject. Builds a taste profile over time. Exports as XML or JSON for any agent's system prompt.

import{MemoryStore}from"@argus-design/memory";conststore=newMemoryStore();store.recordDecision({context: "reject",selector: ".card",properties: ["border-radius"],values: {"border-radius": {from: "16px",to: "8px"}},timestamp: Date.now(),});constxml=store.exportXML();// → <design_preferences source="argus">// → <rule category="consistency" weight="0.80">AVOID border-radius: 16px</rule>// → </design_preferences>

MCP Server — Connect

Runs as a stdio MCP server. Any agent that supports MCP can connect and use all design intelligence tools.

argus mcp

Built-in rules (24)

Spacing (4 rules)

Rule	What it checks
spacing-scale	Margin/padding values align to 8px grid
spacing-consistency	Sibling elements have uniform gaps
spacing-variety	Reasonable number of distinct spacing values
container-padding	Container padding symmetry

Typography (5 rules)

Rule	What it checks
type-scale	Font sizes follow a mathematical scale ratio
font-size-variety	Reasonable number of distinct font sizes (4–7)
font-weight-usage	Font weights create clear hierarchy
line-height	Line heights in readable range (1.3–2.0)
font-family-count	1–3 font families (not 7)

Color (4 rules)

Rule	What it checks
color-palette-size	Focused color palette (not 47 grays)
contrast-compliance	WCAG AA contrast ratios for all text
color-consistency	No near-duplicate colors
pure-black-avoidance	#000 text on white (harsh — use #1a1a1a)

Hierarchy (4 rules)

Rule	What it checks
heading-size-progression	h1 > h2 > h3 in visual size
cta-dominance	Primary CTA is visually dominant
visual-weight-distribution	Clear focal points above the fold
heading-level-structure	No skipped heading levels

Accessibility (4 rules)

Rule	What it checks
image-alt-text	All images have alt attributes
touch-target-size	Interactive elements ≥ 24px (recommended: 44px)
landmark-presence	Page has <main> and <nav> landmarks
document-language	<html> has lang attribute

Consistency (4 rules)

Rule	What it checks
border-radius-consistency	2–4 border-radius values, not 12
shadow-consistency	Consistent elevation scale
custom-property-usage	CSS custom properties for design tokens
interactive-state-consistency	Buttons share consistent sizing

Score interpretation

Score	Grade	Meaning
95–100	A+	Ship it
90–94	A	Excellent
85–89	B+	Good
75–84	B	Solid
65–74	C+	Needs work
55–64	C	Significant issues
40–54	D	Major problems
0–39	F	Fundamental redesign needed

Skills

Skills are higher-level analysis workflows that combine multiple rules. Bundled skills:

Skill	What it does
accessibility	WCAG 2.1 AA compliance audit
spacing-audit	Spacing consistency and grid adherence
typography-audit	Typographic quality and scale analysis
color-harmony	Color palette quality and consistency
responsive-check	Basic responsive design checks
hierarchy-check	Visual hierarchy and information architecture

Custom skills live in ~/.argus/skills/<name>/SKILL.md.

CLI commands

argus onboard Guided first-time setup
argus inspect <url> Analyze page visual structure
argus score <url> Score design quality (0–100)
argus audit <url> Full design + accessibility audit
argus suggest <url> Get improvement suggestions
argus compare <a> <b> Compare two page states
argus preferences show Display current taste profile
argus preferences export Export profile (--format xml|json)
argus preferences reset Reset taste profile
argus doctor Check installation health
argus gateway Start local WebSocket gateway
argus mcp Start MCP server (stdio)
argus config View/edit configuration
argus version Print version

Development

git clone https://github.com/dragoon0x/argus.git
cd argus
pnpm install
pnpm build
pnpm test# Dev mode (auto-reload)
pnpm dev
# Run CLI in dev mode
pnpm argus score https://example.com
# Run MCP server in dev mode
pnpm mcp

Project structure

argus/
├── packages/ ← Core libraries (npm-publishable)
│ ├── protocol/ ← Shared types, interfaces, constants
│ ├── inspector/ ← DOM analysis, CSS extraction, a11y
│ ├── scorer/ ← 24 scoring rules, engine, reporter
│ ├── memory/ ← Preference learning, taste profiles
│ ├── flux/ ← CSS interpolation engine
│ ├── typo/ ← Typography engine
│ ├── pulse/ ← Animation/visualization engine
│ └── lens/ ← Inline component tweaking
├── apps/ ← Runnable applications
│ ├── cli/ ← `argus` command line tool
│ ├── mcp-server/ ← MCP server for AI agents
│ ├── gateway/ ← Local WebSocket server
│ └── browser-ext/ ← Chrome extension
├── skills/ ← Design analysis skills
├── extensions/ ← Tool integrations (Cursor, Figma, VS Code)
├── test/ ← Integration tests
├── docs/ ← Documentation
├── VISION.md ← Project philosophy and architecture
├── AGENTS.md ← Instructions for AI agents using Argus
├── CLAUDE.md ← Instructions for AI agents working on Argus
├── CONTRIBUTING.md ← How to contribute
├── SECURITY.md ← Security model
└── CHANGELOG.md ← Release history

Configuration

Minimal ~/.argus/config.json:

{
"version": 1,
"mcp": {
"port": 18790,
"bind": "loopback"
},
"scoring": {
"threshold": 70,
"enabledCategories": ["spacing", "typography", "color", "hierarchy", "accessibility", "consistency"]
},
"memory": {
"profileName": "default",
"historyEnabled": false
}
}

Security

• All processing happens locally. No data sent to external servers.
• MCP server binds to localhost by default.
• No telemetry. Argus does not phone home.
• Skills are markdown instruction files, not executable code.
• DOM content is treated as untrusted strings (never eval'd).

Full security guide: SECURITY.md

Design principles

1. Local-first. All data stays on your machine.
2. Deterministic. No LLM in the scoring loop. Results are reproducible.
3. Composable. Each package works independently.
4. Observable. Every score comes with full provenance.
5. Fast. Full page analysis in under 200ms.
6. Extensible. Write custom rules as simple functions.

Adding custom rules

importtype{ScoringRule}from"@argus-design/protocol";exportconstmyRule: ScoringRule={id: "my-custom-rule",name: "My Custom Rule",category: "consistency",description: "Checks something specific to my project",evaluate: (snapshot)=>{// Your analysis logic herereturn[{ruleId: "my-custom-rule",severity: "warning",category: "consistency",selector: ".target",message: "Something needs attention",measured: "what was found",expected: "what should be",suggestion: "how to fix it",impact: 10,}];},};

Development channels

• stable — tagged releases, npm dist-tag latest
• beta — prerelease tags, npm dist-tag beta
• dev — head of main, npm dist-tag dev

Everything built so far

Core platform

• Protocol package with 40+ shared types, Result pattern, constants, MCP tool definitions
• Inspector engine: DOM walker, CSS extractor, accessibility analyzer, structure analyzer
• Scorer engine: 24 rules across 6 categories, reporting, comparison, audit
• Memory system: file-based preference store, taste profiles, XML/JSON export
• CLI with 12 commands: onboard, inspect, score, audit, suggest, compare, preferences, doctor, gateway, mcp, config, version
• MCP server with 8 design intelligence tools

Rules coverage

• Spacing: grid adherence, gap consistency, value variety, container padding
• Typography: scale ratio, size variety, weight usage, line height, family count
• Color: palette size, contrast compliance, near-duplicates, pure black avoidance
• Hierarchy: heading progression, CTA dominance, visual weight, heading levels
• Accessibility: alt text, touch targets, landmarks, document language
• Consistency: border-radius, shadows, custom properties, interactive elements

Skills

• 6 bundled skills: accessibility, spacing-audit, typography-audit, color-harmony, responsive-check, hierarchy-check

Infrastructure

• pnpm workspace monorepo
• TypeScript strict mode throughout
• Vitest testing
• oxlint + prettier
• GitHub Actions CI
• Comprehensive documentation: VISION.md, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md

Community

• GitHub Issues for bugs and feature requests
• GitHub Discussions for questions and ideas
• Discord for real-time chat
• AI-assisted PRs welcome

See CONTRIBUTING.md for guidelines.

Disclaimer

This project is experimental and provided for educational purposes only. Argus is under active development and should not be relied upon as a sole measure of design quality in production environments. Scoring rules reflect opinionated design principles and may not suit every use case or design system. Always apply your own judgment. DYOR — do your own research before integrating into critical workflows.

License

MIT — see LICENSE.

---

"Design is direction, not decoration."

Built by Dragoon.