unslop-design 1.10.0 → 1.11.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 CHANGED
@@ -29,7 +29,7 @@
29
29
  you accept or reject them one by one.
30
30
  - **A before/after first.** Nothing in your code changes until you approve it.
31
31
  - **A number, not a vibe.** Scripts measure your UI and score it from 0 to 100:
32
- the example dashboard goes from **24 to 100**, and 89 slop hits to none.
32
+ the example dashboard goes from **21 to 100**, and 91 slop hits to none.
33
33
 
34
34
  <p align="center">
35
35
  <img alt="Claude Code skill" src="https://img.shields.io/badge/Claude%20Code-skill-111111">
@@ -185,10 +185,33 @@ On the example above, `web-audit.mjs` goes from 19 spacing values (15 off
185
185
  the scale), 5 weights, 6 radii, 6 shadows, a page that scrolls sideways
186
186
  on a phone and 11 links with no focus style, to 6 spacing values, all on the scale, 2
187
187
  weights, 1 shadow, no sideways scroll and a focus ring on everything.
188
- `slop-scan.py` finds 89 hits in the before and none in the after, and
189
- `unslop-score.py` goes from 24 to 100 on the code alone. Details
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
190
  in [`web.md`](web.md).
191
191
 
192
+ ## Native apps
193
+
194
+ <p align="center">
195
+ <img src="assets/swiftui-before-after.png" alt="A SwiftUI subscriptions screen before and after. Before: 'Hey Maya!' greeting, 'Your Subscriptions' in Title Case, a purple-to-blue gradient hero card with a glow, three stat tiles, emoji icons in colored circles, pink 'Renews Soon!' pills and a gradient 'Unlock your savings with Pro' button. After: the title 'Subscriptions', $142.87 per month as the one hero number, and a plain system list of next charges with letter monograms and the soonest dates in a role color." width="100%">
196
+ </p>
197
+
198
+ SwiftUI and Jetpack Compose are scanned like the web, not as an
199
+ afterthought: literals in views, elevation and stock-kit colors, emoji,
200
+ greetings, Title Case and rows of stat cards in `.swift` and `.kt` files.
201
+
202
+ | Example | Before | After |
203
+ |---|---|---|
204
+ | [`examples/swiftui/`](examples/swiftui) · subscriptions | 32/100: 10 emoji, glows, 4 gradients, 25 literals, "Hey Maya!" | 100/100 |
205
+ | [`examples/compose/`](examples/compose) · settings | 62/100: 7 emoji, 15 literals, the Android Studio template colors | 100/100 |
206
+
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
+
192
215
  ## Use it
193
216
 
194
217
  Type `/unslop-design` (or `$unslop-design` in Codex), or just ask in plain
@@ -237,7 +260,7 @@ python3 scripts/unslop-score.py src/ --audit unslop-audit/report.json # plus th
237
260
 
238
261
  ```text
239
262
  $ python3 scripts/unslop-score.py examples/dashboard-before.html
240
- unslop score: 24/100 — slop (1 source file)
263
+ unslop score: 21/100 — slop (1 source file)
241
264
 
242
265
  Where the points went (fix the top rows first):
243
266
  - 12 [#32] Colored glows (6)
@@ -245,12 +268,12 @@ Where the points went (fix the top rows first):
245
268
  - 8 [#53] Focus outline removed (1)
246
269
  …
247
270
 
248
- Badge: [![unslop score](https://img.shields.io/badge/unslop_score-24%2F100-red)](https://github.com/marcosnovo/unslop-design)
271
+ Badge: [![unslop score](https://img.shields.io/badge/unslop_score-21%2F100-red)](https://github.com/marcosnovo/unslop-design)
249
272
  ```
250
273
 
251
274
  Each kind of slop costs points per hit up to a cap, so the number says how
252
275
  many kinds are left, not how big the codebase is. Paste the badge in your
