diff --git a/AGENTS.md b/AGENTS.md index 34eec38..ccdb91a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -128,6 +128,7 @@ When the user mentions these keywords, load the corresponding skill: | "agent eval", "agent evaluation", "LLM eval", "LLM evals", "evaluation dataset", "grader calibration", "model judge", "trajectory review", "agent observability", "agent traces", "agent telemetry", "agent regression", "agent release gate", "privacy-aware telemetry", "prompt evaluation", "model testing" | [agent-evals-and-observability](agent-evals-and-observability/SKILL.md) | | "pydanticai", "pydantic AI", "pydantic graph", "AI agent", "LLM agent", "agent framework", "function tool", "tool-using agent", "agent with tools", "agent with dependencies", "structured output", "streaming agent", "agent graph", "state machine graph", "GraphBuilder", "BaseNode", "multi-agent", "agent delegation", "TestModel", "FunctionModel", "capabilities" | [pydanticai](pydanticai/SKILL.md) | | "product discovery", "stakeholder interview", "requirements discovery", "user research", "customer interview", "requirements gathering", "discovery phase", "stakeholder mapping", "interview guide", "discovery conversation", "transcript to spec", "requirements conflict", "what would have to be true", "pre-mortem", "laddering", "assumption busting" | [product-discovery](product-discovery/SKILL.md) | +| "product UX", "product design", "interaction design", "information architecture", "task flow", "user flow", "state model", "recovery path", "interface contract", "UX handoff", "usability study plan" | [product-design-and-ux](product-design-and-ux/SKILL.md) | | "prioritize", "RICE", "MoSCoW", "opportunity solution tree", "decision log", "write a spec", "product spec", "PRD", "stakeholder communication", "executive brief", "feature prioritization", "backlog ranking", "release scope", "build vs buy", "product decision" | [product-methodology](product-methodology/SKILL.md) | | "workflow", "figure out my workflow", "analyze my process", "what do I actually do", "catalog my workflow", "formalize my process", "workflow architect", "onboard me to my own process" | [workflow-architect](bundles/workflow-architect/SKILL.md) | | "default alive", "default dead", "runway", "burn rate", "burn multiple", "financial projection", "startup finances", "cash on hand", "breakeven", "how long until", "profitability" | [yc-default-alive-calculator](yc-default-alive-calculator/SKILL.md) | diff --git a/README.md b/README.md index d0301ed..fefe8d8 100644 --- a/README.md +++ b/README.md @@ -199,6 +199,10 @@ Comprehensive open source contribution guidance — from reading CONTRIBUTING.md PeerTube federated video platform from the terminal. Browse videos and channels, search across instances, view server info. OAuth2 login with token persistence. Set PEERTUBE_SERVER to point at any instance. +### [product-design-and-ux](product-design-and-ux/SKILL.md) + +Turn validated evidence and approved product scope into traceable user-facing behavior: information architecture, plain-language content, task flows, applicable state and recovery models, interface contracts, authorized usability evidence, and observable engineering handoffs. Portable and framework-neutral; routes WCAG/ARIA depth to web-accessibility and formal software acceptance to spec-driven-development. Ships 10 focused references and 6 fillable templates. + ### [product-discovery](product-discovery/SKILL.md) Discover product requirements from human stakeholders — map who to talk to, ask questions that surface hidden assumptions, detect gaps in real time, resolve conflicts, and translate conversations into structured specs. Phase 0 upstream of any spec-driven pipeline. Ships 8 reference files covering stakeholder mapping, question patterns, gap detection, conflict resolution, transcript-to-spec distillation, AI-conducted discovery, power dynamics, and time-constrained discovery; plus 5 templates (discovery plan, interview guide, distillation worksheet, gap register, interpretation log). diff --git a/product-design-and-ux/README.md b/product-design-and-ux/README.md new file mode 100644 index 0000000..4d1eb78 --- /dev/null +++ b/product-design-and-ux/README.md @@ -0,0 +1,37 @@ +# Product Design and UX - Behavior-Ready Product Handoffs + +Turn approved product scope into user-facing behavior that engineers can implement and people can recover from when things go wrong. + +## Why Install This Skill + +Teams often agree on a feature but leave its navigation, permissions, failure recovery, interrupted work, and completion evidence implicit. That ambiguity becomes late rework, inaccessible paths, or a polished happy path that breaks in normal conditions. + +This skill helps an agent turn validated evidence and a chosen scope into traceable outcomes, task and state models, interaction contracts, usability evidence, and an engineering handoff. It stays portable: no design application, component library, CSS, or proprietary workflow is required. + +## What You Get + +| Path | What it provides | +|---|---| +| `SKILL.md` | Compact workflow, routing, and completion rules. | +| `references/` | Detailed guidance for IA, content and cognitive demand, flows, contracts, patterns, usability, handoff, sources, and scenario probes. | +| `templates/` | Fillable traceability, flow/state, inventory, contract, usability, and handoff artifacts. | + +## Quick Start + +Give your agent validated evidence and an approved scope, then ask for a behavior handoff: + +```text +Define the task flow, recovery states, interface contract, and observable acceptance criteria for the approved invoice-dispute feature. Link each decision to the supplied evidence. +``` + +## Triggers + +- Product design, UX design, interaction design, information architecture, or navigation model. +- Task flows, user flows, state models, recovery paths, or interface behavior. +- Interaction contracts, responsive/reflow behavior, usability-study plans, or UX engineering handoffs. + +## Requirements + +- Validated evidence and an approved product scope; use `product-discovery` or `product-methodology` when these are absent. +- No software dependencies, API keys, design tools, or frontend framework. +- Use `web-accessibility` for WCAG/ARIA conformance and accessibility-testing depth. diff --git a/product-design-and-ux/SKILL.md b/product-design-and-ux/SKILL.md new file mode 100644 index 0000000..75e39ec --- /dev/null +++ b/product-design-and-ux/SKILL.md @@ -0,0 +1,63 @@ +--- +name: product-design-and-ux +description: >- + Define user-facing product behavior from validated evidence and approved scope. + Use for information architecture, task flows, state and recovery models, + interface contracts, usability-study plans, interaction-pattern tradeoffs, or + engineering UX handoffs. Use after product discovery and product decisions; + route WCAG/ARIA conformance work to web-accessibility and formal software + specifications to spec-driven-development. +license: MIT +compatibility: Works with any agent framework supporting the Agent Skills format; no design tool, frontend framework, or proprietary service required. +--- + +# Product Design and UX + +Turn validated evidence and chosen scope into observable behavior people can complete and recover from. Design the interaction, not the brand, pixels, CSS, component implementation, or a particular tool. + +## Entry Check + +Confirm the approved scope, outcome, users or roles, evidence links, constraints, measurable experience goals, and open product decisions. Record missing inputs rather than inventing them. + +- Need stakeholder evidence, validation, or raw research? Use [product-discovery](../product-discovery/SKILL.md). +- Need prioritization, scope, or why a feature is being built? Use [product-methodology](../product-methodology/SKILL.md). +- Need WCAG, ARIA, native semantics, or accessibility testing depth? Use [web-accessibility](../web-accessibility/SKILL.md). +- Need an approved interaction contract translated into a software specification and delivery gates? Use [spec-driven-development](../spec-driven-development/SKILL.md). + +## Workflow + +1. Trace each outcome and design decision to evidence with `templates/outcomes-to-design.md`. Optional personas or jobs must change a decision and cite evidence; do not create decorative demographics. +2. Establish information architecture from goals, content objects, terminology, permissions, findability, and service context. Read `references/information-architecture.md`. +3. Define consequential labels, instructions, status, errors, and completion content; review the task's memory, choice, switching, interruption, and recovery demands. Use heuristics to generate testable questions, not verdicts. Read `references/content-and-cognitive-demand.md`. +4. Model important tasks, including forces that create decisions, alternatives, interruption, re-entry, cancellation, recovery, irreversible actions, side effects, permission changes, and completion evidence. Read `references/task-flows-and-state-models.md` and use `templates/task-flow-state-model.md`. +5. Inventory only states forced by the flow, data, permissions, connectivity, and risk. Record risky omissions. Use `templates/screen-state-inventory.md`. +6. Write framework-neutral contracts for content, controls, accessible interaction requirements, actions, transitions, persistence, permissions, responsive/reflow behavior, telemetry, and open decisions. Read `references/interface-contracts-and-responsive-behavior.md` and use `templates/interface-contract.md`. +7. Treat patterns as hypotheses. Compare alternatives, tradeoffs, evidence, and disconfirming conditions with `references/interaction-pattern-selection.md`. +8. Plan or synthesize only authorized usability work. Read `references/usability-testing-and-privacy.md`; use `templates/usability-study.md`. Never invent participants, consent, observations, quotes, or results. +9. Produce an engineering handoff with observable acceptance evidence, dependencies, owners, gates, and deployed-boundary verification. Read `references/engineering-handoff.md`; use `templates/engineering-handoff.md`. Hand approved behavior to [spec-driven-development](../spec-driven-development/SKILL.md). + +## Load On Demand + +| Need | Load | +|---|---| +| Scope boundary, traceability, or adjacent-skill routing | `references/boundaries-and-traceability.md` | +| Goals, labels, navigation, findability, permissions | `references/information-architecture.md` | +| Plain-language content, heuristic review, cognitive demand | `references/content-and-cognitive-demand.md` | +| Task paths, state applicability, recovery, side effects | `references/task-flows-and-state-models.md` | +| Interaction contract or inclusive responsive behavior | `references/interface-contracts-and-responsive-behavior.md` | +| Pattern alternatives and decision evidence | `references/interaction-pattern-selection.md` | +| Usability protocol, synthesis, consent, or privacy | `references/usability-testing-and-privacy.md` | +| Handoff, acceptance criteria, or deployed verification | `references/engineering-handoff.md` | +| Methodology self-check with synthetic fixtures | `references/scenario-probes.md` | +| Source authority, status, and examples | `references/source-index.md` | + +## Guardrails + +- Accessibility is designed throughout, but WCAG/ARIA/native-semantics and testing depth remain with `web-accessibility`. +- Specify behavior under relevant width, zoom/reflow, text expansion/localization, orientation, input modes, reduced motion, degraded connectivity, interruption, and re-entry. Do not use device breakpoints as the model. +- Use synthetic fixtures such as `sample-user@example.test` and `INV-DEMO-042`; never request real credentials, payments, financial access, or secrets for an unsafe prototype. +- A finding from usability work is bounded evidence, not accessibility conformance, population prevalence, analytics, or outcome proof. + +## Completion + +Stop when every in-scope behavior has traceable evidence, an applicable state/recovery model, observable acceptance criteria, and either a resolved decision or an owner and resolution gate. Report limitations and untested risks rather than filling gaps with assumptions. diff --git a/product-design-and-ux/references/boundaries-and-traceability.md b/product-design-and-ux/references/boundaries-and-traceability.md new file mode 100644 index 0000000..3bf2e99 --- /dev/null +++ b/product-design-and-ux/references/boundaries-and-traceability.md @@ -0,0 +1,23 @@ +# Boundaries and Traceability + +## Pipeline Boundary + +| Concern | Owner | This skill receives or produces | +|---|---|---| +| Obtain and validate human evidence | `product-discovery` | Validated needs, evidence links, limitations, unresolved assumptions. | +| Decide scope, priority, and rationale | `product-methodology` | Chosen outcome, scope boundary, decisions, and success measures. | +| Define user-facing behavior | This skill | IA, task/state models, interface contracts, usability evidence, and handoff. | +| Accessibility conformance depth | `web-accessibility` | Routed requirements and its implementation/testing evidence. | +| Formal software specification and gates | `spec-driven-development` | Approved interaction contracts and observable acceptance criteria. | + +Do not replace discovery with invented research, reopen an approved scope through prioritization, issue a WCAG conformance claim, or prescribe visual implementation. + +## Traceability Method + +Assign stable identifiers to evidence (`E-01`), outcomes (`O-01`), decisions (`D-01`), tasks (`T-01`), contracts (`IC-01`), and acceptance criteria (`AC-01`). For each decision, record the source, confidence or limitation, affected role, and what would change it. A claim without evidence is an assumption; name its owner and resolution gate. + +Read `templates/outcomes-to-design.md` when creating the trace. The trace is complete when a reviewer can move both directions: outcome to interface behavior, and interface behavior to evidence or an explicit open decision. + +## Accessibility Routing + +Carry requirements such as keyboard reachability, focus outcome, accessible name/role/state expectations, text alternatives, reflow, and error recovery into contracts. For exact criterion applicability, semantics selection, ARIA, browser/AT evidence, or conformance claims, link the work to [web-accessibility](../../web-accessibility/SKILL.md) rather than summarizing standards here. diff --git a/product-design-and-ux/references/content-and-cognitive-demand.md b/product-design-and-ux/references/content-and-cognitive-demand.md new file mode 100644 index 0000000..50398d9 --- /dev/null +++ b/product-design-and-ux/references/content-and-cognitive-demand.md @@ -0,0 +1,54 @@ +# Content, Heuristic Review, and Cognitive Demand + +Content is part of behavior. Labels, instructions, status, errors, and confirmation evidence determine what a person understands and can recover from; they are not decoration added after the interaction model. + +## Content Contract + +For consequential content, record: + +- audience, task, decision, and moment of use; +- source and accountable owner; +- terminology and evidence for the chosen label; +- required facts, uncertainty, consequence, and next action; +- state variants such as loading, empty, pending, stale, denied, partial, failed, and complete; +- localization, text expansion, formatting, and fallback behavior; +- review and freshness requirements. + +Use the person's domain language unless technical or legal precision requires another term; explain unavoidable specialized language at the point of use. Prefer a concrete action or outcome over a vague label. Error content should say what happened, what was preserved, what the person can do, and where to get help when self-recovery is unavailable. Do not blame the person or claim success before the side effect is known. + +Plain language is contextual, not a sentence-length formula. Preserve necessary nuance, risk, and legal meaning. Test whether intended people can find, understand, and act on the content rather than relying on a readability score alone. + +## Cognitive Demand Review + +Inspect the task for demands created by the design: + +| Demand | Questions and possible responses | +|---|---| +| Recall | Must people remember an identifier, rule, prior value, or hidden choice? Keep context visible or make recognition possible. | +| Choice and comparison | Are options distinguishable by consequences that matter? Group or stage only when it preserves overview and comparison. | +| Context switching | Does the task require moving between surfaces, channels, or documents? Preserve state, references, and return paths. | +| Interruption | Can a person tell what is saved, pending, expired, or changed when they return? | +| Error interpretation | Does feedback identify the affected field/action, retained input, consequence, and recovery? | +| Time or attention pressure | Are irreversible actions, expiring state, or background work communicated without forcing premature decisions? | +| Unfamiliar sequence | Is guidance available at the decision point, and can experienced people bypass it safely? | + +Reduce unnecessary demand without hiding decisions, removing control, or oversimplifying risk. Defaults can reduce effort but must be safe, visible, reversible where possible, and appropriate to the role. Progressive disclosure can reduce scanning but becomes harmful when it hides consequence, status, or recovery. + +Do not use a magic limit for steps, options, or memory. The stopping criterion is whether the task's demands are supported in the actual context and whether evidence exposes avoidable confusion or recovery failure. + +## Heuristic Review as a Hypothesis Generator + +Use these prompts to find questions, not to issue a usability verdict: + +- Is system status timely and truthful, including pending and partial work? +- Does language match the domain and distinguish neighboring concepts? +- Can people cancel, undo, recover, or understand why they cannot? +- Are similar actions consistent without forcing unlike tasks into one pattern? +- Does the design prevent consequential mistakes at the right boundary? +- Is necessary context visible rather than dependent on memory? +- Can frequent and infrequent users complete the task without blocking each other? +- Is every piece of content relevant to the current decision or recovery? +- Do errors preserve work and provide a specific correction or support path? +- Is help available where the domain cannot make the task self-explanatory? + +For every finding, identify the task, state, evidence, risk, affected role, and contract change. A heuristic match without task evidence is a review lead, not proof. Validate consequential findings through the appropriate evidence path: source review, domain/policy review, accessibility evaluation, authorized usability work, or deployed-boundary observation. diff --git a/product-design-and-ux/references/engineering-handoff.md b/product-design-and-ux/references/engineering-handoff.md new file mode 100644 index 0000000..71fcffa --- /dev/null +++ b/product-design-and-ux/references/engineering-handoff.md @@ -0,0 +1,65 @@ +# Engineering Handoff + +Handoff is a traceable behavior package, not a mockup link or presentation. It should let implementation and verification reconstruct what the user can observe, where the evidence came from, which decisions remain open, and how to prove the delivered boundary matches the approved contract. + +## Required Package + +Include: + +- approved outcome and scope, affected users/roles, and evidence trace; +- information architecture and terminology decisions; +- task flows, state/transition inventory, recovery, permission, and side-effect models; +- interface contracts and content requirements; +- accessibility requirements routed to `web-accessibility`, with the expected evidence boundary; +- usability evidence, negative cases, fidelity limits, and untested paths; +- data/content/service dependencies, ownership, freshness, fallback, and failure behavior; +- telemetry purpose and minimum event contract where evidence requires it; +- implementation risks, unresolved decisions, owners, and gates; +- observable acceptance criteria and deployed-boundary verification plan. + +Do not attach a pile of artifacts without a navigation surface. `templates/engineering-handoff.md` is the index and gate record; link every supporting artifact from it. + +## Observable Acceptance Criteria + +Write criteria at the user-facing or deployed boundary. A useful criterion identifies: + +1. entry condition, role, permission, and relevant data state; +2. action or external event; +3. visible behavior and state transition; +4. persistence or side effect, including partial/failure behavior; +5. recovery, interruption/re-entry, and completion evidence where applicable; +6. accessibility expectation and routed test evidence; +7. exact environment, fixture, observation, and result record. + +Avoid “works well,” “is intuitive,” “is responsive,” or “is accessible.” Replace them with observable behavior. Do not force a binary criterion when the open decision genuinely needs research; record the decision and gate instead. + +## Dependency Contract + +For each content, data, service, policy, permission, or platform dependency, record: + +| Field | Question | +|---|---| +| Provider/owner | Who can answer and change it? | +| Contract/source | What schema, content source, policy, or platform behavior is expected? | +| Freshness and availability | When can it be stale, delayed, missing, or revoked? | +| Failure/fallback | What does the person see and retain when it fails? | +| Privacy/security boundary | What data or authority crosses the boundary? | +| Verification | How will implementation and deployed behavior be checked? | + +A dependency without an owner or fallback is an unresolved design risk, not an engineering detail. + +## Handoff Review + +Run a walkthrough using at least one normal path and the highest-risk permission, interruption, partial-commit, stale/conflict, or failure path. Trace each behavior backward to evidence or an explicit assumption and forward to an acceptance criterion. Confirm no mockup-only state, inaccessible interaction, placeholder content, or simulated side effect is represented as complete. + +Classify findings: + +- **Blocking:** implementation would invent consequential behavior, expose unsafe data/action, omit required recovery, or lack a testable contract. +- **Conditional:** an owner and resolution gate exist and implementation can proceed without guessing past that gate. +- **Nonblocking:** clarification improves maintainability without changing behavior or risk. + +## Deployed-Boundary Verification + +Component or prototype success does not prove integration behavior. Name the actual delivery boundary, supported environment, fixture, steps, expected observation, evidence capture, and cleanup. Include permissions, persistence, external effects, responsive behavior, and accessibility environment where relevant. Record failed, blocked, and not-applicable results instead of converting absent evidence into a pass. + +After approval, pass the interaction contracts and criteria to [spec-driven-development](../../spec-driven-development/SKILL.md) for formal software specification and delivery gates. Keep UX evidence linked rather than flattening it into implementation prose. diff --git a/product-design-and-ux/references/information-architecture.md b/product-design-and-ux/references/information-architecture.md new file mode 100644 index 0000000..e7e3629 --- /dev/null +++ b/product-design-and-ux/references/information-architecture.md @@ -0,0 +1,43 @@ +# Information Architecture + +Information architecture (IA) makes objects, actions, relationships, and routes findable and understandable. Start with what people need to accomplish and locate, not with a preferred navigation control or the current database schema. + +## Inventory Before Structure + +Record: + +- user goals and entry contexts; +- content or domain objects, their relationships, ownership, and lifecycle; +- language people use and conflicting internal terminology; +- roles, permissions, visibility boundaries, and cross-account or cross-tenant context; +- likely entry points from links, search, notifications, history, and other channels; +- frequency, urgency, risk, comparison needs, and interruption/re-entry; +- content volume, growth, freshness, archival, and deletion behavior. + +Do not expose implementation nouns merely because they already exist. Do not flatten distinct user concepts because they share a table. Preserve a vocabulary conflict as an open decision until evidence resolves it. + +## Derive and Test the Model + +For each important object or action, answer: + +| Question | Evidence to retain | +|---|---| +| Where can a person enter directly? | Entry-point inventory and required context | +| Where would they look first? | Research, domain language, support/search evidence, or explicit assumption | +| What label distinguishes it from neighbors? | Terminology evidence and rejected labels | +| What role or ownership changes visibility or action? | Permission matrix and empty/denied behavior | +| How do they move between overview, object, action, and history? | Navigation/search model and return path | +| How do they resume after interruption? | Stable identifier, preserved filters/context, and re-entry route | +| What happens when the object is missing, stale, archived, or moved? | Recovery, redirect, explanation, and support path | + +Validate labels, grouping, hierarchy, navigation, and search assumptions with the smallest evidence capable of disproving them. Depending on uncertainty, that may be source review, content inventory, tree/path exercise, search-log analysis, or authorized task-based observation. Name the method and limitation; do not call an untested sitemap intuitive. + +## Navigation and Disclosure Decisions + +Choose navigation only after the object and task model is visible. Compare depth, breadth, orientation, backtracking, scanning, cross-linking, search dependence, permission-induced gaps, and context preservation. A sitemap, route map, or search schema documents the result; none substitutes for reasoning. + +Progressive disclosure is a hypothesis. Reveal detail when it supports the next decision, but never hide information needed to assess consequence, cost, privacy, authorization, or irreversibility. Record what is hidden, the reveal trigger, how the trigger is discoverable, whether state persists, and how keyboard, touch, and assistive input reach it. + +## Output Gate + +Use `templates/outcomes-to-design.md` to connect goals and evidence to findability decisions, then carry entry points, labels, object context, and permissions into `templates/interface-contract.md`. IA is ready for flow design when every in-scope task has a plausible entry and return path, permission-driven absences are explained, and unresolved terminology has an owner and resolution gate. diff --git a/product-design-and-ux/references/interaction-pattern-selection.md b/product-design-and-ux/references/interaction-pattern-selection.md new file mode 100644 index 0000000..8a501a1 --- /dev/null +++ b/product-design-and-ux/references/interaction-pattern-selection.md @@ -0,0 +1,43 @@ +# Interaction Pattern Selection + +Patterns are reusable hypotheses, not prescriptions. A familiar component can still be wrong for the task, risk, frequency, data shape, permission model, platform, or recovery requirement. + +## Decision Record + +For every consequential pattern, record: + +1. the user goal and context; +2. forces: frequency, urgency, reversibility, data volume, uncertainty, comparison, permissions, connectivity, interruption, and accessibility; +3. plausible alternatives, including a simpler native interaction; +4. tradeoffs and failure modes of each alternative; +5. supporting and disconfirming evidence; +6. the selected approach, owner, assumptions, and revisit trigger. + +Do not present a design-system example as proof. If no evidence distinguishes alternatives, name the choice as provisional and define the observation that would change it. + +## Common Pattern Forces + +| Pattern family | Questions that determine fit | +|---|---| +| Forms and validation | When can validity be known? Is input preserved? Can errors be associated, summarized, and corrected without losing context? | +| Search and filtering | Is the person locating, exploring, comparing, or narrowing? How are active filters, zero results, stale results, saved views, and re-entry handled? | +| Dense tables and dashboards | Which comparisons and actions matter? What does sorting, truncation, horizontal movement, personalization, or narrow width do to meaning? | +| Onboarding and guidance | Is instruction needed before action, at the decision point, or only after failure? Can experienced users bypass it? | +| Disclosures and progressive detail | Is hidden information nonessential to the current decision? Is the reveal discoverable, reachable, stateful, and safe? | +| Destructive or consequential actions | Is the effect reversible, delayed, repeated, or rare? Would confirmation, typed intent, preview, undo, delayed commit, or approval reduce the actual risk? | +| Autosave and optimistic update | What is the commit boundary? How are pending, failed, conflicting, offline, and restored states communicated? | +| Pagination, load-more, and streaming | Is the task exploration, exhaustive review, comparison, return-to-position, or audit? How are total, order, updates, failure, and re-entry represented? | + +## Tradeoff Examples + +- Confirmation can reduce accidental irreversible action, but repeated confirmations can become automatic dismissal. Prefer a risk-matched barrier and preserve a recovery path where the domain permits it. +- Undo can improve recovery, but only when retention, authorization, synchronization, and user-visible time boundaries make restoration real. +- Infinite scroll can support exploration, but it can weaken location, comparison, footer access, completion sense, and re-entry. Pagination or load-more may fit bounded review better. +- Optimistic updates can improve perceived responsiveness, but they require truthful pending/failure/conflict behavior and must not imply a side effect committed when it did not. +- Wizards can sequence complex dependencies, but may hide overview, make branching awkward, and complicate interruption. A reviewable single flow or staged checklist may be better. + +## Evidence and Revisit Gate + +Use authorized task evidence, support/search data, domain constraints, accessibility evidence, production failures, and implementation feasibility. Do not count preference alone as task success. Define a revisit condition such as a recurring recovery failure, unexpected permission path, inability to resume, or observed comparison burden. + +GOV.UK and USWDS are useful rolling government examples, not universal standards. Link to their live guidance through `source-index.md`; do not copy a component or infer that government context matches the product. diff --git a/product-design-and-ux/references/interface-contracts-and-responsive-behavior.md b/product-design-and-ux/references/interface-contracts-and-responsive-behavior.md new file mode 100644 index 0000000..4a3b80c --- /dev/null +++ b/product-design-and-ux/references/interface-contracts-and-responsive-behavior.md @@ -0,0 +1,45 @@ +# Interface Contracts and Inclusive Responsive Behavior + +An interface contract describes observable behavior, not visual styling, component names, or framework APIs. It lets design, content, accessibility, engineering, testing, operations, and product review the same boundary without assuming the mockup contains all behavior. + +## Contract Fields + +For each surface or meaningful state, specify: + +- linked outcome, task, evidence, role, and entry conditions; +- content, source, freshness, formatting responsibility, and fallback; +- controls and their purpose, visible label, accessible name/role/state expectation, and enabled/disabled/hidden rules; +- allowed actions, validation timing, error placement, correction path, and preservation of input; +- transition trigger, destination, focus or orientation outcome, persistence, and re-entry; +- permission checks at view and action boundaries, including changed or expired authority; +- side effects, commit boundary, retry/deduplication behavior, cancellation, undo, and completion evidence; +- telemetry purpose and minimum event fields, without default content capture; +- assumptions, unresolved decisions, owners, and resolution gates. + +The contract should describe what a person can observe and do. Leave layout coordinates, CSS, component props, and internal service calls to implementation artifacts unless they are externally constrained. + +## Responsive Behavior as Constraints + +Do not reduce responsiveness to named device breakpoints. For each relevant constraint, record what remains available, what changes, and how context survives: + +| Constraint | Contract questions | +|---|---| +| Available width and zoom/reflow | What can wrap, stack, scroll, collapse, or remain pinned without losing order, labels, comparison, or actions? | +| Text expansion and localization | Which containers grow, which labels cannot truncate, and what happens to tables, controls, errors, and status? | +| Orientation and viewport change | Is work preserved? Does focus or reading position remain logical? | +| Keyboard, pointer, touch, switch, and voice input | Is every action reachable with appropriate target, order, naming, and non-drag alternative? | +| Reduced motion or animation failure | Is meaning preserved without motion, and can movement be suppressed where required? | +| Degraded connectivity and delayed work | What becomes unavailable, queued, stale, partial, retryable, or cancellable? | +| Interruption and re-entry | What draft, filters, step, ownership, permission, and conflict information is restored or revalidated? | + +Only include constraints relevant to the supported product context, but record why a high-risk constraint was ruled out. Fixed pixel values may be implementation evidence, not the reasoning model. + +## Accessibility Boundary + +Carry keyboard reachability, focus outcome, accessible name/role/state expectations, text alternatives, error recovery, reflow, motion, and input alternatives into the interaction contract. Route exact success-criterion applicability, native semantics, ARIA selection, browser/assistive-technology matrices, and conformance evidence to [web-accessibility](../../web-accessibility/SKILL.md). + +An accessibility field is useful only when it is observable. Replace “accessible control” with the intended name, role, state/value, keyboard behavior, focus outcome, error behavior, and evidence path. + +## Contract Review + +Review one contract against its task/state model and data/permission boundary. Reject it when a transition has no recovery, a mutation lacks completion evidence, a role can see but not understand an unavailable action, content ownership is missing, telemetry has no purpose/minimization rule, or responsive behavior is deferred to “the frontend.” Use `templates/interface-contract.md` to capture the result. diff --git a/product-design-and-ux/references/scenario-probes.md b/product-design-and-ux/references/scenario-probes.md new file mode 100644 index 0000000..b9930c4 --- /dev/null +++ b/product-design-and-ux/references/scenario-probes.md @@ -0,0 +1,25 @@ +# Synthetic Scenario Probes + +Use these probes to review a proposed design artifact. They use synthetic fixtures only and grade force coverage, traceability, privacy, accessibility routing, recovery, and observable evidence, not numbers of screens, states, or participants. + +## Transactional Partial Commit + +`Northstar Travel` reserves `DEMO-ITINERARY-42`. A submit may reserve an itinerary before payment confirmation times out. A later retry can duplicate a reservation. Cancellation becomes irreversible after a stated fulfillment boundary. + +Expect entry conditions, validation preservation, pending/partial-commit visibility, retry and deduplication behavior, interruption/re-entry, cancellation, irreversible warning, recovery/support route, completion receipt, and no real payment fixture. + +## Permissions-Heavy Workspace + +`Atlas Review` has synthetic items owned by teams. Reviewers can annotate, owners can submit, administrators can archive, and auditors can only view history. Ownership can change while a reviewer has an item open; filters can return stale results and simultaneous edits can conflict. + +Expect IA grounded in roles/findability, view versus action permissions, ownership change behavior, stale/conflict recovery, dense-data filtering tradeoffs, audit and recovery path, and completion evidence. + +## Interrupted Responsive Flow + +`Civic Permit Demo` saves a draft request. Content may be narrow or reflowed at zoom, localized text can expand, orientation can change, a keyboard/touch/assistive input method can be used, and connectivity can degrade before final submission. + +Expect preserved context, save/re-entry, applicable offline/degraded behavior, text/reflow and input-mode contract, reduced-motion consideration, validation/recovery, and routing of detailed accessibility verification to `web-accessibility`. + +## Review Questions + +For each probe, ask: Which evidence supports the behavior? Which forces were considered or ruled out? What recovery is available? Which accessibility questions were routed? What data is synthetic? Which criterion can be observed after deployment? diff --git a/product-design-and-ux/references/source-index.md b/product-design-and-ux/references/source-index.md new file mode 100644 index 0000000..225f044 --- /dev/null +++ b/product-design-and-ux/references/source-index.md @@ -0,0 +1,22 @@ +# Source and Status Index + +Use sources for their demonstrated scope. This skill synthesizes portable decision methods; it does not reproduce vendor component specifications or turn examples into universal requirements. Status and URLs were checked 2026-07-13. + +| Source | Status | Use in this skill | Do not infer | +|---|---|---|---| +| [ISO 9241-210:2019](https://www.iso.org/standard/77520.html) | International Standard for human-centred design for interactive systems, second edition published 2019 and confirmed 2025 | Lifecycle framing: understand context, specify user requirements, produce design solutions, and evaluate them iteratively | A detailed interface-pattern catalog, fixed research protocol, or certification verdict | +| [WCAG 2.2](https://www.w3.org/TR/WCAG22/) | W3C Recommendation; current published page dated 2024-12-12 | Establish that accessibility criteria require a separate, scoped contract and evidence path | That a usability session, design review, or automated scan establishes conformance | +| [W3C Making Content Usable for People with Cognitive and Learning Disabilities](https://www.w3.org/TR/coga-usable/) | W3C Working Group Note whose status section describes the material as work in progress | Supplemental inclusive-content and interaction considerations for cognitive and learning disabilities | WCAG success criteria, legal requirements, or universally applicable prescriptions | +| [GOV.UK Government Design Principles](https://www.gov.uk/guidance/government-design-principles) | Rolling United Kingdom government guidance | Examples of user-need, whole-service, evidence, accessibility, and iteration framing | A universal product lifecycle or proof a pattern fits another domain | +| [GOV.UK moderated usability testing](https://www.gov.uk/service-manual/user-research/using-moderated-usability-testing) | Rolling United Kingdom government service guidance | Example considerations for task-based, moderated observation and session conduct | A mandatory method, participant count, or success threshold | +| [GOV.UK research consent](https://www.gov.uk/service-manual/user-research/getting-users-consent-for-research) | Rolling United Kingdom government service guidance | Example consent transparency, recording, withdrawal, and data-use considerations | Legal advice or a consent form valid in every organization or jurisdiction | +| [USWDS Design Principles](https://designsystem.digital.gov/design-principles/) | Rolling United States government design-system guidance | Examples of accessibility, continuity, trust, evidence, and device/context considerations | A mandatory component library, breakpoint model, or universal government policy | +| [Web Accessibility skill source index](../../web-accessibility/references/source-index.md) | Maintained local catalog source index | WCAG, ARIA, HTML, accessible-name, pattern, and accessibility-evidence authority | That this UX skill owns conformance interpretation | + +## Source Discipline + +1. Record the exact source, version or page status, retrieval date, and the decision it informed. +2. Separate normative requirements, informative guidance, examples, and this skill's synthesis. +3. Verify live status before making a current-standard claim. A rolling page can change without a versioned release. +4. If a source conflicts with user evidence, policy, legal advice, platform behavior, or the supported accessibility environment, preserve the conflict and route it to the accountable owner; do not silently choose the prettier rule. +5. Do not cite a source merely because its vocabulary resembles the decision. Show the link from source scope to the artifact field or acceptance criterion it supports. diff --git a/product-design-and-ux/references/task-flows-and-state-models.md b/product-design-and-ux/references/task-flows-and-state-models.md new file mode 100644 index 0000000..0cb86cf --- /dev/null +++ b/product-design-and-ux/references/task-flows-and-state-models.md @@ -0,0 +1,19 @@ +# Task Flows and State Models + +Model one meaningful outcome at a time. A flow starts with entry conditions and ends with observable completion evidence, not merely a button press. Include decisions, alternative and exception paths, cancellation, interruption and re-entry, recovery, irreversible actions, side effects, permissions, ownership changes, and stale or conflicting data where the system can create them. + +## Force-Driven State Applicability + +Do not require a fixed inventory. Consider a state only when a force makes it relevant: + +| Force | States or questions to consider | +|---|---| +| First use, no records, or no results | Initial or empty; what explains the absence and next action? | +| Fetching, background work, or delayed commit | Loading, partial, pending, cancellation, and status visibility. | +| User input or business rules | Validation timing, preservation of input, correction path. | +| Role, ownership, or authorization changes | Permission denied, reduced capability, request/escalation, audit path. | +| Network, sync, or cache | Offline/degraded, stale, conflict, retry, deduplication, re-entry. | +| Mutation or destructive effect | Confirmation, undo, delayed commit, partial commit, irreversible warning, completion proof. | +| System failure | Recoverable or unrecoverable failure, support route, retained context. | + +Record why a likely state is not applicable when its omission would create risk. Use `templates/task-flow-state-model.md` for transitions and `templates/screen-state-inventory.md` for the resulting inventory. Diagrams are optional; readable tables are sufficient. diff --git a/product-design-and-ux/references/usability-testing-and-privacy.md b/product-design-and-ux/references/usability-testing-and-privacy.md new file mode 100644 index 0000000..a5b12a3 --- /dev/null +++ b/product-design-and-ux/references/usability-testing-and-privacy.md @@ -0,0 +1,61 @@ +# Usability Testing and Privacy + +Usability work answers a bounded design question by observing authorized people attempt representative tasks. It does not manufacture customer truth, establish population prevalence, prove business outcomes, or replace accessibility conformance evaluation. + +## Authorization Gate + +Before recruiting, recording, or collecting any participant data, identify the responsible owner and confirm: + +- the decision the work may inform and who has authority to act on it; +- participant characteristics grounded in actual users or affected roles; +- recruitment and compensation rules, including conflicts or power dynamics; +- accommodations and accessible participation paths; +- informed-consent information, voluntary participation, withdrawal, recording/transcription, and data use; +- collection minimization, access, storage, retention, deletion, and incident handling appropriate to policy and jurisdiction; +- whether legal, ethics, privacy, security, or institutional review is required. + +An agent can draft materials and synthesize supplied authorized evidence. It cannot consent for a participant, invent a participant, impersonate research, or decide that policy and law do not apply. + +## Plan From the Decision + +Define: + +1. research or design question; +2. behavior or decision the evidence could change; +3. participant characteristics and excluded populations, with rationale; +4. method and session context; +5. task starting state, realistic goal, completion evidence, and safety boundary; +6. prototype fidelity, unavailable behavior, and synthetic or approved data environment; +7. observation and note-taking method; +8. analysis plan and disagreement handling; +9. limitations and claims the study cannot support. + +Choose participation scope based on decision risk, task and participant variation, accessibility needs, uncertainty, and the cost of missed failure. Do not use a universal participant count, time target, success threshold, or severity scale. + +## Task and Facilitation Design + +Write tasks as goals with enough context to act, not step-by-step instructions that reveal the interface. Avoid leading language and product terminology that the design is supposed to test. Include realistic interruption, permission, failure, or recovery only when the research question requires it and the environment can do so safely. + +During moderated work, use neutral follow-ups about expectations, observations, and decisions. Distinguish what the participant did, what they said, what the facilitator inferred, and what the team decided. A preference statement is not automatically a task barrier; a completed task is not automatically free of confusion or risk. + +## Safe Prototypes and Data + +Use clearly synthetic fixtures such as `DEMO-CARD-NOT-VALID`, `workspace-demo-7`, or reserved `.example`/`.test` identifiers. Do not ask participants to enter real credentials, payment data, financial access, secrets, health data, or personal data into an unsafe prototype. When realistic data is necessary, use an approved environment and document safeguards, fidelity, retention, and deletion. + +Do not claim a prototype performed a side effect it cannot perform. Mark simulated notifications, persistence, payments, approvals, or external-system changes as simulation and account for the fidelity gap in findings. + +## Analysis and Reporting + +Retain an audit trail from observation to implication: + +| Layer | Example form | +|---|---| +| Observation | What occurred in the task and context | +| Participant interpretation | Quote or paraphrase only when actually recorded and authorized | +| Researcher inference | Why the behavior may have occurred, with alternatives | +| Design implication | Contract or hypothesis that might change | +| Decision | Accepted, rejected, deferred, or needs more evidence, with owner | + +Group findings by task force, failure/recovery pattern, role, and context rather than only by screen. Preserve disagreement and negative cases. State whose behavior was not studied, which paths were simulated, where facilitator intervention changed the task, and what evidence would be needed to generalize. + +A usability session reports observed barriers and successes within its tasks, participants, and environment. It does not establish WCAG conformance, accessibility across disability contexts, population prevalence, analytics performance, preference at scale, or product outcome. Use `templates/usability-study.md` for the plan and results, and route accessibility test design to [web-accessibility](../../web-accessibility/SKILL.md). diff --git a/product-design-and-ux/templates/engineering-handoff.md b/product-design-and-ux/templates/engineering-handoff.md new file mode 100644 index 0000000..b1da923 --- /dev/null +++ b/product-design-and-ux/templates/engineering-handoff.md @@ -0,0 +1,29 @@ +# Engineering Handoff + +## Scope and Evidence + +- Approved outcome/scope: +- Traceability artifact: +- IA, task/state, and interface contract links: +- Usability evidence and limitations: +- Accessibility work routed to `web-accessibility`: + +## Dependencies and Risks + +| Dependency or risk | Provider/owner | Contract or content needed | Fallback/recovery | Verification path | +|---|---|---|---|---| +| | | | | | + +## Observable Acceptance Criteria + +| ID | Given/entry condition | When/action | Then observable result | Evidence at deployed boundary | +|---|---|---|---|---| +| AC-01 | | | | | + +Include relevant permissions, accessible name/role/state expectations, persistence, state transitions, failure/recovery, interruption/re-entry, reflow, side effects, and completion evidence. + +## Unresolved Decisions + +| Decision | Owner | Impact if unresolved | Resolution gate | +|---|---|---|---| +| | | | | diff --git a/product-design-and-ux/templates/interface-contract.md b/product-design-and-ux/templates/interface-contract.md new file mode 100644 index 0000000..8bb0571 --- /dev/null +++ b/product-design-and-ux/templates/interface-contract.md @@ -0,0 +1,21 @@ +# Interface Contract + +## Identity + +- Contract ID, surface, and linked outcome/task: +- Entry conditions and permitted roles: +- Evidence and assumptions: + +## Behavior + +| Element/content | Control and accessible name/role/state expectation | Action and validation timing | Transition/persistence/side effect | Permission and recovery | Responsive/inclusive behavior | Telemetry purpose | +|---|---|---|---|---|---|---| +| | | | | | | | + +## Open Decisions + +| Decision | Options/tradeoff | Owner | Impact | Resolution gate | +|---|---|---|---|---| +| | | | | | + +Route semantic, ARIA, WCAG, and test details to `web-accessibility`; do not substitute this table for accessibility conformance evidence. diff --git a/product-design-and-ux/templates/outcomes-to-design.md b/product-design-and-ux/templates/outcomes-to-design.md new file mode 100644 index 0000000..a2afbda --- /dev/null +++ b/product-design-and-ux/templates/outcomes-to-design.md @@ -0,0 +1,19 @@ +# Outcomes-to-Design Traceability + +## Inputs + +| ID | Validated evidence link | Source/limitation | Chosen outcome and scope | Role or context | +|---|---|---|---|---| +| E-01 | | | O-01: | | + +## Design Trace + +| Outcome | IA/findability decision | Task/contract IDs | Pattern hypothesis and evidence | Accessibility routing | Open decision, owner, gate | +|---|---|---|---|---|---| +| O-01 | | | | | | + +## Review + +- Can every behavior trace to validated evidence or an explicit assumption? +- Can every outcome trace to observable completion evidence? +- Does any optional persona or job change a decision and cite evidence? diff --git a/product-design-and-ux/templates/screen-state-inventory.md b/product-design-and-ux/templates/screen-state-inventory.md new file mode 100644 index 0000000..0ae9cce --- /dev/null +++ b/product-design-and-ux/templates/screen-state-inventory.md @@ -0,0 +1,11 @@ +# Screen and State Inventory + +| Surface/state ID | Goal and entry point | Content/permission dependency | Applicable force and state | Recovery or next action | Responsive/inclusive constraint | Contract/AC link | +|---|---|---|---|---|---|---| +| SS-01 | | | | | | | + +## Omission Review + +| Potential state omitted | Why not applicable | Risk if wrong | Owner/review gate | +|---|---|---|---| +| | | | | diff --git a/product-design-and-ux/templates/task-flow-state-model.md b/product-design-and-ux/templates/task-flow-state-model.md new file mode 100644 index 0000000..dac7516 --- /dev/null +++ b/product-design-and-ux/templates/task-flow-state-model.md @@ -0,0 +1,27 @@ +# Task Flow and State Model + +## Task + +- ID and outcome: +- Role, permission, and entry conditions: +- Evidence/contract links: +- Completion evidence: + +## Flow + +| Step | Actor/system action | Decision or alternative | Side effect/persistence | Recovery, cancellation, or re-entry | +|---|---|---|---|---| +| 1 | | | | | + +## State and Transition Model + +| State | Force making it applicable | Entry trigger | User-visible behavior | Allowed actions | Exit/recovery | Evidence | +|---|---|---|---|---|---|---| +| | | | | | | | + +## Risk Review + +- Irreversible action and warning/alternative: +- Partial commit, retry, and deduplication behavior: +- Permission/ownership/stale/conflict behavior: +- States considered not applicable and why: diff --git a/product-design-and-ux/templates/usability-study.md b/product-design-and-ux/templates/usability-study.md new file mode 100644 index 0000000..9099bac --- /dev/null +++ b/product-design-and-ux/templates/usability-study.md @@ -0,0 +1,25 @@ +# Usability Study Plan and Results + +## Authorization and Plan + +- Responsible owner and authorization: +- Decision/research question: +- Participant characteristics grounded in actual users: +- Method, prototype fidelity, and synthetic or approved data environment: +- Accommodations and accessibility considerations: +- Consent, recording/transcription, access, retention, withdrawal, and deletion handling: +- Limitations and what this study cannot establish: + +## Task Scripts + +| Task | Starting context | Completion evidence | Safety/privacy constraint | +|---|---|---|---| +| | | | Use no real credentials, payments, financial access, secrets, or personal data. | + +## Authorized Observations and Synthesis + +| Observation ID | Authorized evidence link | Task/context | Observed barrier or success | Design implication | Confidence/limitation | Owner and next action | +|---|---|---|---|---|---|---| +| | | | | | | | + +Leave results empty until authorized observations exist. Do not fabricate participants, quotes, consent, or findings. diff --git a/product-discovery/SKILL.md b/product-discovery/SKILL.md index 9871e88..b053c88 100644 --- a/product-discovery/SKILL.md +++ b/product-discovery/SKILL.md @@ -48,7 +48,7 @@ Load the reference for the phase you're entering. | Limited time with a stakeholder | Load `references/time-constrained-discovery.md` — maximize signal in minimal time | | An AI agent conducting interviews | Load `references/ai-conducted-discovery.md` — account for sycophancy and trust dynamics | -**Done with discovery?** Jump to the [Is Discovery Complete?](#quick-reference-is-discovery-complete) checklist at the bottom. +**Done with discovery?** Use [product-methodology](../product-methodology/SKILL.md) to choose scope, then [product-design-and-ux](../product-design-and-ux/SKILL.md) to define user-facing behavior. Jump to the [Is Discovery Complete?](#quick-reference-is-discovery-complete) checklist at the bottom. ## Trigger Conditions diff --git a/product-methodology/SKILL.md b/product-methodology/SKILL.md index c60f764..b7fcb56 100644 --- a/product-methodology/SKILL.md +++ b/product-methodology/SKILL.md @@ -60,7 +60,7 @@ Load this skill when: ## When Not to Use - **Stakeholder discovery and interviews** — load `product-discovery` first. This skill starts from validated evidence, not raw stakeholder conversations. -- **Interaction design, task flows, or usability** — `product-design-and-ux` is the downstream concern (currently a proposed skill, not yet shipped in this catalog). This skill produces the spec; design-and-ux produces the interaction model. +- **Interaction design, task flows, state/recovery models, or usability-study planning** — use [product-design-and-ux](../product-design-and-ux/SKILL.md) after this skill has chosen scope. This skill decides what to build and why; design-and-ux defines user-facing behavior. ## Working Method diff --git a/product-methodology/references/source-index.md b/product-methodology/references/source-index.md index eb0f787..570caa7 100644 --- a/product-methodology/references/source-index.md +++ b/product-methodology/references/source-index.md @@ -45,4 +45,4 @@ Source review completed July 2026. Framework URLs verified live. | Skill | Relationship | Status | |---|---|---| | `product-discovery` | Upstream — feeds validated evidence into methodology | Ships in this catalog | -| `product-design-and-ux` | Downstream — consumes specs from methodology | Proposed (issue #24); not yet shipped in this catalog | +| `product-design-and-ux` | Downstream — turns approved scope and evidence into user-facing behavior and interaction handoff | Ships in this catalog | diff --git a/spec-driven-development/SKILL.md b/spec-driven-development/SKILL.md index 2ef7bff..0b8d3ba 100644 --- a/spec-driven-development/SKILL.md +++ b/spec-driven-development/SKILL.md @@ -121,6 +121,7 @@ You don't always start at SPECIFY. Enter at the phase matching what you already | You Have This | Enter At | Start With | |-------------|----------|------------| | A vague idea, conversation, or PRD | **Phase 1 — SPECIFY** | `templates/SPEC.md` + `references/format-translation.md` | +| Approved product scope with interaction contracts | **Phase 1 — SPECIFY** | [product-design-and-ux](../product-design-and-ux/SKILL.md) handoff + `templates/SPEC.md` | | A clear, approved specification | **Phase 2 — DECOMPOSE** | `templates/TASK-PLAN.md` + `references/ai-factory-pipeline.md` | | A spec + approved task plan | **Phase 3 — IMPLEMENT** | Task cards with per-task directives | | Existing code needing verification | **Phase 4 — VERIFY** | `templates/VERIFICATION.md` | diff --git a/web-accessibility/SKILL.md b/web-accessibility/SKILL.md index f49d240..1c2877e 100644 --- a/web-accessibility/SKILL.md +++ b/web-accessibility/SKILL.md @@ -58,5 +58,5 @@ Stop when each acceptance criterion has direct evidence or a recorded failed, bl ## When Not To Use - For Hugo template architecture, theme-wide layout, or CMS rendering concerns, use [hugo-theme](../hugo-theme/SKILL.md) and its [design/accessibility reference](../hugo-theme/references/design-accessibility.md). -- For product workflow, discovery, or requirements outside accessibility, use [product-methodology](../product-methodology/SKILL.md). Keep this skill responsible for the accessibility interaction contract. +- For evidence gathering, scope decisions, or user-facing behavior outside accessibility, use [product-discovery](../product-discovery/SKILL.md), [product-methodology](../product-methodology/SKILL.md), or [product-design-and-ux](../product-design-and-ux/SKILL.md). Keep this skill responsible for accessibility interaction and conformance depth. - For framework or library APIs, consult the current official documentation after defining this skill's semantic and interaction contract. diff --git a/web-accessibility/references/routing.md b/web-accessibility/references/routing.md index a4fc1eb..5315781 100644 --- a/web-accessibility/references/routing.md +++ b/web-accessibility/references/routing.md @@ -5,7 +5,9 @@ Keep the semantic and interaction contract framework-agnostic first. Then use th | Situation | Route | |---|---| | Hugo template architecture, theme-wide layout, or CMS rendering | [hugo-theme](../../hugo-theme/SKILL.md) and its [design/accessibility reference](../../hugo-theme/references/design-accessibility.md) | -| Product workflow, discovery, or requirements outside accessibility | [product-methodology](../../product-methodology/SKILL.md); keep the accessibility contract here | +| Stakeholder evidence and validation | [product-discovery](../../product-discovery/SKILL.md) | +| Product scope, priority, or rationale | [product-methodology](../../product-methodology/SKILL.md) | +| User-facing behavior, task flows, state/recovery models, or engineering UX handoff | [product-design-and-ux](../../product-design-and-ux/SKILL.md); keep accessibility conformance depth here | | Browser platform behavior | WHATWG HTML in `source-index.md` | | ARIA roles/pattern contracts | WAI-ARIA 1.2 and APG in `source-index.md` | | Framework-specific component API | Current official documentation after requirements are defined |