chill-agent 1.1.0 → 1.3.0

package/skills/chill-slop-human/SKILL.md

@@ -1,24 +1,73 @@
 ---
 name: chill-slop-human
-description: "Ergonomics, Human Factors & Accessibility Standard. Guarantees WCAG AA 4.5:1 contrast, visible focus rings, 44px touch targets, and zero-barrier keyboard navigation."
+description: "Comprehensive Ergonomics, Human Factors & Accessibility Standard. Enforces WCAG AA 4.5:1 contrast, visible focus rings, 44px touch targets, Escape-key dialogs, and accessible screen-reader semantics."
 license: MIT
 ---
 
-# ChillSlop Human: Ergonomics & Accessibility
+# ChillSlop Human: Comprehensive Ergonomics & Accessibility Standard
 
-> *"Accessibility is not a feature; it is the baseline of professional craftsmanship."*
+> *"Accessibility is not an optional polish phase. An interface that cannot be used by everyone is simply an unfinished interface."*
 
-## 1. Contrast & Legibility
-- **WCAG AA Minimum Contrast:** Text and interactive elements must maintain at least `4.5:1` contrast ratio against their immediate background (`3:1` for bold text >= 18pt).
-- **No Low-Contrast Gray-on-Gray Slop:** Never use `#71717A` text on `#18181B` backgrounds for critical body copy. Reserve muted gray exclusively for secondary metadata labels.
+---
+
+## 1. Contrast Ratios & Visual Legibility
+
+### WCAG AA Minimum Thresholds
+- **Normal Body Text (< 18pt regular):** Minimum contrast ratio of **4.5:1** against its immediate background.
+- **Large Text (>= 18pt regular or >= 14pt bold):** Minimum contrast ratio of **3:1**.
+- **Interactive UI Components & Hairlines:** Minimum contrast ratio of **3:1** against adjacent surfaces.
+
+### Banned Contrast Sins
+- **No Low-Contrast Gray-on-Gray Slop:** Never place `#71717A` body text on a `#18181B` card surface. Secondary metadata may use muted text only if text size is at least 11px and contrast is verified >= 4.5:1.
+- **No White Text Over Light Gradients:** If using a gradient, text passing over it must maintain 4.5:1 contrast across the *entire* gradient spectrum, not just the dark endpoint.
+
+---
+
+## 2. Keyboard Navigation & Focus Management
+
+### Visible Focus Indicators
+- Every interactive element (`<button>`, `<a>`, `<input>`, `<select>`, `<textarea>`) must display a visible, unclipped focus indicator upon keyboard Tab navigation:
+  ```css
+  :focus-visible {
+    outline: 2px solid #818CF8;
+    outline-offset: 2px;
+  }
+  ```
+- **FORBIDDEN:** Setting `outline: none` or `outline: 0` without immediately supplying a custom focus indicator.
+
+### Modals, Drawers & Focus Trapping
+- **Escape Key Interception:** Any open modal, drawer, dropdown, or overlay dialog MUST close immediately upon pressing the `Escape` key.
+- **Focus Restoration:** Upon closing an overlay, focus must return directly to the trigger button that launched it.
+- **Focus Trap:** When a modal is open, keyboard `Tab` cycles only through interactive elements inside the modal; background page content must be inert (`aria-hidden="true"` or `inert`).
+
+---
+
+## 3. Touch Targets & Tactile Ergonomics
+
+- **Minimum Dimensions:** All buttons, toggle switches, links, and icon triggers on touch screens must measure at least **44x44px** (or provide 44px of hit area via padding).
+- **Spacing Between Targets:** Adjacent touch controls must have at least `8px` of separation to prevent accidental mis-taps.
+
+---
+
+## 4. Semantics & Screen Reader Affordances
+
+### Native HTML First
+- Use `<button>` for actions. Use `<a href="...">` for navigation to real URLs.
+- **FORBIDDEN:** `<div onClick={...}>` or `<span onClick={...}>` without `role="button"`, `tabIndex={0}`, and `onKeyDown` handlers.
 
