docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,430 @@
|
||||
# Specification Audit Report
|
||||
|
||||
**Date:** {YYYY-MM-DD}
|
||||
**Auditor:** {Name/Agent}
|
||||
**Scope:** {Scenario name or Page name}
|
||||
**Audit Level:** {Quick/Standard/Complete}
|
||||
**Project:** {Project name}
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Overall Status:** {✅ Pass / ⚠️ Pass with Issues / ❌ Fail}
|
||||
|
||||
**Issue Counts:**
|
||||
- 🔴 Critical Issues: {count}
|
||||
- 🟡 Warnings: {count}
|
||||
- 🔵 Suggestions: {count}
|
||||
|
||||
**Recommendation:** {Ready for development / Needs fixes before development / Major rework required}
|
||||
|
||||
---
|
||||
|
||||
## Level 0: Specification Formatting & Standards
|
||||
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
### Markdown Structure
|
||||
**Checklist:**
|
||||
- [ ] Proper heading hierarchy (H1 → H2 → H3 → H4)
|
||||
- [ ] Only one H1 per page
|
||||
- [ ] No skipped heading levels
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description, line number, and severity}
|
||||
|
||||
---
|
||||
|
||||
### Area Label Format
|
||||
**Checklist:**
|
||||
- [ ] Format: `**AREA LABEL**: `{label}``
|
||||
- [ ] Naming convention: `{page}-{section}-{element}`
|
||||
- [ ] Consistent throughout
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description, line number, and severity}
|
||||
|
||||
---
|
||||
|
||||
### Translation Format
|
||||
**Checklist:**
|
||||
- [ ] Each language on separate line
|
||||
- [ ] Format: `- {LANG}: "{content}"`
|
||||
- [ ] All product languages present
|
||||
- [ ] Consistent language order
|
||||
- [ ] No inline translations
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description, line number, and severity}
|
||||
|
||||
---
|
||||
|
||||
### List & Code Formatting
|
||||
**Checklist:**
|
||||
- [ ] Use `-` for bullets (not `*` or `+`)
|
||||
- [ ] Consistent indentation
|
||||
- [ ] Code blocks have language specified
|
||||
- [ ] Proper spacing
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description, line number, and severity}
|
||||
|
||||
---
|
||||
|
||||
### Section Organization
|
||||
**Checklist:**
|
||||
- [ ] Sections in standard order
|
||||
- [ ] No missing required sections
|
||||
- [ ] Logical flow maintained
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description, line number, and severity}
|
||||
|
||||
---
|
||||
|
||||
### File Naming
|
||||
**Checklist:**
|
||||
- [ ] Follows WDS naming conventions
|
||||
- [ ] No generic names (README.md, GUIDE.md)
|
||||
- [ ] Descriptive and specific
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description and severity}
|
||||
|
||||
---
|
||||
|
||||
## Level 1: Scenario-Level Findings
|
||||
|
||||
### Strategic Foundation
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
**Checklist:**
|
||||
- [ ] User situation clearly defined
|
||||
- [ ] Usage context documented
|
||||
- [ ] Strategic context (Trigger Map) defined and linked
|
||||
- [ ] Scenario purpose stated
|
||||
- [ ] Success criteria defined
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description and severity}
|
||||
|
||||
---
|
||||
|
||||
### Navigation Flow
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
**Checklist:**
|
||||
- [ ] All pages in scenario identified
|
||||
- [ ] Entry points documented for each page
|
||||
- [ ] Exit points documented for each page
|
||||
- [ ] User can navigate through all pages
|
||||
- [ ] Navigation paths logical and complete
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description and severity}
|
||||
|
||||
---
|
||||
|
||||
## Level 2: Page-Level Findings
|
||||
|
||||
### Structure & Organization
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Page purpose clearly stated
|
||||
- [ ] Success criteria defined
|
||||
- [ ] Trigger Map reference present
|
||||
- [ ] Sections properly separated and named
|
||||
- [ ] Section purposes defined
|
||||
- [ ] Page layout logical and flows well
|
||||
|
||||
**Structural Area Labels:**
|
||||
- [ ] Page container (`{page-name}-page`)
|
||||
- [ ] Header section (`{page-name}-header`)
|
||||
- [ ] Main content area (`{page-name}-main`)
|
||||
- [ ] Form container (`{page-name}-form`)
|
||||
- [ ] Section containers (`{page-name}-{section}-section`)
|
||||
- [ ] Section header bars (`{page-name}-{section}-header-bar`)
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description and severity}
|
||||
|
||||
---
|
||||
|
||||
### Visual-Spec Alignment
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Sketch/visualization exists
|
||||
- [ ] Sketch linked in specification
|
||||
- [ ] All objects in sketch documented in spec
|
||||
- [ ] All objects in spec visible in sketch
|
||||
- [ ] Visual hierarchy matches spec structure
|
||||
|
||||
**Misalignments Found:**
|
||||
- **Objects in sketch but missing from spec:**
|
||||
- {Object name and location}
|
||||
- **Objects in spec but missing from sketch:**
|
||||
- {Object name and location}
|
||||
- **Visual discrepancies:**
|
||||
- {Description of mismatch}
|
||||
|
||||
---
|
||||
|
||||
### Area Label Coverage
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
**Checklist:**
|
||||
- [ ] All interactive elements have Area Labels
|
||||
- [ ] Labels follow naming convention (`{page}-{section}-{element}`)
|
||||
- [ ] Labels are unique within page
|
||||
- [ ] ARIA labels match Area Labels
|
||||
|
||||
**Missing Area Labels:**
|
||||
- {Element description and suggested label}
|
||||
|
||||
**Naming Convention Issues:**
|
||||
- {ID that doesn't follow pattern and suggested fix}
|
||||
|
||||
---
|
||||
|
||||
## Level 3: Component-Level Findings
|
||||
|
||||
### Componentization
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Reusable sections identified
|
||||
- [ ] Components properly separated from page specs
|
||||
- [ ] Component specifications exist
|
||||
- [ ] Component references valid and linked
|
||||
|
||||
**Issues Found:**
|
||||
- **Components needing extraction:**
|
||||
- {Component name and pages where it appears}
|
||||
- **Missing component specs:**
|
||||
- {Component name}
|
||||
- **Broken component references:**
|
||||
- {Reference location and issue}
|
||||
|
||||
---
|
||||
|
||||
### Design System Integration
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail / N/A}
|
||||
|
||||
**Checklist:**
|
||||
- [ ] All components added to design system
|
||||
- [ ] Components at proper hierarchy level
|
||||
- [ ] Design tokens applied
|
||||
- [ ] Figma components linked
|
||||
|
||||
**Issues Found:**
|
||||
- {Issue description and severity}
|
||||
|
||||
---
|
||||
|
||||
## Level 4: Feature-Level Findings
|
||||
|
||||
### Shared Functionality
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Common features identified
|
||||
- [ ] Feature files created and documented
|
||||
- [ ] Feature references consistent across pages
|
||||
- [ ] Validation rules centralized
|
||||
|
||||
**Issues Found:**
|
||||
- **Features needing extraction:**
|
||||
- {Feature name and pages where it appears}
|
||||
- **Inconsistent implementations:**
|
||||
- {Feature name and inconsistency description}
|
||||
|
||||
---
|
||||
|
||||
## Level 5: Content Audit Findings
|
||||
|
||||
### Text Content
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
**Checklist:**
|
||||
- [ ] All content defined (no placeholders)
|
||||
- [ ] Multi-language content complete
|
||||
- [ ] Field labels present and clear
|
||||
- [ ] Button text defined
|
||||
- [ ] Error messages in all languages
|
||||
- [ ] Success messages in all languages
|
||||
- [ ] Empty state messages defined
|
||||
- [ ] Loading state messages defined
|
||||
- [ ] Meta content (page title, meta description) for public pages
|
||||
- [ ] Social sharing content (title, description, image) for public pages
|
||||
|
||||
**Missing Content:**
|
||||
- {Element and missing content type}
|
||||
|
||||
**Language Gaps:**
|
||||
- {Content that's missing in specific languages}
|
||||
|
||||
**Meta Content Issues:**
|
||||
- {Missing or incomplete meta tags for public pages}
|
||||
|
||||
---
|
||||
|
||||
### Accessibility Content
|
||||
**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
|
||||
|
||||
**ARIA Labels:**
|
||||
- [ ] All interactive elements have aria-label
|
||||
- [ ] ARIA labels descriptive and meaningful
|
||||
|
||||
**Missing ARIA Labels:**
|
||||
- {Element description}
|
||||
|
||||
**Images:**
|
||||
- [ ] All images have alt text
|
||||
- [ ] Alt text descriptive
|
||||
|
||||
**Missing Alt Text:**
|
||||
- {Image location and suggested alt text}
|
||||
|
||||
**Forms:**
|
||||
- [ ] All inputs have labels
|
||||
- [ ] Required fields marked
|
||||
- [ ] Field instructions present
|
||||
|
||||
**Form Issues:**
|
||||
- {Issue description}
|
||||
|
||||
**Keyboard Navigation:**
|
||||
- [ ] Tab order documented
|
||||
- [ ] Focus management specified
|
||||
- [ ] Skip links present
|
||||
|
||||
**Keyboard Issues:**
|
||||
- {Issue description}
|
||||
|
||||
**Screen Reader Support:**
|
||||
- [ ] Semantic HTML specified
|
||||
- [ ] Heading hierarchy logical
|
||||
- [ ] ARIA live regions for dynamic content
|
||||
|
||||
**Screen Reader Issues:**
|
||||
- {Issue description}
|
||||
|
||||
**Visual Accessibility:**
|
||||
- [ ] Color contrast meets WCAG AA
|
||||
- [ ] Information not color-dependent
|
||||
- [ ] Focus indicators visible
|
||||
|
||||
**Visual Accessibility Issues:**
|
||||
- {Issue description}
|
||||
|
||||
**WCAG Compliance:**
|
||||
- [ ] Target level documented
|
||||
- [ ] Known issues documented
|
||||
|
||||
**WCAG Issues:**
|
||||
- {Issue description}
|
||||
|
||||
---
|
||||
|
||||
## Summary of Issues
|
||||
|
||||
### 🔴 Critical Issues (Must Fix Before Development)
|
||||
|
||||
1. **{Issue Title}**
|
||||
- **Location:** {Page/Section}
|
||||
- **Problem:** {Description}
|
||||
- **Impact:** {Why this is critical}
|
||||
- **Recommended Fix:** {Specific action to take}
|
||||
|
||||
2. **{Issue Title}**
|
||||
- **Location:** {Page/Section}
|
||||
- **Problem:** {Description}
|
||||
- **Impact:** {Why this is critical}
|
||||
- **Recommended Fix:** {Specific action to take}
|
||||
|
||||
---
|
||||
|
||||
### 🟡 Warnings (Should Fix)
|
||||
|
||||
1. **{Issue Title}**
|
||||
- **Location:** {Page/Section}
|
||||
- **Problem:** {Description}
|
||||
- **Impact:** {Why this matters}
|
||||
- **Recommended Fix:** {Specific action to take}
|
||||
|
||||
2. **{Issue Title}**
|
||||
- **Location:** {Page/Section}
|
||||
- **Problem:** {Description}
|
||||
- **Impact:** {Why this matters}
|
||||
- **Recommended Fix:** {Specific action to take}
|
||||
|
||||
---
|
||||
|
||||
### 🔵 Suggestions (Nice to Have)
|
||||
|
||||
1. **{Issue Title}**
|
||||
- **Location:** {Page/Section}
|
||||
- **Problem:** {Description}
|
||||
- **Impact:** {Why this would improve quality}
|
||||
- **Recommended Fix:** {Specific action to take}
|
||||
|
||||
2. **{Issue Title}**
|
||||
- **Location:** {Page/Section}
|
||||
- **Problem:** {Description}
|
||||
- **Impact:** {Why this would improve quality}
|
||||
- **Recommended Fix:** {Specific action to take}
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Immediate Actions
|
||||
1. {Action item with priority and owner}
|
||||
2. {Action item with priority and owner}
|
||||
|
||||
### Before Development Handoff
|
||||
1. {Action item with priority and owner}
|
||||
2. {Action item with priority and owner}
|
||||
|
||||
### Future Improvements
|
||||
1. {Action item with priority and owner}
|
||||
2. {Action item with priority and owner}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [ ] Fix critical issues
|
||||
- [ ] Address warnings
|
||||
- [ ] Consider suggestions
|
||||
- [ ] Re-audit after fixes
|
||||
- [ ] Update specifications
|
||||
- [ ] Update sketches if needed
|
||||
- [ ] Notify development team when ready
|
||||
|
||||
---
|
||||
|
||||
## Audit Metrics
|
||||
|
||||
**Specification Completeness:** {percentage}%
|
||||
- Structural Area Labels: {X/Y complete}
|
||||
- Interactive Area Labels: {X/Y complete}
|
||||
- Content defined: {X/Y complete}
|
||||
- Accessibility: {X/Y complete}
|
||||
|
||||
**Quality Score:** {percentage}%
|
||||
- Based on critical issues, warnings, and suggestions
|
||||
|
||||
**Development Readiness:** {Ready / Not Ready / Needs Review}
|
||||
|
||||
---
|
||||
|
||||
**Audit Completed:** {YYYY-MM-DD HH:MM}
|
||||
**Next Audit Scheduled:** {YYYY-MM-DD or "After fixes"}
|
||||
|
||||
---
|
||||
|
||||
_Generated using WDS Specification Audit Workflow_
|
||||
@@ -0,0 +1,104 @@
|
||||
# WDS Design Delivery Template
|
||||
# Copy this template to: deliveries/DD-XXX-name.yaml
|
||||
|
||||
delivery:
|
||||
id: "DD-XXX" # Format: DD-001, DD-002, etc.
|
||||
name: "Feature Name" # Human-readable name
|
||||
type: "user_flow" # user_flow | feature | component
|
||||
status: "ready" # ready | in_progress | blocked
|
||||
priority: "high" # high | medium | low
|
||||
created_by: "wds-ux-expert"
|
||||
created_at: "YYYY-MM-DDTHH:MM:SSZ"
|
||||
updated_at: "YYYY-MM-DDTHH:MM:SSZ"
|
||||
version: "1.0"
|
||||
|
||||
description: |
|
||||
[Describe what this delivery contains and why it matters.
|
||||
Include the complete user flow and key features.]
|
||||
|
||||
user_value:
|
||||
problem: "[What user problem does this solve?]"
|
||||
solution: "[How does this feature solve it?]"
|
||||
success_criteria:
|
||||
- "[Measurable success criterion 1]"
|
||||
- "[Measurable success criterion 2]"
|
||||
- "[Measurable success criterion 3]"
|
||||
|
||||
design_artifacts:
|
||||
scenarios:
|
||||
- id: "XX-scenario-name"
|
||||
path: "C-UX-Scenarios/XX-scenario-name/"
|
||||
screens: ["screen1", "screen2"]
|
||||
|
||||
- id: "XX-scenario-name"
|
||||
path: "C-UX-Scenarios/XX-scenario-name/"
|
||||
screens: ["screen1"]
|
||||
|
||||
user_flows:
|
||||
- name: "Flow Name"
|
||||
path: "C-UX-Scenarios/flows/flow-name.excalidraw"
|
||||
entry: "entry-screen"
|
||||
exit: "exit-screen"
|
||||
|
||||
design_system:
|
||||
components:
|
||||
- "Component Name (variants)"
|
||||
- "Component Name (variants)"
|
||||
path: "D-Design-System/"
|
||||
|
||||
technical_requirements:
|
||||
platform:
|
||||
frontend: "framework-name" # From platform-requirements.yaml
|
||||
backend: "framework-name" # From platform-requirements.yaml
|
||||
|
||||
integrations:
|
||||
- name: "integration-name"
|
||||
purpose: "[Why this integration is needed]"
|
||||
required: true # true | false
|
||||
|
||||
- name: "integration-name"
|
||||
purpose: "[Why this integration is needed]"
|
||||
required: false
|
||||
|
||||
data_models:
|
||||
- name: "ModelName"
|
||||
fields: ["field1", "field2", "field3"]
|
||||
|
||||
- name: "ModelName"
|
||||
fields: ["field1", "field2"]
|
||||
|
||||
acceptance_criteria:
|
||||
functional:
|
||||
- "[Functional requirement 1]"
|
||||
- "[Functional requirement 2]"
|
||||
- "[Functional requirement 3]"
|
||||
|
||||
non_functional:
|
||||
- "[Performance requirement]"
|
||||
- "[Accessibility requirement]"
|
||||
- "[Security requirement]"
|
||||
|
||||
edge_cases:
|
||||
- "[Edge case 1] → [Expected behavior]"
|
||||
- "[Edge case 2] → [Expected behavior]"
|
||||
- "[Edge case 3] → [Expected behavior]"
|
||||
|
||||
testing_guidance:
|
||||
user_testing:
|
||||
- "[User testing instruction 1]"
|
||||
- "[User testing instruction 2]"
|
||||
|
||||
qa_testing:
|
||||
- "[QA testing instruction 1]"
|
||||
- "[QA testing instruction 2]"
|
||||
- "[QA testing instruction 3]"
|
||||
|
||||
estimated_complexity:
|
||||
size: "medium" # small | medium | large
|
||||
effort: "2-3 weeks" # Time estimate
|
||||
risk: "low" # low | medium | high
|
||||
dependencies: [] # List of DD-XXX IDs needed first
|
||||
|
||||
notes: |
|
||||
[Any special considerations, important context, or
|
||||
critical details that the development team should know.]
|
||||
@@ -0,0 +1,227 @@
|
||||
# Diagnostic Report Template
|
||||
|
||||
**Use this template for generating diagnostic reports during page specification validation.**
|
||||
|
||||
---
|
||||
|
||||
## Step-Specific Diagnostic Report
|
||||
|
||||
```markdown
|
||||
🔍 [Step Name] Audit
|
||||
|
||||
**Status:** ✅ PASS / ⚠️ WARNING / ❌ CRITICAL
|
||||
|
||||
**Issues Found:**
|
||||
1. [Issue type] [Description]
|
||||
- Location: Line X-Y
|
||||
- Current: [what exists now]
|
||||
- Should be: [what it should be]
|
||||
- Why: [explanation of why this matters]
|
||||
|
||||
2. [Issue type] [Description]
|
||||
- Location: Line X-Y
|
||||
- Current: [what exists now]
|
||||
- Should be: [what it should be]
|
||||
- Why: [explanation of why this matters]
|
||||
|
||||
**Recommendation:**
|
||||
[Specific actionable fix with examples]
|
||||
|
||||
**Example of Correct Format:**
|
||||
```[language]
|
||||
[code example showing correct implementation]
|
||||
```
|
||||
|
||||
Would you like me to fix this?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist Format
|
||||
|
||||
```yaml
|
||||
[section_name]_validated:
|
||||
field_1: [true/false]
|
||||
field_2: [true/false]
|
||||
field_3: [true/false]
|
||||
status: [pass/warning/critical]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue Severity Levels
|
||||
|
||||
### ✅ PASS
|
||||
- All checks passed
|
||||
- No issues found
|
||||
- Specification meets standards
|
||||
|
||||
### ⚠️ WARNING
|
||||
- Non-critical issues found
|
||||
- Specification functional but could be improved
|
||||
- Recommended fixes, not required
|
||||
|
||||
### ❌ CRITICAL
|
||||
- Critical issues that must be fixed
|
||||
- Missing required sections
|
||||
- Specification incomplete or non-compliant
|
||||
- Blocks developer handoff
|
||||
|
||||
---
|
||||
|
||||
## Common Issue Types
|
||||
|
||||
### Missing Section
|
||||
```markdown
|
||||
❌ Missing required section: [Section Name]
|
||||
- Location: Should appear after [Previous Section]
|
||||
- Why: [Explanation of why this section is required]
|
||||
- Example: [Show what the section should look like]
|
||||
```
|
||||
|
||||
### Incorrect Format
|
||||
```markdown
|
||||
⚠️ Incorrect format: [Element Name]
|
||||
- Location: Line X
|
||||
- Current: [what's there now]
|
||||
- Should be: [correct format]
|
||||
- Why: [Explanation of why format matters]
|
||||
```
|
||||
|
||||
### Missing Object ID
|
||||
```markdown
|
||||
❌ Missing Object ID: [Component Name]
|
||||
- Location: Line X
|
||||
- Current: Component has no OBJECT ID declaration
|
||||
- Should be: **OBJECT ID**: `component-name`
|
||||
- Why: Object IDs enable traceability from spec → code → Figma
|
||||
```
|
||||
|
||||
### Design System Violation
|
||||
```markdown
|
||||
❌ Design System violation: CSS details in page spec
|
||||
- Location: Line X-Y
|
||||
- Current: Contains hex codes, pixel values, CSS classes
|
||||
- Should be: Component references with Design System links
|
||||
- Why: Page specs focus on WHAT/WHY, Design System handles HOW
|
||||
```
|
||||
|
||||
### Incomplete Coverage
|
||||
```markdown
|
||||
⚠️ Incomplete Object Registry coverage
|
||||
- Missing: [list of Object IDs not in registry]
|
||||
- Orphaned: [list of Object IDs in registry but not in sections]
|
||||
- Coverage: X% (should be 100%)
|
||||
- Why: Registry must be single source of truth for all elements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommendation Format
|
||||
|
||||
### Simple Fix
|
||||
```markdown
|
||||
**Recommendation:**
|
||||
Add the missing section after [Previous Section]:
|
||||
|
||||
```markdown
|
||||
## [Section Name]
|
||||
|
||||
[Content template]
|
||||
```
|
||||
|
||||
Would you like me to add this section?
|
||||
```
|
||||
|
||||
### Complex Fix
|
||||
```markdown
|
||||
**Recommendation:**
|
||||
1. Extract CSS details to Design System documentation
|
||||
2. Replace inline styles with component references
|
||||
3. Add Design System links for colors/typography
|
||||
4. Keep page-specific layout notes (mobile vs desktop behavior)
|
||||
|
||||
**Next Steps:**
|
||||
- Move color values to `Design-System/Foundation/Colors/`
|
||||
- Move typography to `Design-System/Foundation/Typography/`
|
||||
- Update page spec to reference Design System components
|
||||
|
||||
Would you like me to help extract these styles to the Design System?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Final Validation Report Format
|
||||
|
||||
```markdown
|
||||
# Page Specification Quality Report
|
||||
|
||||
**Page:** [Page Number] [Page Name]
|
||||
**Audit Date:** [Date]
|
||||
**Overall Status:** ✅ PASS / ⚠️ NEEDS WORK / ❌ CRITICAL ISSUES
|
||||
|
||||
## Executive Summary
|
||||
[Brief overview of specification quality]
|
||||
|
||||
## Critical Issues (Must Fix Before Handoff)
|
||||
[List critical issues from all steps]
|
||||
|
||||
## Warnings (Should Fix)
|
||||
[List warnings from all steps]
|
||||
|
||||
## Info (Nice to Have)
|
||||
[List informational items]
|
||||
|
||||
## Coverage Metrics
|
||||
- Object Registry Coverage: X%
|
||||
- Sketch Coverage: X%
|
||||
- Design System References: X%
|
||||
- Platform Metadata: Complete/Incomplete
|
||||
|
||||
## Recommendations
|
||||
[Prioritized list of fixes]
|
||||
|
||||
## Next Steps
|
||||
[What to do next based on findings]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
1. **Be Specific:** Always include line numbers and exact examples
|
||||
2. **Be Helpful:** Explain WHY each issue matters
|
||||
3. **Be Actionable:** Provide clear recommendations with examples
|
||||
4. **Be Conversational:** Use friendly, collaborative tone
|
||||
5. **Be Respectful:** Let designer decide whether to implement fixes
|
||||
6. **Be Thorough:** Don't skip issues, but group related problems
|
||||
|
||||
---
|
||||
|
||||
## Example Complete Report
|
||||
|
||||
```markdown
|
||||
🔍 Page Metadata Audit
|
||||
|
||||
**Status:** ⚠️ WARNING
|
||||
|
||||
**Issues Found:**
|
||||
1. ⚠️ Missing scenario inheritance reference (Line 17-23)
|
||||
- Location: Page Metadata section
|
||||
- Current: All platform fields present but no inheritance link
|
||||
- Should be: "**Inherits From:** Scenario 03 Platform Strategy"
|
||||
- Why: Creates explicit traceability from Product Brief → Scenario → Page
|
||||
|
||||
**Recommendation:**
|
||||
Add inheritance reference after Navigation Context:
|
||||
|
||||
```markdown
|
||||
**Navigation Context**: Authenticated - overlays calendar page
|
||||
|
||||
**Inherits From**: Scenario 03 Platform Strategy (see scenario overview)
|
||||
```
|
||||
|
||||
This creates explicit traceability chain and ensures platform context is properly inherited.
|
||||
|
||||
Would you like me to add this reference?
|
||||
```
|
||||
@@ -0,0 +1,166 @@
|
||||
# Accessibility Audit Workflow
|
||||
|
||||
**Purpose:** Agent-led accessibility review with explanations and suggestions
|
||||
|
||||
---
|
||||
|
||||
## How This Works
|
||||
|
||||
1. Agent reads the page specification and/or prototype code
|
||||
2. Agent evaluates each area against WCAG 2.1 AA
|
||||
3. Agent explains findings in plain language
|
||||
4. Agent proposes specific fixes
|
||||
5. User approves, rejects, or asks for alternatives
|
||||
|
||||
---
|
||||
|
||||
## Agent Instructions
|
||||
|
||||
### Step 1: Analyze Color Contrast
|
||||
|
||||
Read the design system colors and check:
|
||||
|
||||
```
|
||||
For each text element:
|
||||
- Calculate contrast ratio against background
|
||||
- WCAG AA requires: 4.5:1 for normal text, 3:1 for large text (18px+)
|
||||
|
||||
Report:
|
||||
"The button text (#FFFFFF) on primary background (#2563EB)
|
||||
has a contrast ratio of 8.6:1 ✓ Passes WCAG AA
|
||||
|
||||
The helper text (#9CA3AF) on white (#FFFFFF)
|
||||
has a contrast ratio of 2.9:1 ✗ Fails WCAG AA
|
||||
→ Suggestion: Darken to #6B7280 (4.6:1) or #4B5563 (7:1)"
|
||||
```
|
||||
|
||||
**Ask user:** "Should I darken the helper text to #6B7280?"
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Analyze Keyboard Navigation
|
||||
|
||||
Read the page structure and determine logical tab order:
|
||||
|
||||
```
|
||||
Looking at the page layout, the logical keyboard flow should be:
|
||||
|
||||
1. Skip to main content link (hidden until focused)
|
||||
2. Logo (if clickable) → Home
|
||||
3. Navigation items left to right
|
||||
4. Main content, top to bottom
|
||||
5. Form fields in visual order
|
||||
6. Submit/action buttons
|
||||
7. Footer links
|
||||
|
||||
Current spec has these interactive elements:
|
||||
- `header-logo` ✓ Has behavior defined
|
||||
- `nav-home` ✓ Link
|
||||
- `form-email` ✗ Missing keyboard info
|
||||
- `submit-btn` ✗ Missing focus state
|
||||
|
||||
→ Suggestion: Add to form-email:
|
||||
| Keyboard | Tab to focus, type to enter |
|
||||
| Focus | 2px blue ring (#2563EB) |
|
||||
```
|
||||
|
||||
**Ask user:** "Should I add keyboard properties to these elements?"
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Analyze Screen Reader Experience
|
||||
|
||||
Check each element has appropriate labels:
|
||||
|
||||
```
|
||||
Reviewing interactive elements:
|
||||
|
||||
`booking-submit` - Button with text "Book"
|
||||
→ Issue: "Book" alone may be unclear out of context
|
||||
→ Suggestion: aria-label="Book this walk slot"
|
||||
|
||||
`booking-cancel` - Icon button with X
|
||||
→ Issue: No text, screen reader says nothing
|
||||
→ Suggestion: aria-label="Cancel booking"
|
||||
|
||||
`status-indicator` - Colored dot (green/red/gray)
|
||||
→ Issue: Color only, no text alternative
|
||||
→ Suggestion: Add aria-label="Status: Available" and visually hidden text
|
||||
```
|
||||
|
||||
**Ask user:** "Should I add these aria-labels to the spec?"
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Analyze Dynamic Content
|
||||
|
||||
Check state changes and notifications:
|
||||
|
||||
```
|
||||
This page has dynamic content:
|
||||
|
||||
State changes (drawer opens/closes):
|
||||
→ Need: aria-expanded on trigger, focus management
|
||||
→ Suggestion: When drawer opens, move focus to drawer header
|
||||
|
||||
Loading states:
|
||||
→ Need: aria-busy="true" on container, "Loading..." announcement
|
||||
→ Suggestion: Add aria-live="polite" region for status updates
|
||||
|
||||
Error messages:
|
||||
→ Need: aria-live="assertive" so errors are announced immediately
|
||||
→ Suggestion: Link error to field with aria-describedby
|
||||
```
|
||||
|
||||
**Ask user:** "Should I add these dynamic content specifications?"
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Summary Report
|
||||
|
||||
```
|
||||
## Accessibility Audit Summary
|
||||
|
||||
### Passes ✓
|
||||
- Color contrast on primary buttons (8.6:1)
|
||||
- Semantic HTML structure (header, main, nav)
|
||||
- Form labels present
|
||||
|
||||
### Needs Attention ⚠
|
||||
- Helper text contrast (2.9:1 → needs 4.5:1)
|
||||
- 3 buttons missing aria-labels
|
||||
- Tab order not documented
|
||||
- Focus states not specified
|
||||
|
||||
### Recommendations
|
||||
1. Darken helper text to #6B7280
|
||||
2. Add aria-labels to icon buttons
|
||||
3. Document keyboard flow
|
||||
4. Specify focus ring style (2px #2563EB)
|
||||
|
||||
Implement these changes? [Yes to all / Review each / Skip]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference for Agent
|
||||
|
||||
| Check | WCAG Rule | Requirement |
|
||||
|-------|-----------|-------------|
|
||||
| Text contrast | 1.4.3 | 4.5:1 normal, 3:1 large |
|
||||
| Focus visible | 2.4.7 | Clear visual indicator |
|
||||
| Labels | 1.3.1 | All inputs labeled |
|
||||
| Keyboard | 2.1.1 | All functions keyboard accessible |
|
||||
| Error ID | 3.3.1 | Errors identified and described |
|
||||
| Name/Role | 4.1.2 | Interactive elements have accessible names |
|
||||
|
||||
---
|
||||
|
||||
## Agent Prompts
|
||||
|
||||
Use these to guide the conversation:
|
||||
|
||||
- "I found {N} contrast issues. Want me to explain each one?"
|
||||
- "This button has no accessible name. Should I suggest one based on its purpose?"
|
||||
- "The tab order seems unclear. Can you confirm the intended flow?"
|
||||
- "Screen readers won't announce this status change. Should I add aria-live?"
|
||||
@@ -0,0 +1,102 @@
|
||||
# Accessibility Specification
|
||||
|
||||
**Include when:** Specifying interactive elements, forms, or navigation
|
||||
|
||||
---
|
||||
|
||||
## For Each Interactive Element
|
||||
|
||||
When documenting buttons, links, inputs, add:
|
||||
|
||||
```markdown
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| aria-label | "{What it does}" |
|
||||
| Keyboard | {Enter / Space / Arrow keys} |
|
||||
| Focus style | {ring / outline / highlight} |
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
#### Submit Button
|
||||
**OBJECT ID:** `form-submit`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| aria-label | "Submit booking request" |
|
||||
| Keyboard | Enter or Space |
|
||||
| Focus | 2px blue ring |
|
||||
| Disabled state | aria-disabled="true", gray, no focus |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tab Order
|
||||
|
||||
Document the logical sequence:
|
||||
|
||||
```markdown
|
||||
## Keyboard Flow
|
||||
|
||||
1. `header-logo` → Home link
|
||||
2. `header-nav` → Main navigation
|
||||
3. `main-content` → Skip to here
|
||||
4. `form-name` → First input
|
||||
5. `form-email` → Second input
|
||||
6. `form-submit` → Submit button
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dynamic Content
|
||||
|
||||
When content changes without page reload:
|
||||
|
||||
```markdown
|
||||
| Element | Announces |
|
||||
|---------|-----------|
|
||||
| `toast-success` | aria-live="polite" — "Booking confirmed" |
|
||||
| `error-message` | aria-live="assertive" — Error text |
|
||||
| `loading-spinner` | aria-busy="true" on parent |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Color Independence
|
||||
|
||||
For status indicators, ensure alternatives:
|
||||
|
||||
| Status | Color | Also Has |
|
||||
|--------|-------|----------|
|
||||
| Success | Green | Checkmark icon + "Complete" text |
|
||||
| Error | Red | Warning icon + error message |
|
||||
| Active | Blue | Bold text + underline |
|
||||
|
||||
---
|
||||
|
||||
## Form Errors
|
||||
|
||||
Link errors to fields:
|
||||
|
||||
```markdown
|
||||
#### Email Error
|
||||
**OBJECT ID:** `form-email-error`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| aria-describedby | Links to `form-email` |
|
||||
| Role | "alert" |
|
||||
| Content | "Please enter a valid email" |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Checks
|
||||
|
||||
Before finalizing:
|
||||
|
||||
- [ ] Every button has aria-label or visible text
|
||||
- [ ] Every image has alt (or alt="" if decorative)
|
||||
- [ ] Every input has associated label
|
||||
- [ ] Focus visible on all interactive elements
|
||||
- [ ] Status not conveyed by color alone
|
||||
@@ -0,0 +1,69 @@
|
||||
# Data & API Requirements
|
||||
|
||||
**Include when:** Page requires data from APIs or external sources
|
||||
|
||||
---
|
||||
|
||||
## Data Sources
|
||||
|
||||
| Data Element | Source | Type | Required | Notes |
|
||||
|--------------|--------|------|----------|-------|
|
||||
| `{data-field}` | {API / static / localStorage} | {string / number / array} | {yes/no} | {notes} |
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### {Endpoint Name}
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Method | {GET / POST / PUT / DELETE} |
|
||||
| Path | `/api/{path}` |
|
||||
| Purpose | {What this endpoint does} |
|
||||
| Auth | {Required / Optional / None} |
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"field": "value"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (Success):**
|
||||
```json
|
||||
{
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
**Response (Error):**
|
||||
```json
|
||||
{
|
||||
"error": "message",
|
||||
"code": "ERR_XXX"
|
||||
}
|
||||
```
|
||||
|
||||
**Error Codes:**
|
||||
| Code | Meaning | User Message |
|
||||
|------|---------|--------------|
|
||||
| `{code}` | {technical meaning} | {user-friendly message} |
|
||||
|
||||
---
|
||||
|
||||
## Loading States
|
||||
|
||||
| State | Duration | UI |
|
||||
|-------|----------|-----|
|
||||
| Initial load | {expected ms} | {skeleton / spinner / etc.} |
|
||||
| Refresh | {expected ms} | {indicator type} |
|
||||
| Background | {expected ms} | {silent / toast} |
|
||||
|
||||
---
|
||||
|
||||
## Caching Strategy
|
||||
|
||||
| Data | Cache Duration | Invalidation |
|
||||
|------|----------------|--------------|
|
||||
| {data type} | {duration} | {when to refresh} |
|
||||
@@ -0,0 +1,54 @@
|
||||
# Form Validation
|
||||
|
||||
**Include when:** Page has forms or input fields
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
| Field | Rule | Error Code | Error Message |
|
||||
|-------|------|------------|---------------|
|
||||
| `{field-name}` | {validation-rule} | `{ERR_CODE}` | {message} |
|
||||
|
||||
---
|
||||
|
||||
## Error Messages
|
||||
|
||||
| Error Code | Trigger | EN | SE | Recovery |
|
||||
|------------|---------|-----|-----|----------|
|
||||
| `ERR_001` | {When occurs} | "{English}" | "{Swedish}" | {How to fix} |
|
||||
|
||||
---
|
||||
|
||||
## Form States
|
||||
|
||||
### Valid State
|
||||
- All fields pass validation
|
||||
- Submit button enabled
|
||||
- No error indicators
|
||||
|
||||
### Invalid State
|
||||
- Error fields highlighted
|
||||
- Error messages visible
|
||||
- Submit button disabled until fixed
|
||||
|
||||
### Submitting State
|
||||
- Submit button shows loading
|
||||
- Fields disabled
|
||||
- Cancel option available
|
||||
|
||||
---
|
||||
|
||||
## Field Specifications
|
||||
|
||||
### {Field Name}
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **OBJECT ID** | `{form-field-id}` |
|
||||
| Type | {text / email / password / select / etc.} |
|
||||
| Required | {yes / no} |
|
||||
| Placeholder EN | "{Placeholder text}" |
|
||||
| Placeholder SE | "{Swedish placeholder}" |
|
||||
| Validation | {rules} |
|
||||
| Error Message | {message} |
|
||||
@@ -0,0 +1,37 @@
|
||||
# Meta Content & Social Sharing
|
||||
|
||||
**Include when:** Page is Public (SEO/social sharing needed)
|
||||
|
||||
---
|
||||
|
||||
## Page Title
|
||||
**Limit:** 55-60 characters
|
||||
|
||||
`{title}`
|
||||
|
||||
---
|
||||
|
||||
## Meta Description
|
||||
**Limit:** 150-160 characters
|
||||
|
||||
`{description}`
|
||||
|
||||
---
|
||||
|
||||
## Social Sharing
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Title | {60-70 chars, can differ from page title} |
|
||||
| Description | {120-150 chars} |
|
||||
| Image | 1200x630px, `/images/social/{page-name}.jpg` |
|
||||
| Image Alt | {alt text} |
|
||||
|
||||
---
|
||||
|
||||
## Agent Questions
|
||||
|
||||
1. "What should appear in browser tab/search results?" (< 60 chars)
|
||||
2. "Describe this page to encourage clicks" (150-160 chars)
|
||||
3. "What title for social shares?"
|
||||
4. "What image represents this page?" (1200x630px)
|
||||
@@ -0,0 +1,164 @@
|
||||
# Open Questions — Auto-Population Guide
|
||||
|
||||
**Purpose:** During page specification creation or audit, automatically add relevant questions based on page characteristics.
|
||||
|
||||
---
|
||||
|
||||
## How to Use
|
||||
|
||||
When creating or auditing a page specification:
|
||||
1. Review the checklist below
|
||||
2. For each applicable category, check if the page specification addresses it
|
||||
3. If not addressed, add to the Open Questions section
|
||||
|
||||
---
|
||||
|
||||
## Responsive Behavior
|
||||
|
||||
**Trigger:** Page metadata indicates multiple viewports OR page is responsive
|
||||
|
||||
| Condition | Add Question |
|
||||
|-----------|--------------|
|
||||
| No responsive sketches | "What are the responsive breakpoint layouts? (Mobile/Tablet/Desktop)" |
|
||||
| Mobile-first but no desktop spec | "How does the layout adapt for desktop users?" |
|
||||
| Desktop-first but no mobile spec | "How does the layout adapt for mobile users?" |
|
||||
| Touch + mouse interaction | "Are there hover states that need touch alternatives?" |
|
||||
|
||||
---
|
||||
|
||||
## Loading & Error States
|
||||
|
||||
**Trigger:** Page fetches data OR has async operations
|
||||
|
||||
| Condition | Add Question |
|
||||
|-----------|--------------|
|
||||
| API data but no loading state | "What does the user see while data is loading?" |
|
||||
| No error state documented | "What happens if the data fails to load?" |
|
||||
| No empty state documented | "What does the user see when there's no data?" |
|
||||
| Async actions (save, submit) | "What feedback does the user get during async operations?" |
|
||||
| Network-dependent features | "What happens if the user is offline?" |
|
||||
|
||||
---
|
||||
|
||||
## SEO & Meta Content
|
||||
|
||||
**Trigger:** Page is public (visibility = Public)
|
||||
|
||||
| Condition | Add Question |
|
||||
|-----------|--------------|
|
||||
| No page title specified | "What is the page title for SEO?" |
|
||||
| No meta description | "What is the meta description for search results?" |
|
||||
| No Open Graph tags | "What should the social sharing preview show?" |
|
||||
| Dynamic content | "How do we handle SEO for dynamic/personalized content?" |
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
**Trigger:** All pages (accessibility is always relevant)
|
||||
|
||||
| Condition | Add Question |
|
||||
|-----------|--------------|
|
||||
| Live updating content (timers, feeds) | "Should live updates announce to screen readers (aria-live)?" |
|
||||
| Modal/drawer interactions | "Where does focus go when modal opens/closes?" |
|
||||
| Color-coded states | "Is information conveyed by color alone?" |
|
||||
| Custom components | "Do custom components have proper ARIA roles?" |
|
||||
| Animations | "Are animations respecting prefers-reduced-motion?" |
|
||||
| Complex interactions | "What is the keyboard navigation pattern?" |
|
||||
|
||||
---
|
||||
|
||||
## User Permissions & Roles
|
||||
|
||||
**Trigger:** Page has authenticated users OR multiple user types
|
||||
|
||||
| Condition | Add Question |
|
||||
|-----------|--------------|
|
||||
| Multi-user feature | "What does User B see when User A is performing an action?" |
|
||||
| Role-based access | "Which elements are visible/hidden per role?" |
|
||||
| Shared resources | "What happens if two users act simultaneously?" |
|
||||
| Destructive actions | "Should destructive actions require confirmation?" |
|
||||
|
||||
---
|
||||
|
||||
## Time-Sensitive Features
|
||||
|
||||
**Trigger:** Page has countdowns, timers, or time-based state changes
|
||||
|
||||
| Condition | Add Question |
|
||||
|-----------|--------------|
|
||||
| Countdown timer | "What happens when the countdown reaches zero?" |
|
||||
| Time windows | "Can users act before the time window opens?" |
|
||||
| Time windows | "What happens after the time window closes?" |
|
||||
| Background behavior | "Does the timer continue when app is backgrounded?" |
|
||||
| Session timeout | "What happens when the session expires?" |
|
||||
|
||||
---
|
||||
|
||||
## Form Interactions
|
||||
|
||||
**Trigger:** Page has form inputs
|
||||
|
||||
| Condition | Add Question |
|
||||
|-----------|--------------|
|
||||
| No validation rules | "What are the validation rules for each field?" |
|
||||
| No error messages | "What error messages are shown for each validation failure?" |
|
||||
| No success state | "What happens after successful form submission?" |
|
||||
| Partial completion | "Can users save partial progress?" |
|
||||
| Sensitive data | "Are there security considerations for this form data?" |
|
||||
|
||||
---
|
||||
|
||||
## Navigation & Flow
|
||||
|
||||
**Trigger:** Page is part of a multi-step flow
|
||||
|
||||
| Condition | Add Question |
|
||||
|-----------|--------------|
|
||||
| No back navigation | "Can users go back to the previous step?" |
|
||||
| Browser back button | "What happens when user presses browser back?" |
|
||||
| Unsaved changes | "Should we warn users about unsaved changes?" |
|
||||
| Deep linking | "Can this page be accessed via direct URL?" |
|
||||
|
||||
---
|
||||
|
||||
## Integration Checklist
|
||||
|
||||
When creating a page specification, check these categories:
|
||||
|
||||
```
|
||||
[ ] Responsive — Do we have all breakpoint layouts?
|
||||
[ ] Loading — Is the loading state documented?
|
||||
[ ] Error — Is the error state documented?
|
||||
[ ] Empty — Is the empty state documented?
|
||||
[ ] SEO — Is meta content defined (if public)?
|
||||
[ ] Accessibility — Are a11y requirements specified?
|
||||
[ ] Permissions — Are role-based views documented?
|
||||
[ ] Time — Are time-sensitive behaviors defined?
|
||||
[ ] Forms — Are validation rules specified?
|
||||
[ ] Navigation — Is back/forward behavior defined?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Open Questions Section
|
||||
|
||||
For a responsive page with API data and timer:
|
||||
|
||||
```markdown
|
||||
## Open Questions
|
||||
|
||||
| # | Question | Context | Status |
|
||||
|---|----------|---------|--------|
|
||||
| 1 | What are the tablet/desktop layouts? | Only mobile sketch provided | 🔴 Open |
|
||||
| 2 | What does user see while loading? | API fetch on page load | 🔴 Open |
|
||||
| 3 | What happens if API call fails? | Error handling | 🔴 Open |
|
||||
| 4 | Does timer continue when app backgrounded? | Mobile behavior | 🔴 Open |
|
||||
| 5 | Should timer announce to screen readers? | Accessibility | 🔴 Open |
|
||||
|
||||
**Status Legend:** 🔴 Open | 🟡 In Discussion | 🟢 Resolved
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
_Use this guide during specification creation and audits to ensure comprehensive coverage._
|
||||
@@ -0,0 +1,64 @@
|
||||
# Responsive Behavior
|
||||
|
||||
**Include when:** Page needs different layouts across breakpoints
|
||||
|
||||
---
|
||||
|
||||
## Breakpoints
|
||||
|
||||
| Name | Range | Primary Use |
|
||||
|------|-------|-------------|
|
||||
| Mobile | < 768px | Touch, single column |
|
||||
| Tablet | 768px - 1024px | Touch/mouse, flexible |
|
||||
| Desktop | > 1024px | Mouse, multi-column |
|
||||
|
||||
---
|
||||
|
||||
## Mobile (< 768px)
|
||||
|
||||
### Layout Changes
|
||||
- {What changes from desktop}
|
||||
|
||||
### Hidden Elements
|
||||
- {Elements not shown on mobile}
|
||||
|
||||
### Mobile-Specific
|
||||
- {Touch targets, gestures, etc.}
|
||||
|
||||
---
|
||||
|
||||
## Tablet (768px - 1024px)
|
||||
|
||||
### Layout Changes
|
||||
- {What changes}
|
||||
|
||||
### Adaptations
|
||||
- {Specific tablet behaviors}
|
||||
|
||||
---
|
||||
|
||||
## Desktop (> 1024px)
|
||||
|
||||
### Full Layout
|
||||
- {Desktop-specific features}
|
||||
|
||||
### Enhancements
|
||||
- {Hover states, keyboard shortcuts}
|
||||
|
||||
---
|
||||
|
||||
## Component Breakpoint Behavior
|
||||
|
||||
| Component | Mobile | Tablet | Desktop |
|
||||
|-----------|--------|--------|---------|
|
||||
| `{component}` | {behavior} | {behavior} | {behavior} |
|
||||
|
||||
---
|
||||
|
||||
## Navigation Changes
|
||||
|
||||
| Breakpoint | Navigation Style |
|
||||
|------------|------------------|
|
||||
| Mobile | {hamburger / bottom nav / etc.} |
|
||||
| Tablet | {style} |
|
||||
| Desktop | {full nav / sidebar / etc.} |
|
||||
@@ -0,0 +1,163 @@
|
||||
# SEO Content Instructions
|
||||
|
||||
**Condition:** Include when page visibility = "Public"
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Ensure every public page is optimized for search engines during specification — not as an afterthought during development.
|
||||
|
||||
---
|
||||
|
||||
## Required: Check Project Brief SEO Strategy
|
||||
|
||||
Before specifying this page, check the project brief's **SEO Strategy** section:
|
||||
|
||||
1. Find this page in the **Page-Keyword Map**
|
||||
2. Note the **primary keyword** and **secondary keywords**
|
||||
3. Note the **URL slug**
|
||||
4. Note any **structured data** requirements
|
||||
|
||||
If the page is missing from the keyword map, flag it as an open question.
|
||||
|
||||
---
|
||||
|
||||
## SEO Specification Checklist
|
||||
|
||||
### 1. URL Slug
|
||||
|
||||
```markdown
|
||||
**URL:** /{slug}
|
||||
```
|
||||
|
||||
- Short, descriptive, keyword-rich
|
||||
- Lowercase, hyphens between words
|
||||
- No special characters (å→a, ä→a, ö→o)
|
||||
- Consistent with URL structure pattern from project brief
|
||||
|
||||
### 2. Heading Hierarchy
|
||||
|
||||
Verify the page has:
|
||||
|
||||
- [ ] **Exactly one H1** — Contains primary keyword
|
||||
- [ ] **Logical H2 → H3 flow** — No skipped levels
|
||||
- [ ] **Keywords in headings** — Natural placement, not stuffed
|
||||
- [ ] **H1 differs from page title tag** if needed (H1 = on-page, title = search results)
|
||||
|
||||
Document in page spec:
|
||||
|
||||
```markdown
|
||||
### Heading Hierarchy
|
||||
|
||||
| Level | Content | Keyword |
|
||||
|-------|---------|---------|
|
||||
| H1 | {Main page heading} | {primary keyword} |
|
||||
| H2 | {Section heading} | {secondary keyword} |
|
||||
| H3 | {Subsection heading} | — |
|
||||
```
|
||||
|
||||
### 3. Internal Links
|
||||
|
||||
Every public page should link to at least 2 other pages on the site.
|
||||
|
||||
- [ ] **Descriptive anchor text** — "Läs mer om vår AC-service" not "Klicka här"
|
||||
- [ ] **Related content links** — Service ↔ vehicle type, article ↔ service
|
||||
- [ ] **CTA links** — Contact, phone, booking
|
||||
|
||||
Document link targets:
|
||||
|
||||
```markdown
|
||||
### Internal Links
|
||||
|
||||
| Anchor Text | Target Page | Context |
|
||||
|-------------|-------------|---------|
|
||||
| "Läs mer om service" | /service | About section |
|
||||
| "Ring oss" | tel:+46485-27070 | CTA section |
|
||||
```
|
||||
|
||||
### 4. Image SEO
|
||||
|
||||
For every image on the page:
|
||||
|
||||
- [ ] **Alt text in all languages** — Descriptive, keyword where relevant
|
||||
- [ ] **File name** — Descriptive (`verkstad-ac-service.jpg` not `IMG_001.jpg`)
|
||||
- [ ] **Dimensions specified** — Width and height attributes (prevents CLS)
|
||||
- [ ] **Max file size** — < 200KB per image (hero images < 400KB)
|
||||
- [ ] **Format** — WebP with JPEG/PNG fallback
|
||||
- [ ] **Lazy loading** — For below-the-fold images
|
||||
- [ ] **Responsive** — srcset for mobile/desktop versions of large images
|
||||
|
||||
### 5. Meta Content
|
||||
|
||||
Include the meta content section (see [meta-content.instructions.md](meta-content.instructions.md)):
|
||||
|
||||
- [ ] **Page title** — ≤ 60 chars, includes primary keyword + brand
|
||||
- [ ] **Meta description** — 150-160 chars, includes keyword + CTA
|
||||
- [ ] **Social sharing** — Title, description, image
|
||||
|
||||
### 6. Structured Data
|
||||
|
||||
If the project brief's structured data plan includes this page type:
|
||||
|
||||
```markdown
|
||||
### Structured Data
|
||||
|
||||
**Schema Type:** {e.g., Service, Article, FAQPage}
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| name | {service/article name} |
|
||||
| description | {from meta description} |
|
||||
| provider | {business name} |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SEO Section Template
|
||||
|
||||
Add this section to the page specification:
|
||||
|
||||
```markdown
|
||||
## SEO & Search
|
||||
|
||||
**Primary Keyword (SE):** {keyword}
|
||||
**Primary Keyword (EN):** {keyword}
|
||||
**Primary Keyword (DE):** {keyword}
|
||||
**URL:** /{slug}
|
||||
|
||||
### Page Title (Browser Tab & Search Results)
|
||||
|
||||
- SE: "{title} | {brand}" (≤ 60 chars)
|
||||
- EN: "{title} | {brand}" (≤ 60 chars)
|
||||
- DE: "{title} | {brand}" (≤ 60 chars)
|
||||
|
||||
### Meta Description
|
||||
|
||||
- SE: "{description with keyword and CTA}" (150-160 chars)
|
||||
- EN: "{description with keyword and CTA}" (150-160 chars)
|
||||
- DE: "{description with keyword and CTA}" (150-160 chars)
|
||||
|
||||
### Heading Hierarchy
|
||||
|
||||
| Level | SE | EN | DE | Keyword |
|
||||
|-------|----|----|----|---------|
|
||||
| H1 | ... | ... | ... | primary |
|
||||
| H2 | ... | ... | ... | secondary |
|
||||
|
||||
### Structured Data
|
||||
|
||||
**Type:** {Schema type}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Meta Content Instructions](meta-content.instructions.md) — Detailed meta content specification
|
||||
- [SEO Strategy Guide](../../../data/agent-guides/saga/seo-strategy-guide.md) — Comprehensive SEO reference
|
||||
- [Specification Quality](../../../data/agent-guides/freya/specification-quality.md) — Quality checklist
|
||||
|
||||
---
|
||||
|
||||
*Every public page is a search result. Specify it accordingly.*
|
||||
@@ -0,0 +1,314 @@
|
||||
<!--
|
||||
NAVIGATION BEST PRACTICE: Navigation links appear in THREE places:
|
||||
1. Above the sketch (top)
|
||||
2. Below the sketch (still in header area)
|
||||
3. At document bottom
|
||||
This is intentional for long specifications - users should not need to
|
||||
scroll the entire document to navigate between pages.
|
||||
-->
|
||||
|
||||
### {page-number}-{page-name}
|
||||
|
||||
**Previous Step:** ← [{previous-page-name}]({previous-page-path})
|
||||
**Next Step:** → [{next-page-name}]({next-page-path})
|
||||
|
||||
|
||||
|
||||
**Previous Step:** ← [{previous-page-name}]({previous-page-path})
|
||||
**Next Step:** → [{next-page-name}]({next-page-path})
|
||||
|
||||
---
|
||||
|
||||
# {page-number}-{page-name}
|
||||
|
||||
## Page Metadata
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Scenario** | {scenario-name} |
|
||||
| **Page Number** | {page-number} |
|
||||
| **Platform** | {Mobile web / Desktop / PWA / Native} |
|
||||
| **Page Type** | {Full Page / Modal / Drawer / Popup} |
|
||||
| **Viewport** | {Mobile-first / Desktop-first} |
|
||||
| **Interaction** | {Touch-first / Mouse+keyboard} |
|
||||
| **Visibility** | {Public / Authenticated / Admin} |
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**Page Purpose:** {What job must this page accomplish?}
|
||||
|
||||
**User Situation:** {What brings the user here?}
|
||||
|
||||
**Success Criteria:** {How will we know this page succeeded?}
|
||||
|
||||
**Entry Points:**
|
||||
- {How users arrive}
|
||||
|
||||
**Exit Points:**
|
||||
- {Where users go next}
|
||||
|
||||
---
|
||||
|
||||
## Reference Materials
|
||||
|
||||
**Strategic Foundation:**
|
||||
- [Product Brief]({path}) - {brief description}
|
||||
- [Trigger Map]({path}) - {brief description}
|
||||
|
||||
**Related Pages:**
|
||||
- [{Related Page}]({path})
|
||||
|
||||
**Design System:**
|
||||
- [{Component}]({path})
|
||||
|
||||
---
|
||||
|
||||
## Layout Structure
|
||||
|
||||
{High-level description of page layout}
|
||||
|
||||
```
|
||||
[ASCII layout diagram]
|
||||
+------------------+
|
||||
| Header |
|
||||
+------------------+
|
||||
| Main Content |
|
||||
+------------------+
|
||||
| Footer |
|
||||
+------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Spacing
|
||||
|
||||
<!--
|
||||
All spacing values MUST use token names from the project's spacing scale.
|
||||
The scale is defined in D-Design-System/00-design-system.md → Spacing Scale.
|
||||
This can be the WDS default scale, Tailwind classes, Material tokens, or any system.
|
||||
Do NOT use arbitrary pixel values. If unsure, check the scale.
|
||||
-->
|
||||
|
||||
**Scale:** [Spacing Scale](../../D-Design-System/00-design-system.md#spacing-scale)
|
||||
|
||||
| Property | Token |
|
||||
|----------|-------|
|
||||
| Page padding (horizontal) | {e.g., space-md mobile / space-lg desktop} |
|
||||
| Section gap | {e.g., space-xl} |
|
||||
| Element gap (default within sections) | {e.g., space-md} |
|
||||
| Component gap (within groups) | {e.g., space-sm} |
|
||||
|
||||
---
|
||||
|
||||
## Typography
|
||||
|
||||
<!--
|
||||
Text sizes use token names from the project's type scale.
|
||||
The scale is defined in D-Design-System/00-design-system.md → Type Scale.
|
||||
|
||||
IMPORTANT: Semantic level (H1, H2, p) signals document structure — for accessibility and SEO.
|
||||
Visual styling (size, weight, typeface) signals visual hierarchy — how it looks.
|
||||
They are related but NOT locked together. An H2 can be text-sm. A <p> can be text-2xl.
|
||||
Headings can have different typefaces and styles on different pages — that's fine.
|
||||
-->
|
||||
|
||||
**Scale:** [Type Scale](../../D-Design-System/00-design-system.md#type-scale)
|
||||
|
||||
| Element | Semantic | Size | Weight | Typeface |
|
||||
|---------|----------|------|--------|----------|
|
||||
| {Page title} | H1 | {e.g., text-2xl} | {e.g., bold} | {e.g., display / default} |
|
||||
| {Section heading} | H2 | {e.g., text-xl} | {e.g., semibold} | {default} |
|
||||
| {Body text} | p | text-md | normal | {default} |
|
||||
| {Caption/helper} | p | {e.g., text-xs} | normal | {default} |
|
||||
|
||||
---
|
||||
|
||||
## Page Sections
|
||||
|
||||
### Section: {Section Name}
|
||||
|
||||
**OBJECT ID:** `{page-name}-{section-name}`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Purpose | {What this section does} |
|
||||
| Component | [{Design System Component}]({path}) |
|
||||
| Padding | {e.g., space-lg space-md} |
|
||||
| Element gap | {e.g., space-md — or "default" if same as page-level} |
|
||||
|
||||
---
|
||||
|
||||
#### {Object Name}
|
||||
|
||||
**OBJECT ID:** `{page-name}-{object-name}`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Component | [{Component}]({path}) |
|
||||
| Translation Key | `{translation.key}` |
|
||||
| SE | "{Swedish text}" |
|
||||
| EN | "{English text}" |
|
||||
| Behavior | {onClick / onChange / etc.} |
|
||||
|
||||
#### ↕ `{page}-{v|h}-{type}-{size}` — {reason}
|
||||
|
||||
<!--
|
||||
Spacing objects sit between content objects. They have IDs and are first-class.
|
||||
|
||||
NAMING: {page}-{v|h}-{type}-{size}
|
||||
- v = vertical, h = horizontal
|
||||
- type = space, separator, line
|
||||
- size = the token name (zero, sm, md, lg, xl, 2xl, 3xl, flex)
|
||||
The ID describes WHAT the spacing IS, not which objects it sits between.
|
||||
|
||||
RULES:
|
||||
- Default element spacing (from the Spacing section above) is implicit — no spacing object needed.
|
||||
- Non-default spacing MUST be an explicit spacing object with an ID.
|
||||
- Zero spacing (overlap / flush) MUST be documented: ↕ `id` — space-zero (reason)
|
||||
- Same spacing shared by all items in a group → define on the group, not between each item.
|
||||
- Spacing objects flow into D-Design-System/00-design-system.md → Patterns.
|
||||
|
||||
FORMAT: #### ↕ `{id}` — {reason}
|
||||
|
||||
EXAMPLES:
|
||||
#### ↕ `hem-v-space-zero` — header and service menu form one continuous nav unit
|
||||
#### ↕ `hem-v-separator-2xl` — gray line, space-2xl above and below. Separates about from trust cards.
|
||||
#### ↕ `hem-v-space-3xl` — major section boundary between seasons and footer
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
#### {Object Name 2}
|
||||
|
||||
**OBJECT ID:** `{page-name}-{object-name-2}`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Component | [{Component}]({path}) |
|
||||
| Translation Key | `{translation.key}` |
|
||||
| SE | "{Swedish text}" |
|
||||
| EN | "{English text}" |
|
||||
|
||||
---
|
||||
|
||||
#### {Group Name} (Container)
|
||||
|
||||
**OBJECT ID:** `{page-name}-{group-name}`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Component | [{Container Component}]({path}) |
|
||||
| Purpose | {Groups related objects} |
|
||||
| Layout | {Horizontal / Vertical / Grid} |
|
||||
|
||||
##### {Object in Group}
|
||||
|
||||
**OBJECT ID:** `{page-name}-{group-name}-{object}`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Component | [{Component}]({path}) |
|
||||
| Translation Key | `{translation.key}` |
|
||||
| SE | "{Swedish text}" |
|
||||
| EN | "{English text}" |
|
||||
|
||||
##### ↕ `{page-name}-{group-name}-{obj1}-{obj2}-gap` — {spacing token}
|
||||
|
||||
##### {Object in Group 2}
|
||||
|
||||
**OBJECT ID:** `{page-name}-{group-name}-{object-2}`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Component | [{Component}]({path}) |
|
||||
| Translation Key | `{translation.key}` |
|
||||
| SE | "{Swedish text}" |
|
||||
| EN | "{English text}" |
|
||||
|
||||
---
|
||||
|
||||
## Page States
|
||||
|
||||
| State | When | Appearance | Actions |
|
||||
|-------|------|------------|---------|
|
||||
| Default | {condition} | {description} | {available actions} |
|
||||
| Loading | {condition} | {description} | {available actions} |
|
||||
| Empty | {condition} | {description} | {available actions} |
|
||||
| Error | {condition} | {description} | {recovery actions} |
|
||||
| Success | {condition} | {description} | {next steps} |
|
||||
|
||||
---
|
||||
|
||||
## Conditional Sections
|
||||
|
||||
Include these micro-instructions when applicable:
|
||||
|
||||
| Condition | Include |
|
||||
|-----------|---------|
|
||||
| Public page (SEO needed) | → [meta-content.instructions.md](instructions/meta-content.instructions.md) |
|
||||
| Public page (SEO needed) | → [seo-content.instructions.md](instructions/seo-content.instructions.md) |
|
||||
| Has forms/inputs | → [form-validation.instructions.md](instructions/form-validation.instructions.md) |
|
||||
| Needs API data | → [data-api.instructions.md](instructions/data-api.instructions.md) |
|
||||
| Multiple breakpoints | → [responsive.instructions.md](instructions/responsive.instructions.md) |
|
||||
| Final review | → [accessibility.instructions.md](instructions/accessibility.instructions.md) |
|
||||
| Multiple sketches | → [storyboard-specification.template.md](storyboard-specification.template.md) |
|
||||
| **Always (spec creation/audit)** | → [open-questions.instructions.md](instructions/open-questions.instructions.md) |
|
||||
|
||||
---
|
||||
|
||||
## Technical Notes
|
||||
|
||||
{Any constraints, performance requirements, or implementation notes}
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
<!--
|
||||
This section captures decisions needed before development.
|
||||
During spec creation or audits, auto-populate questions based on:
|
||||
→ instructions/open-questions.instructions.md
|
||||
|
||||
Categories to check:
|
||||
- Responsive breakpoints (if multiple viewports)
|
||||
- Loading/Error/Empty states (if API data)
|
||||
- SEO meta content (if public page)
|
||||
- Accessibility requirements
|
||||
- User permissions/roles
|
||||
- Time-sensitive behaviors
|
||||
- Form validation rules
|
||||
- Navigation/back behavior
|
||||
-->
|
||||
|
||||
_No open questions at this time._
|
||||
|
||||
<!-- When questions exist, use this format:
|
||||
| # | Question | Context | Status |
|
||||
|---|----------|---------|--------|
|
||||
| 1 | {What needs to be decided?} | {Why it matters} | 🔴 Open |
|
||||
| 2 | {Question} | {Context} | 🟢 Resolved: {answer} |
|
||||
|
||||
**Status Legend:** 🔴 Open | 🟡 In Discussion | 🟢 Resolved
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Page purpose clear
|
||||
- [ ] All Object IDs assigned
|
||||
- [ ] Components reference design system
|
||||
- [ ] Translations complete (SE/EN)
|
||||
- [ ] States documented
|
||||
- [ ] Conditional sections included where needed
|
||||
|
||||
---
|
||||
|
||||
**Previous Step:** ← [{previous-page-name}]({previous-page-path})
|
||||
**Next Step:** → [{next-page-name}]({next-page-path})
|
||||
|
||||
---
|
||||
|
||||
_Created using Whiteport Design Studio (WDS) methodology_
|
||||
@@ -0,0 +1,159 @@
|
||||
# {scenario-number}-{scenario-name}
|
||||
|
||||
**Project:** {project-name}
|
||||
**Created:** {date}
|
||||
**Method:** Whiteport Design Studio (WDS)
|
||||
|
||||
---
|
||||
|
||||
## Scenario Overview
|
||||
|
||||
**User Journey:** {High-level description of what users accomplish in this scenario}
|
||||
|
||||
**Entry Point:** {Where users begin this scenario}
|
||||
**Success Exit:** {Where users end after successful completion}
|
||||
**Alternative Exits:** {Other possible endpoints - errors, cancellations, etc.}
|
||||
|
||||
**Target Personas:** {Which personas from Trigger Map use this scenario}
|
||||
|
||||
---
|
||||
|
||||
## Pages in This Scenario
|
||||
|
||||
| Page # | Page Name | Status | Purpose |
|
||||
| ------ | ----------- | ---------------- | --------------- |
|
||||
| {n}.1 | {page-name} | {draft/complete} | {Brief purpose} |
|
||||
| {n}.2 | {page-name} | {draft/complete} | {Brief purpose} |
|
||||
| {n}.3 | {page-name} | {draft/complete} | {Brief purpose} |
|
||||
|
||||
---
|
||||
|
||||
## User Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[{Entry Point}] --> B[{Page n.1}]
|
||||
B --> C[{Page n.2}]
|
||||
C --> D{{Decision Point?}}
|
||||
D -->|Yes| E[{Page n.3}]
|
||||
D -->|No| F[{Alternative Path}]
|
||||
E --> G[{Success Exit}]
|
||||
F --> G
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scenario Steps
|
||||
|
||||
### Step 1: {Step Name}
|
||||
|
||||
**Page:** {n.1-Page-Name}
|
||||
**User Action:** {What the user does}
|
||||
**System Response:** {How the system responds}
|
||||
**Success Criteria:** {What defines success for this step}
|
||||
|
||||
### Step 2: {Step Name}
|
||||
|
||||
**Page:** {n.2-Page-Name}
|
||||
**User Action:** {What the user does}
|
||||
**System Response:** {How the system responds}
|
||||
**Success Criteria:** {What defines success for this step}
|
||||
|
||||
{Repeat for all steps}
|
||||
|
||||
---
|
||||
|
||||
## Trigger Map Connections
|
||||
|
||||
### Positive Drivers Addressed
|
||||
|
||||
From Trigger Map analysis, this scenario serves these user goals:
|
||||
|
||||
- ✅ {Positive goal from Trigger Map}
|
||||
- ✅ {Positive goal from Trigger Map}
|
||||
|
||||
### Negative Drivers Avoided
|
||||
|
||||
This scenario helps users avoid:
|
||||
|
||||
- ❌ {Negative outcome from Trigger Map}
|
||||
- ❌ {Negative outcome from Trigger Map}
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
**Primary Metric:** {Main measure of scenario success}
|
||||
|
||||
**Secondary Metrics:**
|
||||
|
||||
- {Metric 1}
|
||||
- {Metric 2}
|
||||
|
||||
**User Satisfaction Indicators:**
|
||||
|
||||
- {What indicates good user experience}
|
||||
|
||||
---
|
||||
|
||||
## Edge Cases & Error Handling
|
||||
|
||||
| Edge Case | How Handled | Page(s) Affected |
|
||||
| ----------------------- | ------------------- | ----------------- |
|
||||
| {edge-case-description} | {handling-approach} | {page-references} |
|
||||
|
||||
---
|
||||
|
||||
## Technical Requirements
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
{Entry} → [Fetch Data] → {Display} → [User Action] → [Validate] → [API Call] → {Success}
|
||||
```
|
||||
|
||||
### API Endpoints Used
|
||||
|
||||
| Endpoint | Page(s) | Purpose |
|
||||
| --------------- | ----------- | -------------- |
|
||||
| {endpoint-path} | {page-refs} | {what-it-does} |
|
||||
|
||||
### State Management
|
||||
|
||||
{How state is managed across pages in this scenario}
|
||||
|
||||
---
|
||||
|
||||
## Design Assets
|
||||
|
||||
**Scenario Folder:** `C-UX-Scenarios/{scenario-number}-{scenario-name}/`
|
||||
|
||||
**Page Specifications:**
|
||||
|
||||
- {n}.1-{page-name}/{page-name}.md
|
||||
- {n}.2-{page-name}/{page-name}.md
|
||||
- {n}.3-{page-name}/{page-name}.md
|
||||
|
||||
**Prototypes:**
|
||||
|
||||
- {n}.1-{page-name}/Prototype/
|
||||
- {n}.2-{page-name}/Prototype/
|
||||
- {n}.3-{page-name}/Prototype/
|
||||
|
||||
---
|
||||
|
||||
## Development Notes
|
||||
|
||||
{Any scenario-level technical considerations, performance requirements, security notes, etc.}
|
||||
|
||||
---
|
||||
|
||||
## Revision History
|
||||
|
||||
| Date | Changes | Author |
|
||||
| ------ | ------------------------ | -------- |
|
||||
| {date} | Initial scenario created | {author} |
|
||||
|
||||
---
|
||||
|
||||
_Created using Whiteport Design Studio (WDS) methodology_
|
||||
@@ -0,0 +1,94 @@
|
||||
# Storyboard Extension
|
||||
|
||||
**Use when:** Page has multiple sketches (multi-step flows, state changes, transitions)
|
||||
|
||||
**Base:** Start with [page-specification.template.md](page-specification.template.md)
|
||||
|
||||
---
|
||||
|
||||
## What Changes
|
||||
|
||||
### 1. Add State Flow Overview (before Page Sections)
|
||||
|
||||
After Reference Materials, add:
|
||||
|
||||
```markdown
|
||||
## State Flow Overview
|
||||
|
||||
{Brief description of states}
|
||||
|
||||
|
||||
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ STATE 1 │───▶│ STATE 2 │───▶│ STATE 3 │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
|
||||
| State | Name | Visual | Entry | Actions |
|
||||
|-------|------|--------|-------|---------|
|
||||
| **1** | {name} | {color/icon} | {trigger} | {actions} |
|
||||
| **2** | {name} | {color/icon} | {trigger} | {actions} |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. State 1 = Normal Page Specification
|
||||
|
||||
Document State 1 using the standard page spec structure:
|
||||
- Page Sections
|
||||
- Objects with OBJECT IDs
|
||||
- Groups with nested objects
|
||||
|
||||
This is the **baseline** that other states reference.
|
||||
|
||||
---
|
||||
|
||||
### 3. States 2+ = Differences Only
|
||||
|
||||
After State 1, add for each additional state:
|
||||
|
||||
```markdown
|
||||
# State 2: {State Name} — Differences from State 1
|
||||
|
||||
|
||||
|
||||
> **The Story:** {User experience narrative}
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Purpose | {what this state does} |
|
||||
| Entry | {trigger from previous state} |
|
||||
| Previous | State 1 |
|
||||
| Next | State 3 / {options} |
|
||||
|
||||
### Changes from State 1
|
||||
|
||||
| OBJECT ID | Change | Details |
|
||||
|-----------|--------|---------|
|
||||
| `{existing-id}` | Modified | {what changed} |
|
||||
| `{existing-id}` | Hidden | {why hidden} |
|
||||
| `{new-id}` | Added | {new element} |
|
||||
|
||||
### State 2 Elements
|
||||
|
||||
{Only document NEW objects not in State 1}
|
||||
|
||||
#### {New Object}
|
||||
|
||||
**OBJECT ID:** `{page-name}-{new-object}`
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Component | [{Component}]({path}) |
|
||||
| Translation Key | `{key}` |
|
||||
| SE | "{text}" |
|
||||
| EN | "{text}" |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **State 1 is baseline** — fully documented
|
||||
2. **States 2+ show only changes** — reuse OBJECT IDs
|
||||
3. **Same IDs across states** — `booking-detail-header` stays the same, just describe what changed
|
||||
4. **New elements get new IDs** — only in the state they first appear
|
||||
@@ -0,0 +1,192 @@
|
||||
# WDS Test Scenario Template
|
||||
# Save to: test-scenarios/TS-XXX-name.yaml
|
||||
|
||||
test_scenario:
|
||||
id: "TS-XXX" # Format: TS-001, TS-002, etc.
|
||||
name: "Feature Testing" # Human-readable name
|
||||
delivery_id: "DD-XXX" # Related Design Delivery
|
||||
type: "user_acceptance" # user_acceptance | integration | e2e
|
||||
status: "ready" # ready | in_progress | blocked
|
||||
tester: "designer" # designer | qa | developer
|
||||
created_at: "YYYY-MM-DDTHH:MM:SSZ"
|
||||
|
||||
test_objectives:
|
||||
- "Validate implementation matches design specifications"
|
||||
- "Verify user flow is intuitive and smooth"
|
||||
- "Confirm all edge cases are handled"
|
||||
- "Ensure design system components are used correctly"
|
||||
- "Test accessibility and usability"
|
||||
|
||||
test_environment:
|
||||
devices:
|
||||
- "Device 1 (OS version)"
|
||||
- "Device 2 (OS version)"
|
||||
|
||||
test_data:
|
||||
- field: "value"
|
||||
- field: "value"
|
||||
|
||||
# Happy Path Tests
|
||||
happy_path:
|
||||
- id: "HP-001"
|
||||
name: "Main User Flow"
|
||||
priority: "critical" # critical | high | medium | low
|
||||
|
||||
steps:
|
||||
- action: "[User action]"
|
||||
expected: "[Expected result]"
|
||||
design_ref: "[Path to specification]#[section]"
|
||||
|
||||
- action: "[User action]"
|
||||
expected: "[Expected result]"
|
||||
design_ref: "[Path to specification]#[section]"
|
||||
|
||||
success_criteria:
|
||||
- "[Success criterion 1]"
|
||||
- "[Success criterion 2]"
|
||||
- "[Success criterion 3]"
|
||||
|
||||
# Error State Tests
|
||||
error_states:
|
||||
- id: "ES-001"
|
||||
name: "Error Scenario"
|
||||
priority: "high"
|
||||
|
||||
steps:
|
||||
- action: "[Action that triggers error]"
|
||||
- expected: "[Expected error message]"
|
||||
- expected: "[Expected recovery option]"
|
||||
- design_ref: "[Path to specification]#[error-section]"
|
||||
|
||||
success_criteria:
|
||||
- "[Error handling criterion 1]"
|
||||
- "[Error handling criterion 2]"
|
||||
|
||||
# Edge Case Tests
|
||||
edge_cases:
|
||||
- id: "EC-001"
|
||||
name: "Edge Case Scenario"
|
||||
priority: "medium"
|
||||
|
||||
steps:
|
||||
- action: "[Unusual action]"
|
||||
- expected: "[Expected handling]"
|
||||
- design_ref: "[Path to specification]#[edge-case-section]"
|
||||
|
||||
success_criteria:
|
||||
- "[Edge case criterion 1]"
|
||||
|
||||
# Design System Validation
|
||||
design_system_checks:
|
||||
- id: "DS-001"
|
||||
name: "Component Validation"
|
||||
checks:
|
||||
- component: "Component Name"
|
||||
instances: ["Location 1", "Location 2"]
|
||||
verify:
|
||||
- "[Visual property 1]"
|
||||
- "[Visual property 2]"
|
||||
- "[State behavior 1]"
|
||||
design_ref: "D-Design-System/path/to/component.md"
|
||||
|
||||
# Accessibility Tests
|
||||
accessibility:
|
||||
- id: "A11Y-001"
|
||||
name: "Screen Reader Navigation"
|
||||
priority: "high"
|
||||
|
||||
setup: "Enable screen reader (VoiceOver/TalkBack)"
|
||||
|
||||
steps:
|
||||
- action: "[Navigate with screen reader]"
|
||||
- verify:
|
||||
- "[Accessibility check 1]"
|
||||
- "[Accessibility check 2]"
|
||||
|
||||
success_criteria:
|
||||
- "[Accessibility criterion 1]"
|
||||
- "[Accessibility criterion 2]"
|
||||
|
||||
# Usability Tests
|
||||
usability:
|
||||
- id: "UX-001"
|
||||
name: "First Impression"
|
||||
type: "observational"
|
||||
|
||||
instructions: |
|
||||
[Instructions for conducting usability test]
|
||||
|
||||
success_criteria:
|
||||
- "[Usability criterion 1]"
|
||||
- "[Usability criterion 2]"
|
||||
|
||||
# Performance Tests
|
||||
performance:
|
||||
- id: "PERF-001"
|
||||
name: "Performance Check"
|
||||
|
||||
verify:
|
||||
- "[Performance metric 1]"
|
||||
- "[Performance metric 2]"
|
||||
|
||||
success_criteria:
|
||||
- "[Performance target 1]"
|
||||
- "[Performance target 2]"
|
||||
|
||||
# Test Report Template
|
||||
report_template:
|
||||
sections:
|
||||
- name: "Test Summary"
|
||||
fields:
|
||||
- "Date tested"
|
||||
- "Tester name"
|
||||
- "Device tested"
|
||||
- "Build version"
|
||||
- "Overall result (Pass/Fail/Partial)"
|
||||
|
||||
- name: "Happy Path Results"
|
||||
fields:
|
||||
- "Test ID"
|
||||
- "Result (Pass/Fail)"
|
||||
- "Notes"
|
||||
- "Screenshots"
|
||||
|
||||
- name: "Issues Found"
|
||||
fields:
|
||||
- "Issue ID"
|
||||
- "Severity (Critical/High/Medium/Low)"
|
||||
- "Description"
|
||||
- "Steps to reproduce"
|
||||
- "Expected vs Actual"
|
||||
- "Screenshot/Video"
|
||||
- "Design reference violated"
|
||||
|
||||
- name: "Design System Compliance"
|
||||
fields:
|
||||
- "Component"
|
||||
- "Compliant (Yes/No)"
|
||||
- "Deviations noted"
|
||||
|
||||
- name: "Recommendations"
|
||||
fields:
|
||||
- "What worked well"
|
||||
- "What needs improvement"
|
||||
- "Suggested changes"
|
||||
|
||||
# Sign-off Criteria
|
||||
sign_off:
|
||||
required_for_approval:
|
||||
- "All critical tests pass"
|
||||
- "No critical or high severity issues"
|
||||
- "Design system compliance > 95%"
|
||||
- "Accessibility tests pass"
|
||||
- "Usability metrics meet targets"
|
||||
|
||||
designer_approval:
|
||||
statement: |
|
||||
I confirm that the implemented feature matches the design
|
||||
specifications and meets the quality standards defined in
|
||||
this test scenario.
|
||||
|
||||
signature: "________________"
|
||||
date: "________________"
|
||||
Reference in New Issue
Block a user