@monoes/monodesign

Frontend design intelligence for AI agents — OKLCH design tokens, a 51-rule AI-slop antipattern detector, and the /monodesign agent skill for Claude Code and Gemini agy.

Part of the Monomind ecosystem. v1.2.4 · Apache-2.0

Install

npm install @monoes/monodesign

What's Inside

| Module | Export path | Purpose | |---|---|---| | Design tokens (TS) | @monoes/monodesign | Typed constants for font, spacing, color, motion | | Design tokens (CSS) | @monoes/monodesign/tokens | CSS custom properties (tokens.css) | | Detection engine | @monoes/monodesign/engine | Node-side 51-rule antipattern detector | | Browser bundle | @monoes/monodesign/engine/browser | Browser-compatible detector (no Node deps) |

Design Tokens

Source: src/tokens.ts + src/tokens.css

All color tokens are in OKLCH — no hex colors in the token system.

Token Categories

| Category | Key Values | |---|---| | Typography | Fonts: 'Cormorant Garamond' (display), 'Instrument Sans' (body), 'Space Grotesk' (mono). Scale: xs (12px) → 7xl (72px). Line-heights: 1.2–2.0 | | Spacing | 8px base grid: --space-1 (4px) → --space-30 (120px) | | Color | Neutrals: ink/charcoal/ash/mist/cream/paper/white. Accent: Editorial Magenta oklch(60% 0.25 350) with 9-stop tonal ramp | | Motion | Expo-out primary cubic-bezier(0.16,1,0.3,1), plus quint, in-out, in. Durations: 0s → 1.2s | | Shadows | sm/md/lg/accent. Max 0.15 alpha. | | Radius | none(0) → sm(4px) → md(8px) → lg(12px) → xl(16px) → full(9999px) | | Z-index | Named scale: below(−1) → base(0) → raised(1) → overlay(10) → modal(20) → toast(30) → top(40) |

CSS Usage

/* Import CSS custom properties */
@import '@monoes/monodesign/tokens';

.hero {
  font-family: var(--font-display);
  color: var(--color-ink);
  padding: var(--space-8);
  border-radius: var(--radius-lg);
  transition: transform var(--duration-default) var(--easing-expo-out);
}

TypeScript Usage

import { fontFamily, fontSize, spacing, easing, duration, color, accentScale, shadow, radius } from '@monoes/monodesign';

console.log(color.accent);    // oklch(60% 0.25 350)
console.log(spacing[8]);      // 32px
console.log(radius.lg);       // 12px

Antipattern Detection (51 Rules)

Source: cli/engine/registry/antipatterns.mjs (entry point, re-exports from antipatterns-slop.mjs, antipatterns-quality.mjs and antipatterns-provider.mjs) — 51 entries.

Rule Categories

slop (21 rules) — AI-generation tells that make UIs feel generic:

side-tab, border-accent-on-rounded, overused-font, single-font, flat-type-hierarchy, gradient-text, ai-color-palette, cream-palette, nested-cards, monotonous-spacing, bounce-easing, dark-glow, icon-tile-stack, italic-serif-display, hero-eyebrow-chip, repeated-section-kickers, numbered-section-markers, em-dash-overuse, marketing-buzzword, aphoristic-cadence, oversized-h1, extreme-negative-tracking, broken-image

quality (24 rules) — Accessibility and design principle violations:

gray-on-color, low-contrast, layout-transition, line-length, cramped-padding, body-text-viewport-edge, tight-leading, skipped-heading, justified-text, tiny-text, all-caps-body, wide-tracking, text-overflow, clipped-overflow-container, design-system-font, design-system-color, design-system-radius, design-system-font-size, missing-focus-visible, small-touch-target, hover-only-affordance, image-missing-dimensions, dark-scheme-contrast-blindspot

Provider-gated (4 advisory rules, opt-in via --gpt/--gemini): gpt-thin-border-wide-shadow, repeating-stripes-gradient, codex-grid-background, theater-slop-phrase