253
- README, and put "score 24 → 100" at the top of the PR. It's a smoke alarm,
276
+ README, and put "score 21 → 100" at the top of the PR. It's a smoke alarm,
254
277
  not a judge: a 95 can still have a flat hierarchy. `--min 80` makes it exit
255
278
  1 below 80 if you want it in a pre-commit hook, and `--save` keeps every run
256
279
  in `.unslop/history.json` so the score has a trend.
@@ -277,7 +300,7 @@ jobs:
277
300
  runs-on: ubuntu-latest
278
301
  steps:
279
302
  - uses: actions/checkout@v4
280
- - uses: marcosnovo/unslop-design@v1.10.0
303
+ - uses: marcosnovo/unslop-design@v1.11.0
281
304
  with:
282
305
  paths: src
283
306
  min: 80 # optional; also: allow, scale, type-scale
@@ -434,7 +457,7 @@ before/after without the whole team.
434
457
  | [`scripts/slop-scan.py`](scripts/slop-scan.py) | Finds slop patterns in source with file, line and fix number |
435
458
  | [`scripts/web-audit.mjs`](scripts/web-audit.mjs) | Measures a rendered page: overflow, value census, contrast, focus |
436
459
  | [`scripts/unslop-score.py`](scripts/unslop-score.py) | Both as one score from 0 to 100, with the breakdown and a badge |
437
- | [`examples/`](examples) | One dashboard before and after, to try the scripts on |
460
+ | [`examples/`](examples) | Before/after pairs to try the scripts on: a web dashboard, a SwiftUI screen, a Compose screen |
438
461
  | [`.claude-plugin/`](.claude-plugin) | Claude Code plugin and marketplace manifests |
439
462
  | [`hooks/`](hooks) | The Claude Code hook that scans each UI edit |
440
463
  | [`action.yml`](action.yml) | The GitHub Action: annotations, job summary, minimum score |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "unslop-design",
3
- "version": "1.10.0",
3
+ "version": "1.11.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)",
@@ -110,6 +110,24 @@ RULES = [
110
110
  r"\bsave \d+\s?%(?!(?:\s|<[^<>]+>)*(?:vs\.?|versus|compared|than)\b))"), "all"),
111
111
  ("plural-hack", "#71", "\"item(s)\" in UI text (let the platform's plural rules pick the form)",
112
112
  re.compile(r"(?:[\"'`]|(?<!=)>)[^\"'<`\n]*(?<=[\s>\"'`])[A-Za-z][a-z]{2,}\(s\)(?=[\s.,:!?<\"'`]|$)"), "all"),
