# [ADR Number] [Title]

## Status

[Proposed | Accepted | Deprecated | Superseded | Rejected]

A created ADR starts at `Proposed` and advances `Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`.

`Accepted` records the currently selected means, not an obligation to retain it. When later evidence supports a smaller sufficient choice, update or supersede this decision while the confirmed outcome, desired-future requirements, and non-goals remain true.

## Context

[Describe the background and reasons why this decision is needed. Include the essence of the problem, current challenges, and constraints]

## Decision Point

- **Question**: [The technical choice requiring comparison and selection]
- **Why a decision exists**: [Evidence for at least two credible, materially distinct options]
- **Scope boundary**: [Confirmed requirement or existing contract this decision serves]

## Decision

[Describe the actual decision made. Aim for specific and clear descriptions]

### Decision Details

| Item | Content |
|------|---------|
| **Decision** | [The decision in one sentence] |
| **Why this** | [Why this option over alternatives (1-3 lines)] |
| **Known unknowns** | [Uncertainty that changes implementation or verification; otherwise N/A] |
| **Reconsider when** | [Observable condition that changes the option comparison; otherwise N/A] |

## Rationale

[Explain why this decision was made and why it is the best option compared to alternatives]

### Options Considered

Compare credible, materially distinct options supported by current requirements and repository evidence. The evidence determines how many options exist, and relative evidence-backed cost is sufficient. Add a Mermaid option-comparison diagram only when the relationship between options stays unclear in the table below.

| Option | Confirmed product value | Repository fit | Total complexity | Maintainability | Material trade-offs | Reversibility |
|--------|-------------------------|----------------|------------------|-----------------|---------------------|---------------|
| [Option 1] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] |
| [Option 2] | [value required now] | [fit and evidence] | [materially different activated surfaces and lifecycle costs] | [fit with ownership and representative patterns] | [trade-offs] | [cost and conditions to reverse] |

**Selected**: [The smallest sufficient option whose total complexity is justified by confirmed product value and repository evidence]

## Consequences

### Positive Consequences

- [List positive impacts on the project or system]

### Negative Consequences

- [List negative impacts or trade-offs that need to be accepted]

### Neutral Consequences

[List decision-relevant neutral changes, or N/A]

## Architecture Impact

[Describe how this decision affects existing architecture: (1) components that change, (2) new dependencies introduced, (3) architectural constraints added or removed]

## Related Information

- [Links to related ADRs, documents, issues, PRs, etc.]

# [Feature Name] Design Document

## Overview

[Explain the purpose and overview of this feature in 2-3 sentences]

### Referenced UI Spec (when applicable)
- UI Spec path: [docs/ui-spec/xxx-ui-spec.md]
- Component structure and state design are inherited from UI Spec

## Background and Context

### Prerequisite ADRs

List the accepted ADRs that govern the changed responsibility, including accepted common (cross-cutting) ADRs, and verify this design aligns with each recorded decision.

- [docs/adr/ADR-XXXX.md]: [Related decision items]
- Reference common technical ADRs when applicable

### External Resources Used

Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table.

| Resource (project-tier label) | Feature-specific identifier | Notes |
|-------------------------------|-----------------------------|-------|
| [Resource label] | [e.g., specific endpoint path, schema source path, IaC module] | [feature-specific scope] |

### Requirement Convergence

Records exclusions **the user decided** at requirement time. Mark the first two bullets `N/A — covered by PRD [path]` when a PRD holds them, or the whole section `N/A — reverse-engineer/as-is document`. Open questions stay here in every case because design readiness depends on them. This section contains confirmed requirements and boundaries; evaluation requests, speculative ideas, and unselected mechanisms remain only in pre-confirmation convergence context.

- **Outcome**: [one observable result this change must produce]
- **Non-Goals**: [capability the user excluded | None — user confirmed there are none]
- **Open questions**: [field the user left as weak-but-explicit | None]

### Standards and Assumptions

#### Applicable Standards
- [ ] [Standard/convention] `[explicit]` - Source: [config / rule file / documentation path]
- [ ] [Observed pattern] `[implicit]` - Evidence: [file paths] - Confirmed: [Yes/No]

#### Assumed Behaviors
Behavioral or factual claims the design relies on (framework/library defaults, capabilities assumed already provided, features assumed already implemented). Each claim carries evidence. Before verification, use `Confirmed: No` for a specific unresolved premise and state the exact evidence needed and its design effect. A premise that can change the Selected Design must be resolved before approval. After verification, `Confirmed: No` is valid only for residual implementation uncertainty whose possible outcomes leave the Selected Design valid, with a matching Risks and Mitigation row that restates the claim as its Risk and names how it will be verified or guarded. Mark the subsection N/A when the design relies on no such claims.