Detection Engines

| Engine | Method | Optional dep | |---|---|---| | regex | Source text / CSS-in-JS scan | none | | static-html | HTMLparser2 static DOM parse | none | | browser | Live-page scan | @monoes/monobrowse (optional) with an installed Chrome, Chromium or Edge, else a puppeteer you install yourself | | visual | Visual contrast analysis | @monoes/monobrowse (optional) |

Auto-Fix

cli/engine/fix/fixers.mjs implements safe per-rule codemods. --dry-run prints unified diffs. --rule <id,...> narrows the fix to specific rule IDs.

OKLCH Palette Seed Library

Source: packages/@monomind/cli/src/commands/design-palette.ts#SEEDS, with the seed data in design-palette-seeds-1.ts and design-palette-seeds-2.ts

• 129 hand-curated seeds spanning the full hue wheel (0°–360°)
• Each seed: { id, oklch: [L, C, H], mood: string, strategy: string }
• Hue-zone weighting: inverse-frequency across 30° buckets — equal probability for all hue regions regardless of seed density
• Env var override: MONODESIGN_PALETTE_SEED

The /monodesign Agent Skill

Source: skill/SKILL.src.md · v2.0.0 · Apache-2.0

Triggers: /monodesign, /design, /frontend-design, plus 40+ natural-language triggers.

24 Skill Commands

| Category | Commands | |---|---| | Build | craft, shape, init, document, extract, components, images, palette | | Evaluate | critique, audit, research, detect | | Refine | polish, bolder, quieter, distill, harden, onboard | | Enhance | animate, colorize, typeset, layout, delight, overdrive | | Fix | clarify, adapt, optimize | | Iterate | live | | Management | pin, unpin, hooks |

Sub-Agents

| Agent file | Role | |---|---| | skill/agents/monodesign-asset-producer.md | Image/asset generation | | skill/agents/monodesign-manual-edit-applier.md | Accepts live manual edits during live sessions |

Hooks Integration

When enabled (.monodesign/config.json), antipattern detection runs automatically after UI file edits:

{
  "hook": {
    "enabled": true,
    "limits": { "maxFindings": 5, "maxChars": 8000 }
  }
}

Manage via monomind design ignores or /monodesign hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>.

CLI Subcommands (monomind design)

| Command | Purpose | |---|---| | monomind design detect [-t <path>] [--json] | Scan HTML/CSS for antipatterns | | monomind design fix [-t <path>] [--dry-run] [--json] [--rule <ids>] | Auto-fix with safe codemods | | monomind design ignores <list\|add-rule\|add-file\|add-value\|remove-rule> | Manage detector ignores | | monomind design palette [--id <id>] [--from <key>] [--random] [--json] | Pick OKLCH brand seed |

Design System Consistency

Source: cli/engine/design-system.mjs (entry point, split across design-system-parse.mjs and design-system-checks.mjs)

Parses DESIGN.md / .monodesign/design.json to enforce consistency rules (design-system-font, design-system-color, design-system-radius, design-system-font-size). The skill writes DESIGN.md; the detector reads it for drift detection.

Search order: DESIGN.md → .agents/context/DESIGN.md → docs/DESIGN.md.

Package Exports

{
  ".":                   "./src/index.ts",
  "./tokens":            "./src/tokens.css",
  "./engine":            "./cli/engine/detect-antipatterns.mjs",
  "./engine/browser":    "./cli/engine/detect-antipatterns-browser.js"
}

Dependencies: css-select, css-tree, domutils, fflate, htmlparser2, marked
Optional: @monoes/monobrowse (browser detection and live URL scanning). puppeteer is no longer a dependency; install it yourself only for URL scans on a machine with no Chrome, Chromium or Edge. Through monomind design detect, monomind downloads a Chrome on first use instead.

Links

• GitHub
• Documentation
• Issues

License

Apache-2.0