heimdall-agent 1.0.0 → 1.2.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.
Files changed (250) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +443 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +71 -34
  5. package/agents/database-architect.md +31 -25
  6. package/agents/frontend-designer.md +30 -28
  7. package/agents/mobile-designer.md +25 -24
  8. package/agents/modernizer.md +68 -0
  9. package/agents/orchestrator.md +107 -93
  10. package/agents/reviewer.md +102 -71
  11. package/agents/security-auditor.md +27 -27
  12. package/agents/tester.md +97 -90
  13. package/commands/grill-me.md +20 -4
  14. package/commands/orchestrate.md +16 -0
  15. package/commands/orchestrator.md +16 -0
  16. package/commands/plan.md +17 -1
  17. package/config/agents.json +31 -3
  18. package/config/mcp.json +72 -0
  19. package/config/models.json +26 -16
  20. package/config/profiles.json +2 -4
  21. package/config/skills.json +762 -573
  22. package/docs/SKILLS.md +393 -275
  23. package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
  24. package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
  25. package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
  26. package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
  27. package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
  28. package/docs/runs/skill-audit/2026-11-12-compare-report.json +1028 -0
  29. package/docs/runs/skill-audit/2026-11-12-upstream-audit.json +275 -0
  30. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  31. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  32. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  33. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  34. package/docs/runs/skill-audit/customization-report.json +380 -0
  35. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  36. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  37. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  38. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  39. package/docs/runs/skill-audit/inventory.json +308 -0
  40. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  41. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  42. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  43. package/docs/runs/skill-audit/probe.ps1 +16 -0
  44. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  45. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  46. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  47. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  50. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  51. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  52. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  53. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  54. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  55. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  56. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  57. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  58. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  59. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  60. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  61. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  62. package/docs/runs/skill-audit/update-manifest.md +88 -0
  63. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  64. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  65. package/docs/runs/skill-audit/upstream-status.json +563 -0
  66. package/docs/runs/skill-audit/verification-results.json +252 -0
  67. package/doctrine/AGENTS.md +42 -77
  68. package/hooks/git/pre-commit +11 -0
  69. package/hooks/heimdall-hook.cjs +81 -2
  70. package/hooks/herdr-agent-state.ps1 +55 -0
  71. package/hooks/hooks.json +0 -11
  72. package/lib/catalog-sync.cjs +167 -0
  73. package/lib/hermes-context.cjs +57 -0
  74. package/lib/model-context.cjs +123 -0
  75. package/lib/path-discovery.cjs +94 -0
  76. package/package.json +7 -3
  77. package/playbooks/01-interactive-grilling-gate.md +23 -6
  78. package/playbooks/02-fast-code-deep-verification.md +3 -2
  79. package/playbooks/03-adversarial-code-review.md +15 -7
  80. package/playbooks/05-canonical-plan-template.md +35 -19
  81. package/playbooks/06-model-registry-matrix.md +24 -13
  82. package/playbooks/07-legacy-code-modernization.md +74 -0
  83. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  84. package/setup.mjs +592 -172
  85. package/skills/antislop/SKILL.md +76 -56
  86. package/skills/antislop/VERSION +1 -0
  87. package/skills/antislop-copywriting/SKILL.md +407 -372
  88. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  89. package/skills/antislop-human/SKILL.md +204 -147
  90. package/skills/antislop-human/contrast-check.py +168 -165
  91. package/skills/antislop-human/contrast-mcp.py +6 -3
  92. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  93. package/skills/antislop-human/references/WCAG.md +127 -0
  94. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  95. package/skills/antislop-ui/SKILL.md +344 -304
  96. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  97. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  98. package/skills/brainstorming/SKILL.md +296 -265
  99. package/skills/brainstorming/builder-check-prompt.md +23 -0
  100. package/skills/brainstorming/scripts/frame-template.html +213 -213
  101. package/skills/brainstorming/scripts/server.cjs +723 -723
  102. package/skills/brandkit/SKILL.md +798 -798
  103. package/skills/brutalist-skill/SKILL.md +93 -92
  104. package/skills/caveman/README.md +68 -0
  105. package/skills/caveman/SKILL.md +73 -38
  106. package/skills/claude-collaborator/SKILL.md +24 -44
  107. package/skills/clean-code/SKILL.md +152 -0
  108. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  109. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  110. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  111. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  112. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  113. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  114. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  115. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  116. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  117. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  118. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  119. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  120. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  121. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  122. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  123. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  124. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  125. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  126. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  127. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  128. package/skills/codebase-design/DEEPENING.md +37 -0
  129. package/skills/codebase-design/DESIGN-IT-TWICE.md +44 -0
  130. package/skills/codebase-design/SKILL.md +114 -0
  131. package/skills/codex-collaborator/SKILL.md +24 -45
  132. package/skills/communication-doctrine/SKILL.md +89 -0
  133. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  134. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  135. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  136. package/skills/domain-modeling/ADR-FORMAT.md +47 -0
  137. package/skills/domain-modeling/GLOSSARY-FORMAT.md +60 -0
  138. package/skills/domain-modeling/SKILL.md +74 -0
  139. package/skills/executing-plans/SKILL.md +6 -56
  140. package/skills/executing-plans/scripts/task-done +52 -52
  141. package/skills/executing-plans/scripts/task-start +28 -28
  142. package/skills/gemini-collaborator/SKILL.md +24 -56
  143. package/skills/grill-me/SKILL.md +65 -0
  144. package/skills/handoff/SKILL.md +64 -0
  145. package/skills/herdr/SKILL.md +243 -0
  146. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  147. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  148. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  149. package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  150. package/skills/improve-codebase-architecture/SKILL.md +71 -0
  151. package/skills/karpathy-guidelines/SKILL.md +67 -67
  152. package/skills/mcp-engineering/SKILL.md +74 -0
  153. package/skills/minimalist-skill/SKILL.md +87 -85
  154. package/skills/output-skill/SKILL.md +49 -49
  155. package/skills/owasp-security/reference/config-and-supply-chain.md +346 -344
  156. package/skills/owasp-security/reference/languages.md +378 -372
  157. package/skills/owasp-security/reference/owasp-report.md +1144 -1140
  158. package/skills/owasp-security/reference/review-checklist.md +134 -132
  159. package/skills/ponytail/SKILL.md +36 -52
  160. package/skills/postgres-best-practices/SKILL.md +30 -52
  161. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  162. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  163. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  164. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  165. package/skills/postgres-best-practices/references/indexing.md +318 -0
  166. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  167. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  168. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  169. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  170. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  171. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  172. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  173. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  174. package/skills/progressive-disclosure/SKILL.md +68 -0
  175. package/skills/pstack-discipline/SKILL.md +40 -0
  176. package/skills/receiving-code-review/SKILL.md +2 -23
  177. package/skills/requesting-code-review/SKILL.md +7 -36
  178. package/skills/soft-skill/SKILL.md +99 -98
  179. package/skills/stitch-skill/DESIGN.md +121 -121
  180. package/skills/stitch-skill/SKILL.md +185 -184
  181. package/skills/strix-security/SKILL.md +54 -53
  182. package/skills/subagent-driven-development/SKILL.md +35 -264
  183. package/skills/subagent-driven-development/references/batching.md +11 -0
  184. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  185. package/skills/subagent-driven-development/references/final-review.md +47 -0
  186. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  187. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  188. package/skills/subagent-driven-development/references/preflight.md +26 -0
  189. package/skills/subagent-driven-development/references/resuming.md +12 -0
  190. package/skills/subagent-driven-development/scripts/review-package +53 -53
  191. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  192. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  193. package/skills/systematic-debugging/SKILL.md +283 -306
  194. package/skills/taste-skill/SKILL.md +542 -1206
  195. package/skills/taste-skill/references/app-screens.md +1199 -0
  196. package/skills/taste-skill/references/colour.md +141 -0
  197. package/skills/taste-skill/references/copy.md +177 -0
  198. package/skills/taste-skill/references/critique.md +182 -0
  199. package/skills/taste-skill/references/imagery.md +791 -0
  200. package/skills/taste-skill/references/layout.md +292 -0
  201. package/skills/taste-skill/references/motion.md +980 -0
  202. package/skills/taste-skill/references/research.md +356 -0
  203. package/skills/taste-skill/references/scenes.md +174 -0
  204. package/skills/taste-skill/references/tells.md +115 -0
  205. package/skills/taste-skill/references/type.md +170 -0
  206. package/skills/test-driven-development/SKILL.md +330 -337
  207. package/skills/thermo/SKILL.md +67 -0
  208. package/skills/threat-modeling/SKILL.md +55 -0
  209. package/skills/to-spec/SKILL.md +75 -0
  210. package/skills/to-tickets/SKILL.md +105 -0
  211. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  212. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  213. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  214. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  215. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  216. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  217. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  218. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  219. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  220. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  221. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  222. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  223. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  224. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  225. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  226. package/skills/verification-before-completion/SKILL.md +0 -14
  227. package/skills/wayfinder/SKILL.md +128 -0
  228. package/skills/writing-plans/SKILL.md +11 -15
  229. package/skills/writing-skills/SKILL.md +21 -303
  230. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  231. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  232. package/skills/writing-skills/references/bulletproofing.md +80 -0
  233. package/skills/writing-skills/references/discovery.md +201 -0
  234. package/skills/writing-skills/references/flowcharts.md +37 -0
  235. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  236. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  237. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  238. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  239. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  240. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  241. package/skills/gpt-tasteskill/SKILL.md +0 -74
  242. package/skills/taste-skill-v1/SKILL.md +0 -226
  243. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  244. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  245. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  246. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  247. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  248. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  249. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  250. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -1,165 +1,168 @@