113
+ ("justified-text", "#28", "Justified text (uneven gaps on screens; align left)",
114
+ re.compile(r"text-align\s*:\s*justify\b|\btext-justify\b(?!\s*:)"), "web"),
115
+ ("extreme-tracking", "#29", "Letter-spacing tighter than -0.04em (letters collide; a bit tighter, not crushed)",
116
+ re.compile(r"letter-spacing\s*:\s*-0?\.(?:0[5-9]|[1-9])\d*em|\btracking-\[-0?\.(?:0[5-9]|[1-9])\d*em\]"), "web"),
117
+ ("fixed-width", "#57", "Fixed width of 400px or more (scrolls sideways on a phone: max-width and fluid)",
118
+ re.compile(r"(?<![-\w(])(?:min-)?width\s*:\s*(?:[4-9]\d{2}|\d{4,})px|(?<![\w-])(?:min-)?w-\[(?:[4-9]\d{2}|\d{4,})px\]"), "web"),
119
+ ("lorem", "#48", "Lorem ipsum (real content in every mock)",
120
+ re.compile(r"(?i:\blorem ipsum\b|\bdolor sit amet\b)"), "all"),
121
+ ("placeholder-image", "#35 #48", "Placeholder image service (real images, or none)",
122
+ re.compile(r"(?i:via\.placeholder\.com|placehold\.(?:co|it)\b|picsum\.photos|dummyimage\.com|placekitten\.com|"
123
+ r"loremflickr\.com|source\.unsplash\.com/random|placeimg\.com)"), "all"),
124
+ ("bare-delta", "#52", "A delta with no baseline (\"+12%\" vs what? \"+12% vs September\")",
125
+ re.compile(r"(?:>|[\"'`]|\(\s*\")\s*[+↑▲↓▼−]\s?\d+(?:[.,]\d+)?\s?%(?!(?:[^<\"'`\n]|<[^<>]+>){0,48}?"
126
+ r"(?i:\b(?:vs\.?|versus|than|from|since|compared|over|last|previous|prior|yesterday|week|month|quarter|year|"
127
+ r"yoy|mom|wow|qoq|baseline|target|goal|avg|average)\b))"), "all"),
128
+ ("straight-quotes", "#61", "Straight quote or apostrophe in UI copy (use ’ “ ”)",
129
+ re.compile(r">[^<>{}\n]*[A-Za-z]'[A-Za-z][^<>{}\n]*<|>[^<>{}\n=]*\s\"[A-Za-z][^\"<>{}\n]*\"[^<>{}\n]*<|"
130
+ r"\b(?:Text|Button|Label|navigationTitle)\(\s*(?:text\s*=\s*)?\"[^\"\n]*[A-Za-z]'[A-Za-z]"), "all"),
113
131
  ("no-focus", "#53", "Focus outline removed — is there a :focus-visible style?",
114
132
  re.compile(r"outline\s*:\s*(none|0)\b|\boutline-none\b|focus:outline-none"), "web"),
115
133
  ]
@@ -396,6 +414,12 @@ def file_checks(path, text, kind, hits):
396
414
  # Rule-level checks (#60, #66-#69): what a declaration means depends on its neighbors in the
397
415
  # same rule or class list, so they read whole CSS blocks and whole class attributes.
398
416
  CSS_EXT = {".css", ".scss", ".sass", ".less", ".html", ".htm", ".vue", ".svelte", ".astro"}
417
+ MARKUP_EXT = {".html", ".htm", ".jsx", ".tsx", ".vue", ".svelte", ".astro", ".mdx"}
418
+ PAGE_EXT = {".html", ".htm", ".vue", ".svelte", ".astro"}
419
+ ANY_CLASS = re.compile(r"""\bclass(?:Name)?\s*=\s*["'{`]+([^"'`}]+)""")
420
+ SECTION_NUMBER = re.compile(r">\s*0([1-9])\s*[.·/—–-]?\s*<")
421
+ COUNT_PILL = re.compile(r"""<(?:span|small|b|div|em|i)\b[^<>]*\bclass(?:Name)?\s*=\s*["'{`]+[^"'`}]*(?:\brounded-full\b[^"'`}]*\bbg-[a-z]+-(?:[4-9]00)\b|\bbg-[a-z]+-(?:[4-9]00)\b[^"'`}]*\brounded-full\b|\b(?:badge|pill)\b)[^"'`}]*["'`}]+[^<>]*>\s*\d{1,4}\+?\s*</""")
422
+ ICON_CIRCLE = re.compile(r"(?=.*\brounded-(?:full|xl|2xl)\b)(?=.*\bbg-[a-z]+-(?:50|100|200)\b)(?=.*\b(?:size|w|h)-(?:8|9|10|11|12|14)\b)")
399
423
  CSS_BLOCK = re.compile(r"([^{}]+)\{([^{}]*)\}")
400
424
  SIDE_BORDER = re.compile(r"border-(?:left|right|inline-start|inline-end)(?:-width)?\s*:\s*(\d+(?:\.\d+)?)px\s*(?:solid|[^;]*)", re.I)
401
425
  RADIUS = re.compile(r"border-radius\s*:(?!\s*0(?:px)?\s*(?:[;}]|$))", re.I)