-## 2. Keyboard & Focus Management
-- **Visible Focus Rings:** Every button, input, anchor, and clickable div must render a clear, unclipped focus indicator:
-  `outline: 2px solid var(--focus-ring); outline-offset: 2px;`
-  Never set `outline: none` without a high-visibility replacement.
-- **Escape Key Interception:** All modals, drawers, and overlay dialogs must close immediately on `Escape` keypress and restore focus to the triggering element.
-- **Logical Tab Order:** Ensure the DOM tab order matches visual layout. Never jump focus unexpectedly across the viewport.
+### Icon Buttons & Accessible Labels
+- Every button containing only an SVG or icon glyph **MUST** have an accessible text label:
+  ```html
+  <button aria-label="Close dialog">
+    <svg aria-hidden="true">...</svg>
+  </button>
+  ```
+- All decorative images must declare empty `alt=""`. All content images must have concise, descriptive `alt` text.
 
-## 3. Touch Targets & Affordances
-- Interactive touch targets on mobile and touch-enabled devices must measure at least `44x44px` (or `48x48px` for primary controls).
-- Every icon button lacking visible text must include an unambiguous `aria-label` attribute (e.g. `<button aria-label="Close dialog">`).
+### Form Fields
+- Every `<input>`, `<textarea>`, and `<select>` must have a visible `<label>` bound via `id` and `for`:
+  ```html
+  <label for="session-id">Session ID</label>
+  <input id="session-id" type="text" />
+  ```
+- Never rely solely on `placeholder="..."` as the field label. Placeholders disappear when typed and fail contrast checks.

