heimdall-agent 1.0.0 → 1.1.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 (231) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +429 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +66 -35
  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 +66 -0
  9. package/agents/orchestrator.md +94 -93
  10. package/agents/reviewer.md +100 -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 +21 -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 +210 -100
  22. package/docs/SKILLS.md +341 -245
  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/add_progressive_disclosure.cjs +30 -0
  29. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  30. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  31. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  32. package/docs/runs/skill-audit/customization-report.json +380 -0
  33. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  34. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  35. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  36. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  37. package/docs/runs/skill-audit/inventory.json +308 -0
  38. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  39. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  40. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  41. package/docs/runs/skill-audit/probe.ps1 +16 -0
  42. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  43. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  44. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  45. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  46. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  47. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  50. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  51. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  52. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  53. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  54. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  55. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  56. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  57. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  58. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  59. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  60. package/docs/runs/skill-audit/update-manifest.md +88 -0
  61. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  62. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  63. package/docs/runs/skill-audit/upstream-status.json +563 -0
  64. package/docs/runs/skill-audit/verification-results.json +252 -0
  65. package/doctrine/AGENTS.md +39 -77
  66. package/hooks/git/pre-commit +11 -0
  67. package/hooks/heimdall-hook.cjs +81 -2
  68. package/hooks/herdr-agent-state.ps1 +55 -0
  69. package/hooks/hooks.json +0 -11
  70. package/lib/catalog-sync.cjs +162 -0
  71. package/lib/hermes-context.cjs +57 -0
  72. package/lib/model-context.cjs +123 -0
  73. package/lib/path-discovery.cjs +94 -0
  74. package/package.json +7 -3
  75. package/playbooks/01-interactive-grilling-gate.md +14 -1
  76. package/playbooks/02-fast-code-deep-verification.md +3 -2
  77. package/playbooks/03-adversarial-code-review.md +3 -3
  78. package/playbooks/05-canonical-plan-template.md +32 -18
  79. package/playbooks/06-model-registry-matrix.md +24 -13
  80. package/playbooks/07-legacy-code-modernization.md +74 -0
  81. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  82. package/setup.mjs +592 -172
  83. package/skills/antislop/SKILL.md +76 -56
  84. package/skills/antislop/VERSION +1 -0
  85. package/skills/antislop-copywriting/SKILL.md +372 -372
  86. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  87. package/skills/antislop-human/SKILL.md +204 -147
  88. package/skills/antislop-human/contrast-check.py +168 -165
  89. package/skills/antislop-human/contrast-mcp.py +6 -3
  90. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  91. package/skills/antislop-human/references/WCAG.md +127 -0
  92. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  93. package/skills/antislop-ui/SKILL.md +344 -304
  94. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  95. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  96. package/skills/brainstorming/SKILL.md +274 -265
  97. package/skills/brainstorming/builder-check-prompt.md +23 -0
  98. package/skills/brainstorming/scripts/frame-template.html +213 -213
  99. package/skills/brainstorming/scripts/server.cjs +723 -723
  100. package/skills/brandkit/SKILL.md +798 -798
  101. package/skills/brutalist-skill/SKILL.md +93 -92
  102. package/skills/caveman/README.md +68 -0
  103. package/skills/caveman/SKILL.md +73 -38
  104. package/skills/claude-collaborator/SKILL.md +24 -44
  105. package/skills/clean-code/SKILL.md +152 -0
  106. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  107. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  108. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  109. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  110. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  111. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  112. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  113. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  114. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  115. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  116. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  117. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  118. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  119. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  120. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  121. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  122. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  123. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  124. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  125. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  126. package/skills/codex-collaborator/SKILL.md +24 -45
  127. package/skills/communication-doctrine/SKILL.md +89 -0
  128. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  129. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  130. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  131. package/skills/executing-plans/SKILL.md +0 -52
  132. package/skills/executing-plans/scripts/task-done +52 -52
  133. package/skills/executing-plans/scripts/task-start +28 -28
  134. package/skills/gemini-collaborator/SKILL.md +24 -56
  135. package/skills/herdr/SKILL.md +243 -0
  136. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  137. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  138. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  139. package/skills/karpathy-guidelines/SKILL.md +67 -67
  140. package/skills/mcp-engineering/SKILL.md +74 -0
  141. package/skills/minimalist-skill/SKILL.md +87 -85
  142. package/skills/output-skill/SKILL.md +49 -49
  143. package/skills/ponytail/SKILL.md +36 -52
  144. package/skills/postgres-best-practices/SKILL.md +30 -52
  145. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  146. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  147. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  148. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  149. package/skills/postgres-best-practices/references/indexing.md +318 -0
  150. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  151. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  152. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  153. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  154. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  155. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  156. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  157. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  158. package/skills/progressive-disclosure/SKILL.md +68 -0
  159. package/skills/pstack-discipline/SKILL.md +40 -0
  160. package/skills/receiving-code-review/SKILL.md +2 -23
  161. package/skills/requesting-code-review/SKILL.md +7 -36
  162. package/skills/soft-skill/SKILL.md +99 -98
  163. package/skills/stitch-skill/DESIGN.md +121 -121
  164. package/skills/stitch-skill/SKILL.md +185 -184
  165. package/skills/strix-security/SKILL.md +54 -53
  166. package/skills/subagent-driven-development/SKILL.md +28 -260
  167. package/skills/subagent-driven-development/references/batching.md +11 -0
  168. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  169. package/skills/subagent-driven-development/references/final-review.md +47 -0
  170. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  171. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  172. package/skills/subagent-driven-development/references/preflight.md +26 -0
  173. package/skills/subagent-driven-development/references/resuming.md +12 -0
  174. package/skills/subagent-driven-development/scripts/review-package +53 -53
  175. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  176. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  177. package/skills/systematic-debugging/SKILL.md +283 -306
  178. package/skills/taste-skill/SKILL.md +542 -1206
  179. package/skills/taste-skill/references/app-screens.md +1199 -0
  180. package/skills/taste-skill/references/colour.md +141 -0
  181. package/skills/taste-skill/references/copy.md +177 -0
  182. package/skills/taste-skill/references/critique.md +182 -0
  183. package/skills/taste-skill/references/imagery.md +791 -0
  184. package/skills/taste-skill/references/layout.md +292 -0
  185. package/skills/taste-skill/references/motion.md +980 -0
  186. package/skills/taste-skill/references/research.md +356 -0
  187. package/skills/taste-skill/references/scenes.md +174 -0
  188. package/skills/taste-skill/references/tells.md +115 -0
  189. package/skills/taste-skill/references/type.md +170 -0
  190. package/skills/test-driven-development/SKILL.md +330 -337
  191. package/skills/thermo/SKILL.md +67 -0
  192. package/skills/threat-modeling/SKILL.md +55 -0
  193. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  194. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  195. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  196. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  197. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  198. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  199. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  200. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  201. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  202. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  203. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  204. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  205. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  206. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  207. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  208. package/skills/verification-before-completion/SKILL.md +0 -14
  209. package/skills/writing-plans/SKILL.md +11 -15
  210. package/skills/writing-skills/SKILL.md +21 -303
  211. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  212. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  213. package/skills/writing-skills/references/bulletproofing.md +80 -0
  214. package/skills/writing-skills/references/discovery.md +201 -0
  215. package/skills/writing-skills/references/flowcharts.md +37 -0
  216. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  217. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  218. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  219. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  220. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  221. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  222. package/skills/gpt-tasteskill/SKILL.md +0 -74
  223. package/skills/taste-skill-v1/SKILL.md +0 -226
  224. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  225. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  226. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  227. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  228. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  229. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  230. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  231. /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.