@@ -470,6 +494,23 @@ def block_checks(path, text, ignored, line_of, hits):
470
494
  for m in TW_MONO_HEADING.finditer(text):
471
495
  add(mono, m.start(), f"<{m.group(1)} class=… font-mono>")
472
496
 
497
+ if ext in MARKUP_EXT:
498
+ # #13: one h1 per page; section titles are labels.
499
+ h1s = [m.start() for m in re.finditer(r"<h1\b", text)]
500
+ if len(h1s) >= 2 and ext in PAGE_EXT: # a .tsx file often holds several components
501
+ add(("multiple-h1", "#13", "More than one h1 on the page (section titles are labels, not h1)"), h1s[1], f"{len(h1s)} × <h1>")
502
+ # #60: 01 / 02 / 03 on sections.
503
+ nums = [(m.start(), int(m.group(1))) for m in SECTION_NUMBER.finditer(text)]
504
+ if {1, 2, 3} <= {n for _, n in nums}:
505
+ add(("section-numbers", "#60", "Sections numbered 01 / 02 / 03 (does the order carry information?)"), nums[0][0], "01, 02, 03…")
506
+ # #50: counts in filled pills.
507
+ for m in COUNT_PILL.finditer(text):
508
+ add(("count-pill", "#50", "A count in a filled pill (counts are muted tabular text: \"Inbox 12\")"), m.start(), m.group(0)[-40:])
509
+ # #33: icons in colored circles, row after row.
510
+ circles = [m.start() for m in ANY_CLASS.finditer(text) if ICON_CIRCLE.search(m.group(1))]
511
+ if len(circles) >= 3:
512
+ add(("icon-circle", "#33", "Icons in colored circles on every row (one icon style; shapes only in empty states)"), circles[0], f"{len(circles)} tinted circles")
513
+
473
514
 
474
515
  # Custom properties across the scanned files: a var(--name) nobody defines falls back in
475
516
  # silence (after a rename, a merge, a typo). Only when some token is defined in scope.
@@ -492,6 +533,7 @@ def token_checks(paths, hits):
492
533
  for n, line in enumerate(text.splitlines(), 1):
493
534
  if "unslop-ignore" not in line:
494
535
  uses += [(path, n, m.group(1)) for m in TOKEN_USE.finditer(line)]
536
+ project_checks(paths, hits)
495
537
  if not defined:
496
538
  return # the token file isn't in what was scanned: nothing to compare against
497
539
  key = ("undefined-token", "#1", "Token used but defined nowhere in the scanned files")
@@ -500,6 +542,43 @@ def token_checks(paths, hits):
500
542
  hits.setdefault(key, []).append((path, n, f"var({name})"))
501
543
 
502
544
 