1
- #!/usr/bin/env python3
2
- """WCAG 2.x contrast checker, home of the antislop-human contrast checker.
3
-
4
- Usage:
5
- python3 contrast-check.py "#FFFFFF" "#777777"
6
- python3 contrast-check.py FFFFFF 777777
7
- python3 contrast-check.py --selftest
8
-
9
- Prints the contrast ratio and a PASS/FAIL verdict for normal text (4.5:1)
10
- and large text (3:1, 18px+ per antislop R-25). Exit code 0 only when both
11
- verdicts pass, so scripts can chain on it.
12
-
13
- --selftest parses the reference table out of the SKILL.md next to this script
14
- (the skill doc is the source of truth, not a list copied into this script) and
15
- recomputes every row with the formula, checking the ratio and both verdicts.
16
- """
17
-
18
- import os
19
- import re
20
- import sys
21
-
22
- REFERENCE_HEADER = "| Pairing (text on background) | Ratio | Normal text (4.5) | Large text (3.0) |"
23
- NAMED_COLORS = {"black": (0, 0, 0), "white": (255, 255, 255)}
24
-
25
-
26
- def parse_hex(value):
27
- value = value.strip().lstrip("#")
28
- if len(value) == 3:
29
- value = "".join(ch * 2 for ch in value)
30
- if not re.fullmatch(r"[0-9A-Fa-f]{6}", value):
31
- raise ValueError(f"expected a hex color like #FFFFFF, got {value!r}")
32
- return tuple(int(value[i:i + 2], 16) for i in (0, 2, 4))
33
-
34
-
35
- def parse_pairing(pairing):
36
- """Turn 'White on #333333' or '#555555 on black' into two RGB tuples."""
37
- colors = []
38
- for token in re.split(r"\s+on\s+", pairing):
39
- token = token.strip()
40
- match = re.search(r"#[0-9A-Fa-f]{3,6}", token)
41
- if match:
42
- colors.append(parse_hex(match.group(0)))
43
- elif token.lower() in NAMED_COLORS:
44
- colors.append(NAMED_COLORS[token.lower()])
45
- else:
46
- raise ValueError(f"cannot parse {token!r} from pairing {pairing!r}")
47
- if len(colors) != 2:
48
- raise ValueError(f"expected two colors in pairing {pairing!r}")
49
- return tuple(colors)
50
-
51
-
52
- def linearize(channel):
53
- c = channel / 255.0
54
- if c <= 0.03928:
55
- return c / 12.92
56
- return ((c + 0.055) / 1.055) ** 2.4
57
-
58
-
59
- def luminance(rgb):
60
- r, g, b = (linearize(ch) for ch in rgb)
61
- return 0.2126 * r + 0.7152 * g + 0.0722 * b
62
-
63
-
64
- def contrast_ratio(color_a, color_b):
65
- lum_a, lum_b = luminance(color_a), luminance(color_b)
66
- lighter, darker = sorted((lum_a, lum_b), reverse=True)
67
- return (lighter + 0.05) / (darker + 0.05)
68
-
69
-
70
- def reference_doc_path():
71
- here = os.path.dirname(os.path.abspath(__file__))
72
- candidate = os.path.join(here, "SKILL.md")
73
- return candidate if os.path.isfile(candidate) else None
74
-
75
-
76
- def parse_reference_rows(path):
77
- """Reference table rows from SKILL.md, with the ratio already a float.
78
-
79
- A row that does not split into four cells is dropped silently, not raised.
80
- """
81
- rows = []
82
- with open(path, encoding="utf-8") as handle:
83
- in_table = False
84
- for raw in handle:
85
- line = raw.rstrip("\n")
86
- if line.startswith(REFERENCE_HEADER):
87
- in_table = True
88
- continue
89
- if not in_table:
90
- continue
91
- if not line.startswith("|"):
92
- break
93
- if line.startswith("|---"):
94
- continue
95
- cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
96
- if len(cells) != 4:
97
- continue
98
- pairing, ratio, normal, large = cells
99
- rows.append({
100
- "pairing": pairing,
101
- "ratio": float(ratio),
102
- "normal": normal,
103
- "large": large,
104
- })
105
- return rows
106
-
107
-
108
- def selftest():
109
- doc = reference_doc_path()
110
- if doc is None:
111
- print("selftest: SKILL.md not found next to the script; cannot check the table")
112
- return 2
113
- try:
114
- rows = parse_reference_rows(doc)
115
- except (OSError, ValueError) as exc:
116
- print(f"selftest: could not read the table from SKILL.md: {exc}")
117
- return 1
118
- if not rows:
119
- print("selftest: no reference rows found in SKILL.md")
120
- return 1
121
-
122
- failures = 0
123
- for row in rows:
124
- color_a, color_b = parse_pairing(row["pairing"])
125
- computed = round(contrast_ratio(color_a, color_b), 2)
126
- expected_normal = "Pass" if computed >= 4.5 else "Fail"
127
- expected_large = "Pass" if computed >= 3.0 else "Fail"
128
- if f"{computed:.2f}" != f"{row['ratio']:.2f}":
129
- failures += 1
130
- print(f"selftest: {row['pairing']}: table says {row['ratio']}, the formula says {computed:.2f}")
131
- if row["normal"] != expected_normal:
132
- failures += 1
133
- print(f"selftest: {row['pairing']}: normal text marked {row['normal']}, should be {expected_normal}")
134
- if row["large"] != expected_large:
135
- failures += 1
136
- print(f"selftest: {row['pairing']}: large text marked {row['large']}, should be {expected_large}")
137
-
138
- if failures:
139
- return 1
140
- print(f"selftest: {len(rows)} reference pairs OK")
141
- return 0
142
-
143
-
144
- def main(argv):
145
- if len(argv) == 1 and argv[0] == "--selftest":
146
- return selftest()
147
- if len(argv) != 2:
148
- print("usage: python3 contrast-check.py <hex1> <hex2> | --selftest")
149
- return 2
150
- try:
151
- ratio = contrast_ratio(parse_hex(argv[0]), parse_hex(argv[1]))
152
- except ValueError as exc:
153
- print(f"error: {exc}")
154
- return 2
155
-
156
- normal = ratio >= 4.5
157
- large = ratio >= 3.0
158
- print(f"ratio: {ratio:.2f}:1")
159
- print(f"normal text (4.5:1): {'PASS' if normal else 'FAIL'}")
160
- print(f"large text (3.0:1): {'PASS' if large else 'FAIL'}")
161
- return 0 if normal and large else 1
162
-
163
-
164
- if __name__ == "__main__":
165
- sys.exit(main(sys.argv[1:]))
1
+ #!/usr/bin/env python3
2
+ """WCAG 2.x contrast checker, home of the antislop-human contrast checker.
3
+
4
+ Usage:
5
+ python3 contrast-check.py "#FFFFFF" "#777777"
6
+ python3 contrast-check.py FFFFFF 777777
7
+ python3 contrast-check.py --selftest
8
+
9
+ Prints the contrast ratio and a PASS/FAIL verdict for normal text (4.5:1)
10
+ and large text (3:1, 18px+ per antislop R-25). Exit code 0 only when both
11
+ verdicts pass, so scripts can chain on it.
12
+
13
+ --selftest parses the reference table out of the SKILL.md next to this script
14
+ (the skill doc is the source of truth, not a list copied into this script) and
15
+ recomputes every row with the formula, checking the ratio and both verdicts.
16
+ """
17
+
18
+ import os
19
+ import re
20
+ import sys
21
+
22
+ REFERENCE_HEADER = "| Pairing (text on background) | Ratio | Normal text (4.5) | Large text (3.0) |"
23
+ NAMED_COLORS = {"black": (0, 0, 0), "white": (255, 255, 255)}
24
+
25
+
26
+ def parse_hex(value):
27
+ value = value.strip().lstrip("#")
28
+ if len(value) == 3:
29
+ value = "".join(ch * 2 for ch in value)
30
+ if not re.fullmatch(r"[0-9A-Fa-f]{6}", value):
31
+ raise ValueError(f"expected a hex color like #FFFFFF, got {value!r}")
32
+ return tuple(int(value[i:i + 2], 16) for i in (0, 2, 4))
33
+
34
+
35
+ def parse_pairing(pairing):
36
+ """Turn 'White on #333333' or '#555555 on black' into two RGB tuples."""
37
+ colors = []
38
+ for token in re.split(r"\s+on\s+", pairing):
39
+ token = token.strip()
40
+ match = re.search(r"#[0-9A-Fa-f]{3,6}", token)
41
+ if match:
42
+ colors.append(parse_hex(match.group(0)))
43
+ elif token.lower() in NAMED_COLORS:
44
+ colors.append(NAMED_COLORS[token.lower()])
45
+ else:
46
+ raise ValueError(f"cannot parse {token!r} from pairing {pairing!r}")
47
+ if len(colors) != 2:
48
+ raise ValueError(f"expected two colors in pairing {pairing!r}")
49
+ return tuple(colors)
50
+
51
+
52
+ def linearize(channel):
53
+ c = channel / 255.0
54
+ if c <= 0.03928:
55
+ return c / 12.92
56
+ return ((c + 0.055) / 1.055) ** 2.4
57
+
58
+
59
+ def luminance(rgb):
60
+ r, g, b = (linearize(ch) for ch in rgb)
61
+ return 0.2126 * r + 0.7152 * g + 0.0722 * b
62
+
63
+
64
+ def contrast_ratio(color_a, color_b):
65
+ lum_a, lum_b = luminance(color_a), luminance(color_b)
66
+ lighter, darker = sorted((lum_a, lum_b), reverse=True)
67
+ return (lighter + 0.05) / (darker + 0.05)
68
+
69
+
70
+ def reference_doc_path():
71
+ here = os.path.dirname(os.path.abspath(__file__))
72
+ candidate = os.path.join(here, "SKILL.md")
73
+ return candidate if os.path.isfile(candidate) else None
74
+
75
+
76
+ def parse_reference_rows(path):
77
+ """Reference table rows from SKILL.md, with the ratio already a float.
78
+
79
+ A row that does not split into four cells is dropped silently, not raised.
80
+ """
81
+ rows = []
82
+ with open(path, encoding="utf-8") as handle:
83
+ in_table = False
84
+ for raw in handle:
85
+ line = raw.rstrip("\n")
86
+ if line.startswith(REFERENCE_HEADER):
87
+ in_table = True
88
+ continue
89
+ if not in_table:
90
+ continue
91
+ if not line.startswith("|"):
92
+ break
93
+ if line.startswith("|---"):
94
+ continue
95
+ cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
96
+ if len(cells) != 4:
97
+ continue
98
+ pairing, ratio, normal, large = cells
99
+ rows.append({
100
+ "pairing": pairing,
101
+ "ratio": float(ratio),
102
+ "normal": normal,
103
+ "large": large,
104
+ })
105
+ return rows
106
+
107
+
108
+ def selftest():
109
+ doc = reference_doc_path()
110
+ if doc is None:
111
+ print("selftest: SKILL.md not found next to the script; cannot check the table")
112
+ return 2
113
+ try:
114
+ rows = parse_reference_rows(doc)
115
+ except (OSError, ValueError) as exc:
116
+ print(f"selftest: could not read the table from SKILL.md: {exc}")
117
+ return 1
118
+ if not rows:
119
+ print("selftest: no reference rows found in SKILL.md")
120
+ return 1
121
+
122
+ failures = 0
123
+ for row in rows:
124
+ color_a, color_b = parse_pairing(row["pairing"])
125
+ # The verdicts read the unrounded ratio, exactly as main() does. Rounding first
126
+ # turns a 4.498:1 pairing into a displayed 4.50 that would pass 4.5:1 on paper.
127
+ raw = contrast_ratio(color_a, color_b)
128
+ computed = round(raw, 2)
129
+ expected_normal = "Pass" if raw >= 4.5 else "Fail"
130
+ expected_large = "Pass" if raw >= 3.0 else "Fail"
131
+ if f"{computed:.2f}" != f"{row['ratio']:.2f}":
132
+ failures += 1
133
+ print(f"selftest: {row['pairing']}: table says {row['ratio']}, the formula says {computed:.2f}")
134
+ if row["normal"] != expected_normal:
135
+ failures += 1
136
+ print(f"selftest: {row['pairing']}: normal text marked {row['normal']}, should be {expected_normal}")
137
+ if row["large"] != expected_large:
138
+ failures += 1
139
+ print(f"selftest: {row['pairing']}: large text marked {row['large']}, should be {expected_large}")
140
+
141
+ if failures:
142
+ return 1
143
+ print(f"selftest: {len(rows)} reference pairs OK")
144
+ return 0
145
+
146
+
147
+ def main(argv):
148
+ if len(argv) == 1 and argv[0] == "--selftest":
149
+ return selftest()
150
+ if len(argv) != 2:
151
+ print("usage: python3 contrast-check.py <hex1> <hex2> | --selftest")
152
+ return 2
153
+ try:
154
+ ratio = contrast_ratio(parse_hex(argv[0]), parse_hex(argv[1]))
155
+ except ValueError as exc:
156
+ print(f"error: {exc}")
157
+ return 2
158
+
159
+ normal = ratio >= 4.5
160
+ large = ratio >= 3.0
161
+ print(f"ratio: {ratio:.2f}:1")
162
+ print(f"normal text (4.5:1): {'PASS' if normal else 'FAIL'}")
163
+ print(f"large text (3.0:1): {'PASS' if large else 'FAIL'}")
164
+ return 0 if normal and large else 1
165
+
166
+
167
+ if __name__ == "__main__":
168
+ sys.exit(main(sys.argv[1:]))
@@ -8,7 +8,7 @@ import sys
8
8
 
