@bacnh85/pi-ux 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.4.7 (2026-09-12)
+
+### Fixed
+
+- `ux_audit` states hints now match the actual failure. With interactive
+  selectors present but focus/disabled rules failing (the fragment case 0.4.6
+  promised to catch), the result appends "states rules may live in another
+  file — pass the COMPLETE stylesheet" (previously: no hint at all). With zero
+  interactive selectors the only possible failure is reduced-motion, so the
+  hint names that fix and only conditionally suggests the fragment case
+  instead of assertively mislabeling a complete stylesheet.
+  (`scanStates` reports `hasInteractive`; `formatAuditResult` is now exported
+  and covered by a test.)
+- README Usage: bare `/ux` resets to the configured default mode (it never
+  toggled).
+
 ## 0.4.6 (2026-09-06)
 
 ### Added

package/README.md

@@ -19,7 +19,7 @@ Pi auto-discovers the extension and skill.
 ## Usage
 
 ```
-/ux              # toggle / show status
+/ux              # reset to configured default mode
 /ux strict       # guardrail + enforce ux_audit gate before handoff (default)
 /ux lite         # guardrail only (ideation, exploration)
 /ux off          # disable

package/extensions/index.js

@@ -38,7 +38,9 @@ export function parseUxCommand(text, defaultMode = DEFAULT_MODE) {
   const normalizedText = String(text || "").trim().toLowerCase();
 
   if (!normalizedText) {
-    return { type: "set-mode", mode: fallback === "off" ? "strict" : fallback };
+    // Reset to the configured default, whatever it is — a deliberate
+    // `/ux default off` must survive bare `/ux` too.
+    return { type: "set-mode", mode: fallback };
   }
 
   const [primary, secondary] = normalizedText.split(/\s+/);
@@ -90,7 +92,7 @@ function auditParametersSchema() {
   };
 }
 
-function formatAuditResult(result) {
+export function formatAuditResult(result) {
   const lines = [];
   lines.push(result.pass ? "✅ UX AUDIT PASSED" : "❌ UX AUDIT FAILED");
   lines.push("");
@@ -113,6 +115,17 @@ function formatAuditResult(result) {
   for (const m of s.missingFocusVisible) lines.push(`  ✗ ${m}`);
   for (const m of s.missingDisabled) lines.push(`  ✗ ${m}`);
   for (const m of s.missingReducedMotion || []) lines.push(`  ✗ ${m}`);
+  if (!s.pass) {
+    if (s.missingFocusVisible.length || s.missingDisabled.length) {
+      // Interactive selectors ARE present, yet focus/disabled rules failed —
+      // for a fragment those rules may simply live in another file.
+      lines.push("  ℹ If this is a fragment, states rules may live in another file — pass the COMPLETE stylesheet.");
+    } else if (s.hasInteractive === false) {
+      // No interactive selectors: the only possible failure is reduced-motion.
+      // Say how to fix it, and only conditionally suggest the fragment case.
+      lines.push("  ℹ Motion needs a prefers-reduced-motion fallback. If this is the complete stylesheet, add one; if it is a fragment, audit the COMPLETE stylesheet.");
+    }
+  }
 
   const st = result.gates.slopTells;
   lines.push(st.pass ? "✓ Slop tells" : "✗ Slop tells");

package/hooks/ux-audit.js

@@ -206,7 +206,7 @@ function scanOffSystem(css, tokens) {
 // .test() flake across calls, so use plain includes().
 function scanStates(css) {
   css = css.replace(/\/\*[\s\S]*?\*\//g, ' '); // dead code must not fail the gate
-  const findings = { missingFocusVisible: [], missingDisabled: [], missingReducedMotion: [] };
+  const findings = { missingFocusVisible: [], missingDisabled: [], missingReducedMotion: [], hasInteractive: false };
 
   // Motion needs a reduced-motion fallback regardless of interactive elements
   // (a hero fade-in on a page with no buttons still needs one).
@@ -219,6 +219,7 @@ function scanStates(css) {
   const hasInteractive =
     /\b(?:button|a|input|select|textarea)\b/i.test(css) || /\[role\s*=\s*"?button"?\]/i.test(css);
   if (!hasInteractive) return findings;
+  findings.hasInteractive = true;
 
   if (!css.includes(':focus-visible')) findings.missingFocusVisible.push('no :focus-visible rule for interactive elements');
   if (!css.includes(':disabled')) findings.missingDisabled.push('no :disabled rule for interactive elements');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-ux",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Anti-slop UI/UX design discipline for your Pi agent — anchors a lintable DESIGN.md, runs deterministic slop-audit gates (APCA contrast + tokens + states + slop tells), works with text-only models, ships reference design-system presets.",
   "keywords": [
     "pi-package",

package/skills/ux-capture/SKILL.md

@@ -12,7 +12,18 @@ description: >
 
 Judge captures at viewer resolution (1×–3×); never chase sub-visible precision.
 
-## Default — local capture (offline, no daemon)
+## Default — web_screenshot (pi-web ≥0.7.0, auto local detection)
+
+`web_screenshot` auto-routes localhost/LAN/file URLs to the locally installed
+headless Chrome and returns the PNG inline — no daemon, no manual commands:
+
+- `web_screenshot url="http://localhost:PORT"` — done; the model sees the render.
+- `full_page=true` captures a tall 8000px window; `wait_for` settles JS via
+  `--virtual-time-budget`; `engine="local"` forces local on a public URL.
+- `web_pdf` works the same way (`--print-to-pdf`) for full-content archival.
+- If Chrome is missing: `web_status` shows `localChrome.path`; set `CHROME_PATH`.
+
+## Fallback — manual headless Chrome (pi-web <0.7.0 or if the tool errors)
 
 Headless Chrome writes the PNG; the `read` tool shows it inline (multimodal models see it).