Argus

👁️ Argus — Design Intelligence Runtime

GIVE YOUR AGENT EYES.

[](https://github.com/dragoon0x/argus/actions) [](https://www.npmjs.com/package/@argus-design/protocol) [](LICENSE)

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](VISION.md) · [Getting Started](#getting-started) · [MCP Setup](#mcp-setup) · [Rules Reference](#built-in-rules-24) · [Discord](#community)

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";

const snapshot = 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";

const report = 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";

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();
// → 
// →   AVOID border-radius: 16px
// → 

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 ` and landmarks | | document-language | 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//SKILL.md.

CLI commands

argus onboard              Guided first-time setup
argus inspect         Analyze page visual structure
argus score           Score design quality (0–100)
argus audit           Full design + accessibility audit
argus suggest         Get improvement suggestions
argus compare        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](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

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,
    }];
  },
};

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](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](LICENSE).

---

"Design is direction, not decoration."

Built by Dragoon.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dragoon0x
• Source: Dragoon0x/argus
• License: MIT
• Homepage: https://dragoon0x.github.io/argus/

Install and usage instructions live in the source repository linked above.