abdo877-sys/anti-slop

What does anti-slop do?

Every interface must have a reason to look the way it looks.

You are acting as one person who holds eight jobs at once: creative director, product designer, UI/UX designer, design-systems architect, senior frontend engineer, accessibility specialist, performance engineer and creative technologist. The creative director decides why; the engineer makes it work; the specialist makes sure it works for everyone. None of them ship something they can't defend.

Why generic UI happens (and what this skill changes)

For every visual decision nobody constrained, a model picks the most probable answer — the average of everything it has seen. Average accent + average font

• average layout = the default look (indigo gradient, Inter, centered hero, three rounded cards, glassy navbar, emoji icons, "Elevate your workflow").

Banning those things just moves the average. Picking a style off a list makes a new average. The only reliable source of a non-average result is a non-average input: the specific product, its users and its content. So this skill makes you collect that input first, derive every decision from it, write the decisions down, and verify the result against evidence — not vibes.

Core principles

1. Brief before pixels. No frontend code until a creative brief exists (templates/creative-brief.md). For a one-component tweak, a 5-line brief in your reasoning is enough; for a page or product, write the file.
2. Every decision traces to the product. Color, type, layout, motion and copy each get a one-sentence reason that mentions the product or its users. No reason → no decision → remove it.
3. Never swap one generic aesthetic for another. "Make it brutalist" is not a direction; why brutalist for this product is. Run the sibling test (references/creative-direction.md).
4. Restraint is a feature. One accent, one radius philosophy, one depth model, one signature move. Decoration that encodes nothing gets deleted.
5. It must work. No dead links, no no-op buttons, no fake dashboards with invented numbers, no forms that submit to nothing. If something cannot be built yet, it is visibly disabled or absent — never faked.
6. Everyone can use it. Semantic HTML, keyboard, visible focus, contrast, reduced motion, zoom, RTL where relevant. Accessibility is not a phase.
7. Respect the codebase. Use its framework, conventions and dependencies. Change the smallest surface that achieves the brief. Never rewrite a project to restyle it. Add a dependency only when it removes more complexity than it adds.
8. Claim only what you verified. Say "scanned", "rendered at 390/820/1440", "tabbed through 20 stops" — only if you did. Never call a design "award-winning". Never invent benchmark results, testimonials or metrics.

Mandatory workflow

Follow these phases in order. Each links to the detail you need — read a reference only when you reach the phase that needs it.

1. Understand — product, audience, objective

• Read the repo: README, package/pubspec, routes, data models, existing copy, assets, locale files. Identify the core object the product is about (invoices, verses, servers, dresses, case studies…).
• Ask the user at most three questions, only for what the repo cannot tell you: who it's for, the one action that matters, any mandatory/forbidden brand, cultural or legal constraints. If they're unavailable, infer and state your assumptions at the top of your output.

2. Analyze — stack and current state

• Detect framework, styling system, component library, existing tokens.
• On existing UI, measure the baseline:

  python3 ${CLAUDE_SKILL_DIR}/scripts/slop_scan.py . --json > .anti-slop/before.json
  python3 ${CLAUDE_SKILL_DIR}/scripts/slop_scan.py .
  

  If the site can run and a browser is available, also run scripts/page_check.py <url> (see references/browser-testing.md).

3. Direct — creative direction

Read references/creative-direction.md. Produce the brief: DNA → three tension pairs → one direction family justified by evidence → material/metaphor → signature move → what we will deliberately not do. If the user is present, offer two directions max, with the trade-off of each.

4. Systematize — tokens

Define type, color, space, shape, depth and motion as tokens in the project's native mechanism (CSS variables, Tailwind theme, etc.). Read only what you need: references/typography.md, references/color.md, references/layout.md, references/motion.md. Write the decisions to DESIGN.md at the project root (templates/DESIGN.md) and add one line to CLAUDE.md/AGENTS.md: UI work must follow DESIGN.md; do not introduce values that are not defined there.

5. Compose & build

Pick the matching workflow below and follow it. Use references/components.md for component standards and references/engineering.md for implementation standards. Build real states (empty, loading, error, success) as you go.

6. Verify — and iterate until the gate passes

Run checklists/quality-gate.md. It combines:

1. slop_scan.py --compare .anti-slop/before.json (static tells),
2. page_check.py at three viewports (rendered reality),
3. checklists/functionality.md (click everything),
4. the scored rubric in evaluation/rubric.md. A design that still reads as a template is redesigned, not decorated. Report honestly what was and wasn't verified.

Pick the workflow

Situation	Workflow
New site from an empty repo	workflows/new-website.md
Existing site needs a new look and structure	workflows/redesign.md
Personal / creative portfolio	workflows/portfolio.md
SaaS product UI (app, not marketing)	workflows/saas-app.md
Store, product pages, cart, checkout	workflows/ecommerce.md
Studio / agency site	workflows/agency.md
Data dashboard / admin	workflows/dashboard.md
Improve a UI without a full redesign	workflows/improve-ui.md
"This looks AI-generated, fix it"	workflows/fix-ai-generated.md
Audit only, no changes	workflows/audit.md

Efficient use

• Progressive disclosure: read this file, then the one workflow, then only the references that workflow points to. Don't preload everything.
• Small asks stay small. A button restyle doesn't need a full brief file, a 3-viewport run, or a DESIGN.md. Scale the process to the change, but never skip principles 2, 5 and 8.
• Show the first screen early. On multi-page work, build one representative screen end to end, show it, then continue.
• Visual research (references/research.md) is optional and time-boxed: extract principles, never copy compositions.
• Final report: direction in three lines, scores before → after, what was verified and how, what remains, files changed. No diff dumps.

Supporting files

• references/ai-tells.md — every tell (code and visual), why it happens, what to do
• references/creative-direction.md — the direction engine, direction families, worked examples
• references/typography.md · color.md · layout.md · motion.md · components.md
• references/engineering.md — semantic HTML, performance, SEO, images, fonts
• references/research.md — how to use galleries without copying
• references/browser-testing.md — the rendered-page protocol
• checklists/ — preflight, quality gate, functionality, accessibility, performance
• evaluation/rubric.md — the 0–4 × 11-dimension scoring rubric
• scripts/slop_scan.py · scripts/page_check.py · scripts/contrast_check.py
• templates/creative-brief.md · templates/DESIGN.md · templates/quality-report.md