- [ ] [Claim — e.g., "framework X defaults to Y", "service already returns Z"] - Evidence: [file:line / command output / doc URL / exact evidence needed] - Design effect: [what changes if false | Selected Design remains valid] - Confirmed: [Yes/No]

#### Bounded Self-Verification Evidence (when applied)

Include only when a fresh review-triggered technical-designer update executed a capability probe. Keep the durable record compact; raw logs and temporary artifacts are discarded during probe cleanup.

| Applied finding | Premise | Method and observed boundary | Observation | Limitation | Design effect |
|---|---|---|---|---|---|
| [finding ID] | [exact premise] | [bounded method and consumer-visible postcondition] | [observed result] | [remaining limitation that constrains the design effect, or None] | [Selected Design change or confirmation] |

#### Quality Assurance Mechanisms
How quality is enforced in the change area. Each item is either adopted (will be enforced during implementation) or noted (observed but not adopted, with reason).

- [ ] [Tool/check name] — Enforces: [what] — Config: [path] — Covers: [file paths/patterns, or "project-wide"] — Status: `adopted` / `noted (reason)`
- [ ] [Domain-specific constraint] — Enforces: [what] — Source: [path] — Covers: [file paths/patterns, or "project-wide"] — Status: `adopted` / `noted (reason)`

### Problem to Solve

[Specific problems or challenges this feature aims to address]

### Current Challenges

[Current system issues or limitations]

### Requirements

#### Functional Requirements

- [List mandatory functional requirements]

#### Non-Functional Requirements

- **Performance**: [Response time, throughput requirements]
- **Scalability**: [Requirements for handling increased load]
- **Reliability**: [Error rate, availability requirements]
- **Maintainability**: [Code readability and changeability]

## Acceptance Criteria (AC) - EARS Format

Each AC is written in EARS (Easy Approach to Requirements Syntax) format.
Keywords determine test type and reduce ambiguity.

**EARS Keywords**:
| Keyword | Usage | Test Type |
|---------|-------|-----------|
| **When** | Event-triggered behavior | Event-driven test |
| **While** | State-dependent behavior | State condition test |
| **If-then** | Conditional behavior | Branch coverage test |
| (none) | Ubiquitous behavior | Basic functionality test |

**Format**: `[Keyword] <trigger/condition>, the system shall <expected behavior>`

The rows below demonstrate EARS syntax only. Replace their domain, values, messages, and thresholds with requirements from the PRD or accepted requirement analysis; none is a default product requirement.

Keep the smallest representative set of observable behaviors that has a stable repository-verifiable pass/fail condition. Use repository-controlled contract/interface proof instead of a live external connection unless the confirmed requirement needs that boundary. Include a performance threshold only with a sourced target and reproducible benchmark, and exact visual positioning only with an approved visual contract and deterministic comparison. Implementation details remain outside ACs.

### [Functional Requirement 1]

- [ ] **When** [accepted trigger occurs], the system shall [observable result]
- [ ] **If** [accepted condition holds], **then** the system shall [observable conditional result]
- [ ] **While** [accepted state holds], the system shall [observable state-dependent result]
- [ ] (ubiquitous, no keyword) The system shall [observable invariant]

## Existing Codebase Analysis

### Implementation Path Mapping
| Type | Path | Description |
|------|------|-------------|
| Existing | src/[actual-path] | [Current implementation] |
| New | src/[planned-path] | [Planned new creation] |

### Integration Points (Include even for new implementations)
- **Integration Target**: [What to connect with]
- **Invocation Method**: [How it will be invoked]

### Code Inspection Evidence

| File/Function | Relevance |
|---------------|-----------|
| [path:function] | [similar functionality / integration point / pattern reference] |

### Fact Disposition Table

One row per codebase analysis `focusAreas` entry. This table is the single binding between existing-behavior facts and the design — other sections that describe existing behavior reference the row by Focus Area name.

| Fact ID | Focus Area | Disposition | Rationale | Evidence |
|---------|------------|-------------|-----------|----------|
| [fact_id from focusAreas] | [area name from focusAreas] | preserve / transform / remove / out-of-scope | [for transform: state new outcome; for remove: state reason; for out-of-scope: state which scope boundary excludes it; for preserve: brief confirmation] | [evidence value carried verbatim from focusAreas] |

## Design

### Change Impact Map

```yaml
Change Target: [Component/feature to change]
Direct Impact:
  - [Files/functions requiring direct changes]
  - [Interface change points]
Indirect Impact:
  - [Data format changes]
  - [Processing time changes]
No Ripple Effect:
  - [Explicitly specify unaffected features]
```

### Interface Change Matrix

| Existing | New | Conversion Required | Compatibility Method |
|----------|-----|--------------------|--------------------|
| [Function/method/operation name] | [Function/method/operation name] | [Yes/No] | [Approach: adapter, wrapper, deprecation, etc.] |

