Rules for an AI coding agent to filter out generic AI-generated UI designs, text, and code.
JavaScript accessibilityagent-skillsai-agentsai-coding-agentai-slopanti-slopclaude-codecopywritingdesign-rulesui-design
Update Version 2.4.0
miqdadbadzubair-designb4f12463a514
diff --git a/README.md b/README.mdindex 7a404fc..8df6d9f 100644--- a/README.md+++ b/README.md@@ -38,15 +38,15 @@ That's it. The pointer block is the source of truth: every later session loads tProject root/├── AGENTS.md (or CLAUDE.md, GEMINI.md, etc.) # router: tells the agent what to read├── DESIGN.md # direction: the soul of your UI (yours)-└── antislop.md + the skill files you want # filter: from this repo+└── antislop.md # filter: from this repo``````bashcurl -o antislop.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/main/antislop.md-curl -o antislop-ui.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/main/antislop-ui.md-curl -o antislop-copywriting.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/main/antislop-copywriting.md```+`antislop.md` alone is a complete filter. Skills add depth for one concern at a time; the wizard installs them, or download any you want the same way (`curl -o <skill-name>.md`).+Then add a pointer block to your entry file, listing exactly the skills you installed:```md@@ -65,9 +65,10 @@ You can optionally put a dial line in `DESIGN.md` (`Dial: ENERGY 2 / RHYTHM 3 /|-------|----------------|----------|| `antislop-ui` | UI / visual: layout, color, components, decoration, motion, structure | v2.2.0 || `antislop-copywriting` | Copy & text: headlines, CTAs, tone, fake stats, anti-AI-writing patterns, markdown hygiene | v2.3.0 |-| `antislop-a11y` | Accessibility: contrast, keyboard, focus states | v2.4.0 (planned) |-| `antislop-docs` | Documentation: READMEs, API references, changelogs, tutorials | v2.5.0 (planned) |-| `antislop-identity` | Identity & naming: product names, taglines, brand voice | v2.6.0 (planned) |+| `antislop-human` | Human: contrast, keyboard, focus, states | v2.4.0 (planned) |+| `antislop-layoutmobile` | Mobile layout: responsive breakpoints, grids, overflow, tap targets | v2.5.0 (planned) |+| `antislop-docs` | Documentation: READMEs, API references, changelogs, tutorials | v2.6.0 (planned) |+| `antislop-identity` | Identity & naming: product names, taglines, brand voice | v2.7.0 (planned) |Pick what matches the work: UI work → `antislop-ui`, copy work → `antislop-copywriting`, both → "All", or none (the core alone is a complete filter).diff --git a/ROADMAP.md b/ROADMAP.mdindex e9e0a43..8a04ed5 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -24,9 +24,10 @@ This keeps the filter pull-only-what-you-need, and it makes the v3 packaging mec|---------|-------|---------|| v2.2.0 | `antislop-ui` | UI / visual: layout, color, components, decoration, motion, structure || v2.3.0 | `antislop-copywriting` | Copy and text: headlines, CTAs, tone, fake stats, markdown hygiene |-| v2.4.0 | `antislop-a11y` | Accessibility: contrast, keyboard, focus states (home of the contrast checker) |-| v2.5.0 | `antislop-docs` | Documentation: READMEs, API references, changelogs, tutorials |-| v2.6.0 | `antislop-identity` | Identity and naming: product names, taglines, brand voice |+| v2.4.0 | `antislop-human` | Human: contrast, keyboard, focus, states (home of the contrast checker) |+| v2.5.0 | `antislop-layoutmobile` | Mobile layout: responsive breakpoints, grids, overflow, tap targets |+| v2.6.0 | `antislop-docs` | Documentation: READMEs, API references, changelogs, tutorials |+| v2.7.0 | `antislop-identity` | Identity and naming: product names, taglines, brand voice |### v3.0.0: the skill/plugin@@ -43,9 +44,10 @@ Target release: end of Q3 2026.- [x] v2.1.1 - English only; Indonesian mirrors removed- [x] v2.2.0 - core + First-Run Install Wizard + `antislop-ui` skill- [x] v2.3.0 - `antislop-copywriting` skill-- [ ] v2.4.0 - `antislop-a11y`-- [ ] v2.5.0 - `antislop-docs`-- [ ] v2.6.0 - `antislop-identity`+- [ ] v2.4.0 - `antislop-human`+- [ ] v2.5.0 - `antislop-layoutmobile`+- [ ] v2.6.0 - `antislop-docs`+- [ ] v2.7.0 - `antislop-identity`- [ ] v3.0.0 - skill/plugin packaging## Not in scopediff --git a/antislop-human.md b/antislop-human.mdnew file mode 100644index 0000000..ee73664--- /dev/null+++ b/antislop-human.md@@ -0,0 +1,142 @@+# antislop-human++> Anti AI Slop: Design & Copy Rules. Human skill++> Part of the antislop system. Read together with `antislop.md` (the core). This skill deep-dives the human concern: the UI must stay usable by people with different eyes, hands, and setups. Contrast, keyboard, focus, states, and the mobile details that exclude people. The layout mechanics behind mobile (breakpoints, grids, overflow, tap targets) live in `antislop-layoutmobile`.++## How to use this skill++- Load together with `antislop.md` whenever the task builds or edits UI. The core holds the mechanism (the purpose test, the three tiers, the Delivery Gate); this skill holds the human-side depth: the parts of a UI that exclude people with different eyes, hands, and setups.+- Every entry has the same shape: **Tell** (the pattern), **Why** (who it excludes, and why it reads as unfinished), **Fix** (what to do instead), with the governing core rule cited as R-XX.+- Accessibility is not a checklist of extras bolted on at the end. It is part of the core promise that "the UI holds up" (C-4). The Delivery Gate in the core remains the gate; the "Human Skill Checklist" at the end of this file is the supplement to run alongside it.+- The contrast checker (formula + reference table + script) lives in this skill. Use it for every color pairing you cannot verify by eye.+- For the layout mechanics behind mobile (breakpoints, grids, overflow, tap targets), load `antislop-layoutmobile` together with this skill. This skill keeps only the mobile details that exclude people: zooming, and the on-screen keyboard.++## Color & Contrast++### Low-Contrast Text++- **Tell:** light grey text on a white or near-white background, thin body text, muted labels chosen because they look "elegant" but are hard to read.+- **Why:** it excludes low-vision users and everyone in bright light. It is a visual choice made without checking the standard, which is exactly the kind of default the filter exists to catch.+- **Fix:** meet WCAG AA minimums (R-25): 4.5:1 for normal text, 3:1 for large text (18px+). Compute the ratio; do not eyeball it.++### Text Over a Photo or Gradient++- **Tell:** white text placed directly over an image or gradient that is light in some areas, checked at one bright spot only.+- **Why:** contrast is local. Where the image is light, the text drops below 4.5:1 even if the hero still "looks" fine. R-25 requires testing the whole area the text passes over, not a single point.+- **Fix:** add a scrim or a solid color block behind the text, then verify the worst spot, not the best. If any part of the text area fails, the treatment fails.++### The Grey-on-Grey Hallucination++- **Tell:** "dark grey on black" or "light grey on white" claimed to pass AA without a computation.+- **Why:** this is the most common accessibility hallucination. The eye overestimates contrast on grey pairs, and agents repeat the claim because it sounds plausible. #555555 on black is 2.8:1. It fails.+- **Fix:** never assert a pairing passes. Run the contrast checker (below) or apply the formula. When neither is possible, use the reference table.++### Non-Text Contrast++- **Tell:** interactive components (buttons, icons, input borders, focus indicators, chart segments) distinguished from their background by less than 3:1.+- **Why:** non-text UI carries information by shape and edge. When the edge is a hair of tint, low-vision users cannot find the control. The same bar applies to states like hover and selected.+- **Fix:** give every component boundary and every status indicator a 3:1 ratio against adjacent colors (WCAG 1.4.11). Pair icons with a text label that meets 4.5:1.++### The Contrast Checker++The home of the contrast checker. Three layers, from most to least convenient:++**The script.** When a script runtime is available and the file is present, run it instead of computing by hand:++```bash+python scripts/contrast-check.py "#FFFFFF" "#777777"+# normal text: FAIL (4.48 < 4.5)+# large text: PASS (4.48 >= 3.0)+```++The script exists so agents stop hallucinating AA. It takes two hex colors and prints the ratio and the verdict for both text sizes. It ships with the skill; if it is missing from an older setup, the formula and table below are complete on their own. Never block on the script.++**The formula (WCAG 2.x).**++1. Contrast ratio = (L1 + 0.05) / (L2 + 0.05), where L1 is the lighter relative luminance and L2 the darker.+2. Relative luminance L of one color: convert each channel to 0-1 (`c = hex / 255`), then linearize: if `c <= 0.03928`, `c_lin = c / 12.92`; otherwise `c_lin = ((c + 0.055) / 1.055)^2.4`.+3. `L = 0.2126*R + 0.7152*G + 0.0722*B`.+4. Round the ratio to two decimals and compare: 4.5:1 for normal text, 3:1 for large text (18px+, per R-25). The maximum ratio is 21.0 (black on white).++**The reference table** (common pairings, computed with the formula):++| Pairing (text on background) | Ratio | Normal text (4.5) | Large text (3.0) |+|------------------------------|-------|-------------------|------------------|+| Black on white | 21.0 | Pass | Pass |+| White on black | 21.0 | Pass | Pass |+| White on #333333 | 12.6 | Pass | Pass |+| White on #666666 | 5.7 | Pass | Pass |+| #777777 on white | 4.5 | Borderline, compute | Pass |+| White on #888888 | 3.5 | Fail | Pass |+| White on #999999 | 2.8 | Fail | Fail |+| #555555 on black | 2.8 | Fail | Fail |++Read the table as a sanity check, not as a substitute. Any pairing not listed, or anything near a threshold, goes through the formula or the script.++## Keyboard++### Removed Focus Outline++- **Tell:** `outline: none` or `outline: 0` with no replacement focus style.+- **Why:** keyboard users cannot see where they are. It is the fastest way to make a UI unusable without a mouse, and R-32 forbids it outright.+- **Fix:** keep or replace the outline with a visible `:focus-visible` style that meets the same contrast bar (3:1 against its neighbors). Never set `outline: none` without a replacement.++### Mouse-Only Patterns++- **Tell:** menus that open on hover only, dropdowns that click-open but do not keyboard-open, drag-and-drop with no keyboard fallback.+- **Why:** each one excludes keyboard and assistive-technology users (R-32). If a control cannot be reached and operated by Tab, Enter, or Space, it does not exist for a whole group of people.+- **Fix:** every interactive element is reachable and operable by keyboard (R-32): logical tab order following visual order, activation with Enter or Space, and dialogs closable with Escape (R-26).++### Broken Tab Order++- **Tell:** focus jumps around the page, skips content, or lands on hidden elements because the DOM order does not match the visual order.+- **Why:** tab order that reads the code order instead of the visual order makes navigation unpredictable (R-32). Users lose their place and the page feels broken.+- **Fix:** keep the source order matching the visual order, add skip links for long pages, and never give real content `tabindex="-1"` unless it is part of a controlled focus trap such as a dialog.++## Focus & States++### Weak or Invisible Focus Indicator++- **Tell:** a focus ring the same color as the background, a ring that only appears on hover, or an indicator thinner than a 1px border.+- **Why:** the focus indicator is how keyboard users know where they are. If it fails the contrast bar or only shows on hover, keyboard-only use breaks (R-32, R-34).+- **Fix:** a visible focus indicator on every interactive element, 3:1 against adjacent colors, in every theme you ship. Check it in dark and light mode.++### Color-Only Feedback++- **Tell:** success, error, and status communicated only by color: red error text, green success border, a tinted chip, with no icon, label, or text.+- **Why:** it excludes color-blind and low-vision users, and it disappears entirely in forced-colors mode. A status that depends on seeing hue is not a status (C-4).+- **Fix:** pair every color signal with text, an icon, or a pattern. Error states are text first: "Password must be at least 8 characters", not just a red border.++### Missing UI States++- **Tell:** a data view with no empty, loading, or error state, or states that exist but are invisible: a spinner with no text, an empty screen with no explanation.+- **Why:** R-27 requires the three states; the accessibility angle is that each must be perceivable and informative, not decorative. A loading spinner with no context reads as a frozen page to screen-reader users.+- **Fix:** every data view has all three states (R-27), each announced or visible: an explicit empty message, a loading state with text, and an error state that says what happened and how to proceed.++## Zoom & Mobile Use++The layout mechanics behind mobile (breakpoints, grids, overflow, tap targets) live in `antislop-layoutmobile`. This section keeps only the mobile details that exclude people: zooming, and the on-screen keyboard.++### Text That Cannot Zoom++- **Tell:** fixed pixel font sizes, or containers with `overflow: hidden` that clip text at 200% zoom.+- **Why:** users must be able to resize text (WCAG 1.4.4). If zooming to 200% clips the content or forces horizontal scroll, the text is not resizable in practice.+- **Fix:** fluid type that reflows with zoom, no clipping containers on text, and verify the layout holds at 200% zoom on a narrow viewport (R-35).++### Mobile Keyboard Covers the Form++- **Tell:** inputs at the bottom of the viewport hidden behind the on-screen keyboard, with no scroll-into-view and no room for the input.+- **Why:** a form the user cannot see or reach is a form they cannot complete. It is a mobile-only exclusion (R-35).+- **Fix:** when an input is focused, it scrolls into view above the keyboard, with enough bottom padding that the focused field is never covered. Test with a real device or an emulated keyboard.++## Human Skill Checklist++Run these alongside the core Delivery Gate when the task involves UI. Any **yes** on a must-be-no item, or **no** on a must-be-yes item, is a FAIL:++- [ ] Is every text and background pairing verified against the contrast checker (formula, table, or script), including text over images and gradients? (R-25)+- [ ] Does every interactive component boundary and status indicator meet 3:1 against its background? (non-text contrast)+- [ ] Is the focus indicator visible, high-contrast, and present on every interactive element in every theme? (R-32, R-34)+- [ ] Is every interactive element reachable and operable by keyboard, with dialogs closable via Escape and no `outline: none` without a replacement? (R-32, R-26)+- [ ] Are the empty, loading, and error states of every data view present and perceivable, not color-only? (R-27, C-4)+- [ ] Can text be resized to 200% without being clipped, and does the mobile keyboard never cover a focused input? (R-35)diff --git a/antislop.md b/antislop.mdindex 3ceb462..ba640c0 100644--- a/antislop.md+++ b/antislop.md@@ -18,9 +18,10 @@ If no antislop pointer exists and this file is being read for the first time, ru1. **Declare the setup before doing anything.** Tell the user you will (a) download the skill file(s) they choose into the same folder as this file, and (b) append an antislop pointer block at the end of the project's entry file. Get approval. Never modify the entry file silently.2. **Ask which skills to install** (multi-select, in the user's chat language). List only the skills that exist in this version of antislop:- - **1. All** (recommended): install every available skill. Choose this when the work spans both UI and copy.+ - **1. All** (recommended): install every available skill. Choose this when the work spans UI, copy, or people.- **2. `antislop-ui`** (UI / visual): pick this for building or editing a website, web app, or interface: color, layout, components, decoration, motion.- **3. `antislop-copywriting`** (copy & text): pick this for writing or editing copy: headlines, CTAs, value propositions, tone, landing-page text, product prose.+ - **4. `antislop-human`** (people): pick this for making sure a UI works for people with different eyes, hands, and setups: contrast, keyboard, focus, states.- New skills appear here as they ship; never offer a skill that does not exist in this version.If the user declines or says "core only", stop here and use this file alone as the filter. Do not install anything.@@ -28,18 +29,22 @@ If no antislop pointer exists and this file is being read for the first time, ru- **1. The user supplies direction (recommended).** They write their own `DESIGN.md`, or answer a few direction questions (identity, personality, palette, typography, mood) and the agent transcribes their answers into `DESIGN.md`. The user is the author; the agent only formats. Never invent example content for `DESIGN.md`.- **2. The agent supplies direction, with an honest warning.** The agent writes the direction itself, stating explicitly that agent-generated style tends toward default AI taste, which is the slop antislop filters, so the result is likely monotonous. If chosen, still ask a minimal brief (product, audience, mood) before building.- **3. The user skips direction for now.** Proceed without a `DESIGN.md`. Any UI built this way must be labeled *"draft without direction"* with dials ENERGY 1 / RHYTHM 1 / MOTION 1 (R-37), and is not a shippable deliverable.-4. **Download the chosen skill file(s)** into the same folder as this file, level with it (never inside nested folders), pinned to the release tag that matches this version so a newer skill never mixes with an older core:+4. **Download the chosen skill file(s)** into the same folder as this file, level with it, pinned to the release tag that matches this version so a newer skill never mixes with an older core. When `antislop-human` is chosen, also download its contrast-check script into a `scripts/` subfolder:```bash- curl -o antislop-ui.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/v2.3.0/antislop-ui.md- curl -o antislop-copywriting.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/v2.3.0/antislop-copywriting.md+ curl -o antislop-ui.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/v2.4.0/antislop-ui.md+ curl -o antislop-copywriting.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/v2.4.0/antislop-copywriting.md+ curl -o antislop-human.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/v2.4.0/antislop-human.md+ mkdir -p scripts+ curl -o scripts/contrast-check.py https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/v2.4.0/scripts/contrast-check.py```5. **Append the pointer block at the END of the project's entry file** (the file the running tool reads at session start: `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex, `GEMINI.md` for Gemini CLI, and so on). If that file does not exist, create it. Never modify existing content:```md<!-- antislop: auto-managed block, do not edit -->## antislop- For UI or copy work, read `antislop.md` (core) and then the skill for the task:+ For UI, copy, or people work, read `antislop.md` (core) and then the skill for the task:- UI / visual: `antislop-ui.md`- Copy & text: `antislop-copywriting.md`+ - People: `antislop-human.md`Before starting, ask the user when antislop applies: during the work, or after it is done.```If an older antislop block exists (even without the marker), replace just that block instead of appending a duplicate.diff --git a/scripts/contrast-check.py b/scripts/contrast-check.pynew file mode 100644index 0000000..0036d1e--- /dev/null+++ b/scripts/contrast-check.py@@ -0,0 +1,63 @@+#!/usr/bin/env python3+"""WCAG 2.x contrast checker, home of the antislop-human contrast checker.++Usage:+ python contrast-check.py "#FFFFFF" "#777777"+ python contrast-check.py FFFFFF 777777++Prints the contrast ratio and a PASS/FAIL verdict for normal text (4.5:1)+and large text (3:1, 18px+ per antislop R-25). Exit code 0 only when both+verdicts pass, so scripts can chain on it.+"""++import re+import sys+++def parse_hex(value):+ value = value.strip().lstrip("#")+ if len(value) == 3:+ value = "".join(ch * 2 for ch in value)+ if not re.fullmatch(r"[0-9A-Fa-f]{6}", value):+ raise ValueError(f"expected a hex color like #FFFFFF, got {value!r}")+ return tuple(int(value[i:i + 2], 16) for i in (0, 2, 4))+++def linearize(channel):+ c = channel / 255.0+ if c <= 0.03928:+ return c / 12.92+ return ((c + 0.055) / 1.055) ** 2.4+++def luminance(rgb):+ r, g, b = (linearize(ch) for ch in rgb)+ return 0.2126 * r + 0.7152 * g + 0.0722 * b+++def contrast_ratio(color_a, color_b):+ lum_a, lum_b = luminance(parse_hex(color_a)), luminance(parse_hex(color_b))+ lighter, darker = sorted((lum_a, lum_b), reverse=True)+ return (lighter + 0.05) / (darker + 0.05)+++def main(argv):+ if len(argv) != 2:+ print("usage: python contrast-check.py <hex1> <hex2>")+ return 2+ try:+ ratio = contrast_ratio(*argv)+ except ValueError as exc:+ print(f"error: {exc}")+ return 2++ normal = ratio >= 4.5+ large = ratio >= 3.0+ print(f"ratio: {ratio:.2f}:1")+ print(f"normal text (4.5:1): {'PASS' if normal else 'FAIL'}")+ print(f"large text (3.0:1): {'PASS' if large else 'FAIL'}")+ return 0 if normal and large else 1+++if __name__ == "__main__":+ sys.exit(main(sys.argv[1:]))