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
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.
Runtime: Node 20+ (Node 22+ recommended).
npm install -g @argus-design/cli@latest
# or: pnpm add -g @argus-design/cli@latest
argus onboard# 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 doctorAdd Argus to your AI agent's MCP configuration:
{
"mcpServers": {
"argus": {
"command": "argus",
"args": ["mcp"]
}
}
}Add to .cursor/mcp.json:
{
"mcpServers": {
"argus": {
"command": "argus",
"args": ["mcp"]
}
}
}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 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";
const snapshot = walkDOM({ maxElements: 500 });
// → PageSnapshot with full visual state24 built-in rules across 6 categories. All deterministic. No LLM. Runs in milliseconds.
import { score, formatReport } from "@argus-design/scorer";
const report = score(snapshot);
console.log(formatReport(report));
// → Design Score: 82/100 (B+)
// → Spacing: 90/100 ████████░░
// → Typography: 75/100 ████████░░
// → ...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";
const store = new MemoryStore();
store.recordDecision({
context: "reject",
selector: ".card",
properties: ["border-radius"],
values: { "border-radius": { from: "16px", to: "8px" } },
timestamp: Date.now(),
});
const xml = store.exportXML();
// → <design_preferences source="argus">
// → <rule category="consistency" weight="0.80">AVOID border-radius: 16px</rule>
// → </design_preferences>Runs as a stdio MCP server. Any agent that supports MCP can connect and use all design intelligence tools.
argus mcp| 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 |
| 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) |
| 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) |
| 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 |
| 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 |
| 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 | 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 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.
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
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 mcpargus/
├── 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
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
}
}- 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
- Local-first. All data stays on your machine.
- Deterministic. No LLM in the scoring loop. Results are reproducible.
- Composable. Each package works independently.
- Observable. Every score comes with full provenance.
- Fast. Full page analysis in under 200ms.
- Extensible. Write custom rules as simple functions.
import type { ScoringRule } from "@argus-design/protocol";
export const myRule: ScoringRule = {
id: "my-custom-rule",
name: "My Custom Rule",
category: "consistency",
description: "Checks something specific to my project",
evaluate: (snapshot) => {
// Your analysis logic here
return [{
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,
}];
},
};- stable — tagged releases, npm dist-tag
latest - beta — prerelease tags, npm dist-tag
beta - dev — head of
main, npm dist-tagdev
- 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
- 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
- 6 bundled skills: accessibility, spacing-audit, typography-audit, color-harmony, responsive-check, hierarchy-check
- 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
- 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.
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.
MIT — see LICENSE.
"Design is direction, not decoration."
Built by Dragoon.