### Architecture Overview

[How this feature is positioned within the overall system]

Add an architecture or data-flow Mermaid diagram only when the changed relationships stay unclear in prose or a compact table; otherwise keep the prose form.

### Data Flow

```
[Express data flow using diagrams or pseudo-code]
```

### Integration Points List

| Integration Point | Location | Old Implementation | New Implementation | Switching Method | Verification Method |
|-------------------|----------|-------------------|-------------------|------------------|-------------------|
| [Integration Point] | [Class/Function] | [Existing Process or N/A] | [New Process] | [DI/Factory/config/etc.] | [How to verify this switching works] |

### Main Components

#### [Component] (repeat per component)

- **Responsibility**: [Scope of responsibility for this component]
- **Interface**: [APIs and contract definitions provided]
- **Dependencies**: [Relationships with other components]

### Data Representation Decision (When Introducing New Structures)

| Criterion | Assessment | Reason |
|-----------|-----------|--------|
| Semantic Fit | [Yes/No] | [Does existing structure's meaning align?] |
| Responsibility Fit | [Yes/No] | [Same bounded context?] |
| Lifecycle Fit | [Yes/No] | [Same creation/mutation/deletion timing?] |
| Boundary/Interop Cost | [Low/Medium/High] | [Cost of sharing across boundaries?] |

**Decision**: [reuse / extend / new] — [rationale in 1-2 sentences]

### Selected Design

Describe the complete selected end-to-end path. Candidate paths and rejected additions remain active analysis; an accepted ADR may retain alternatives as decision history. Mark this whole section `N/A — reverse-engineer/as-is document` for a reverse-engineer/as-is document.

[Selected responsibilities, control/data flow, and use of existing system capabilities]

For each added design surface—user decision, setting, mode, concept, output, persistent state, implementation path, public contract, abstraction, service, or component split—record:

- **Addition**: [selected design surface]
- **Current evidence**: [requirement, accepted decision, verified constraint, observed problem, or evidence-backed material risk]
- **Lower-surface insufficiency**: [why reuse, derivation, on-demand computation, or current-boundary ownership does not satisfy the same condition]
- **Subtraction result**: [confirmed outcome, required boundary, or proof that becomes unmet when removed]

Use `None — existing design surface is sufficient` when the selected design adds none of these surfaces.

### Data Contracts

When a UI Spec states that a surface displays a value, the contract feeding that surface carries it. A field set that cannot render a specified display is incomplete, not a simplification.

#### [Component or Boundary] (repeat per component/boundary)

```yaml
Contract: [interface / function / API / schema name]
Input:
  Type: [Data shape, contract, or schema]
  Preconditions: [Required items, format constraints]
  Validation: [Validation method]

Output:
  Type: [Data shape, contract, or schema]
  Guarantees: [Conditions that must always be met]
  On Error: [Exception/null/default value]

Invariants:
  - [Conditions that remain unchanged before and after processing]
```

### Field Propagation Map (When Fields Cross Boundaries)

A boundary here includes a **serialized boundary** — a value encoded on one side and parsed on the other through a medium such as a query string, CLI argument, environment variable, config entry, message/queue payload, storage key, or file — not only cross-process calls. For those, record the exact encoded representation and how the consumer parses it, so producer and consumer agree.

| Field | Boundary | Status | Serialized Format | Consumer Parse Rule | Detail |
|-------|----------|--------|-------------------|---------------------|--------|
| [field name] | [Component A → B] | preserved / transformed / dropped | [exact representation the producer emits when the boundary is serialized; "—" otherwise] | [how the consumer decodes and validates that representation; "—" when not serialized] | [logic or reason] |

### State Transitions and Invariants (When Applicable)

```yaml
State Definition:
  - Initial State: [Initial values and conditions]
  - Possible States: [List of states]

State Transitions:
  Current State → Event → Next State

System Invariants:
  - [Conditions that hold in any state]
```

### UI Error State Design (when feature includes frontend)

| Component / Screen | Loading | Empty | Error | Partial |
|-------------------|---------|-------|-------|---------|
| [Component name] | [Skeleton / spinner] | [Empty state + CTA] | [Error message + Retry] | [Cached display + Banner] |

### Client State Design (when feature includes frontend)

| State Category | State | Management Method | Sync Strategy | Reset/Clear Behavior |
|---------------|-------|-------------------|---------------|----------------------|
| Server state | [Fetched data] | [Cache library / custom hook] | [Polling / WebSocket / manual refresh] | [Cleared on clear-all / preserved] |
| Local UI state | [Modal open, tab selection] | [useState / useReducer] | - | [Reset to default / preserved] |
| Temporary state | [Form input, draft] | [useState / form library] | [Auto-save / manual save] | [Cleared on reset / persisted] |

Fill the Reset/Clear Behavior column when the feature has a reset or clear-all operation. A state that must return to its unused/default value on reset is a state-lifecycle negative (an observable contract: the state stays unused after reset) — record it so it is verified rather than assumed.

### UI Action - API Contract Mapping (when feature includes frontend)

| UI Action | API Endpoint | Request | Response | Error Contract |
|-----------|-------------|---------|----------|----------------|
| [Button click / form submit] | [POST /api/xxx] | [Request body fields] | [Response fields] | [Error codes and UI handling] |

### Error Handling

| Error Category | Example | Detection | Recovery Strategy | User Impact |
|---------------|---------|-----------|-------------------|-------------|
| [Validation / External / Infrastructure / Business logic] | [Specific error] | [How detected] | [Retry / Fallback / Propagate / Log-and-continue] | [User-facing message or silent handling] |

### Logging and Monitoring

Include this section only when the feature changes an observable operational boundary or an accepted requirement/project policy requires diagnostics, metrics, or alerts.

- **Log events**: [Key events to log: state transitions, external calls, error occurrences, performance thresholds]
- **Log levels**: [Which events at DEBUG/INFO/WARN/ERROR]
- **Sensitive data**: [Fields to mask or exclude — coordinate with Security Considerations]
- **Monitoring**: [Metrics to track, alert thresholds, dashboard requirements]

## Implementation Plan

### Implementation Approach

**Selected Approach**: [Approach name or combination]
**Selection Reason**: [Reason considering project constraints and technical dependencies]

### Technical Dependencies and Implementation Order

#### Required Implementation Order (in dependency order, one entry per component/feature)

1. **[Component/Feature]**
   - Technical Reason: [Why this needs to be implemented at this position]
   - Prerequisites / Dependent Elements: [Components depended on or that depend on this]

### Migration Strategy

[Technical migration approach, ensuring backward compatibility]

## Security Considerations

Evaluate the following for this feature's trust boundaries and data flow:

- **Authentication & Authorization**: What authentication is required for new entry points? What authorization checks protect resource access?
- **Input Validation**: Where does external input enter the system? How is it validated before processing?
- **Sensitive Data Handling**: What data requires protection (encryption, masking, access control)? What data is safe to include in logs and error responses?

Mark items as N/A with brief rationale when the feature has no relevant trust boundary.

## Test Boundaries

### Mock Boundary Decisions

| Component/Dependency | Mock? | Rationale |
|---------------------|-------|-----------|
| [External API / DB / File system / etc.] | [Yes/No] | [Why this boundary was chosen] |

### Data Layer Testing Strategy

- **Schema dependencies**: [List tables/models this feature reads from or writes to, with paths to their definitions]
- **Test data approach**: [How test data is provided — fixtures, factories, seed scripts, or real database]
- **Mock limitations acknowledged**: [What cannot be reliably tested with mocks alone for this feature]

Mark as N/A with brief rationale when the feature has no data layer dependencies.

### Integration Verification Points

- [List critical integration points that require testing beyond unit-level mocks]

## Verification Strategy

Verification Strategy defines what correctness means and how to prove it at design time. L1/L2/L3 levels (L1: functional operation works as end-user feature; L2: tests added and passing; L3: build succeeds without errors) define completion verification granularity at task execution time.

### Correctness Proof Method

- **Correctness definition**: [What "correct" means for this change — e.g., "output matches existing behavior", "all ACs pass in production-equivalent environment", "generated queries execute without error on target DB"]
- **Verification method**: [Specific technique — e.g., "compare new implementation output against existing implementation", "run against staging DB", "contract test with real API"]
- **Verification timing**: [When verification occurs — e.g., "after first vertical slice", "per repository", "at integration phase"]

### Early Verification Point

- **First verification target**: [The smallest unit that proves the approach works — e.g., "first repository migration", "single API endpoint", "one screen flow"]
- **Success criteria**: [Observable outcome — e.g., "CSV download produces identical output to legacy", "API returns 200 with expected schema"]
- **Failure response**: [What to do if early verification fails — e.g., "reassess approach before proceeding", "return to the governing decision gate"]

### Output Comparison (When Replacing or Modifying Existing Behavior)

How will behavioral equivalence be verified between existing and new implementation?

- **Comparison input**: [Identical input used for both implementations — e.g., "same DB snapshot", "same API request payload"]
- **Expected output fields**: [Specific fields/columns to compare — e.g., "all output columns", "response body fields: id, status, amount"]
- **Diff method**: [How to compare — e.g., "file-level diff", "JSON field-by-field comparison", "row count + spot check"]
- **Transformation pipeline coverage**: [Each step from codebase analysis `dataTransformationPipelines` and what the comparison covers]

Mark as N/A with brief rationale when the design introduces entirely new behavior with no existing equivalent.

## Design Boundaries

Record boundaries needed by a current requirement, downstream implementer, or verifier. This section contains selected design boundaries rather than discovered candidates or unselected future possibilities.

- **Intentional limitations**: [Current behavior or responsibility deliberately kept outside the selected design, with the governing scope reason]
- **Existing extension points used**: [Interfaces or hooks the selected design uses, with each named current consumer | None]

## Risks and Mitigation

Include only evidenced residual risks that can change rollout, rollback, contract handling, or verification strategy while leaving the Selected Design valid.

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| [Risk 1] | High/Medium/Low | High/Medium/Low | [Countermeasure] |

## References

- [Related documentation and links]

## Update History

| Date | Version | Changes | Author |
|------|---------|---------|--------|
| YYYY-MM-DD | 1.0 | Initial version | [Name] |

# Work Plan: [Feature Name] Implementation

Created Date: YYYY-MM-DD
Type: feature|fix|refactor
Related Issue/PR: #XXX (if any)
Review Scope: [repository responsibilities or expected files derived from the Design Doc]

## Governing Documents

- Design Doc: [docs/design/XXX.md]
- UI Spec: [docs/ui-spec/XXX.md] (when applicable)
- ADR: [docs/adr/ADR-XXXX-title.md] (when applicable)
- PRD: [docs/prd/XXX.md] (when applicable)
- Test skeletons: [paths] (when generated)

## Implementation Scope

[One concise statement of the repository implementation outcome defined by the Design Doc.]

## Implementation Phases

Use the implementation approach and dependency order from the Design Doc. Each phase groups work that reaches a shared observable verification point. Keep implementation, tests, configuration, wiring, and documentation together when they become complete at that point.

Shape the phases from the approach the Design Doc selected:

- **Vertical Slice**: each phase is one value unit (feature, component, or migration target) carrying its own implementation and verification per the Verification Strategy.
- **Horizontal Slice**: foundation (contract definitions, interfaces/signatures, test preparation) → core feature (business logic, unit tests) → integration (external connections, presentation layer).
- **Hybrid**: combine the two as the Design Doc's implementation approach defines.

Whole-repository quality assurance stays outside the plan as a separate execution responsibility.

### Phase 1: [First implementation outcome]

#### Tasks

- [ ] **P1-T1: [Repository implementation outcome]**
  - **Source**: [every directly constraining Design Doc, ADR, or UI Spec path and section; AC IDs]
  - **Scope**: [responsibility, component, or expected files]
  - **Depends on**: none | [task IDs]
  - **Executor lane**: backend|frontend
  - **Rollback boundary**: [repository change that reverts with this task]
  - **Verification**: [Design Doc verification method or repository command]
  - **Primary failure**: [optional: most material false-green state]
  - **Observable check**: [optional: smallest check that detects the primary failure]

### Phase 2: [Next implementation outcome] (when required)

#### Tasks

- [ ] **P2-T1: [Repository implementation outcome]**
  - **Source**: [every directly constraining governing path and section; AC IDs]
  - **Scope**: [responsibility, component, or expected files]
  - **Depends on**: [task IDs]
  - **Executor lane**: backend|frontend
  - **Rollback boundary**: [repository change that reverts with this task]
  - **Verification**: [Design Doc verification method or repository command]
  - **Primary failure**: [optional]
  - **Observable check**: [optional]

## Completion Criteria

- [ ] Every Design Doc obligation needed for implementation is covered by at least one task
- [ ] Every task cites each directly constraining governing section and applicable AC
- [ ] Every task produces a repository implementation outcome required by its source
- [ ] Dependencies permit execution in the listed order
- [ ] Verification is executable from repository artifacts or the task's own output
- [ ] Task verification passes and cited acceptance criteria are satisfied

# PRD: [Feature Name]

## Overview

### One-line Summary
[Describe this feature in one line]

### Background
[Why is this feature needed? What problem does it solve?]

## User Stories

### Primary Users
[Define the main target users]

### User Stories
```
As a [user type]
I want to [goal/desire]
So that [expected value/benefit]
```

### Use Cases
1. [Specific usage scenario 1]
2. [Specific usage scenario 2]
3. [Specific usage scenario 3]

### User Journey Diagram (When Needed)

[Include when prose does not make the material user flow clear; otherwise remove this subsection.]
```mermaid
journey
    title [Feature Name] User Journey
    section [Phase 1]
      [Step]: [satisfaction score]: [actor]
```
[Map the end-to-end user experience from trigger event to goal completion]

### Scope Boundary Diagram (When Needed)

[Include when prose does not make the material in-scope/out-of-scope relationship clear; otherwise remove this subsection.]
```mermaid
C4Context
    Boundary(scope, "In Scope") {
        [Components in scope]
    }
    Boundary(out, "Out of Scope") {
        [Components out of scope]
    }
```
[Clarify what is and is not included in this feature]

## Functional Requirements

### MVP Requirements
- [ ] Requirement 1: [Detailed description]
  - AC-001: [Acceptance criteria - Given/When/Then format or measurable standard]
  - AC-002: [Acceptance criteria]
- [ ] Requirement 2: [Detailed description]
  - AC-003: [Acceptance criteria]

### Future / Out of Scope

Record user-authored non-goals and any current exclusion required to make the MVP boundary executable. The table is limited to confirmed boundaries; evaluation requests, speculative ideas, and unselected possibilities remain only in pre-confirmation convergence context. Record `None — user confirmed there are none` when the user considered exclusions and found none.

Use `user` for a user-authored non-goal and `analysis` for a current exclusion required to make the confirmed MVP boundary executable.

| Capability | Disposition | Origin | Reason |
|---|---|---|---|
| [Confirmed non-goal or required current scope exclusion] | future / out-of-scope | user / analysis | [Governing scope reason] |

## Non-Functional Requirements

### Performance
- Response Time: [Target value]
- Throughput: [Target value]
- Concurrency: [Target value]

### Reliability
- Availability: [Target value]
- Error Rate: [Target value]

### Security
- [Security requirements details]

### Scalability
- [Considerations for future scaling]

### Accessibility (when feature includes UI)
- Compliance standard (when established by an accepted organizational, legal, contractual, or confirmed product source): [standard]
- Target assistive technologies: [Screen reader, keyboard operation, voice control, etc.]
- Platform requirements: [e.g., app store review requirements]
- Known constraints: [e.g., external library limitations]

## Success Criteria

### Quantitative Metrics
1. [Metric name]: [numeric target] measured by [method] within [timeframe]
2. [Metric name]: [numeric target] measured by [method] within [timeframe]
3. [Metric name]: [numeric target] measured by [method] within [timeframe]

### Qualitative Metrics
1. [User experience metric 1]
2. [User experience metric 2]

### UI Quality Metrics (when feature includes UI)
1. [Key operation completion rate / error recovery rate / retry success rate]
2. [Accessibility audit target score]

## Technical Considerations

### Dependencies
- [Dependencies on existing systems]
- [Dependencies on external services]

### Constraints
- [Technical constraints]
- [Resource constraints]

### Assumptions
- [Prerequisite requiring validation 1]
- [Prerequisite requiring validation 2]

### Risks and Mitigation
Include only evidenced product or delivery risks that can change scope, success criteria, sequencing, or acceptance.

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| [Risk 1] | High/Medium/Low | High/Medium/Low | [Countermeasure] |
| [Risk 2] | High/Medium/Low | High/Medium/Low | [Countermeasure] |

## Undetermined Items

- [ ] [Question 1]: [Description of options or impacts]
- [ ] [Question 2]: [Description of options or impacts]

*Discuss with user until this section is empty, then delete after confirmation*

## Appendix

### References
- [Related document 1]
- [Related document 2]

### Glossary
- **Term 1**: [Definition]
- **Term 2**: [Definition]

# Task: [Task Name]

Metadata:
- Source Work Plan Task: [P1-T1]
- Dependencies: none | [Work Plan task IDs]
- Executor lane: backend|frontend
- Rollback boundary: [copied from Work Plan]

## Implementation Outcome

[Repository change that completes the source Work Plan task.]

## Governing Sources

Preserve every directly constraining Work Plan citation unchanged so the executor reads the authoritative contract directly.

- [Design Doc path (§ section); AC IDs]
- [UI Spec or ADR path (§ section), when directly constraining]

## Target Files

- [Implementation file or responsibility]
- [Test file, when required]

## Investigation Targets

Read the smallest representative set needed to implement the task:

- [Governing document section]
- [Existing implementation]
- [Adjacent representative test]

## Investigation Notes

- [Record only facts that change implementation, scope, or verification.]

## Implementation Steps

1. Read the Investigation Targets and record relevant repository facts.
2. Add or update the focused test required by the cited verification strategy.
3. Implement the smallest repository change that completes the outcome.
4. Refactor within the same outcome while focused checks remain green.
5. Run task verification.

## Operation Verification Methods

- **Verification method**: [Governing verification method or repository command]
- **Success criteria**: [Observable result tied to cited ACs]
- **Verification level**: [L1 functional operation | L2 passing tests | L3 successful build — per implementation-approach]

## Verification Focus

Include only when the Work Plan supplies it.

- **Primary failure**: [Copied unchanged from Work Plan]
- **Observable check**: [Copied unchanged from Work Plan]

## Completion Criteria

- [ ] The cited implementation outcome is complete
- [ ] The cited ACs are satisfied
- [ ] Required focused tests pass
- [ ] Operation verification succeeds
- [ ] Verification Focus is satisfied when present

## Notes

- [Execution-relevant information only]

# [Feature Name] UI Specification

## Overview

[Purpose and scope of this UI Specification in 2-3 sentences]

### Confirmed Requirement Context
- PRD path: [docs/prd/xxx-prd.md | "N/A — based on requirements analysis output"]
- Feature scope: [Which confirmed requirements this UI Spec covers]

### Design Source
| Source | Path | Version |
|--------|------|---------|
| Prototype code | [docs/ui-spec/assets/xxx/] | [commit SHA / tag] |

## Prototype Management

Prototype code is an **attachment** to this UI Spec. The canonical specification is always this document + the Design Doc.

- **Attachment path**: [docs/ui-spec/assets/{feature-name}/]
- **Version identification**: [commit SHA / tag]
- **Compliance premise**: [e.g., design system compliance, component library usage]
- **Reference strength**: [`binding` — implementation follows the attachment's rendering except where this document states otherwise | `reference` — only what this document records reaches implementation]
- **Relationship to canonical spec**: Differences between prototype and this spec are resolved in favor of this document under either strength.

## External Resources Used

Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table.

| Resource (project-tier label) | Feature-specific identifier | Notes |
|-------------------------------|-----------------------------|-------|
| Design Origin | [feature-specific identifier] | [scope notes] |
| Design System | [components used in this feature] | [variants, customizations] |
| Visual Verification Environment | [story names / test paths / page routes] | [how this feature is rendered for review] |

## AC Traceability (Prototype)

Map confirmed acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided.

| Criterion ID / Reference | Criterion Summary | Screen / State | Prototype Reference (element ID / path) | Adoption Decision |
|-------|-----------|----------------|----------------------------------------|-------------------|
| AC-001 | [EARS AC summary] | [Screen / state name] | [element or file reference] | Adopted / Not adopted / On hold |

## Screen List and Transitions

Add a screen-transition or component-tree Mermaid diagram only when the material interaction or hierarchy stays unclear in the tables below; otherwise keep the table form.

### Screen List

| Screen ID | Screen Name | Description | Entry Condition |
|-----------|------------|-------------|-----------------|
| S-01 | [Screen name] | [Purpose] | [How user reaches this screen] |

### Transition Conditions

| Source | Destination | Trigger | Guard Condition |
|--------|------------|---------|-----------------|
| S-01 | S-02 | [User action] | [Precondition if any] |

## Component Decomposition

### Component Tree

```
[Page/Screen]
  +-- [Container Component]
  |   +-- [Presentational Component A]
  |   +-- [Presentational Component B]
  +-- [Container Component]
      +-- [Presentational Component C]
```

### Component: [ComponentName]

> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. Duplicate or paraphrased headings break downstream propagation to implementation tasks.

#### State x Display Matrix

The matrix contains one row for each state supported by confirmed requirements, approved UI direction, preserved behavior, or repository/design-system rules.

| State | Trigger | Display | Interaction / Recovery | Evidence |
|-------|---------|---------|------------------------|----------|
| [Applicable state] | [Condition that activates it] | [Rendered outcome] | [Available action or N/A] | [Requirement, UI evidence, or repository rule] |

#### Interaction Definition

| Criterion ID / Reference | EARS Condition | User Action | System Response | State Transition | Error Handling |
|-------|---------------|-------------|-----------------|-----------------|----------------|
| AC-001 | When [trigger] | [Click / input / etc.] | [Expected behavior] | [From state -> To state] | [Retry / Reset / Fallback] |

### Component: [ComponentName2]

[Repeat the applicable State x Display Matrix and Interaction Definition for each in-scope interactive component]

## Design Tokens and Component Map

### Environment Constraints

- Target browsers: [e.g., Chrome 120+, Safari 17+]
- Theme support: [e.g., light/dark, system preference]

#### Responsive Behavior

| Breakpoint | Width | Key Changes |
|-----------|-------|-------------|
| Mobile | [e.g., < 768px] | [e.g., single column, hamburger nav, 14px body text] |
| Tablet | [e.g., 768px - 1023px] | [e.g., 2-column grid, collapsed sidebar] |
| Desktop | [e.g., ≥ 1024px] | [e.g., full layout, expanded nav, sidebar visible] |

### Existing Component Reuse Map

| UI Element | Decision | Existing Component | Notes |
|-----------|----------|-------------------|-------|
| [Button] | Reuse | [components/ui/Button] | [No modifications needed] |
| [DataTable] | Extend | [components/ui/Table] | [Add sorting support] |
| [FeatureCard] | New | - | [No similar component exists] |

### Design Tokens

#### Color Roles

| Role | Token | Value | Usage |
|------|-------|-------|-------|
| Background Surface | [bg-primary] | [e.g., #FFFFFF] | [Page background] |
| Background Surface | [bg-secondary] | [e.g., #F9FAFB] | [Card, section background] |
| Text | [text-primary] | [e.g., #111827] | [Headings, body text] |
| Text | [text-secondary] | [e.g., #6B7280] | [Captions, placeholders] |
| Brand / Accent | [color-brand] | [e.g., #1A73E8] | [Primary actions, links] |
| Status | [color-success] | [e.g., #22C55E] | [Success states, confirmations] |
| Status | [color-error] | [e.g., #EF4444] | [Error states, destructive actions] |
| Border | [border-primary] | [e.g., #E5E7EB] | [Card borders, dividers] |

#### Typography Hierarchy

| Role | Font | Size | Weight | Line Height | Letter Spacing |
|------|------|------|--------|-------------|----------------|
| Heading 1 | [e.g., Inter] | [e.g., 30px] | [e.g., 700] | [e.g., 1.2] | [e.g., -0.02em] |
| Heading 2 | [e.g., Inter] | [e.g., 24px] | [e.g., 600] | [e.g., 1.3] | [e.g., -0.01em] |
| Body | [e.g., Inter] | [e.g., 16px] | [e.g., 400] | [e.g., 1.5] | [e.g., 0] |
| Caption | [e.g., Inter] | [e.g., 12px] | [e.g., 400] | [e.g., 1.4] | [e.g., 0.01em] |
| Monospace | [e.g., JetBrains Mono] | [e.g., 14px] | [e.g., 400] | [e.g., 1.6] | [e.g., 0] |

#### Spacing Scale

| Token | Value | Usage |
|-------|-------|-------|
| [spacing-xs] | [e.g., 4px] | [Inline element gaps] |
| [spacing-sm] | [e.g., 8px] | [Compact padding] |
| [spacing-md] | [e.g., 16px] | [Default component padding] |
| [spacing-lg] | [e.g., 24px] | [Section spacing] |
| [spacing-xl] | [e.g., 40px] | [Page section separation] |

#### Elevation (Depth)

| Level | Treatment | Usage |
|-------|-----------|-------|
| 0 (Flat) | [e.g., none] | [Inline elements, text] |
| 1 (Raised) | [e.g., 0 1px 2px rgba(0,0,0,0.05)] | [Cards, buttons] |
| 2 (Floating) | [e.g., 0 4px 12px rgba(0,0,0,0.1)] | [Dropdowns, popovers] |
| 3 (Overlay) | [e.g., 0 8px 24px rgba(0,0,0,0.15)] | [Modals, dialogs] |

#### Border Radius Scale

| Token | Value | Usage |
|-------|-------|-------|
| [radius-sm] | [e.g., 4px] | [Badges, chips] |
| [radius-md] | [e.g., 8px] | [Cards, inputs] |
| [radius-lg] | [e.g., 12px] | [Modals, panels] |
| [radius-full] | [e.g., 9999px] | [Avatars, pills] |

## Visual Acceptance

### Golden States
Define the key visual states that serve as acceptance benchmarks:

1. **[State name]**: [Description of what should be visually confirmed]
2. **[State name]**: [Description]

### Layout Constraints
- [Min/max width, height constraints]
- [Spacing rules between components]
- [Overflow behavior]

## Accessibility Requirements

### Keyboard Navigation

| Component | Tab Order | Key Binding | Behavior |
|-----------|-----------|-------------|----------|
| [Component] | [Order number] | [Enter / Space / Arrow] | [Expected behavior] |

### Screen Reader

| Component | Role | Accessible Name | Live Region |
|-----------|------|-----------------|-------------|
| [Component] | [ARIA role] | [aria-label / aria-labelledby] | [polite / assertive / none] |

### Contrast Requirements

| Element | Foreground | Background | Ratio Target |
|---------|-----------|------------|-------------|
| [Text element] | [Color] | [Color] | [4.5:1 for normal text / 3:1 for large text] |

## Open Items

| ID | Description | Blocking Effect | Required Owner / Evidence |
|----|-------------|-----------------|---------------------------|
| TBD-01 | [Only a decision-blocking unresolved item] | [What cannot proceed] | [Who decides or what evidence resolves it] |

Omit non-blocking unknowns from this table or state them in the relevant section. Resolve decision-blocking items before Design Doc creation.

## Update History

| Date | Version | Changes | Author |
|------|---------|---------|--------|
| YYYY-MM-DD | 1.0 | Initial version | [Name] |