package/skills/chill-slop-human/contrast-check.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""WCAG 2.x contrast checker, home of the antislop-human contrast checker.
+
+Usage:
+    python3 contrast-check.py "#FFFFFF" "#777777"
+    python3 contrast-check.py FFFFFF 777777
+    python3 contrast-check.py --selftest
+
+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.
+
+--selftest parses the reference table out of the SKILL.md next to this script
+(the skill doc is the source of truth, not a list copied into this script) and
+recomputes every row with the formula, checking the ratio and both verdicts.
+"""
+
+import os
+import re
+import sys
+
+REFERENCE_HEADER = "| Pairing (text on background) | Ratio | Normal text (4.5) | Large text (3.0) |"
+NAMED_COLORS = {"black": (0, 0, 0), "white": (255, 255, 255)}
+
+
+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 parse_pairing(pairing):
+    """Turn 'White on #333333' or '#555555 on black' into two RGB tuples."""
+    colors = []
+    for token in re.split(r"\s+on\s+", pairing):
+        token = token.strip()
+        match = re.search(r"#[0-9A-Fa-f]{3,6}", token)
+        if match:
+            colors.append(parse_hex(match.group(0)))
+        elif token.lower() in NAMED_COLORS:
+            colors.append(NAMED_COLORS[token.lower()])
+        else:
+            raise ValueError(f"cannot parse {token!r} from pairing {pairing!r}")
+    if len(colors) != 2:
+        raise ValueError(f"expected two colors in pairing {pairing!r}")
+    return tuple(colors)
+
+
+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(color_a), luminance(color_b)
+    lighter, darker = sorted((lum_a, lum_b), reverse=True)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def reference_doc_path():
+    here = os.path.dirname(os.path.abspath(__file__))
+    candidate = os.path.join(here, "SKILL.md")
+    return candidate if os.path.isfile(candidate) else None
+
+
+def parse_reference_rows(path):
+    """Reference table rows from SKILL.md, with the ratio already a float.
+
+    A row that does not split into four cells is dropped silently, not raised.
+    """
+    rows = []
+    with open(path, encoding="utf-8") as handle:
+        in_table = False
+        for raw in handle:
+            line = raw.rstrip("\n")
+            if line.startswith(REFERENCE_HEADER):
+                in_table = True
+                continue
+            if not in_table:
+                continue
+            if not line.startswith("|"):
+                break
+            if line.startswith("|---"):
+                continue
+            cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
+            if len(cells) != 4:
+                continue
+            pairing, ratio, normal, large = cells
+            rows.append({
+                "pairing": pairing,
+                "ratio": float(ratio),
+                "normal": normal,
+                "large": large,
+            })
+    return rows
+
+
+def selftest():
+    doc = reference_doc_path()
+    if doc is None:
+        print("selftest: SKILL.md not found next to the script; cannot check the table")
+        return 2
+    try:
+        rows = parse_reference_rows(doc)
+    except (OSError, ValueError) as exc:
+        print(f"selftest: could not read the table from SKILL.md: {exc}")
+        return 1
+    if not rows:
+        print("selftest: no reference rows found in SKILL.md")
+        return 1
+
+    failures = 0
+    for row in rows:
+        color_a, color_b = parse_pairing(row["pairing"])
+        # The verdicts read the unrounded ratio, exactly as main() does. Rounding first
+        # turns a 4.498:1 pairing into a displayed 4.50 that would pass 4.5:1 on paper.
+        raw = contrast_ratio(color_a, color_b)
+        computed = round(raw, 2)
+        expected_normal = "Pass" if raw >= 4.5 else "Fail"
+        expected_large = "Pass" if raw >= 3.0 else "Fail"
+        if f"{computed:.2f}" != f"{row['ratio']:.2f}":
+            failures += 1
+            print(f"selftest: {row['pairing']}: table says {row['ratio']}, the formula says {computed:.2f}")
+        if row["normal"] != expected_normal:
+            failures += 1
+            print(f"selftest: {row['pairing']}: normal text marked {row['normal']}, should be {expected_normal}")
+        if row["large"] != expected_large:
+            failures += 1
+            print(f"selftest: {row['pairing']}: large text marked {row['large']}, should be {expected_large}")
+
+    if failures:
+        return 1
+    print(f"selftest: {len(rows)} reference pairs OK")
+    return 0
+
+
+def main(argv):
+    if len(argv) == 1 and argv[0] == "--selftest":
+        return selftest()
+    if len(argv) != 2:
+        print("usage: python3 contrast-check.py <hex1> <hex2> | --selftest")
+        return 2
+    try:
+        ratio = contrast_ratio(parse_hex(argv[0]), parse_hex(argv[1]))
+    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:]))

package/skills/chill-slop-human/contrast-mcp.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Minimal MCP stdio server exposing the antislop contrast checker as a tool.
+
+All logging goes to stderr; stdout is reserved for JSON-RPC responses.
+"""
+import json
+import sys
+
+PROTOCOL_VERSION = "2024-11-05"
+SERVER_NAME = "antislop-contrast"
+SERVER_VERSION = "3.2.26"
+
+TOOLS = [
+    {
+        "name": "check_contrast",
+        "description": "Compute the WCAG contrast ratio between two hex colors and the pass or fail verdict for normal and large text. Use this instead of guessing whether a color pairing meets AA.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "foreground": {"type": "string", "description": "Hex color of the text, for example #777777"},
+                "background": {"type": "string", "description": "Hex color of the background, for example #FFFFFF"},
+            },
+            "required": ["foreground", "background"],
+        },
+    }
+]
+
+
+def _channel(c):
+    c = c / 255.0
+    return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+
+def relative_luminance(hex_color):
+    h = hex_color.strip().lstrip("#")
+    if len(h) == 3:
+        h = "".join(ch * 2 for ch in h)
+    r, g, b = (int(h[i : i + 2], 16) for i in (0, 2, 4))
+    return 0.2126 * _channel(r) + 0.7152 * _channel(g) + 0.0722 * _channel(b)
+
+
+def contrast_ratio(fg, bg):
+    """The unrounded WCAG ratio. Callers decide what to print, never what to compare."""
+    l1, l2 = relative_luminance(fg), relative_luminance(bg)
+    lighter, darker = max(l1, l2), min(l1, l2)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def check_contrast(fg, bg):
+    # The threshold is read from the raw ratio: 4.498:1 fails 4.5:1 even though it
+    # displays as 4.50 once rounded, and a rounded verdict would report the opposite.
+    ratio = contrast_ratio(fg, bg)
+    return {
+        "foreground": fg,
+        "background": bg,
+        "ratio": round(ratio, 2),
+        "normal_text": {"threshold": 4.5, "pass": ratio >= 4.5},
+        "large_text": {"threshold": 3.0, "pass": ratio >= 3.0},
+    }
+
+
+def _send(msg):
+    sys.stdout.write(json.dumps(msg) + "\n")
+    sys.stdout.flush()
+
+
+def _text(content):
+    return {"content": [{"type": "text", "text": content}], "isError": False}
+
+
+def _error(message):
+    return {"content": [{"type": "text", "text": message}], "isError": True}
+
+
+def _reply(msg_id, result):
+    _send({"jsonrpc": "2.0", "id": msg_id, "result": result})
+
+
+def main():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        msg_id = msg.get("id")
+        method = msg.get("method")
+
+        if method == "initialize":
+            _reply(msg_id, {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION},
+            })
+        elif method == "notifications/initialized":
+            pass
+        elif method == "ping":
+            _reply(msg_id, {})
+        elif method == "tools/list":
+            _reply(msg_id, {"tools": TOOLS})
+        elif method == "tools/call":
+            params = msg.get("params") or {}
+            name = params.get("name")
+            args = params.get("arguments") or {}
+            if name == "check_contrast":
+                try:
+                    result = check_contrast(args["foreground"], args["background"])
+                    _reply(msg_id, _text(json.dumps(result)))
+                except Exception as exc:
+                    _reply(msg_id, _error("check_contrast failed: " + str(exc)))
+            else:
+                _reply(msg_id, _error("Unknown tool: " + str(name)))
+        elif msg_id is not None:
+            _reply(msg_id, {})
+
+
+if __name__ == "__main__":
+    main()

