unslop-design 1.13.0 → 1.14.0
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.
- package/README.md +45 -366
- package/bin/unslop.mjs +5 -0
- package/package.json +2 -1
- package/scripts/contrast.py +91 -0
- package/scripts/slop-scan.py +1 -1
package/README.md
CHANGED
|
@@ -10,11 +10,9 @@
|
|
|
10
10
|
<a href="https://marcosnovo.github.io/unslop-design/"><b>Website and live demo</b></a> ·
|
|
11
11
|
<a href="#quick-start">Quick start</a> ·
|
|
12
12
|
<a href="#use-it">Use it</a> ·
|
|
13
|
-
<a href="#the-72-fixes">The 72 fixes</a> ·
|
|
14
13
|
<a href="#keep-it-clean">Hook and CI</a> ·
|
|
15
|
-
<a href="#
|
|
16
|
-
<a href="#
|
|
17
|
-
<a href="#faq">FAQ</a>
|
|
14
|
+
<a href="#the-72-fixes">The 72 fixes</a> ·
|
|
15
|
+
<a href="#guide">Guide</a>
|
|
18
16
|
</p>
|
|
19
17
|
|
|
20
18
|
<p align="center">
|
|
@@ -63,8 +61,8 @@ npx skills add marcosnovo/unslop-design -g
|
|
|
63
61
|
```
|
|
64
62
|
|
|
65
63
|
Pick one route per agent: installing the same skill twice makes it show up
|
|
66
|
-
twice.
|
|
67
|
-
|
|
64
|
+
twice. One project only, chat apps (claude.ai, ChatGPT) and manual clones:
|
|
65
|
+
[guide/install.md](guide/install.md).
|
|
68
66
|
|
|
69
67
|
**Check it works.** In a project, paste a screenshot and write *unslop this
|
|
70
68
|
screen*. You should get five numbered fixes, each with its reason, and a
|
|
@@ -104,68 +102,6 @@ see which one helped.
|
|
|
104
102
|
|
|
105
103
|
<sub>The app is in Spanish. Full-quality MP4s: <a href="assets/videos/refil-mapa.mp4">map</a> · <a href="assets/videos/refil-perfil.mp4">profile</a>.</sub>
|
|
106
104
|
|
|
107
|
-
## More ways to install
|
|
108
|
-
|
|
109
|
-
**Claude Code from a terminal:** `claude plugin marketplace add
|
|
110
|
-
marcosnovo/unslop-design && claude plugin install unslop-design@unslop`.
|
|
111
|
-
Update with `claude plugin marketplace update unslop && claude plugin update
|
|
112
|
-
unslop-design@unslop`. Plugin skills are namespaced, so the command is
|
|
113
|
-
`/unslop-design:unslop-design`; asking in plain words works the same.
|
|
114
|
-
|
|
115
|
-
**Every agent on your machine, one command:**
|
|
116
|
-
|
|
117
|
-
```bash
|
|
118
|
-
curl -fsSL https://raw.githubusercontent.com/marcosnovo/unslop-design/main/install.sh | bash
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
It clones the skill once into `~/.agents/skills/unslop-design` and links it
|
|
122
|
-
into every agent it finds, so one `git pull` updates them all. Nothing is
|
|
123
|
-
overwritten: an existing folder with the same name is left alone.
|
|
124
|
-
`--dry-run` shows what it would do, `--copy` copies instead of linking, and
|
|
125
|
-
`--uninstall` removes only what it installed.
|
|
126
|
-
([Read the script](install.sh) before piping it into a shell.)
|
|
127
|
-
|
|
128
|
-
**Or one agent by hand.** Clone into its skills folder:
|
|
129
|
-
|
|
130
|
-
| Agent | Global folder | Call it |
|
|
131
|
-
|---|---|---|
|
|
132
|
-
| Claude Code | `~/.claude/skills/` | `/unslop-design` |
|
|
133
|
-
| Codex · Replit · Cline · Zed | `~/.agents/skills/` | `$unslop-design` (Codex) |
|
|
134
|
-
| Cursor | `~/.cursor/skills/` | ask for it by name |
|
|
135
|
-
| GitHub Copilot | `~/.copilot/skills/` | ask for it by name |
|
|
136
|
-
| Gemini CLI | `~/.gemini/skills/` | ask for it by name |
|
|
137
|
-
| Antigravity | `~/.gemini/antigravity/skills/` | ask for it by name |
|
|
138
|
-
| Windsurf | `~/.codeium/windsurf/skills/` | ask for it by name |
|
|
139
|
-
| OpenCode | `~/.config/opencode/skills/` | ask for it by name |
|
|
140
|
-
| Amp | `~/.config/agents/skills/` | ask for it by name |
|
|
141
|
-
| Kiro | `~/.kiro/skills/` | ask for it by name |
|
|
142
|
-
| Goose · Roo Code · Junie | `~/.config/goose/skills/` · `~/.roo/skills/` · `~/.junie/skills/` | ask for it by name |
|
|
143
|
-
| Devin · Grok Build · Hermes | `~/.config/devin/skills/` · `~/.grok/skills/` · `~/.hermes/skills/` | ask for it by name |
|
|
144
|
-
| Pi · Oh My Pi · Qoder | `~/.pi/agent/skills/` · `~/.omp/agent/skills/` · `~/.qoder/skills/` | ask for it by name |
|
|
145
|
-
| Trae · Rovo Dev · Mistral Vibe · DeepSeek | `~/.trae/skills/` · `~/.rovodev/skills/` · `~/.vibe/skills/` · `~/.dsh/skills/` | ask for it by name |
|
|
146
|
-
|
|
147
|
-
```bash
|
|
148
|
-
git clone https://github.com/marcosnovo/unslop-design ~/.claude/skills/unslop-design
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
Every agent also picks it up on its own when the request matches (design
|
|
152
|
-
review, screenshots, "less AI"), so calling it by name is optional.
|
|
153
|
-
|
|
154
|
-
<details>
|
|
155
|
-
<summary>Only for one project, or in a chat app</summary>
|
|
156
|
-
|
|
157
|
-
- **One project:** clone it into `.agents/skills/unslop-design` inside the
|
|
158
|
-
repo (Claude Code: `.claude/skills/`, Windsurf: `.windsurf/skills/`,
|
|
159
|
-
Kiro: `.kiro/skills/`) and commit it, so your team and cloud sessions get
|
|
160
|
-
it too.
|
|
161
|
-
- **claude.ai, Claude desktop or ChatGPT:** download `unslop-design.zip`
|
|
162
|
-
from the [latest release](https://github.com/marcosnovo/unslop-design/releases/latest)
|
|
163
|
-
and upload it as a skill (Claude: Settings → Capabilities → Skills).
|
|
164
|
-
Chat apps can review screenshots and draw the before/after; the parts
|
|
165
|
-
that touch a codebase need a coding agent.
|
|
166
|
-
|
|
167
|
-
</details>
|
|
168
|
-
|
|
169
105
|
## Web and dashboards
|
|
170
106
|
|
|
171
107
|
<p align="center">
|
|
@@ -174,20 +110,10 @@ review, screenshots, "less AI"), so calling it by name is optional.
|
|
|
174
110
|
|
|
175
111
|
<p align="center"><sub><a href="examples/dashboard-before.html">examples/dashboard-before.html</a> → <a href="examples/dashboard-after.html">examples/dashboard-after.html</a>, rendered at 1280 px. Drag between the two on <a href="https://marcosnovo.github.io/unslop-design/#demo">the website</a>.</sub></p>
|
|
176
112
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
node scripts/web-audit.mjs http://localhost:3000 # the rendered page at 390/768/1280 px
|
|
182
|
-
```
|
|
183
|
-
|
|
184
|
-
On the example above, `web-audit.mjs` goes from 19 spacing values (15 off
|
|
185
|
-
the scale), 5 weights, 6 radii, 6 shadows, a page that scrolls sideways
|
|
186
|
-
on a phone and 11 links with no focus style, to 6 spacing values, all on the scale, 2
|
|
187
|
-
weights, 1 shadow, no sideways scroll and a focus ring on everything.
|
|
188
|
-
`slop-scan.py` finds 91 hits in the before and none in the after, and
|
|
189
|
-
`unslop-score.py` goes from 21 to 100 on the code alone. Details
|
|
190
|
-
in [`web.md`](web.md).
|
|
113
|
+
On this example `slop-scan.py` finds 91 hits before and none after, and the
|
|
114
|
+
score goes from 21 to 100; the rendered audit goes from 19 spacing values
|
|
115
|
+
and a sideways scroll on phones to 6 values on the scale and none. The web
|
|
116
|
+
playbook is [`web.md`](web.md).
|
|
191
117
|
|
|
192
118
|
## Native apps
|
|
193
119
|
|
|
@@ -204,26 +130,6 @@ greetings, Title Case and rows of stat cards in `.swift` and `.kt` files.
|
|
|
204
130
|
| [`examples/swiftui/`](examples/swiftui) · subscriptions | 32/100: 10 emoji, glows, 4 gradients, 25 literals, "Hey Maya!" | 100/100 |
|
|
205
131
|
| [`examples/compose/`](examples/compose) · settings | 62/100: 7 emoji, 15 literals, the Android Studio template colors | 100/100 |
|
|
206
132
|
|
|
207
|
-
```bash
|
|
208
|
-
python3 scripts/unslop-score.py examples/swiftui/before # 32/100
|
|
209
|
-
python3 scripts/unslop-score.py examples/swiftui/after # 100/100
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
The SwiftUI folders also hold the HTML mock of each state at iPhone size,
|
|
213
|
-
the way quick mode shows a native before/after when there's no simulator.
|
|
214
|
-
|
|
215
|
-
## Scores in the wild
|
|
216
|
-
|
|
217
|
-
Ran it on your own app or site? [Share the before/after and the
|
|
218
|
-
score](https://github.com/marcosnovo/unslop-design/issues/new?template=score-report.yml),
|
|
219
|
-
and it goes here with your permission: what the app is, the two numbers,
|
|
220
|
-
one image. What it missed is just as useful: that's how rules get added.
|
|
221
|
-
|
|
222
|
-
| App | Platform | Score | |
|
|
223
|
-
|---|---|---|---|
|
|
224
|
-
| [Refil](https://refil.app) (the author's) | iOS, Android | before/after above | [screens](#one-fix-at-a-time) |
|
|
225
|
-
| *Yours?* | | | [share it](https://github.com/marcosnovo/unslop-design/issues/new?template=score-report.yml) |
|
|
226
|
-
|
|
227
133
|
## Use it
|
|
228
134
|
|
|
229
135
|
Type `/unslop-design` (or `$unslop-design` in Codex), or just ask in plain
|
|
@@ -261,309 +167,87 @@ agent reads where you left off and proposes the next two or three steps.
|
|
|
261
167
|
| *unslop audit* | Every finding ranked by fix number; changes nothing |
|
|
262
168
|
| *unslop critique* | A usability report: tasks walked as three users, cognitive load, ten heuristics scored 0-4, P0-P3 findings |
|
|
263
169
|
| *unslop apply* | The accepted fixes still pending in `.unslop/review.md`, one at a time |
|
|
264
|
-
| *unslop full* | The whole process
|
|
265
|
-
|
|
266
|
-
### Score it
|
|
267
|
-
|
|
268
|
-
```bash
|
|
269
|
-
python3 scripts/unslop-score.py src/ # the code alone
|
|
270
|
-
python3 scripts/unslop-score.py src/ --audit unslop-audit/report.json # plus the rendered page (web-audit.mjs)
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
```text
|
|
274
|
-
$ python3 scripts/unslop-score.py examples/dashboard-before.html
|
|
275
|
-
unslop score: 21/100 — slop (1 source file)
|
|
276
|
-
|
|
277
|
-
Where the points went (fix the top rows first):
|
|
278
|
-
- 12 [#32] Colored glows (6)
|
|
279
|
-
- 10 [#33] Emoji in the UI (19)
|
|
280
|
-
- 8 [#53] Focus outline removed (1)
|
|
281
|
-
…
|
|
282
|
-
|
|
283
|
-
Badge: [](https://github.com/marcosnovo/unslop-design)
|
|
284
|
-
```
|
|
170
|
+
| *unslop full* | The whole process with parallel reviewers ([how it works](guide/how-it-works.md)) |
|
|
285
171
|
|
|
286
|
-
|
|
287
|
-
many kinds are left, not how big the codebase is. Paste the badge in your
|
|
288
|
-
README, and put "score 21 → 100" at the top of the PR. It's a smoke alarm,
|
|
289
|
-
not a judge: a 95 can still have a flat hierarchy. `--min 80` makes it exit
|
|
290
|
-
1 below 80 if you want it in a pre-commit hook, and `--save` keeps every run
|
|
291
|
-
in `.unslop/history.json` so the score has a trend.
|
|
172
|
+
How the score works, `--save`, `--baseline` and `--min`: [guide/automation.md](guide/automation.md).
|
|
292
173
|
|
|
293
174
|
## Keep it clean
|
|
294
175
|
|
|
295
176
|
A review fixes the screen; these keep the next edit from undoing it.
|
|
296
177
|
|
|
297
|
-
**While the agent writes
|
|
298
|
-
|
|
299
|
-
edit
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
npx unslop-design hooks gemini --write # .gemini/settings.json, AfterTool
|
|
308
|
-
npx unslop-design hooks copilot --write # .github/hooks/unslop-design.json, postToolUse (preview)
|
|
309
|
-
npx unslop-design hooks codex # prints the ~/.codex/config.toml block, PostToolUse
|
|
310
|
-
```
|
|
311
|
-
|
|
312
|
-
Each runs `npx -y unslop-design hook` after a write or edit, reads the
|
|
313
|
-
agent's event (Gemini's `write_file`/`replace`, Codex's `apply_patch`,
|
|
314
|
-
Copilot's tool arguments) and answers in the format they share. Cursor's and
|
|
315
|
-
Windsurf's post-edit hooks can't send anything back to the agent yet, so
|
|
316
|
-
there is no hook for them; the scanner and the CI work there as anywhere.
|
|
317
|
-
|
|
318
|
-
**On every pull request (GitHub Actions).** Each hit becomes an annotation
|
|
319
|
-
on its line, and one comment on the PR keeps the score and the change
|
|
320
|
-
against the base branch, updated on every push:
|
|
321
|
-
|
|
322
|
-
> ### unslop score: 88/100 (+7 vs main)
|
|
323
|
-
> **Worse** · [#68] Border and shadow on one card: 0 → 2 (-2)
|
|
324
|
-
> **Better** · [#32] Colored glows: 3 → 0 (+8) · [#33] Emoji in the UI: 4 → 0 (+8)
|
|
325
|
-
|
|
326
|
-
The job fails under your minimum, if you set one:
|
|
178
|
+
- **While the agent writes.** After every edit to a UI file, a hook tells the
|
|
179
|
+
agent what slop it just added, with the fix number, and says nothing when
|
|
180
|
+
the edit is clean. Built into the Claude Code plugin; one command for
|
|
181
|
+
Gemini CLI, Codex and Copilot (`npx unslop-design hooks gemini --write`).
|
|
182
|
+
- **On every pull request.** The GitHub Action annotates each line and keeps
|
|
183
|
+
one comment with the score and the change against the base branch
|
|
184
|
+
("88/100, +7 vs main"), failing under your minimum if you set one.
|
|
185
|
+
- **Your decisions, once.** `.unslop/context.md` holds your scales and the
|
|
186
|
+
rules your project allows, so a base-6 grid or a brand face isn't flagged
|
|
187
|
+
twice.
|
|
327
188
|
|
|
328
189
|
```yaml
|
|
329
190
|
# .github/workflows/unslop.yml
|
|
330
191
|
on: pull_request
|
|
331
|
-
permissions:
|
|
332
|
-
contents: read
|
|
333
|
-
pull-requests: write # for the comment
|
|
192
|
+
permissions: { contents: read, pull-requests: write }
|
|
334
193
|
jobs:
|
|
335
194
|
unslop:
|
|
336
195
|
runs-on: ubuntu-latest
|
|
337
196
|
steps:
|
|
338
197
|
- uses: actions/checkout@v5
|
|
339
|
-
- uses: marcosnovo/unslop-design@v1
|
|
340
|
-
with:
|
|
341
|
-
paths: src
|
|
342
|
-
min: 80 # optional; also: allow, scale, type-scale, comment: false
|
|
198
|
+
- uses: marcosnovo/unslop-design@v1
|
|
199
|
+
with: { paths: src, min: 80 }
|
|
343
200
|
```
|
|
344
201
|
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
**Anywhere else.** `python3 scripts/slop-scan.py src --github` prints the
|
|
349
|
-
same annotations, `--json` every hit for other tools, and `--list-rules`
|
|
350
|
-
every rule id. All of them read `.unslop/context.md`, so your scale and your
|
|
351
|
-
allowed rules apply without flags.
|
|
352
|
-
|
|
353
|
-
Screen recordings need `ffmpeg` (`brew install ffmpeg`) so the agent can
|
|
354
|
-
pull frames from them.
|
|
202
|
+
Every option, other agents and the local commands:
|
|
203
|
+
[guide/automation.md](guide/automation.md).
|
|
355
204
|
|
|
356
205
|
## The 72 fixes
|
|
357
206
|
|
|
358
207
|
Every fix has a number so reviewers can cite it ("#20 badge is too loud")
|
|
359
|
-
and you can accept or reject them one by one.
|
|
208
|
+
and you can accept or reject them one by one. Twelve of them:
|
|
360
209
|
|
|
361
210
|
| # | Fix | Instead of |
|
|
362
211
|
|---|---|---|
|
|
363
212
|
| 1 | Non-linear spacing scale, neighbors ≥ 25% apart | `padding(13)`, `padding(15)`, `padding(18)` |
|
|
364
213
|
| 11 | Hierarchy with weight and color before size | three numbers fighting at the same size |
|
|
365
|
-
| 12 | "12 left in stock" | "Stock: 12" |
|
|
366
|
-
| 15 | Number and unit on one baseline | `$` and `/gal` vertically centered |
|
|
367
|
-
| 16 | Only numbers that exist | "vs. last month" with one month of data |
|
|
368
214
|
| 19 | One accent, for one gesture | brand color on cards, icons and titles |
|
|
369
215
|
| 20 | Quiet badges: dark text on a light tint | white on saturated pink |
|
|
370
|
-
| 22 | A shade of the same hue on colored panels | gray or 60% white text |
|
|
371
216
|
| 26 | The title says what the screen is | "Hey Alex! 👋" |
|
|
372
|
-
| 31 | Space, then background, then shadow, border last | a border around everything |
|
|
373
|
-
| 32 | Shadows mean height | shadows as decoration |
|
|
374
217
|
| 33 | One icon set, one stroke | emoji as icons, icons in colored circles |
|
|
375
|
-
| 39 | Charts: today saturated, values on the bars | gridlines and axes nobody reads |
|
|
376
218
|
| 41 | The primary button names where it goes | "Let's Go! 🚀" |
|
|
377
|
-
| 43 | One left and one right rail for everything | blocks starting at 12, 16 and 20 pt |
|
|
378
|
-
| 44 | One gap between sections, no filler copy | "✨ Share your best moments" |
|
|
379
|
-
| 47 | A signature taken from the domain, as a small family | a new font plus a glow |
|
|
380
219
|
| 50 | Counts as muted tabular numbers | `12` in a hot-pink pill, `210 👤` |
|
|
381
220
|
| 52 | A delta names its baseline | "+12%!!" |
|
|
382
221
|
| 55 | Ink headline on a neutral canvas | gradient text over a purple glow |
|
|
383
222
|
| 68 | One separator per surface | a 1px border and a soft shadow on every card |
|
|
384
|
-
| 70 | A modal is the last resort; Undo beats Confirm | "Are you sure?" before every delete |
|
|
385
223
|
| 71 | Plurals, dates and money from the platform | "3 item(s)", a hand-built "MM/DD" |
|
|
386
|
-
| 72 | Four choices or fewer per group | nine filter chips in a row |
|
|
387
|
-
|
|
388
|
-
<details>
|
|
389
|
-
<summary><b>All 72, by section</b></summary>
|
|
390
|
-
|
|
391
|
-
**System** · 1 spacing scale · 2 type scale and two weights · 3 palette with
|
|
392
|
-
shades defined up front · 4 grays with one temperature · 5 named elevation
|
|
393
|
-
and radii · 6 a chosen personality
|
|
394
|
-
|
|
395
|
-
**Spacing** · 7 start with too much space · 8 more space around a group than
|
|
396
|
-
within · 9 uniform card padding · 10 you don't have to fill the screen
|
|
397
|
-
|
|
398
|
-
**Hierarchy** · 11 data first · 12 labels as a last resort · 13 small section
|
|
399
|
-
titles · 14 balance weight and contrast · 15 parts of a number · 16 only
|
|
400
|
-
numbers that exist · 17 each number once per screen · 18 what's next,
|
|
401
|
-
concretely
|
|
402
|
-
|
|
403
|
-
**Color** · 19 one accent · 20 quiet badges · 21 dark ink on brand fills ·
|
|
404
|
-
22 no gray on color · 23 neutral global tint · 24 color never alone
|
|
405
|
-
|
|
406
|
-
**Typography** · 25 sentence case · 26 title, not a greeting · 27 line height
|
|
407
|
-
and length · 28 align for readability · 29 letter-spacing with intent · 69
|
|
408
|
-
code faces for code and data
|
|
409
|
-
|
|
410
|
-
**Decoration and depth** · 30 remove ornaments · 31 fewer borders · 32 shadows
|
|
411
|
-
mean height · 33 one icon style · 34 decoration with conditions · 66 a hard
|
|
412
|
-
offset shadow is a style · 68 one separator per surface
|
|
413
|
-
|
|
414
|
-
**Images and charts** · 35 good images or none · 36 text over images ·
|
|
415
|
-
37 user content in fixed frames · 38 screenshots at their size · 39 charts
|
|
416
|
-
without noise
|
|
417
224
|
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
fewer per group
|
|
225
|
+
All 72 with the reason behind each: [`checklist.md`](checklist.md) (by section:
|
|
226
|
+
[guide/how-it-works.md](guide/how-it-works.md#all-72-fixes-by-section)).
|
|
421
227
|
|
|
422
|
-
|
|
423
|
-
section headers are quiet labels · 46 floating chrome in the system material,
|
|
424
|
-
content solid · 47 a signature is a family · 48 real content in every mock
|
|
425
|
-
|
|
426
|
-
**Web and dashboards** · 49 one icon slot · 50 counts are text, not pills ·
|
|
427
|
-
51 one category, one color · 52 a delta names its baseline · 53 interactive
|
|
428
|
-
states drawn · 54 shortcuts as keys · 55 no gradient text, no page glow ·
|
|
429
|
-
56 a data voice · 57 works at 390, 768 and 1280 px
|
|
430
|
-
|
|
431
|
-
**Beyond clean** · 58 objects before boxes · 59 when the content is a canvas,
|
|
432
|
-
chrome floats · 65 a skeleton from the job, not from the template
|
|
228
|
+
## Scores in the wild
|
|
433
229
|
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
230
|
+
Ran it on your own app or site? [Share the before/after and the
|
|
231
|
+
score](https://github.com/marcosnovo/unslop-design/issues/new?template=score-report.yml),
|
|
232
|
+
and it goes here with your permission: what the app is, the two numbers,
|
|
233
|
+
one image. What it missed is just as useful: that's how rules get added.
|
|
438
234
|
|
|
439
|
-
|
|
235
|
+
| App | Platform | Score | |
|
|
236
|
+
|---|---|---|---|
|
|
237
|
+
| [Refil](https://refil.app) (the author's) | iOS, Android | before/after above | [screens](#one-fix-at-a-time) |
|
|
238
|
+
| *Yours?* | | | [share it](https://github.com/marcosnovo/unslop-design/issues/new?template=score-report.yml) |
|
|
440
239
|
|
|
441
|
-
|
|
240
|
+
## Guide
|
|
442
241
|
|
|
443
|
-
|
|
242
|
+
- [Install](guide/install.md): every agent, one project only, chat apps, manual clone
|
|
243
|
+
- [Score, hook and CI](guide/automation.md): how the number works, the post-edit hook in each agent, the GitHub Action
|
|
244
|
+
- [How it works](guide/how-it-works.md): the full process with parallel reviewers, the principles, every file in the repo
|
|
245
|
+
- [FAQ](guide/faq.md): rewriting without asking, which agent, iOS only?, existing design systems, cost
|
|
444
246
|
|
|
445
|
-
|
|
446
|
-
<img src="assets/process.png" alt="Screen recordings, then a grayscale pass, then 3-4 reviewers in parallel, then a before/after you approve, then devs per area, then audit and PR." width="100%">
|
|
447
|
-
</p>
|
|
247
|
+
## Contributing
|
|
448
248
|
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
2. **System and grayscale pass.** It checks your spacing, type, color and
|
|
452
|
-
shadow scales, then asks whether each screen still works without color.
|
|
453
|
-
If it doesn't, the fix is hierarchy, not paint.
|
|
454
|
-
3. **Reviewers in parallel.** 3-4 agents acting as senior product designers,
|
|
455
|
-
one per area, each drawing an HTML before/after, citing fix numbers and
|
|
456
|
-
filling a spec card (Gap, Rails, Radius, Heads, Accent…).
|
|
457
|
-
A jury agent merges them and resolves conflicts.
|
|
458
|
-
4. **You approve.** One published page with every before/after, the
|
|
459
|
-
numbered decisions, what was dropped and the risks. Nothing is built
|
|
460
|
-
until you say yes.
|
|
461
|
-
5. **Devs per area.** Agents in isolated git worktrees, each with a closed
|
|
462
|
-
brief, so they don't step on each other. Shared tokens land first.
|
|
463
|
-
6. **Audit and PR.** Measured contrast, off-scale literals, platform parity,
|
|
464
|
-
build checks. Then one PR, answers to review bots, and merge when green.
|
|
465
|
-
|
|
466
|
-
Small job? It scales down: a single screen gets the checklist and a
|
|
467
|
-
before/after without the whole team.
|
|
468
|
-
|
|
469
|
-
## Principles
|
|
470
|
-
|
|
471
|
-
1. A fix is a rule, not a tweak: it ships as a token or component.
|
|
472
|
-
2. Hierarchy before color: if it doesn't work in gray, color won't save it.
|
|
473
|
-
3. The first thing you read is the answer.
|
|
474
|
-
4. Color says one thing.
|
|
475
|
-
5. Contrast is measured, not assumed.
|
|
476
|
-
6. Nothing the screen can't deliver: no invented numbers.
|
|
477
|
-
7. One signature gesture, taken from the domain. Everything else native.
|
|
478
|
-
8. Platforms ship together.
|
|
479
|
-
9. Verify what the user sees: dark mode, largest text, long languages.
|
|
480
|
-
|
|
481
|
-
## What's in the repo
|
|
482
|
-
|
|
483
|
-
<details>
|
|
484
|
-
<summary>Files and scripts</summary>
|
|
485
|
-
|
|
486
|
-
| File | What it covers |
|
|
487
|
-
|---|---|
|
|
488
|
-
| [`SKILL.md`](SKILL.md) | Principles, quick mode and the full flow (what the agent reads first) |
|
|
489
|
-
| [`checklist.md`](checklist.md) | The 72 fixes, each with what to do and why |
|
|
490
|
-
| [`context.md`](context.md) | `init`: the `.unslop/context.md` template, `review.md` backlog and what scripts read |
|
|
491
|
-
| [`critique.md`](critique.md) | The usability report: tasks, cognitive load, ten heuristics, severities |
|
|
492
|
-
| [`spec-card.md`](spec-card.md) | The card each reviewer fills: named values, ticked as they land |
|
|
493
|
-
| [`process.md`](process.md) | Inventory, reviewers, proposal, devs, verification, PR |
|
|
494
|
-
| [`platforms.md`](platforms.md) | SwiftUI, Compose, web, widgets, watch and car notes |
|
|
495
|
-
| [`web.md`](web.md) | Web playbook: finding tokens per stack, dashboards, landing pages, web PR checks |
|
|
496
|
-
| [`scripts/slop-scan.py`](scripts/slop-scan.py) | Finds slop patterns in source with file, line and fix number |
|
|
497
|
-
| [`scripts/web-audit.mjs`](scripts/web-audit.mjs) | Measures a rendered page: overflow, value census, contrast, focus |
|
|
498
|
-
| [`scripts/unslop-score.py`](scripts/unslop-score.py) | Both as one score from 0 to 100, with the breakdown and a badge |
|
|
499
|
-
| [`examples/`](examples) | Before/after pairs to try the scripts on: a web dashboard, a SwiftUI screen, a Compose screen |
|
|
500
|
-
| [`.claude-plugin/`](.claude-plugin) | Claude Code plugin and marketplace manifests |
|
|
501
|
-
| [`hooks/`](hooks) | The Claude Code hook that scans each UI edit |
|
|
502
|
-
| [`action.yml`](action.yml) | The GitHub Action: annotations, job summary, minimum score |
|
|
503
|
-
| [`bin/unslop.mjs`](bin/unslop.mjs) | `npx unslop-design install / scan / score / audit / rules` |
|
|
504
|
-
| [`docs/`](docs) | The landing page (GitHub Pages) with the live before/after |
|
|
505
|
-
| [`install.sh`](install.sh) | Installs or updates the skill for every agent it finds |
|
|
506
|
-
| [`scripts/validate.py`](scripts/validate.py) | Checks `SKILL.md` against the Agent Skills spec |
|
|
507
|
-
| [`scripts/test.py`](scripts/test.py) | Regression tests: every case in `tests/cases` gives exactly the hits `tests/expected.json` lists |
|
|
508
|
-
| [`agents/openai.yaml`](agents/openai.yaml) | Codex UI metadata (name, description, default prompt) |
|
|
509
|
-
| [`references.md`](references.md) | Six real before/afters, one reference app and a chapter map of *Refactoring UI* |
|
|
510
|
-
|
|
511
|
-
</details>
|
|
512
|
-
|
|
513
|
-
## FAQ
|
|
514
|
-
|
|
515
|
-
<details>
|
|
516
|
-
<summary><b>Will it rewrite my app without asking?</b></summary>
|
|
517
|
-
|
|
518
|
-
No. The process stops at the before/after page and waits for your yes.
|
|
519
|
-
After that it works on branches and opens a PR; merging is up to your repo's
|
|
520
|
-
rules.
|
|
521
|
-
</details>
|
|
522
|
-
|
|
523
|
-
<details>
|
|
524
|
-
<summary><b>Which agent should I use? What changes between them?</b></summary>
|
|
525
|
-
|
|
526
|
-
Nothing in the rules: all of them read the same `SKILL.md` (the open
|
|
527
|
-
[Agent Skills](https://agentskills.io) format); Codex also reads
|
|
528
|
-
`agents/openai.yaml` for its UI. The parallel reviewers use subagents where
|
|
529
|
-
your tool has them, and run one after another where it doesn't. The
|
|
530
|
-
before/after is a published artifact in Claude Code and a local HTML file
|
|
531
|
-
elsewhere. The full process (parallel reviewers, worktrees, PR) works best
|
|
532
|
-
in agents with subagents and git: Claude Code, Codex, Cursor, Copilot.
|
|
533
|
-
</details>
|
|
534
|
-
|
|
535
|
-
<details>
|
|
536
|
-
<summary><b>Does it only work for iOS?</b></summary>
|
|
537
|
-
|
|
538
|
-
No. The checklist is platform-agnostic and `platforms.md` has notes for
|
|
539
|
-
SwiftUI, Jetpack Compose and the web, plus widgets, watch and car surfaces.
|
|
540
|
-
</details>
|
|
541
|
-
|
|
542
|
-
<details>
|
|
543
|
-
<summary><b>My project already has a design system.</b></summary>
|
|
544
|
-
|
|
545
|
-
Good. The skill uses your tokens and components, and when one of its rules
|
|
546
|
-
clashes with a written decision of yours, yours wins and the proposal says
|
|
547
|
-
so.
|
|
548
|
-
</details>
|
|
549
|
-
|
|
550
|
-
<details>
|
|
551
|
-
<summary><b>Isn't this just Refactoring UI?</b></summary>
|
|
552
|
-
|
|
553
|
-
It builds on it (and you should buy the book). The skill turns those ideas
|
|
554
|
-
into numbered, checkable fixes, adds what came up in real redesigns of
|
|
555
|
-
AI-built apps (invented numbers, greeting titles, emoji icons, carousels
|
|
556
|
-
hiding content), and is stricter where the book allows decoration that
|
|
557
|
-
AI-generated UIs overuse.
|
|
558
|
-
</details>
|
|
559
|
-
|
|
560
|
-
<details>
|
|
561
|
-
<summary><b>How much does a full run cost?</b></summary>
|
|
562
|
-
|
|
563
|
-
The full process spawns several agents (reviewers, a jury, devs, auditors),
|
|
564
|
-
so it uses noticeably more tokens than a normal chat. For one screen, ask
|
|
565
|
-
for the checklist review only.
|
|
566
|
-
</details>
|
|
249
|
+
Found a pattern of AI slop the checklist misses? Open an issue with a
|
|
250
|
+
before/after screenshot and the fix. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
567
251
|
|
|
568
252
|
## Credits
|
|
569
253
|
|
|
@@ -577,11 +261,6 @@ for the checklist review only.
|
|
|
577
261
|
post with "boxes have their purpose, but an app shouldn't only be built
|
|
578
262
|
by them" — and a better-looking app to prove it.
|
|
579
263
|
|
|
580
|
-
## Contributing
|
|
581
|
-
|
|
582
|
-
Found a pattern of AI slop the checklist misses? Open an issue with a
|
|
583
|
-
before/after screenshot and the fix. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
584
|
-
|
|
585
264
|
## License
|
|
586
265
|
|
|
587
266
|
[MIT](LICENSE)
|
package/bin/unslop.mjs
CHANGED
|
@@ -21,6 +21,10 @@ const HELP = `unslop-design: make your app or site stop looking AI-generated
|
|
|
21
21
|
the rendered page at 390/768/1280 px (needs Playwright)
|
|
22
22
|
npx unslop-design rules
|
|
23
23
|
every rule id with its fix number
|
|
24
|
+
npx unslop-design contrast <text-color> <background> [more backgrounds]
|
|
25
|
+
the WCAG ratio of a color pair (hex, rgba(), Compose 0xFF…)
|
|
26
|
+
npx unslop-design hook
|
|
27
|
+
the post-edit hook itself: reads the agent's event on stdin (what hook configs run)
|
|
24
28
|
npx unslop-design hooks <gemini|codex|copilot|claude> [--write]
|
|
25
29
|
the post-edit hook for that agent: prints its config, --write adds it to this project
|
|
26
30
|
|
|
@@ -119,6 +123,7 @@ switch (cmd) {
|
|
|
119
123
|
case "scan": python("slop-scan.py", rest); break;
|
|
120
124
|
case "score": python("unslop-score.py", rest); break;
|
|
121
125
|
case "rules": python("slop-scan.py", ["--list-rules"]); break;
|
|
126
|
+
case "contrast": python("contrast.py", rest); break;
|
|
122
127
|
case "hook": {
|
|
123
128
|
const r = spawnSync(process.execPath, [join(ROOT, "hooks", "unslop-hook.mjs")], { stdio: "inherit" });
|
|
124
129
|
process.exit(r.status ?? 0);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "unslop-design",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.14.0",
|
|
4
4
|
"description": "Make your app or site stop looking AI-generated: install the agent skill, scan UI code for slop and score it 0-100.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Marcos Novo (https://github.com/marcosnovo)",
|
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
"bin/",
|
|
19
19
|
"scripts/slop-scan.py",
|
|
20
20
|
"scripts/unslop-score.py",
|
|
21
|
+
"scripts/contrast.py",
|
|
21
22
|
"scripts/web-audit.mjs",
|
|
22
23
|
"hooks/",
|
|
23
24
|
"install.sh",
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""WCAG contrast of a text or icon color on a background, measured, not assumed.
|
|
3
|
+
|
|
4
|
+
python3 scripts/contrast.py <foreground> <background> [<more backgrounds>…]
|
|
5
|
+
|
|
6
|
+
Colors as #rgb, #rrggbb, #rrggbbaa, rgb(…) or rgba(…). A translucent
|
|
7
|
+
foreground is composited over each background first, the way it renders.
|
|
8
|
+
For text on a gradient or a photo, pass its lightest and darkest colors:
|
|
9
|
+
the worst one is the ratio. Native colors work the same: SwiftUI
|
|
10
|
+
Color(red:green:blue:) and Compose Color(0xFFrrggbb) are hex values too.
|
|
11
|
+
|
|
12
|
+
$ python3 scripts/contrast.py '#ffffff' '#3ddc84'
|
|
13
|
+
#ffffff on #3ddc84: 1.78:1 fails text (4.5), large text (3), icons (3)
|
|
14
|
+
|
|
15
|
+
Exit code 1 if any pair is under 4.5:1 (or under --min). Standard library only.
|
|
16
|
+
"""
|
|
17
|
+
import argparse
|
|
18
|
+
import re
|
|
19
|
+
import sys
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def parse(color):
|
|
23
|
+
c = color.strip().lower()
|
|
24
|
+
if c.startswith("0xff") and len(c) == 10: # Compose Color(0xFFrrggbb)
|
|
25
|
+
c = "#" + c[4:]
|
|
26
|
+
m = re.fullmatch(r"#?([0-9a-f]{3,8})", c)
|
|
27
|
+
if m:
|
|
28
|
+
h = m.group(1)
|
|
29
|
+
if len(h) in (3, 4):
|
|
30
|
+
h = "".join(ch * 2 for ch in h)
|
|
31
|
+
if len(h) not in (6, 8):
|
|
32
|
+
raise ValueError(color)
|
|
33
|
+
r, g, b = (int(h[i:i + 2], 16) for i in (0, 2, 4))
|
|
34
|
+
a = int(h[6:8], 16) / 255 if len(h) == 8 else 1.0
|
|
35
|
+
return r, g, b, a
|
|
36
|
+
m = re.fullmatch(r"rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)", c)
|
|
37
|
+
if m:
|
|
38
|
+
r, g, b = (float(m.group(i)) for i in (1, 2, 3))
|
|
39
|
+
a = m.group(4)
|
|
40
|
+
a = 1.0 if a is None else (float(a[:-1]) / 100 if a.endswith("%") else float(a))
|
|
41
|
+
return r, g, b, a
|
|
42
|
+
raise ValueError(color)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def over(fg, bg):
|
|
46
|
+
"""fg composited over an opaque bg."""
|
|
47
|
+
a = fg[3]
|
|
48
|
+
return tuple(fg[i] * a + bg[i] * (1 - a) for i in range(3)) + (1.0,)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def luminance(c):
|
|
52
|
+
def ch(v):
|
|
53
|
+
v /= 255
|
|
54
|
+
return v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4
|
|
55
|
+
r, g, b = (ch(v) for v in c[:3])
|
|
56
|
+
return 0.2126 * r + 0.7152 * g + 0.0722 * b
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def ratio(fg, bg):
|
|
60
|
+
l1, l2 = sorted((luminance(over(fg, bg)), luminance(bg)), reverse=True)
|
|
61
|
+
return (l1 + 0.05) / (l2 + 0.05)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def main():
|
|
65
|
+
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
|
66
|
+
ap.add_argument("foreground")
|
|
67
|
+
ap.add_argument("backgrounds", nargs="+")
|
|
68
|
+
ap.add_argument("--min", type=float, default=4.5, help="exit 1 under this ratio (default 4.5, body text)")
|
|
69
|
+
a = ap.parse_args()
|
|
70
|
+
try:
|
|
71
|
+
fg = parse(a.foreground)
|
|
72
|
+
bgs = [parse(b) for b in a.backgrounds]
|
|
73
|
+
except ValueError as e:
|
|
74
|
+
sys.exit(f"can't read the color {e}: use #rrggbb, #rrggbbaa, rgb(…) or rgba(…)")
|
|
75
|
+
worst = None
|
|
76
|
+
for raw, bg in zip(a.backgrounds, bgs):
|
|
77
|
+
if bg[3] < 1:
|
|
78
|
+
sys.exit(f"the background {raw} is translucent: pass the color it renders as (composite it first)")
|
|
79
|
+
r = ratio(fg, bg)
|
|
80
|
+
worst = r if worst is None else min(worst, r)
|
|
81
|
+
passes = [name for name, need in (("text", 4.5), ("large text", 3), ("icons", 3)) if r >= need]
|
|
82
|
+
fails = [f"{name} ({need:g})" for name, need in (("text", 4.5), ("large text", 3), ("icons", 3)) if r < need]
|
|
83
|
+
verdict = ("passes " + ", ".join(passes)) if not fails else ("fails " + ", ".join(fails))
|
|
84
|
+
print(f"{a.foreground} on {raw}: {r:.2f}:1 {verdict}")
|
|
85
|
+
if len(bgs) > 1:
|
|
86
|
+
print(f"worst: {worst:.2f}:1")
|
|
87
|
+
return 1 if worst < a.min else 0
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
if __name__ == "__main__":
|
|
91
|
+
sys.exit(main())
|
package/scripts/slop-scan.py
CHANGED
|
@@ -104,7 +104,7 @@ RULES = [
|
|
|
104
104
|
("empty-action", "#64", "A control whose action is empty (it implies a feature that doesn't exist: principle 6)",
|
|
105
105
|
re.compile(r"\bonClick\s*=\s*\{\s*\}|\bonClick=\{\s*\(\s*\)\s*=>\s*\{\s*\}\s*\}|"
|
|
106
106
|
r"\bButton\s*\(\s*(?:action:\s*)?\{\s*\}|\bButton\s*\{\s*\}\s*label|\baction:\s*\{\s*\}"), "all"),
|
|
107
|
-
("pressure", "#64", "Pressure copy (countdown, scarcity, \"most popular\", \"save N%\"): true, computed and sourced?",
|
|
107
|
+
("pressure", "#64", "Pressure copy (countdown, scarcity, \"most popular\", \"save N%\"): true, computed and sourced? (\"Recommended\" is honest)",
|
|
108
108
|
re.compile(r"(?i:\boffer ends in\b|\bends in \d|\blimited[- ]time (?:offer|deal|only)\b|\bonly \d+ (?:left|spots?|seats?)\b|"
|
|
109
109
|
r"\bhurry\b|\bact now\b|\blast chance\b|\bmost popular\b|\bbest (?:value|seller)\b|"
|
|
110
110
|
r"\bsave \d+\s?%(?!(?:\s|<[^<>]+>)*(?:vs\.?|versus|compared|than)\b))"), "all"),
|