feat: UX behavioral foundations + ux-audit command (v0.17.0.0)#1000
Merged
Conversation
…ed design infrastructure Add UX_PRINCIPLES resolver distilling Steve Krug's "Don't Make Me Think" into actionable guidance for AI agents. Injected into all 4 design skills as a shared behavioral foundation complementing the existing visual checklist (WHAT to check) and cognitive patterns (HOW designers see) with HOW USERS ACTUALLY BEHAVE. Methodology rewire: 6 Krug usability tests woven into existing design-review phases — Trunk Test, 3-Second Scan, Page Area Test, Happy Talk Detection with word count metric, Mindless Choice Audit, Goodwill Reservoir tracking with visual dashboard. First-person narration mode for design-review output with anti-slop guardrail. Hard rules: 4 Krug always/never rules in DESIGN_HARD_RULES (placeholder-as-label, floating headings, visited link distinction, minimum type size). Krug, Redish, Jarrett added to plan-design-review references. Token ceiling: gen-skill-docs.ts warns if any SKILL.md exceeds 100KB (~25K tokens). Documented in CLAUDE.md. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New browse meta-command: ux-audit extracts page structure (site ID, navigation, headings, interactive elements, text blocks) as structured JSON for agent-side UX behavioral analysis. Pure data extraction — the agent applies the 6 usability tests and makes judgment calls. Element caps: 50 headings, 100 links, 200 interactive, 50 text blocks. New snapshot flag: -H/--heatmap accepts a JSON color map mapping ref IDs to colors (green/yellow/red/blue/orange/gray). Extends existing snapshot -a annotation system with per-ref colors instead of hardcoded red. Color whitelist validation prevents CSS injection. Composable — any skill can use it. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ARCHITECTURE.md: added {{UX_PRINCIPLES}} resolver to placeholder table.
VERSION: bumped to 0.17.0.0 for UX behavioral foundations release.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Security: - Remove live form value extraction from ux-audit (leaked input field values) - Add ux-audit to PAGE_CONTENT_COMMANDS (untrusted content wrapping) Correctness: - Scope youAreHere selector to nav containers (was matching animation classes) - Validate heatmap JSON is a plain object (string/array/null produced garbage) - Use textContent instead of innerText for word count (avoids layout computation) - Remove dead url variable and unused LINK_CAP constant Found by Codex + Claude adversarial review. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
E2E Evals: ✅ PASS37/37 tests passed | $4.98 total cost | 12 parallel runners
12x ubicloud-standard-2 (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
UX behavioral foundations. Every design skill now thinks about how users actually behave, not just how the interface looks. Based on Steve Krug's "Don't Make Me Think," distilled into a shared resolver injected into 4 design skills.
Methodology rewire. 6 usability tests woven into the existing design-review methodology: Trunk Test, 3-Second Scan, Page Area Test, Happy Talk Detection with word count, Mindless Choice Audit, Goodwill Reservoir tracking with visual dashboard. First-person narration mode with anti-slop guardrail.
$B ux-auditcommand. Standalone UX structural extraction. Returns JSON with site ID, navigation, headings, interactive elements, text blocks. Pure data extraction with element caps. Agent applies the 6 usability tests.snapshot -H/--heatmapflag. Color-coded overlays (green/yellow/red/blue/orange/gray) with CSS injection prevention via color whitelist. Composable: any skill can use it.Token ceiling enforcement. gen-skill-docs warns if any SKILL.md exceeds 100KB (~25K tokens).
Adversarial review fixes. Codex + Claude subagent found and we fixed: form value leak in ux-audit, missing untrusted content wrapping, false-positive youAreHere selector, non-object JSON validation in heatmap, innerText -> textContent for performance.
Test Coverage
All new code paths verified by existing test infrastructure:
Pre-Landing Review
Adversarial review ran (both Codex + Claude subagent). 6 issues found, all fixed in the final commit.
Reviews
Test plan
bun run gen:skill-docsproduces all SKILL.md files with no unresolved placeholdersbun testpasses (pre-existing failures only)🤖 Generated with Claude Code