whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/substeps/4c-03-components-objects.md

@@ -0,0 +1,154 @@
+# Substep 4C-03: Components & Object IDs
+
+**Goal:** Identify all interactive elements, route to object-specific instructions, and assign Object IDs
+
+---
+
+## EXECUTION
+
+<output>**Let's identify and document every component systematically.**
+
+We'll work through each section, going **top-to-bottom, left-to-right** within each section, documenting each object using specialized instructions.</output>
+
+---
+
+## FOR EACH SECTION
+
+<action>For each section identified in 4C-02:
+
+<output>**Section: {{section_name}}**
+
+Starting from top-left corner of this section...</output>
+
+## FOR EACH OBJECT IN SECTION
+
+<action>Loop through objects in section (top-to-bottom, left-to-right):
+
+<output>**Next object in {{section_name}}:**</output>
+
+<ask>What is the first/next object in this section (from top-left)?
+
+Describe what you see:</ask>
+
+<action>Store object_description</action>
+
+### ROUTE TO OBJECT-TYPE INSTRUCTIONS
+
+<action>Load and execute `object-types/object-router.md`</action>
+
+<action>Object-router will: 1. Ask user to identify object type 2. Load appropriate object-type instruction file 3. Guide through complete object documentation 4. Generate specification with Object ID 5. Return here when complete
+</action>
+
+### DESIGN SYSTEM CHECK (IF ENABLED)
+
+<action>After component specification complete: 1. Check project config: Is design system enabled? 2. If YES: Load and execute `workflows/5-design-system/design-system-router.md` 3. Design system router will: - Check for similar components - Run opportunity/risk assessment if needed - Extract component-level info to design system - Return component reference - Update page spec with reference 4. If NO: Keep complete specification on page 5. Continue to next object
+</action>
+
+<ask>**More objects in {{section_name}}?**
+
+1. **Yes** - Document next object (move right, then down)
+2. **No** - Section complete
+
+Choice [1/2]:</ask>
+
+  <check if="choice == 1">
+    <action>Loop back to document next object in section</action>
+  </check>
+  
+  <check if="choice == 2">
+    <output>✅ **Section {{section_name}} complete!**</output>
+    <action>Move to next section</action>
+  </check>
+
+</action>
+
+</action>
+
+---
+
+## ALL SECTIONS COMPLETE
+
+<output>✅ **All components identified and documented!**
+
+**Summary:**
+
+- **Sections processed:** {{section_count}}
+- **Total components:** {{component_count}}
+- **Components by type:**
+  {{#each component_type}}
+  - {{type_name}}: {{count}}
+    {{/each}}
+
+**Object IDs assigned:**
+{{#each component}}
+
+- `{{object_id}}` ({{component_type}})
+  {{/each}}
+
+**Next:** We'll specify the content and languages.</output>
+
+---
+
+## MENU
+
+<ask>[C] Continue to 4C-04 (Content & Languages)</ask>
+
+---
+
+## WORKFLOW NOTES
+
+**This substep uses object-type routing:**
+
+1. For each object, user identifies the type
+2. System loads specialized instruction file (button.md, text-input.md, etc.)
+3. Each instruction file has:
+   - Precise questions for that object type
+   - Complete example outputs
+   - Consistent format across all WDS projects
+4. After documentation, control returns here
+5. Continue until all objects in all sections are documented
+
+**Benefits:**
+
+- ✅ Consistent specifications across all WDS projects
+- ✅ Agents have clear, focused instructions for each object type
+- ✅ Example-driven (show, don't tell)
+- ✅ Systematic coverage (nothing missed)
+- ✅ Reusable patterns across repositories
+
+---
+
+## EXAMPLE COMPONENT REGISTRY
+
+```yaml
+sections_processed:
+  - signin-form:
+      components:
+        - object_id: 'signin-form-email-input'
+          type: 'text-input'
+          documented_via: 'object-types/text-input.md'
+
+        - object_id: 'signin-form-password-input'
+          type: 'text-input'
+          documented_via: 'object-types/text-input.md'
+
+        - object_id: 'signin-form-submit-button'
+          type: 'button'
+          documented_via: 'object-types/button.md'
+
+        - object_id: 'signin-form-forgot-link'
+          type: 'link'
+          documented_via: 'object-types/link.md'
+
+total_components: 4
+component_types:
+  text-input: 2
+  button: 1
+  link: 1
+```
+
+---
+
+## NEXT STEP
+
+Load `substeps/4c-04-content-languages.md`

package/src/workflows/4-ux-design/substeps/4c-04-content-languages.md

@@ -0,0 +1,83 @@
+# Substep 4C-04: Content & Languages
+
+**Goal:** Specify all text content in all supported languages
+
+---
+
+## EXECUTION
+
+<ask>**What languages does this page support?**
+
+List all languages (e.g., English, Swedish, Spanish):</ask>
+
+<action>Store supported_languages array</action>
+
+<output>**Now let's specify all text content.**
+
+We'll go through each text element and provide content in all {{language_count}} languages.</output>
+
+<action>For each text element (labels, buttons, headings, messages):
+<ask>**{{element_name}}:**
+
+{{#each language}}
+
+- {{language}}:
+  {{/each}}
+  </ask>
+
+<action>Store multilingual content for element</action>
+</action>
+
+<output>✅ **Content specified in all languages!**
+
+**Languages:** {{languages_list}}
+**Text elements:** {{text_element_count}}
+
+**Next:** We'll define interactions and behaviors.</output>
+
+---
+
+## MENU
+
+<ask>[C] Continue to 4C-05 (Interactions)</ask>
+
+---
+
+## EXAMPLE OUTPUT
+
+```yaml
+supported_languages:
+  - English
+  - Swedish
+
+content:
+  page_title:
+    en: 'Sign In'
+    sv: 'Logga In'
+
+  email_label:
+    en: 'Email Address'
+    sv: 'E-postadress'
+
+  email_placeholder:
+    en: 'your@email.com'
+    sv: 'din@epost.com'
+
+  password_label:
+    en: 'Password'
+    sv: 'Lösenord'
+
+  submit_button:
+    en: 'Sign In'
+    sv: 'Logga In'
+
+  forgot_password_link:
+    en: 'Forgot password?'
+    sv: 'Glömt lösenord?'
+```
+
+---
+
+## NEXT STEP
+
+Load `substeps/4c-05-interactions.md`

package/src/workflows/4-ux-design/substeps/4c-05-interactions.md

@@ -0,0 +1,82 @@
+# Substep 4C-05: Interactions
+
+**Goal:** Define what happens when users interact with each component
+
+---
+
+## EXECUTION
+
+<output>**Let's define all interactions.**
+
+For each interactive element, we'll specify what happens when users interact with it.</output>
+
+<action>For each component with Object ID:
+<ask>**{{object_id}}** ({{element_type}})
+
+What happens when the user interacts with this?
+
+- On click / on input / on focus?
+- What's the immediate response?
+- What state changes occur?
+- Where does it navigate (if applicable)?
+- What data is sent/received?
+  </ask>
+
+<action>Store interaction_behavior for component</action>
+</action>
+
+<output>✅ **Interactions defined!**
+
+**Components with behaviors:** {{interactive_count}}
+
+**Next:** We'll define all possible states.</output>
+
+---
+
+## MENU
+
+<ask>[C] Continue to 4C-06 (States)</ask>
+
+---
+
+## EXAMPLE OUTPUT
+
+```yaml
+interactions:
+  signin-form-email-input:
+    on_focus:
+      - 'Highlight border (primary color)'
+      - 'Show label above field'
+    on_input:
+      - 'Real-time validation (email format)'
+      - 'Clear error state if valid'
+    on_blur:
+      - 'Validate complete email'
+      - 'Show error if invalid'
+
+  signin-form-password-input:
+    on_focus:
+      - 'Highlight border'
+    on_input:
+      - 'Mask characters as bullets'
+    on_blur:
+      - 'Validate not empty'
+
+  signin-form-submit-button:
+    on_click:
+      - 'Validate all fields'
+      - 'If valid: disable button, show loading state'
+      - 'POST to /api/auth/signin'
+      - 'On success: redirect to /dashboard'
+      - 'On error: show error message, re-enable button'
+
+  signin-form-forgot-link:
+    on_click:
+      - 'Navigate to /auth/forgot-password'
+```
+
+---
+
+## NEXT STEP
+
+Load `substeps/4c-06-states.md`

package/src/workflows/4-ux-design/substeps/4c-06-states.md

@@ -0,0 +1,125 @@
+# Substep 4C-06: States
+
+**Goal:** Define all possible page and component states
+
+---
+
+## EXECUTION
+
+<output>**Let's define all possible states.**
+
+States show how the page and components appear in different situations.</output>
+
+## PAGE-LEVEL STATES
+
+<ask>**What are the different page-level states?**
+
+Think about:
+
+- Default/loaded state
+- Empty state (no data)
+- Loading state (fetching data)
+- Error state (something went wrong)
+- Success state (after action completes)
+
+For each state, describe:
+
+- When it occurs
+- What the user sees
+- What actions are available</ask>
+
+<action>Store page_states with descriptions</action>
+
+## COMPONENT STATES
+
+<output>**Now let's define component states.**
+
+For components with multiple appearances, we'll specify each state.</output>
+
+<action>For components with multiple states:
+<ask>**{{object_id}}** states:
+
+- Default:
+- Hover:
+- Active/Pressed:
+- Focus:
+- Disabled:
+- Loading:
+- Error:
+- Success:
+
+(Only specify states that apply to this component)</ask>
+
+<action>Store component_states</action>
+</action>
+
+<output>✅ **All states defined!**
+
+**Page states:** {{page_state_count}}
+**Component states:** {{component_state_count}}
+
+**Next:** We'll define validation rules.</output>
+
+---
+
+## MENU
+
+<ask>[C] Continue to 4C-07 (Validation)</ask>
+
+---
+
+## EXAMPLE OUTPUT
+
+```yaml
+page_states:
+  default:
+    trigger: 'Page loads normally'
+    appearance: 'Empty form ready for input'
+    actions: 'User can fill form and submit'
+
+  loading:
+    trigger: 'After submit clicked'
+    appearance: 'Submit button shows spinner, form disabled'
+    actions: 'Wait for response'
+
+  error:
+    trigger: 'Authentication fails'
+    appearance: 'Error message above form, submit button re-enabled'
+    actions: 'User can retry with different credentials'
+
+  success:
+    trigger: 'Authentication succeeds'
+    appearance: 'Brief success message'
+    actions: 'Redirect to dashboard'
+
+component_states:
+  signin-form-email-input:
+    default:
+      appearance: 'Gray border, placeholder text'
+    focus:
+      appearance: 'Primary color border, label floats up'
+    filled:
+      appearance: 'Dark border, label stays up'
+    error:
+      appearance: 'Red border, error message below'
+    disabled:
+      appearance: 'Light gray background, cursor not-allowed'
+
+  signin-form-submit-button:
+    default:
+      appearance: 'Primary color background, white text'
+    hover:
+      appearance: 'Darker primary color'
+    active:
+      appearance: 'Even darker, slight scale down'
+    loading:
+      appearance: "Spinner icon, text 'Signing in...'"
+    disabled:
+      appearance: 'Gray background, lower opacity'
+```
+
+---
+
+## NEXT STEP
+
+Load `substeps/4c-07-validation.md`

package/src/workflows/4-ux-design/substeps/4c-07-validation.md

@@ -0,0 +1,124 @@
+# Substep 4C-07: Validation & Errors
+
+**Goal:** Define all validation rules and error messages
+
+---
+
+## EXECUTION
+
+<output>**Let's define validation rules and error messages.**
+
+This ensures users get helpful feedback.</output>
+
+## VALIDATION RULES
+
+<ask>**What fields or inputs need validation?**
+
+For each field, specify:
+
+- What makes it valid?
+- What makes it invalid?
+- When is it validated? (on blur, on submit, real-time?)</ask>
+
+<action>For each validated field:
+<ask>**{{field_name}}** validation:
+
+- Required: yes/no
+- Format rules:
+- Length limits:
+- Custom rules:
+- Validation timing:
+  </ask>
+
+<action>Store validation_rules for field</action>
+</action>
+
+## ERROR MESSAGES
+
+<output>**Now let's define error messages for each validation failure.**
+
+We'll provide messages in all supported languages.</output>
+
+<action>For each validation rule:
+<ask>**Error message when {{rule_name}} fails:**
+
+{{#each language}}
+
+- {{language}}:
+  {{/each}}
+
+Error code (e.g., ERR_EMAIL_INVALID):
+</ask>
+
+<action>Store error_message with code and translations</action>
+</action>
+
+<output>✅ **Validation and errors defined!**
+
+**Validated fields:** {{validated_field_count}}
+**Error messages:** {{error_message_count}}
+
+**Next:** We'll generate the complete specification document.</output>
+
+---
+
+## MENU
+
+<ask>[C] Continue to 4C-08 (Generate Specification)</ask>
+
+---
+
+## EXAMPLE OUTPUT
+
+```yaml
+validation_rules:
+  email_input:
+    required: true
+    format: 'valid email format'
+    timing: 'on_blur and on_submit'
+    rules:
+      - 'Must contain @'
+      - 'Must have domain'
+      - 'No spaces allowed'
+
+  password_input:
+    required: true
+    min_length: 8
+    timing: 'on_submit'
+    rules:
+      - 'At least 8 characters'
+      - 'Not empty'
+
+error_messages:
+  ERR_EMAIL_REQUIRED:
+    en: 'Email address is required'
+    sv: 'E-postadress krävs'
+    field: 'email_input'
+
+  ERR_EMAIL_INVALID:
+    en: 'Please enter a valid email address'
+    sv: 'Ange en giltig e-postadress'
+    field: 'email_input'
+
+  ERR_PASSWORD_REQUIRED:
+    en: 'Password is required'
+    sv: 'Lösenord krävs'
+    field: 'password_input'
+
+  ERR_PASSWORD_TOO_SHORT:
+    en: 'Password must be at least 8 characters'
+    sv: 'Lösenordet måste vara minst 8 tecken'
+    field: 'password_input'
+
+  ERR_AUTH_INVALID:
+    en: 'Invalid email or password'
+    sv: 'Ogiltig e-post eller lösenord'
+    severity: 'critical'
+    display_location: 'above_form'
+```
+
+---
+
+## NEXT STEP
+
+Load `substeps/4c-08-generate-spec.md`

package/src/workflows/4-ux-design/substeps/4c-08-generate-spec.md

@@ -0,0 +1,105 @@
+# Substep 4C-08: Generate Specification Document
+
+**Goal:** Compile all gathered information into the complete specification
+
+---
+
+## EXECUTION
+
+<output>**Excellent! We've gathered everything we need.**
+
+Now I'll compile it all into your complete page specification. 📝</output>
+
+<action>Generate specification document using template at `templates/page-specification.template.md`
+
+Fill in all sections with data collected:
+
+- page_basics (from 4C-01)
+- layout_sections (from 4C-02)
+- components with object_ids (from 4C-03)
+- multilingual_content (from 4C-04)
+- interaction_behaviors (from 4C-05)
+- page_states and component_states (from 4C-06)
+- validation_rules and error_messages (from 4C-07)
+  </action>
+
+<action>Save complete specification to:
+`{output_folder}/C-Scenarios/{scenario}/{page}/{page}.md`
+</action>
+
+<output>✅ **Complete specification generated!**
+
+**Saved to:** `C-Scenarios/{scenario}/{page}/{page}.md`
+
+**What we documented:**
+
+- Page basics and routing
+- {{section_count}} layout sections
+- {{component_count}} components with Object IDs
+- Content in {{language_count}} languages
+- {{interaction_count}} interaction behaviors
+- {{state_count}} total states (page + component)
+- {{validation_count}} validation rules
+- {{error_count}} error messages
+
+**Your specification is development-ready!** 📋✨
+
+The specification document includes:
+
+- Clear Object IDs for every element
+- Complete multilingual content
+- Detailed interaction behaviors
+- All possible states defined
+- Validation rules and error messages
+- Technical notes and data requirements</output>
+
+---
+
+## SPECIFICATION COMPLETE
+
+Substep 4C is now complete. Return control to Step 3 (step-03-design-page.md) which will proceed to Substep 4D (Prototype).
+
+---
+
+## EXAMPLE SPECIFICATION SNIPPET
+
+```markdown
+### Email Input Field
+
+**Object ID:** `signin-form-email-input`
+**Component Type:** text-input
+**Design System Component:** text-input (primary)
+
+**Content:**
+
+- **Label (EN):** Email Address
+- **Label (SV):** E-postadress
+- **Placeholder (EN):** your@email.com
+- **Placeholder (SV):** din@epost.com
+
+**States:**
+
+- **Default:** Gray border, placeholder visible
+- **Focus:** Primary color border, label floats above
+- **Filled:** Dark border, label remains above
+- **Error:** Red border, error message below
+- **Disabled:** Light gray background, not interactive
+
+**Interactions:**
+
+- **On Focus:** Highlight border, float label
+- **On Input:** Real-time email format validation
+- **On Blur:** Full validation, show error if invalid
+
+**Validation:**
+
+- Required: Yes
+- Format: Valid email (contains @, has domain)
+- Error Code: ERR_EMAIL_INVALID
+- Error Message (EN): "Please enter a valid email address"
+- Error Message (SV): "Ange en giltig e-postadress"
+```
+
+---
+
+**Substep 4C Complete!** Return to main page design flow.