CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-09-23 13:20:48 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat: UX behavioral foundations + ux-audit command (v0.17.0.0) (#1000)

Browse Source 
* feat: UX behavioral foundations — Krug's usability principles as shared 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>

* feat: $B ux-audit command + snapshot --heatmap flag

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>

* docs: update project documentation for v0.17.0.0

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>

* chore: bump version and changelog (v0.17.0.0)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: adversarial review fixes for ux-audit and heatmap

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>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-04-14 07:47:11 -10:00
committed by GitHub
co-authored by Claude Opus 4.6
parent 7e96fe299b
commit 2300067267
21 changed files with 836 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
browse/src/commands.ts
+4
View File
@@ -40,6 +40,7 @@ export const META_COMMANDS = new Set([
'watch',
'state',
'frame',
'ux-audit',
]);
export const ALL_COMMANDS = new Set([...READ_COMMANDS, ...WRITE_COMMANDS, ...META_COMMANDS]);
@@ -49,6 +50,7 @@ export const PAGE_CONTENT_COMMANDS = new Set([
'text', 'html', 'links', 'forms', 'accessibility', 'attrs',
'console', 'dialog',
'media', 'data',
'ux-audit',
]);
/** Wrap output from untrusted-content commands with trust boundary markers */
@@ -146,6 +148,8 @@ export const COMMAND_DESCRIPTIONS: Record<string, { category: string; descriptio
'style': { category: 'Interaction', description: 'Modify CSS property on element (with undo support)', usage: 'style <sel> <prop> <value> | style --undo [N]' },
'cleanup': { category: 'Interaction', description: 'Remove page clutter (ads, cookie banners, sticky elements, social widgets)', usage: 'cleanup [--ads] [--cookies] [--sticky] [--social] [--all]' },
'prettyscreenshot': { category: 'Visual', description: 'Clean screenshot with optional cleanup, scroll positioning, and element hiding', usage: 'prettyscreenshot [--scroll-to sel|text] [--cleanup] [--hide sel...] [--width px] [path]' },
// UX Audit
'ux-audit': { category: 'Inspection', description: 'Extract page structure for UX behavioral analysis — site ID, nav, headings, text blocks, interactive elements. Returns JSON for agent interpretation.', usage: 'ux-audit' },
};
// Load-time validation: descriptions must cover exactly the command sets