545
+ # Across the scanned web files (#62, #63): a dark theme with no color-scheme anywhere, and
546
+ # keyframe animations with no reduced-motion alternative anywhere.
547
+ DARK_THEME = re.compile(r"prefers-color-scheme\s*:\s*dark|\[data-theme=[\"']?dark|\bdark:[a-z]")
548
+ COLOR_SCHEME = re.compile(r"(?<![-\w])color-scheme\s*:|name=[\"']color-scheme[\"']|\bcolorScheme\s*:")
549
+ ANIMATION = re.compile(r"@keyframes\s+[\w-]+|\banimate-(?:spin|ping|pulse|bounce|\[)")
550
+ REDUCED_MOTION = re.compile(r"prefers-reduced-motion|\bmotion-(?:reduce|safe):|useReducedMotion|reducedMotion")
551
+
552
+
553
+ def project_checks(paths, hits):
554
+ dark = anim = None
555
+ has_scheme = has_reduced = False
556
+ for path in paths:
557
+ if os.path.splitext(path)[1].lower() not in WEB or path.endswith((".min.js", ".min.css")):
558
+ continue
559
+ try:
560
+ text = open(path, encoding="utf-8", errors="replace").read()
561
+ except OSError:
562
+ continue
563
+ if len(text) > 2_000_000:
564
+ continue
565
+ lines = text.splitlines()
566
+
567
+ def first(rx):
568
+ for n, line in enumerate(lines, 1):
569
+ if "unslop-ignore" not in line and rx.search(line):
570
+ return (path, n, rx.search(line).group(0))
571
+ return None
572
+ dark = dark or first(DARK_THEME)
573
+ anim = anim or first(ANIMATION)
574
+ has_scheme = has_scheme or bool(COLOR_SCHEME.search(text))
575
+ has_reduced = has_reduced or bool(REDUCED_MOTION.search(text))
576
+ if dark and not has_scheme:
577
+ hits.setdefault(("no-color-scheme", "#62", "A dark theme with no color-scheme (form controls and scrollbars stay light)"), []).append(dark)
578
+ if anim and not has_reduced:
579
+ hits.setdefault(("no-reduced-motion", "#63", "Animations with no prefers-reduced-motion alternative"), []).append(anim)
580
+
581
+
503
582
  # A written project decision can allow a taste rule (a base-6 grid, tracked caps as the
504
583
  # brand's signature). It can't allow the floors: contrast and visible focus and target size
505
584
  # (accessibility, principle 5) and invented claims (principle 6). Shared with unslop-score.py.
@@ -551,6 +630,25 @@ def files(paths):
551
630
  yield os.path.join(root, n)
552
631
 
553
632
 
633
+ # Code samples and at-rule conditions aren't UI copy or layout (straight-quotes, fixed-width).
634
+ CODE_SPAN = re.compile(r"<(code|pre|kbd|samp)\b[^>]*>.*?</\1>", re.S)
635
+
636
+
637
+ def mask_code(line, in_pre):
638
+ """The line without code: what a multi-line <pre> still holds, inline <code>/<pre>/<kbd>/<samp>
639
+ spans, and an unclosed <pre> to the end of the line. Returns (masked line, inside <pre> after it)."""
640
+ if in_pre:
641
+ end = line.find("</pre>")
642
+ if end == -1:
643
+ return "", True
644
+ line = line[end + len("</pre>"):]
645
+ line = CODE_SPAN.sub("", line)
646
+ start = line.find("<pre")
647
+ if start != -1:
648
+ return line[:start], True
649
+ return line, False
650
+
651
+ AT_RULE_PRELUDE = re.compile(r"@(?:media|container|supports)\b[^{]*")
554
652
  DEFAULT_SCALE = "0,1,2,4,8,12,16,20,24,32,40,48,64,80,96"
555
653
  DEFAULT_TYPE_SCALE = {11, 12, 13, 14, 15, 16, 17, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 40, 44, 48, 56, 64, 72, 80, 96}
556
654
  # Colored shadows in CSS, any offset: "0 10px 30px rgba(255,107,107,.45)" is a glow too (#32).
@@ -587,7 +685,9 @@ def scan(path, scale, hits, type_scale=None):
587
685
  has_focus_visible = "focus-visible" in text
588
686
  file_checks(path, text, kind, hits)
589
687
  in_root = False
688
+ in_pre = False
590
689
  for n, line in enumerate(text.splitlines(), 1):
690
+ copy_line, in_pre = mask_code(line, in_pre)
591
691
  if "unslop-ignore" in line:
592
692
  continue
593
693
  stripped = line.strip()
@@ -609,7 +709,12 @@ def scan(path, scale, hits, type_scale=None):
609
709
  continue
610
710
  if rid in ("native-literal", "elevation-literal") and is_token_file:
611
711
  continue # Tokens.kt / Type.kt / Theme.swift: literals belong there
