@monoes/monodesign 1.2.3 → 1.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +173 -22
  2. package/package.json +2 -3
package/README.md CHANGED
@@ -8,9 +8,12 @@
8
8
  [![license](https://img.shields.io/npm/l/@monoes/monodesign?style=flat-square)](https://github.com/monoes/monomind/blob/main/LICENSE)
9
9
  [![node](https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
10
10
 
11
- **Frontend design intelligence for AI agents** — design tokens, CSS antipattern detection, and the monodesign skill. The unified design agent for the Monomind ecosystem.
11
+ **Frontend design intelligence for AI agents** — OKLCH design tokens, a 51-rule AI-slop
12
+ antipattern detector, and the `/monodesign` agent skill for Claude Code and Gemini agy.
12
13
 
13
- > Part of the [Monomind](https://github.com/monoes/monomind) ecosystem.
14
+ > Part of the [Monomind](https://github.com/monoes/monomind) ecosystem. v1.2.3 · Apache-2.0
15
+
16
+ ---
14
17
 
15
18
  ## Install
16
19
 
@@ -18,38 +21,186 @@
18
21
  npm install @monoes/monodesign
19
22
  ```
20
23
 
21
- ## What's inside
24
+ ---
25
+
26
+ ## What's Inside
27
+
28
+ | Module | Export path | Purpose |
29
+ |---|---|---|
30
+ | Design tokens (TS) | `@monoes/monodesign` | Typed constants for font, spacing, color, motion |
31
+ | Design tokens (CSS) | `@monoes/monodesign/tokens` | CSS custom properties (`tokens.css`) |
32
+ | Detection engine | `@monoes/monodesign/engine` | Node-side 51-rule antipattern detector |
33
+ | Browser bundle | `@monoes/monodesign/engine/browser` | Browser-compatible detector (no Node deps) |
34
+
35
+ ---
36
+
37
+ ## Design Tokens
38
+
39
+ Source: [`src/tokens.ts`](file:///Users/morteza/Desktop/tools/monomind/packages/@monoes/monodesign/src/tokens.ts) + [`src/tokens.css`](file:///Users/morteza/Desktop/tools/monomind/packages/@monoes/monodesign/src/tokens.css)
40
+
41
+ All color tokens are in **OKLCH** — no hex colors in the token system.
22
42
 
23
- | Export | Purpose |
43
+ ### Token Categories
44
+
45
+ | Category | Key Values |
24
46
  |---|---|
25
- | `tokens` | Design token definitions (colors, spacing, typography, breakpoints) |
26
- | `rules` | Antipattern detection rules for CSS and component structure |
27
- | `antipatterns` | Detect and report common frontend antipatterns |
47
+ | **Typography** | Fonts: `'Cormorant Garamond'` (display), `'Instrument Sans'` (body), `'Space Grotesk'` (mono). Scale: xs (12px) → 7xl (72px). Line-heights: 1.2–2.0 |
48
+ | **Spacing** | 8px base grid: `--space-1` (4px) → `--space-30` (120px) |
49
+ | **Color** | Neutrals: ink/charcoal/ash/mist/cream/paper/white. Accent: Editorial Magenta `oklch(60% 0.25 350)` with 9-stop tonal ramp |
50
+ | **Motion** | Expo-out primary `cubic-bezier(0.16,1,0.3,1)`, plus quint, in-out, in. Durations: 0s → 1.2s |
51
+ | **Shadows** | sm/md/lg/accent. Max 0.15 alpha. |
52
+ | **Radius** | none(0) → sm(4px) → md(8px) → lg(12px) → xl(16px) → full(9999px) |
53
+ | **Z-index** | Named scale: below(−1) → base(0) → raised(1) → overlay(10) → modal(20) → toast(30) → top(40) |
54
+
55
+ ### CSS Usage
56
+
57
+ ```css
58
+ /* Import CSS custom properties */
59
+ @import '@monoes/monodesign/tokens';
60
+
61
+ .hero {
62
+ font-family: var(--font-display);
63
+ color: var(--color-ink);
64
+ padding: var(--space-8);
65
+ border-radius: var(--radius-lg);
66
+ transition: transform var(--duration-default) var(--easing-expo-out);
67
+ }
68
+ ```
28
69
 
29
- ## Design tokens
70
+ ### TypeScript Usage
30
71
 
31
72
  ```typescript
32
- import { tokens } from '@monoes/monodesign';
73
+ import { fontFamily, fontSize, spacing, easing, duration, color, accentScale, shadow, radius } from '@monoes/monodesign';
33
74
 
34
- // Access design system values
35
- tokens.colors.primary // brand colors
36
- tokens.spacing.md // spacing scale
37
- tokens.typography.body // font stacks and sizes
38
- tokens.breakpoints.tablet // responsive breakpoints
75
+ console.log(color.accent); // oklch(60% 0.25 350)
76
+ console.log(spacing[8]); // 32px
77
+ console.log(radius.lg); // 12px
39
78
  ```
40
79
 
41
- ## Antipattern detection
80
+ ---
42
81
 
43
- ```typescript
44
- import { detectAntipatterns } from '@monoes/monodesign';
82
+ ## Antipattern Detection (51 Rules)
83
+
84
+ Source: [`cli/engine/registry/antipatterns.mjs`](file:///Users/morteza/Desktop/tools/monomind/packages/@monoes/monodesign/cli/engine/registry/antipatterns.mjs) — 564 lines, 51 entries.
85
+
86
+ ### Rule Categories
87
+
88
+ **`slop`** (21 rules) — AI-generation tells that make UIs feel generic:
89
+
90
+ `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`
91
+
92
+ **`quality`** (24 rules) — Accessibility and design principle violations:
93
+
94
+ `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`
95
+
96
+ **Provider-gated** (4 advisory rules, opt-in via `--gpt`/`--gemini`): `gpt-thin-border-wide-shadow`, `repeating-stripes-gradient`, `codex-grid-background`, `theater-slop-phrase`
97
+
98
+ ### Detection Engines
99
+
100
+ | Engine | Method | Optional dep |
101
+ |---|---|---|
102
+ | `regex` | Source text / CSS-in-JS scan | none |
103
+ | `static-html` | HTMLparser2 static DOM parse | none |
104
+ | `browser` | Puppeteer live-page scan | `puppeteer` (optional) |
105
+ | `visual` | Visual contrast analysis | `@monoes/monobrowse` (optional) |
106
+
107
+ ### Auto-Fix
108
+
109
+ `cli/engine/fix/fixers.mjs` implements safe per-rule codemods. `--dry-run` prints unified diffs. `--rule <id,...>` narrows the fix to specific rule IDs.
110
+
111
+ ---
112
+
113
+ ## OKLCH Palette Seed Library
114
+
115
+ Source: [`packages/@monomind/cli/src/commands/design-palette.ts:29–417`](file:///Users/morteza/Desktop/tools/monomind/packages/@monomind/cli/src/commands/design-palette.ts#L29-L417)
116
+
117
+ - **129 hand-curated seeds** spanning the full hue wheel (0°–360°)
118
+ - Each seed: `{ id, oklch: [L, C, H], mood: string, strategy: string }`
119
+ - **Hue-zone weighting**: inverse-frequency across 30° buckets — equal probability for all hue regions regardless of seed density
120
+ - **Env var override**: `MONODESIGN_PALETTE_SEED`
121
+
122
+ ---
123
+
124
+ ## The `/monodesign` Agent Skill
125
+
126
+ Source: [`skill/SKILL.src.md`](file:///Users/morteza/Desktop/tools/monomind/packages/@monoes/monodesign/skill/SKILL.src.md) · v2.0.0 · Apache-2.0
127
+
128
+ Triggers: `/monodesign`, `/design`, `/frontend-design`, plus 40+ natural-language triggers.
129
+
130
+ ### 24 Skill Commands
131
+
132
+ | Category | Commands |
133
+ |---|---|
134
+ | Build | `craft`, `shape`, `init`, `document`, `extract`, `components`, `images`, `palette` |
135
+ | Evaluate | `critique`, `audit`, `research`, `detect` |
136
+ | Refine | `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard` |
137
+ | Enhance | `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive` |
138
+ | Fix | `clarify`, `adapt`, `optimize` |
139
+ | Iterate | `live` |
140
+ | Management | `pin`, `unpin`, `hooks` |
141
+
142
+ ### Sub-Agents
143
+
144
+ | Agent file | Role |
145
+ |---|---|
146
+ | `skill/agents/monodesign-asset-producer.md` | Image/asset generation |
147
+ | `skill/agents/monodesign-manual-edit-applier.md` | Accepts live manual edits during `live` sessions |
148
+
149
+ ---
150
+
151
+ ## Hooks Integration
152
+
153
+ When enabled (`.monodesign/config.json`), antipattern detection runs automatically after UI file edits:
154
+
155
+ ```json
156
+ {
157
+ "hook": {
158
+ "enabled": true,
159
+ "limits": { "maxFindings": 5, "maxChars": 8000 }
160
+ }
161
+ }
162
+ ```
163
+
164
+ Manage via `monomind design ignores` or `/monodesign hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>`.
165
+
166
+ ---
167
+
168
+ ## CLI Subcommands (`monomind design`)
169
+
170
+ | Command | Purpose |
171
+ |---|---|
172
+ | `monomind design detect [-t <path>] [--json]` | Scan HTML/CSS for antipatterns |
173
+ | `monomind design fix [-t <path>] [--dry-run] [--json] [--rule <ids>]` | Auto-fix with safe codemods |
174
+ | `monomind design ignores <list\|add-rule\|add-file\|add-value\|remove-rule>` | Manage detector ignores |
175
+ | `monomind design palette [--id <id>] [--from <key>] [--random] [--json]` | Pick OKLCH brand seed |
176
+
177
+ ---
178
+
179
+ ## Design System Consistency
180
+
181
+ Source: [`cli/engine/design-system.mjs`](file:///Users/morteza/Desktop/tools/monomind/packages/@monoes/monodesign/cli/engine/design-system.mjs) — 815 lines
182
+
183
+ 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.
184
+
185
+ Search order: `DESIGN.md` → `.agents/context/DESIGN.md` → `docs/DESIGN.md`.
186
+
187
+ ---
188
+
189
+ ## Package Exports
45
190
 
46
- const issues = detectAntipatterns(cssSource);
47
- // [{ rule: 'no-magic-numbers', line: 42, message: '...' }, ...]
191
+ ```json
192
+ {
193
+ ".": "./src/index.ts",
194
+ "./tokens": "./src/tokens.css",
195
+ "./engine": "./cli/engine/detect-antipatterns.mjs",
196
+ "./engine/browser": "./cli/engine/detect-antipatterns-browser.js"
197
+ }
48
198
  ```
49
199
 
50
- ## The monodesign skill
200
+ **Dependencies:** `css-select`, `css-tree`, `domutils`, `fflate`, `htmlparser2`, `marked`
201
+ **Optional:** `@monoes/monobrowse` (browser detection), `puppeteer` (live URL scanning)
51
202
 
52
- In Claude Code, monodesign is available as `/monodesign` — the single design agent handling UI/component systems, brand strategy, UX research, visual storytelling, CSS architecture, design critique, and more. This package provides the runtime intelligence that skill draws from.
203
+ ---
53
204
 
54
205
  ## Links
55
206
 
@@ -59,4 +210,4 @@ In Claude Code, monodesign is available as `/monodesign` — the single design a
59
210
 
60
211
  ## License
61
212
 
62
- MIT
213
+ Apache-2.0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@monoes/monodesign",
3
- "version": "1.2.3",
3
+ "version": "1.2.4",
4
4
  "description": "Frontend design intelligence for AI agents — design tokens, antipattern detection, and the monodesign skill",
5
5
  "type": "module",
6
6
  "main": "./src/index.ts",
@@ -22,8 +22,7 @@
22
22
  "scripts": {
23
23
  "build": "tsc",
24
24
  "test": "node scripts/run-tests.mjs",
25
- "sync": "node scripts/sync-skill.mjs",
26
- "prepare": "node scripts/sync-skill.mjs"
25
+ "sync": "node scripts/sync-skill.mjs"
27
26
  },
28
27
  "keywords": [
29
28
  "design-system",