whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/templates/instructions/data-api.instructions.md

@@ -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} |

package/src/workflows/4-ux-design/templates/instructions/form-validation.instructions.md

@@ -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} |

package/src/workflows/4-ux-design/templates/instructions/meta-content.instructions.md

@@ -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)

package/src/workflows/4-ux-design/templates/instructions/open-questions.instructions.md

@@ -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._

package/src/workflows/4-ux-design/templates/instructions/responsive.instructions.md

@@ -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.} |

package/src/workflows/4-ux-design/templates/page-specification.template.md

@@ -0,0 +1,227 @@
+<!--
+  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})
+
+![{Page Name}](Sketches/{page-number}-{page-name}.jpg)
+
+**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           |
++------------------+
+```
+
+---
+
+## Page Sections
+
+### Section: {Section Name}
+
+**OBJECT ID:** `{page-name}-{section-name}`
+
+| Property | Value |
+|----------|-------|
+| Purpose | {What this section does} |
+| Component | [{Design System Component}]({path}) |
+
+---
+
+#### {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.} |
+
+---
+
+#### {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}" |
+
+##### {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) |
+| 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_