9
9
  PROTOCOL_VERSION = "2024-11-05"
10
10
  SERVER_NAME = "antislop-contrast"
11
- SERVER_VERSION = "3.2.7"
11
+ SERVER_VERSION = "3.2.25"
12
12
 
13
13
  TOOLS = [
14
14
  {
@@ -40,17 +40,20 @@ def relative_luminance(hex_color):
40
40
 
41
41
 
42
42
  def contrast_ratio(fg, bg):
43
+ """The unrounded WCAG ratio. Callers decide what to print, never what to compare."""
43
44
  l1, l2 = relative_luminance(fg), relative_luminance(bg)
44
45
  lighter, darker = max(l1, l2), min(l1, l2)
45
- return round((lighter + 0.05) / (darker + 0.05), 2)
46
+ return (lighter + 0.05) / (darker + 0.05)
46
47
 
47
48
 
48
49
  def check_contrast(fg, bg):
50
+ # The threshold is read from the raw ratio: 4.498:1 fails 4.5:1 even though it
51
+ # displays as 4.50 once rounded, and a rounded verdict would report the opposite.
49
52
  ratio = contrast_ratio(fg, bg)
50
53
  return {
51
54
  "foreground": fg,
52
55
  "background": bg,
53
- "ratio": ratio,
56
+ "ratio": round(ratio, 2),
54
57
  "normal_text": {"threshold": 4.5, "pass": ratio >= 4.5},
55
58
  "large_text": {"threshold": 3.0, "pass": ratio >= 3.0},
56
59
  }
@@ -0,0 +1,249 @@
1
+ # Accessibility Code Patterns
2
+
3
+ > 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.
4
+
5
+ Practical, copy-paste-ready patterns for common accessibility requirements. Each pattern is self-contained and linked from the main [SKILL.md](../SKILL.md).
6
+
7
+ ---
8
+
9
+ ## Pointer cursor base layer
10
+
11
+ 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.
12
+
13
+ ```css
14
+ a[href], button, summary, select, label[for],
15
+ label:has(> input[type="checkbox"], > input[type="radio"]),
16
+ [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], [role="switch"],
17
+ input[type="checkbox"], input[type="radio"], input[type="file"],
18
+ input[type="submit"], input[type="button"], input[type="reset"], input[type="range"], input[type="color"] {
19
+ cursor: pointer;
20
+ }
21
+ :disabled, [aria-disabled="true"] { cursor: not-allowed; }
22
+ ```
23
+
24
+ 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.
25
+
26
+ ## Modal focus trap
27
+
28
+ Trap keyboard focus inside a modal dialog so Tab/Shift+Tab cycle through its focusable elements and Escape closes it.
29
+
30
+ ```javascript
31
+ function trapFocus(modal, onClose) {
32
+ const focusable = modal.querySelectorAll(
33
+ 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
34
+ );
35
+ if (focusable.length === 0) return () => {};
36
+
37
+ const first = focusable[0];
38
+ const last = focusable[focusable.length - 1];
39
+
40
+ function onKeydown(e) {
41
+ if (e.key === 'Escape') return onClose();
42
+ if (e.key !== 'Tab') return;
43
+ if (e.shiftKey && document.activeElement === first) {
44
+ e.preventDefault();
45
+ last.focus();
46
+ } else if (!e.shiftKey && document.activeElement === last) {
47
+ e.preventDefault();
48
+ first.focus();
49
+ }
50
+ }
51
+
52
+ modal.addEventListener('keydown', onKeydown);
53
+ first.focus();
54
+ return () => modal.removeEventListener('keydown', onKeydown);
55
+ }
56
+ ```
57
+
58
+ Call the returned function when the dialog closes, or a second open stacks a second listener:
59
+
60
+ ```javascript
61
+ const release = trapFocus(dialog, () => dialog.close());
62
+ dialog.addEventListener('close', release, { once: true });
63
+ ```
64
+
65
+ The native `<dialog>` element handles focus trapping automatically, prefer it when browser support allows.
66
+
67
+ ---
68
+
69
+ ## Skip link
70
+
71
+ Allows keyboard users to bypass repetitive navigation and jump straight to main content.
72
+
73
+ ```html
74
+ <body>
75
+ <a href="#main-content" class="skip-link">Skip to main content</a>
76
+ <header><!-- navigation --></header>
77
+ <main id="main-content" tabindex="-1">
78
+ <!-- main content -->
79
+ </main>
80
+ </body>
81
+ ```
82
+
83
+ ```css
84
+ .skip-link {
85
+ position: absolute;
86
+ top: -40px;
87
+ left: 0;
88
+ background: #000;
89
+ color: #fff;
90
+ padding: 8px 16px;
91
+ z-index: 100;
92
+ }
93
+
94
+ .skip-link:focus {
95
+ top: 0;
96
+ }
97
+ ```
98
+
99
+ ---
100
+
101
+ ## Error handling
102
+
103
+ Announce errors to screen readers and focus the first invalid field on submit.
104
+
105
+ ```html
106
+ <form novalidate>
107
+ <div id="error-summary" tabindex="-1" hidden></div>
108
+ <div class="field" aria-live="polite">
109
+ <label for="email">Email</label>
110
+ <input type="email" id="email"
111
+ aria-invalid="true"
112
+ aria-describedby="email-error">
113
+ <p id="email-error" class="error" role="alert">
114
+ Please enter a valid email address (e.g., name@example.com)
115
+ </p>
116
+ </div>
117
+ </form>
118
+ ```
119
+
120
+ ```javascript
121
+ const form = document.querySelector('form');
122
+ const summary = document.getElementById('error-summary');
123
+
124
+ form.addEventListener('submit', (e) => {
125
+ const invalid = [...form.querySelectorAll('[aria-invalid="true"]')];
126
+ if (invalid.length === 0) return;
127
+
128
+ e.preventDefault();
129
+ summary.textContent =
130
+ `${invalid.length} errors found. Please fix them and try again.`;
131
+ summary.hidden = false;
132
+ invalid[0].focus();
133
+ });
134
+ ```
135
+
136
+ This handler reports what the validation already marked: set `aria-invalid="true"` and the field's error text before submit runs.
137
+
138
+ ---
139
+
140
+ ## Form labels
141
+
142
+ Every input needs an associated label, either explicit (`for`/`id`) or implicit (wrapping `<label>`).
143
+
144
+ ```html
145
+ <!-- ❌ No label association -->
146
+ <input type="email" placeholder="Email">
147
+
148
+ <!-- ✅ Explicit label -->
149
+ <label for="email">Email address</label>
150
+ <input type="email" id="email" name="email"
151
+ autocomplete="email" required>
152
+
153
+ <!-- ✅ Implicit label -->
154
+ <label>
155
+ Email address
156
+ <input type="email" name="email" autocomplete="email" required>
157
+ </label>
158
+
159
+ <!-- ✅ With instructions -->
160
+ <label for="password">Password</label>
161
+ <input type="password" id="password"
162
+ aria-describedby="password-requirements">
163
+ <p id="password-requirements">
164
+ Must be at least 8 characters with one number.
165
+ </p>
166
+ ```
167
+
168
+ ---
169
+
170
+ ## Dragging movements
171
+
172
+ Any action triggered by dragging must offer a single-pointer alternative (WCAG 2.5.7).
173
+
174
+ ```html
175
+ <!-- ❌ Drag-only reorder -->
176
+ <ul class="sortable-list" draggable="true">
177
+ <li>Item 1</li>
178
+ <li>Item 2</li>
179
+ </ul>
180
+
181
+ <!-- ✅ Drag + button alternatives -->
182
+ <ul class="sortable-list">
183
+ <li>
184
+ <span>Item 1</span>
185
+ <button aria-label="Move Item 1 up">↑</button>
186
+ <button aria-label="Move Item 1 down">↓</button>
187
+ </li>
188
+ <li>
189
+ <span>Item 2</span>
190
+ <button aria-label="Move Item 2 up">↑</button>
191
+ <button aria-label="Move Item 2 down">↓</button>
192
+ </li>
193
+ </ul>
194
+ ```
195
+
196
+ Also applies to sliders, map panning, colour pickers, and similar drag-based widgets, always provide an equivalent click/tap or keyboard path.
197
+
198
+ ---
199
+
200
+ ## ARIA tabs
201
+
202
+ Tabs require `role="tablist"`, `role="tab"`, and `role="tabpanel"` with proper `aria-selected`, `aria-controls`, and keyboard support.
203
+
204
+ ```html
205
+ <div role="tablist" aria-label="Product information">
206
+ <button role="tab" id="tab-1" aria-selected="true"
207
+ aria-controls="panel-1">Description</button>
208
+ <button role="tab" id="tab-2" aria-selected="false"
209
+ aria-controls="panel-2" tabindex="-1">Reviews</button>
210
+ </div>
211
+ <div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
212
+ <!-- Panel content -->
213
+ </div>
214
+ <div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
215
+ <!-- Panel content -->
216
+ </div>
217
+ ```
218
+
219
+ Arrow keys should move focus between tabs; the active tab receives `tabindex="0"` while inactive tabs use `tabindex="-1"`.
220
+
221
+ ---
222
+
223
+ ## Live regions and notifications
224
+
225
+ Use `aria-live` to announce dynamic content changes to screen readers without moving focus.
226
+
227
+ ```html
228
+ <!-- Status updates (polite, waits for pause in speech) -->
229
+ <div id="polite-announcer" aria-live="polite" aria-atomic="true" class="status">
230
+ <!-- Content updates announced to screen readers -->
231
+ </div>
232
+
233
+ <!-- Urgent alerts (assertive, interrupts) -->
234
+ <div id="assertive-announcer" role="alert" aria-live="assertive">
235
+ <!-- Interrupts current announcement -->
236
+ </div>
237
+ ```
238
+
239
+ ```javascript
240
+ function showNotification(message, type = 'polite') {
241
+ const container = document.getElementById(`${type}-announcer`);
242
+ container.textContent = '';
243
+ requestAnimationFrame(() => {
244
+ container.textContent = message;
245
+ });
246
+ }
247
+ ```
248
+
249
+ Clear the container before writing to ensure the same message triggers a new announcement.