@ericrisco/rsc 3.3.1 → 3.5.0

package/skills/ux/upstream/ux-designer/references/25c-barcode-display.md

@@ -0,0 +1,277 @@
+# Displaying Barcodes & QR Codes
+
+This file covers codes that *your* UI shows for someone else to scan: tickets, boarding
+passes, loyalty cards, wallet passes, QR login and pairing, payment QR, kiosk and slide
+codes, and printed labels and receipts. Most failures here are physical. The module is
+too small, the quiet zone is clipped, the theme inverts the code, or the scanner at the
+gate is a laser. The UX work is making the code big, clean, bright, and instantly
+retrievable, plus a fallback for when it still won't scan.
+
+> Scanning codes with the phone camera: [25a-barcode-camera-scanning.md](25a-barcode-camera-scanning.md).
+> Hardware scanners and scan-driven apps, plus the symbology/GS1 primer:
+> [25b-barcode-scanner-workflows.md](25b-barcode-scanner-workflows.md).
+> Short version of the primer: QR/DataMatrix/Aztec are 2D and read by camera imagers;
+> PDF417 is stacked-linear; EAN/UPC/Code 128 are 1D and the only kind a laser can read.
+
+---
+
+## Contents
+
+- Choosing the Symbology & Payload
+- Sizing: Modules, Quiet Zone, Distance
+- Error Correction, Contrast & Polarity
+- Presenting the Code on a Screen
+- Brightness & Wake Lock
+- Dark Mode & Forced Inversion
+- Fast Retrieval & Offline Access
+- Wallet Passes
+- Security: Rotating Codes & Screenshots
+- QR Login & Device Pairing
+- Payment QR (EMVCo)
+- Human-Readable Fallback
+- Codes on Kiosks, Slides & Signage
+- Print: Labels, Receipts, Boarding Passes
+- Quick Checklist
+- Common Mistakes
+- Sources
+
+---
+
+## Choosing the Symbology & Payload
+
+| Use | Symbology | Why |
+|---|---|---|
+| Phone screen, general | QR | Universal camera support, square, fits portrait screens |
+| Boarding pass (mobile) | Aztec, QR or DataMatrix | IATA BCBP (Res. 792) allows all three with no preference; readers should support all three |
+| Boarding pass (paper) | PDF417 (default) | IATA; 2D matrix allowed since BCBP v7 |
+| Retail product, 2D | GS1 DataMatrix or QR with GS1 Digital Link | GS1 2D-in-retail |
+| Must be read by legacy laser scanners | 1D (Code 128, EAN) **on paper** | Lasers can't read 2D and can't reliably read screens |
+| Apple Watch | QR (square) | Rectangular codes get rotated; Code 128 is not shown on watchOS |
+
+- **Encode an ID, not the data.** A short payload means a lower QR version, which means
+  bigger modules at the same physical size. Apple notes that the most common use of a
+  pass barcode is a unique ID that points to server records.
+- For Wallet passes, send a **fallback array** of formats. The first one the OS supports is
+  shown (e.g. EAN-13 on iOS 27+, QR on older versions).
+- Use `iso-8859-1` message encoding for pass barcodes. Scanners handle Unicode poorly.
+
+## Sizing: Modules, Quiet Zone, Distance
+
+Size is set by the **module** (the smallest square or bar), not by the image. A bigger
+image with a denser code doesn't help.
+
+| Rule | Value | Source |
+|---|---|---|
+| QR quiet zone | **4 modules** on all sides | ISO/IEC 18004, DENSO WAVE, GS1 |
+| Micro QR quiet zone | 2 modules | DENSO WAVE |
+| DataMatrix quiet zone | 1 module | GS1 |
+| Aztec quiet zone | none (central finder) | IATA BCBP guide |
+| EAN-13 / EAN-8 / ITF-14 & GS1-128 quiet zone | 11X left + 7X right / 7X / 10X | GS1 |
+| Module on a screen | **≥ 0.25 mm physical** | IATA BCBP guide |
+| Module in print, standard scanners | ≥ 0.25 mm, ≥ 4 printer dots | DENSO WAVE |
+| GS1 retail 2D X-dimension | min 0.396 / target 0.495 / max 0.990 mm | GS1 |
+| Minimum printed QR | 2 × 2 cm | NN/g (heuristic) |
+| Distance | +1 cm of code per 10 cm of scan distance (~10:1) | NN/g (heuristic, not in ISO) |
+
+- **Screens:** high-density displays can make a code physically tiny. Size it in physical
+  units (mm/pt), not device pixels. Render with an **integer number of device pixels per
+  module** and no smoothing (`image-rendering: pixelated` when upscaling a bitmap; SVG
+  with `shape-rendering: crispEdges`). Fractional scaling blurs module edges. No
+  standard gives a minimum pixel count; the "≥150 px" figures online come from vendor blogs.
+- **Scanner side:** camera decoders need the smallest module to cover about 2 camera
+  pixels or more (ML Kit). That's why a code that's fine up close fails from a distance.
+- **Quiet zone** is part of the code. Anything that intrudes on it (a border, rounded
+  screen corner, notch, toast, cookie bar, home indicator) can break decoding.
+
+## Error Correction, Contrast & Polarity
+
+- **QR error correction:** L 7%, M 15%, Q 25%, H 30% of codewords recoverable.
+  **Default to M** (DENSO: the most commonly chosen level). Use Q/H only for dirty or damaged
+  environments or a centre logo. Higher levels make the symbol denser.
+- **Logos** use up error-correction capacity (GS1). If you add one, raise the level and test.
+- **Contrast:** dark modules on a light background, two colours only. **Don't use red for
+  dark modules**, because scanners and verifiers use red light (GS1). Don't reshape modules
+  (dots, hearts) or warp the grid.
+- **Inverted (light-on-dark):** ISO 18004 allows it and GS1 requires POS imagers to read
+  it, but many camera decoders don't (ZXing needs `TryInverted`, and ML Kit has open
+  issues). **Always render dark-on-light**, even in a dark UI.
+
+## Presenting the Code on a Screen
+
+- Give the code a **dedicated screen or sheet**: the code as large as fits the width, the
+  holder's name and seat/gate/date above it, and nothing animated over it.
+- In a dark theme, put the code on its **own white card that includes the quiet zone**.
+- Keep the code clear of notches, rounded corners, sticky headers, toasts, and banners.
+- Prefer portrait for QR/Aztec. A long 1D code may need a rotate-to-landscape option or
+  a 2D alternative.
+- Several tickets: one per page with a pager ("2 of 4") and swipe, so staff can scan them
+  in sequence. Don't show them in a scrolling list of small codes.
+- Decorative motion (Ticketmaster's sweeping line) is a visual anti-screenshot cue only.
+  The security comes from the rotating code underneath.
+
+## Brightness & Wake Lock
+
+| Platform | Mechanism | Behaviour |
+|---|---|---|
+| iOS | `UIScreen.main.brightness = 1.0` | Persists **until device lock, even after the app closes**. Save the old value and restore it when the code screen closes or backgrounds |
+| Android | `WindowManager.LayoutParams.screenBrightness = BRIGHTNESS_OVERRIDE_FULL` | Per window; reverts automatically when the window leaves the front |
+| Web | **none** | The Screen Brightness API is only a WICG proposal. Ask the user: "Turn up brightness for faster scanning" |
+| Web | `navigator.wakeLock.request('screen')` | Keeps the screen from dimming or locking (Baseline 2025, HTTPS). Released when the page is hidden; re-request on `visibilitychange`. Doesn't change brightness |
+
+- Boost brightness **only while the code is visible**, and restore it on exit.
+- Apple Wallet maxes brightness with no opt-out, and light-sensitive users complain
+  about it (community reports; not documented by Apple). Offer an in-app toggle if your
+  audience includes photosensitive users.
+
+## Dark Mode & Forced Inversion
+
+- Chrome Auto Dark Theme, Vivaldi, and some email clients (Outlook for Windows) recolor
+  pages and can **invert QR codes**. Forced dark broke WhatsApp Web's login QR.
+- Opt the code out with `color-scheme: only light` on its container (or
+  `<meta name="color-scheme" content="only light">` for the whole page).
+- CSS, SVG, or canvas-drawn codes are more at risk than `<img>`. In email, bake a white
+  quiet zone into the image and preview it in dark mode.
+
+## Fast Retrieval & Offline Access
+
+The code gets used at a turnstile, with a queue behind the user and bad signal.
+
+- **Save for offline on first view** and say so ("Available offline"). Never make the
+  code depend on a network fetch at the gate.
+- Offer **Add to Apple Wallet / Google Wallet**. Wallet passes can surface on the lock
+  screen near the right time or place.
+- Put the next upcoming ticket **one tap from app launch** (home card or widget), not
+  behind Orders → Order → Ticket.
+- Email is the weakest channel. IATA notes you have little control over how the code
+  renders there. Link from the email to the app, wallet, or a mobile-optimized page.
+- Give a fallback path on the ticket screen: order number, and "show ID at the desk".
+
+## Wallet Passes
+
+- Put the barcode through the pass APIs, **never baked into a pass image** (Apple HIG).
+- **Apple:** `barcodes` array (QR, PDF417, Aztec, Code 128; iOS 27 adds Code 39, Codabar,
+  EAN-13, ITF). `altText` shows under the code, but **not on watchOS**. Lock-screen
+  relevance comes from `relevantDate` and up to 10 `locations`/`beacons`.
+- **Google:** `BarcodeType` covers the common 1D and 2D types; `alternateText` is the
+  human-readable fallback. Rotating barcodes (below) exist for PDF417 and QR only.
+- A signed payload lets a gate verify offline, but it can't carry changing state such
+  as balances or single-use coupons.
+
+## Security: Rotating Codes & Screenshots
+
+- **Rotating codes are the real control.** Google Wallet rotating barcodes use TOTP
+  (RFC 6238), typically rotating every minute. Ticketmaster SafeTix rotates every 15 s
+  (vendor claim). The scanner accepts only the current value, plus a server-side
+  single-use check.
+- **Screenshot blocking isn't security.** Someone can photograph the screen with another
+  phone. iOS has no public API to block screenshots; it can only detect them after the
+  fact (`userDidTakeScreenshotNotification`) or detect recording (`UIScreen.isCaptured`).
+  Android `FLAG_SECURE` blanks screenshots but is unreliable on older versions. The
+  Android 14 screenshot-detection API shows a system toast, so explain it in context.
+- Don't block screenshots of codes users legitimately need to keep, such as boarding
+  passes and static loyalty cards. Blocking them breaks offline access and helps no one.
+- If a static fallback exists for rotating codes, it undoes most of the protection (Google).
+
+## QR Login & Device Pairing
+
+A QR that signs in or links a device is a phishing target: QRLJacking (OWASP),
+"free Nitro" Discord QR scams, and device-code phishing (Microsoft's Storm-2372, 2024–26).
+
+**Displaying device (TV, desktop, new device):**
+- Say what the code does and which app scans it: "Scan with the *App* app on your phone
+  to sign in on this TV."
+- Show the **short URL and a typed code** next to the QR. RFC 8628 requires the
+  `user_code` to be shown and recommends the text URL. Use a confusable-free alphabet in
+  dash-separated groups (e.g. `WDJB-MJHT`).
+- Short lifetime, auto-refresh, and a visible countdown. Warn "Never scan a sign-in code
+  someone sent you."
+
+**Approving device (the phone that scans):**
+- Show what's being authorized: device type, app, approximate location or IP, and time.
+- Require explicit confirmation plus re-authentication (WhatsApp asks for biometrics or
+  a passcode before linking a device).
+- Make "This wasn't me" as prominent as "Approve".
+
+## Payment QR (EMVCo)
+
+- **Merchant-presented (MPM):** the merchant shows the code and the payer's *payment app*
+  scans it. The OS camera usually can't handle it, so signage should name the accepted apps.
+  Static codes (`11`, a counter sticker) vs dynamic (`12`, per transaction with the amount).
+- **Consumer-presented (CPM):** the payer's phone shows the code and the merchant's scanner
+  reads it. The display rules in this file apply: brightness, offline-generated if possible,
+  a short validity window.
+- The payer app shows the **merchant name and amount before confirmation**.
+- Payload ≤ 512 characters. EMVCo sets no size or error-correction rules of its own, so
+  use ISO 18004 and DENSO guidance.
+
+## Human-Readable Fallback
+
+- Always pair the code with a **human-readable value** that staff can key in: Apple
+  `altText`, Google `alternateText`, a printed number under the code.
+- Retail items with **only** a 2D code must print the 14-digit GTIN as HRI (GS1). GS1
+  logistics labels use HRI ≥ 3 mm high, in a legible font such as OCR-B.
+- For marketing and login codes, show a short, typeable URL as well (NN/g).
+
+## Codes on Kiosks, Slides & Signage
+
+- QR codes carry no information scent, so **label where the code goes and why to scan it**
+  (NN/g).
+- Leave a slide or screen code up for **≥ 15 s** so people can find their phone (NN/g).
+- Size for the farthest viewer with the 10:1 heuristic, and mount signage at a height
+  that doesn't force a steep camera angle.
+- Kiosk printers and screens: test with the actual scanners and paper stock before launch.
+
+## Print: Labels, Receipts, Boarding Passes
+
+- Print quality grades: ISO/IEC 15416 (1D) and 15415 (2D), A–F. The overall grade is the
+  worst parameter. GS1 retail 2D minimum is **1.5/12/660**; many distributors require B.
+- Thermal printers: 200 dpi → 0.5–0.75 mm modules; 300 dpi → 0.33–0.5 mm (4–6 dots per module).
+- Don't truncate 1D bar height (GS1 EAN-13 minimum height is 18.28 mm).
+- Boarding pass PDF417: narrow element ≥ 0.25 mm, height ≥ 6.35 mm. Place it near the
+  page edge so a mounted scanner's foot doesn't cover it (IATA).
+- During the retail 2D transition, keep the 1D and 2D codes within 50 mm of each other (GS1).
+
+---
+
+## Quick Checklist
+
+- [ ] Payload is a short ID/URL; symbology fits the scanner and screen (QR default)
+- [ ] Quiet zone intact (QR 4 modules) and clear of UI chrome, notches, and overlays
+- [ ] Module ≥ 0.25 mm physical; integer device pixels per module; no smoothing
+- [ ] Dark-on-light, two colours, not red; opted out of forced dark (`color-scheme: only light`)
+- [ ] Error correction M by default; H only with a logo or harsh conditions, then tested
+- [ ] Brightness boosted only while the code is shown and restored on exit (iOS!); wake lock on web
+- [ ] Available offline, one tap from launch, Add to Wallet offered
+- [ ] Human-readable value and a staff fallback (order number / ID) visible
+- [ ] Anti-fraud uses rotating codes + server checks, not screenshot blocking
+- [ ] Login/pairing QR: says what it does, has a typed code, expires; the approver sees device details and re-auths
+- [ ] Printed codes verified to grade (GS1 ≥ 1.5, target B) with the real printer and stock
+
+## Common Mistakes
+
+- Inverting the code with a dark theme, or letting the browser force-dark it
+- Showing a dense code at a fixed pixel size that comes out physically tiny on a high-DPI phone
+- Cropping the quiet zone with a card border or rounded corner
+- Code only reachable online, or buried several screens deep
+- Leaving the screen at full brightness after the user leaves (iOS persists it until lock)
+- Expecting laser scanners to read a code from a phone screen
+- Relying on screenshot blocking instead of rotating codes
+- A login QR with no explanation, no typed alternative, and an approver screen that doesn't say what it's approving
+- Stylized QR codes (coloured, rounded dots, big logos) shipped without testing on several decoders
+
+---
+
+## Sources
+
+- [DENSO WAVE — QR Code quiet zone, module size, error correction](https://www.qrcode.com/en/howto/code.html) · [cell size](https://www.qrcode.com/en/howto/cell.html) · [error correction](https://www.qrcode.com/en/about/error_correction.html)
+- [ISO/IEC 18004:2024 preview](https://cdn.standards.iteh.ai/samples/83389/dee29007cb62437f9767323e6af02f90/ISO-IEC-18004-2024.pdf)
+- [GS1 — 2D barcodes in retail](https://ref.gs1.org/guidelines/2d-in-retail/) · [Solution provider 2D readiness](https://ref.gs1.org/sme-guidance/solution-provider-2d-readiness/) · [GS1 Sweden size guide](https://gs1.se/en/guides/how-to-guides/size-guide/)
+- [IATA BCBP Implementation Guide v7](https://www.iata.org/contentassets/1dccc9ed041b4f3bbdcf8ee8682e75c4/2021_03_02-bcbp-implementation-guide-version-7-.pdf)
+- [Apple HIG — Wallet](https://developer.apple.com/design/human-interface-guidelines/wallet) · [Wallet pass barcodes](https://developer.apple.com/documentation/walletpasses/pass/barcodes-data.dictionary) · [PassKit Programming Guide](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html) · [UIScreen.brightness](https://developer.apple.com/documentation/uikit/uiscreen/brightness)
+- [Google Wallet — rotating barcodes](https://developers.google.com/wallet/tickets/events/resources/rotating-barcodes) · [BarcodeType](https://developers.google.com/wallet/reference/rest/v1/BarcodeType)
+- [Android WindowManager.LayoutParams](https://developer.android.com/reference/android/view/WindowManager.LayoutParams) · [FLAG_SECURE guidance](https://developer.android.com/security/fraud-prevention/activities) · [Screenshot detection](https://developer.android.com/about/versions/14/features/screenshot-detection)
+- [MDN — Screen Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API) · [WICG Screen Brightness proposal](https://github.com/WICG/proposals/issues/17) · [Chrome Auto Dark Theme](https://developer.chrome.com/blog/auto-dark-theme)
+- [RFC 8628 — OAuth Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628.html) · [OWASP QRLJacking](https://owasp.org/www-community/attacks/Qrljacking) · [Microsoft — Storm-2372 device code phishing](https://www.microsoft.com/en-us/security/blog/2025/02/13/storm-2372-conducts-device-code-phishing-campaign/)
+- [EMVCo QR Codes](https://www.emvco.com/emv-technologies/qr-codes/) · [What, why and how of EMV QR](https://www.emvco.com/knowledge-hub/the-what-why-and-how-of-emv-qr-codes/)
+- [NN/g — QR code guidelines](https://www.nngroup.com/articles/qr-code-guidelines/)
+- [ML Kit barcode scanning — input image guidelines](https://developers.google.com/ml-kit/vision/barcode-scanning/android)

package/skills/ux/upstream/ux-usability-foundations/GUIDE.md

@@ -0,0 +1,285 @@
+# UX Usability Foundations
+
+## Purpose
+
+Help an agent make interfaces understandable, usable, forgiving, and aligned with user expectations. Treat usability as product behavior, not surface decoration. The agent should turn unclear or fragile UI into an interface where users can quickly answer: what is this, what can I do here, where am I, what happened, how do I recover, and is this worth the effort?
+
+## When to use this skill
+
+Use this skill when the user asks you to critique, redesign, create, or specify a UI, flow, form, app screen, website, dashboard, onboarding, settings page, checkout, navigation model, state behavior, or component interaction for usability. Use it for affordances/signifiers, feedback, constraints, errors, empty/loading/success states, recognition over recall, task clarity, and frontend behavior.
+
+## When not to use this skill
+
+Do not use as the primary skill for deep research operations, brand styling systems, visual polish, typography craft, frontend architecture, or persuasion/growth tactics unless those choices directly affect user understanding, control, or recovery.
+
+## Core principles
+
+1. **Start with goals, not screens.** Identify the user’s goal, task, context, and likely knowledge before changing controls or layout. Design requirements describe needs before widgets.
+2. **Make the next action obvious.** Prefer self-evident interfaces. If the task is inherently novel or complex, make it self-explanatory with structure, labels, examples, and feedback.
+3. **Show what is possible.** Interactive elements must look interactive. Read-only elements must not look editable. Hidden gestures need visible alternatives.
+4. **Match the user’s mental model.** Use the concepts, names, and sequence users understand; do not expose database tables, file paths, internal IDs, or arbitrary system states unless users need them.
+5. **Favor recognition over recall.** Keep needed options, context, examples, and state visible or easy to retrieve.
+6. **Reduce work and excise.** Remove tasks that serve the system rather than the user’s goal: retyping, transferring data, hunting for controls, configuring obvious defaults, or answering inferable questions.
+7. **Guide choices without overloading users.** Use progressive disclosure, sensible defaults, grouping, and prioritization.
+8. **Give immediate, informative feedback.** Every consequential action needs a response that says whether the system received it, what changed, whether waiting is required, and what can happen next.
+9. **Prevent errors before explaining them.** Use constraints, safe defaults, previews, tolerant input, inline validation, and undo where feasible.
+10. **Blame the design, not the user.** Errors reveal a mismatch in expectations or an unsupported edge case. Preserve work and guide recovery.
+11. **Respect platform and convention.** Use familiar patterns when they fit. Break convention only when the user’s goal clearly benefits and the new behavior can be discovered and recovered from.
+12. **Accessibility is usability under pressure.** Design for perceptibility, operability, simplicity, and forgiveness across varied abilities, devices, literacy, stress, and environments.
+
+See [references/principle-cards.md](references/principle-cards.md) for each principle as a reusable card.
+
+## Default recommendations
+
+### Product goal
+Default to optimizing the primary user task before secondary business asks. Override only for legal, safety, fraud, privacy, or business-critical requirements. Ask: “Which obligation must interrupt or constrain the primary task, and what is the consequence of hiding or delaying it?”
+
+### Audience
+Default to motivated but distracted users with average domain knowledge and imperfect memory. Override for trained expert operators using the product frequently under stable conditions. Ask: “Is this primarily for first-time/infrequent users, frequent intermediates, or trained experts?”
+
+### Platform and input
+Default to platform conventions and support pointer, touch, keyboard, and assistive technology where relevant. Ask when platform/input constraints are unknown.
+
+### Information density
+Default to enough context for recognition and decision-making, while hiding rare advanced controls behind clear entry points. Override for comparison, monitoring, or expert workflows. Ask: “Do users need overview density for monitoring/comparison, or step-by-step focus for completion?”
+
+### Navigation
+Default to clear location, current object/state, access to major areas, and a visible route back or onward. Override only for intentional guided flows. Ask: “Should users be free to move around, or should this flow intentionally constrain navigation?”
+
+### Labels and language
+Default to plain, task-oriented labels from the user’s vocabulary. Ask before using internal, clever, legal, or domain-specific terms.
+
+### Forms
+Default to persistent labels, appropriate input types, upfront constraints, inline validation where helpful, preserved data, and a clear primary action. Ask only when density/speed for experts may be more important than first-time clarity.
+
+### Error handling
+Default to prevention first; if error occurs, explain what happened, why it matters, and how to fix it without losing work. Ask when error details are sensitive, regulated, or security-relevant.
+
+### Destructive actions
+Default to visually secondary destructive actions until the final review/confirmation step. Prefer undo for reversible actions; use confirmation for irreversible, costly, legal, or safety actions. Ask about reversibility and harm.
+
+### Feedback and status
+Default to instant receipt feedback, progress for delays, visible completion, and persistent state for long-running or consequential operations. Ask which status changes should interrupt.
+
+### Accessibility
+Default to WCAG-oriented basics: semantic controls, keyboard operation, focus visibility, programmatic labels, sufficient contrast, no color-only meaning, readable copy, and screen-reader-friendly state updates. Do not override basics.
+
+## Required user questions
+
+Do not ask routine best-practice questions. Ask one focused question only when the answer changes the recommendation:
+
+- The primary user/task is unclear.
+- The action has safety, financial, legal, privacy, medical, or irreversible consequences.
+- Novices and experts need different behaviors.
+- Platform/input constraints are unknown.
+- Required terminology or compliance copy may apply.
+- The user requests a nonstandard, hidden, or manipulative pattern.
+- There is a real tradeoff between density and clarity or between guided flow and free navigation.
+
+Use this pattern:
+
+```js
+question({
+  question: "What is the primary task this interface must help users complete?",
+  recommended_default: "Optimize for the most common successful task first, then make secondary actions available but visually quieter.",
+  options: [
+    "Complete one focused task",
+    "Compare or monitor multiple items",
+    "Explore and choose among options",
+    "Other / custom"
+  ]
+})
+```
+
+Use the question-tool-ready prompts in [references/decision-prompts.md](references/decision-prompts.md) for the full decision set.
+
+## Workflow for critiquing an existing UI
+
+Inspect in this order:
+
+1. User goal and task fit.
+2. First-glance comprehension.
+3. Orientation: current place, object, state, and path onward/back.
+4. Action discoverability.
+5. Choice quality and priority.
+6. Labels and language.
+7. Feedback and status.
+8. Error prevention and recovery.
+9. Recognition versus memory burden.
+10. Accessibility and input coverage.
+11. Frontend feasibility and edge states.
+12. Prioritization by task impact, frequency, severity, and fix effort.
+
+Report critique as: highest-impact usability issues, quick wins, behavior/spec details, accessibility notes, and risks/tradeoffs.
+
+## Workflow for creating or improving an interface
+
+1. Clarify the user, goal, success condition, and risk.
+2. Choose the simplest useful flow.
+3. Map user concepts and vocabulary.
+4. Create visible structure and action hierarchy.
+5. Select standard patterns unless a task reason justifies custom behavior.
+6. Design default, hover, focus, active, loading, success, empty, validation, error, offline, disabled, and permission states.
+7. Add constraints, validation, and recovery.
+8. Support first use and repeated use.
+9. Verify accessibility.
+10. Explain decisions in terms of task progress, cognitive load, expectations, and risk.
+
+## Decision framework
+
+Ask yourself:
+
+1. Is the problem comprehension, choice, control, feedback, navigation, or recovery?
+2. Can the design prevent the problem rather than explain it?
+3. Can the interface use recognition instead of recall?
+4. Can a standard pattern solve this without new learning?
+5. Which elements are primary, secondary, tertiary, or dangerous?
+6. Does the user need more information, fewer choices, or a better sequence?
+7. Will the user notice the state change?
+8. What happens if the user is distracted, rushed, using touch, using keyboard, using assistive tech, or recovering from an error?
+9. What is reversible, costly, or irreversible?
+10. Is this serving the user’s task or the system’s convenience?
+
+## Practical rules
+
+### Obviousness and scanning
+- Make each screen’s purpose visible in its heading, structure, and primary action.
+- Use descriptive buttons: “Send invoice,” “Save changes,” or “Book appointment,” not “Submit.”
+- Make click/tap targets look like controls without relying on hover.
+- Use headings, grouping, whitespace, and lists so users can scan.
+- Remove copy and decorative elements that compete with the task.
+
+### Affordances, signifiers, and controls
+- Use native controls when behavior fits.
+- Use icons with labels for unfamiliar or consequential actions.
+- Preserve distinctions between links, buttons, selected items, disabled items, editable fields, and static text.
+- Do not hide essential actions behind gestures, long press, hover, or tiny overflow menus unless visible alternatives exist.
+
+### Choices and progressive disclosure
+- Limit initial choices to the current decision.
+- Use safe, likely defaults.
+- Reveal advanced options near the point of need.
+- Use comparison structures when users must choose among similar plans, products, records, or settings.
+
+### Feedback and state
+- Give immediate micro-feedback for command receipt.
+- Show progress for delays and async operations.
+- Confirm completion when the result is not visible.
+- Make current selection, current page, current filter, unsaved changes, and offline/sync status visible.
+- Avoid noisy feedback for routine non-events.
+
+### Errors and recovery
+- Validate constraints before submission when feasible.
+- Keep invalid user input visible and editable.
+- Place errors next to affected controls and summarize long-form errors.
+- Use undo for reversible actions and confirmation for irreversible or high-risk actions.
+- Never make users start over after a recoverable problem.
+
+### Navigation and orientation
+- Show current section, object, state, and available next/back paths.
+- Use breadcrumbs for deep hierarchy, not as a substitute for clear navigation.
+- Use tabs only for peer sections of the same context.
+- Use drawers/menus for infrequent or space-constrained actions; avoid hiding frequently needed primary navigation.
+- Preserve route, filters, and scroll position when users return from detail to list.
+
+### Learnability
+- Make first-run help temporary and task-focused.
+- Prefer inline examples and empty-state guidance over separate help documents.
+- Let repeated successful use reduce beginner guidance.
+- Design for “perpetual intermediates”: users know the basics but do not remember everything.
+
+## Accessibility and inclusion requirements
+
+- Use semantic HTML and native elements before custom widgets.
+- Ensure all interactive elements have accessible names.
+- Keep focus order aligned with visual/task order.
+- Provide visible focus indicators.
+- Support keyboard operation for all actions.
+- Associate labels, hints, and errors with form controls.
+- Do not rely on placeholder text as the only label.
+- Do not rely on color alone.
+- Announce async status and errors appropriately.
+- Ensure dialogs trap focus while open and restore focus when closed.
+- Respect reduced motion.
+- Make target sizes suitable for touch and motor variability.
+- Write at the simplest level compatible with the task and domain.
+
+## Frontend implementation guidance
+
+### Semantic structure
+- Use `<button>` for actions and `<a>` for navigation.
+- Use persistent programmatic labels for inputs.
+- Use fieldsets/legends for related radio/checkbox groups.
+- Use headings in logical order.
+- Use tables for tabular data, not layout.
+
+### State and feedback
+- Include default, hover, focus-visible, active, selected, expanded/collapsed, disabled, loading, success, warning, error, empty, offline, and read-only states where relevant.
+- Use `aria-expanded`, `aria-controls`, `aria-selected`, `aria-current`, `aria-invalid`, `aria-describedby`, and live regions as needed.
+- Disable controls only when the reason is obvious or explained; otherwise allow the action and guide the user.
+- Prevent duplicate submissions with pending state and idempotent server handling.
+
+### Forms
+- Use `type`, `autocomplete`, `inputmode`, `min`, `max`, `step`, and constraints appropriately.
+- Keep input flexible when users may enter equivalent formats.
+- Validate on blur or submit for complex fields; validate on input only when stable and helpful.
+- Preserve entries across errors, refreshes, authentication interruptions, and network failures whenever possible.
+
+### Responsive and input behavior
+- Do not assume hover.
+- Keep primary actions reachable without hiding context on small screens.
+- Ensure text can zoom/reflow without loss of function.
+- Test with keyboard only, screen reader basics, touch, narrow viewport, slow network, and high zoom.
+
+## Quality checklist
+
+- The primary user goal is stated.
+- The screen’s purpose is clear at a glance.
+- The primary action is stronger than secondary actions.
+- Labels use user language.
+- Interactive elements are discoverable without hover.
+- Required choices are minimized and grouped.
+- The interface provides status feedback after consequential actions.
+- Errors are prevented where possible and recoverable where not.
+- Destructive actions are reversible or clearly confirmed.
+- Users do not lose work due to validation, auth, network, or navigation issues.
+- Navigation answers “where am I?” and “where can I go?”
+- Accessibility fundamentals are included.
+- Frontend behavior is implementable.
+
+Use the full checklists in [references/checklists.md](references/checklists.md).
+
+## Common mistakes to avoid
+
+- Starting with app chrome before the task.
+- Treating “easy to use” as a checklist item.
+- Hiding primary actions behind menus, gestures, or icons.
+- Using clever labels where obvious labels would work.
+- Making all actions equally important.
+- Asking users questions the system can infer safely.
+- Forcing users to remember hidden instructions or state.
+- Replacing undo with constant confirmations.
+- Blaming the user in error copy.
+- Using disabled controls without explanation.
+- Relying on color alone.
+- Designing custom controls without keyboard and assistive-tech behavior.
+- Treating accessibility as a final audit.
+- Confusing visual simplicity with reduced task complexity.
+
+See [references/anti-patterns.md](references/anti-patterns.md) for the full anti-pattern list.
+- Ignoring empty, loading, offline, validation, permission, and edge states.
+
+## How to explain recommendations to the user
+
+Use this pattern:
+
+```markdown
+I recommend [change] because users are likely trying to [goal]. The current version makes them [think/remember/guess/recover] unnecessarily. This change makes [action/state/recovery] visible and reduces [specific risk or effort]. The main tradeoff is [cost], which is acceptable unless [context that would change the decision].
+```
+
+When disagreeing with a requested pattern:
+
+```markdown
+I would not hide this behind an icon-only menu because it is the primary path for the task. A better default is a visible labeled action. Use the menu only for secondary or infrequent actions.
+```
+

package/skills/ux/upstream/ux-usability-foundations/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hueyexe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.