package/skills/chill-slop-human/references/A11Y-PATTERNS.md

@@ -0,0 +1,249 @@
+# Accessibility Code Patterns
+
+> Reference for antislop. Adapted from the MIT-licensed web-quality-skills by Addy Osmani (https://github.com/addyosmani/web-quality-skills); see LICENSE-web-quality-skills in the skill folder.
+
+Practical, copy-paste-ready patterns for common accessibility requirements. Each pattern is self-contained and linked from the main [SKILL.md](../SKILL.md).
+
+---
+
+## Pointer cursor base layer
+
+Set once, in the base CSS layer, so no component has to remember it (R-39). A CSS reset such as Tailwind preflight sets `button` to `cursor: default`, so this layer comes after the reset.
+
+```css
+a[href], button, summary, select, label[for],
+label:has(> input[type="checkbox"], > input[type="radio"]),
+[role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], [role="switch"],
+input[type="checkbox"], input[type="radio"], input[type="file"],
+input[type="submit"], input[type="button"], input[type="reset"], input[type="range"], input[type="color"] {
+  cursor: pointer;
+}
+:disabled, [aria-disabled="true"] { cursor: not-allowed; }
+```
+
+Text inputs keep `cursor: text`, and drag handles use `grab` / `grabbing`. An implicit label that wraps a checkbox or radio is included, since clicking it toggles the control.
+
+## Modal focus trap
+
+Trap keyboard focus inside a modal dialog so Tab/Shift+Tab cycle through its focusable elements and Escape closes it.
+
+```javascript
+function trapFocus(modal, onClose) {
+  const focusable = modal.querySelectorAll(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+  );
+  if (focusable.length === 0) return () => {};
+
+  const first = focusable[0];
+  const last = focusable[focusable.length - 1];
+
+  function onKeydown(e) {
+    if (e.key === 'Escape') return onClose();
+    if (e.key !== 'Tab') return;
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  }
+
+  modal.addEventListener('keydown', onKeydown);
+  first.focus();
+  return () => modal.removeEventListener('keydown', onKeydown);
+}
+```
+
+Call the returned function when the dialog closes, or a second open stacks a second listener:
+
+```javascript
+const release = trapFocus(dialog, () => dialog.close());
+dialog.addEventListener('close', release, { once: true });
+```
+
+The native `<dialog>` element handles focus trapping automatically, prefer it when browser support allows.
+
+---
+
+## Skip link
+
+Allows keyboard users to bypass repetitive navigation and jump straight to main content.
+
+```html
+<body>
+  <a href="#main-content" class="skip-link">Skip to main content</a>
+  <header><!-- navigation --></header>
+  <main id="main-content" tabindex="-1">
+    <!-- main content -->
+  </main>
+</body>
+```
+
+```css
+.skip-link {
+  position: absolute;
+  top: -40px;
+  left: 0;
+  background: #000;
+  color: #fff;
+  padding: 8px 16px;
+  z-index: 100;
+}
+
+.skip-link:focus {
+  top: 0;
+}
+```
+
+---
+
+## Error handling
+
+Announce errors to screen readers and focus the first invalid field on submit.
+
+```html
+<form novalidate>
+  <div id="error-summary" tabindex="-1" hidden></div>
+  <div class="field" aria-live="polite">
+    <label for="email">Email</label>
+    <input type="email" id="email"
+           aria-invalid="true"
+           aria-describedby="email-error">
+    <p id="email-error" class="error" role="alert">
+      Please enter a valid email address (e.g., name@example.com)
+    </p>
+  </div>
+</form>
+```
+
+```javascript
+const form = document.querySelector('form');
+const summary = document.getElementById('error-summary');
+
+form.addEventListener('submit', (e) => {
+  const invalid = [...form.querySelectorAll('[aria-invalid="true"]')];
+  if (invalid.length === 0) return;
+
+  e.preventDefault();
+  summary.textContent =
+    `${invalid.length} errors found. Please fix them and try again.`;
+  summary.hidden = false;
+  invalid[0].focus();
+});
+```
+
+This handler reports what the validation already marked: set `aria-invalid="true"` and the field's error text before submit runs.
+
+---
+
+## Form labels
+
+Every input needs an associated label, either explicit (`for`/`id`) or implicit (wrapping `<label>`).
+
+```html
+<!-- ❌ No label association -->
+<input type="email" placeholder="Email">
+
+<!-- ✅ Explicit label -->
+<label for="email">Email address</label>
+<input type="email" id="email" name="email"
+       autocomplete="email" required>
+
+<!-- ✅ Implicit label -->
+<label>
+  Email address
+  <input type="email" name="email" autocomplete="email" required>
+</label>
+
+<!-- ✅ With instructions -->
+<label for="password">Password</label>
+<input type="password" id="password"
+       aria-describedby="password-requirements">
+<p id="password-requirements">
+  Must be at least 8 characters with one number.
+</p>
+```
+
+---
+
+## Dragging movements
+
+Any action triggered by dragging must offer a single-pointer alternative (WCAG 2.5.7).
+
+```html
+<!-- ❌ Drag-only reorder -->
+<ul class="sortable-list" draggable="true">
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+
+<!-- ✅ Drag + button alternatives -->
+<ul class="sortable-list">
+  <li>
+    <span>Item 1</span>
+    <button aria-label="Move Item 1 up">↑</button>
+    <button aria-label="Move Item 1 down">↓</button>
+  </li>
+  <li>
+    <span>Item 2</span>
+    <button aria-label="Move Item 2 up">↑</button>
+    <button aria-label="Move Item 2 down">↓</button>
+  </li>
+</ul>
+```
+
+Also applies to sliders, map panning, colour pickers, and similar drag-based widgets, always provide an equivalent click/tap or keyboard path.
+
+---
+
+## ARIA tabs
+
+Tabs require `role="tablist"`, `role="tab"`, and `role="tabpanel"` with proper `aria-selected`, `aria-controls`, and keyboard support.
+
+```html
+<div role="tablist" aria-label="Product information">
+  <button role="tab" id="tab-1" aria-selected="true"
+          aria-controls="panel-1">Description</button>
+  <button role="tab" id="tab-2" aria-selected="false"
+          aria-controls="panel-2" tabindex="-1">Reviews</button>
+</div>
+<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
+  <!-- Panel content -->
+</div>
+<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
+  <!-- Panel content -->
+</div>
+```
+
+Arrow keys should move focus between tabs; the active tab receives `tabindex="0"` while inactive tabs use `tabindex="-1"`.
+
+---
+
+## Live regions and notifications
+
+Use `aria-live` to announce dynamic content changes to screen readers without moving focus.
+
+```html
+<!-- Status updates (polite, waits for pause in speech) -->
+<div id="polite-announcer" aria-live="polite" aria-atomic="true" class="status">
+  <!-- Content updates announced to screen readers -->
+</div>
+
+<!-- Urgent alerts (assertive, interrupts) -->
+<div id="assertive-announcer" role="alert" aria-live="assertive">
+  <!-- Interrupts current announcement -->
+</div>
+```
+
+```javascript
+function showNotification(message, type = 'polite') {
+  const container = document.getElementById(`${type}-announcer`);
+  container.textContent = '';
+  requestAnimationFrame(() => {
+    container.textContent = message;
+  });
+}
+```
+
+Clear the container before writing to ensure the same message triggers a new announcement.