612
- if rx.search(line):
712
+ target = line
713
+ if rid == "straight-quotes":
714
+ target = copy_line # code samples keep their straight quotes
715
+ elif rid == "fixed-width":
716
+ target = AT_RULE_PRELUDE.sub("", line) # @media (min-width: 768px) is a breakpoint, not a width
717
+ if rx.search(target):
613
718
  hits.setdefault((rid, ref, desc), []).append((path, n, stripped[:110]))
614
719
  if kind == "web":
615
720
  glow_key = next((r[0], r[1], r[2]) for r in RULES if r[0] == "glow")
@@ -650,12 +755,19 @@ FILE_RULES = [
650
755
  ("bounce-easing", "#67", "Bouncy or elastic easing (ease out, don't overshoot)"),
651
756
  ("ghost-card", "#68", "1px border and a soft shadow on the same card (pick one separator)"),
652
757
  ("mono-disguise", "#69", "Monospace on headings or the whole page (code faces are for code and data)"),
758
+ ("multiple-h1", "#13", "More than one h1 on the page (section titles are labels, not h1)"),
759
+ ("section-numbers", "#60", "Sections numbered 01 / 02 / 03 (does the order carry information?)"),
760
+ ("count-pill", "#50", "A count in a filled pill (counts are muted tabular text: \"Inbox 12\")"),
761
+ ("icon-circle", "#33", "Icons in colored circles on every row (one icon style; shapes only in empty states)"),
762
+ ("no-color-scheme", "#62", "A dark theme with no color-scheme (form controls and scrollbars stay light)"),
763
+ ("no-reduced-motion", "#63", "Animations with no prefers-reduced-motion alternative"),
653
764
  ]
654
765
 
655
766
 
656
767
  def all_rules():
657
768
  return [(r[0], r[1], r[2], r[4]) for r in RULES] + [(i, ref, d, "web" if i in ("hidden-nav", "side-stripe", "hard-shadow",
658
- "bounce-easing", "ghost-card", "mono-disguise", "off-scale", "undefined-token") else "all") for i, ref, d in FILE_RULES]
769
+ "bounce-easing", "ghost-card", "mono-disguise", "off-scale", "undefined-token", "multiple-h1", "section-numbers",
770
+ "count-pill", "icon-circle", "no-color-scheme", "no-reduced-motion") else "all") for i, ref, d in FILE_RULES]
659
771
 
660
772
 
661
773
  def gh_escape(s):
@@ -66,6 +66,19 @@ CODE = {
66
66
  "ghost-card": ("Border and shadow on one card", "#68", 1, 4),
67
67
  "mono-disguise": ("Monospace headings or body", "#69", 2, 4),
68
68
  "plural-hack": ("\"item(s)\" plurals", "#71", 1, 3),
69
+ "justified-text": ("Justified text", "#28", 1, 3),
70
+ "extreme-tracking": ("Crushed letter-spacing", "#29", 1, 3),
71
+ "fixed-width": ("Fixed widths of 400px+", "#57", 2, 6),
72
+ "lorem": ("Lorem ipsum", "#48", 3, 6),
73
+ "placeholder-image": ("Placeholder images", "#48", 2, 6),
74
+ "bare-delta": ("Deltas with no baseline", "#52", 1, 4),
75
+ "straight-quotes": ("Straight quotes in copy", "#61", 0.5, 3),
76
+ "multiple-h1": ("More than one h1", "#13", 2, 2),
77
+ "section-numbers": ("Sections numbered 01/02/03", "#60", 1, 1),
78
+ "count-pill": ("Counts in filled pills", "#50", 1, 4),
79
+ "icon-circle": ("Icons in colored circles", "#33", 1, 2),
80
+ "no-color-scheme": ("Dark theme without color-scheme", "#62", 2, 2),
81
+ "no-reduced-motion": ("Animation without reduced motion", "#63", 3, 3),
69
82
  }
70
83
  # Rendered page. "sprawl" = distinct values beyond what a system needs.
71
84
  PAGE = {