siesa-agents 2.1.89 → 2.1.91

package/siesa-agents/wds/data/design-system/token-architecture.md

@@ -0,0 +1,474 @@
+# Design Token Architecture
+
+**Purpose:** Core principles for separating semantic structure from visual style.
+
+**Referenced by:** All component-type instructions
+
+---
+
+## Core Principle
+
+**Separate semantic structure from visual style.**
+
+```
+HTML/Structure = Meaning (what it is)
+Design Tokens = Appearance (how it looks)
+
+They should be independent!
+```
+
+---
+
+## The Problem
+
+**Bad Practice:**
+
+```html
+<h2 class="text-4xl font-bold text-blue-600">Heading</h2>
+```
+
+**Issues:**
+
+- Visual styling mixed with semantic HTML
+- Can't change h2 appearance without changing all h2s
+- h2 means "second-level heading" but looks like "display large"
+- Breaks separation of concerns
+
+---
+
+## The Solution
+
+**Good Practice:**
+
+**HTML (Semantic):**
+
+```html
+<h2 class="heading-section">Heading</h2>
+```
+
+**Design Tokens (Visual):**
+
+```css
+.heading-section {
+  font-size: var(--text-4xl);
+  font-weight: var(--font-bold);
+  color: var(--color-primary-600);
+}
+```
+
+**Benefits:**
+
+- Semantic HTML stays semantic
+- Visual style is centralized
+- Can change appearance without touching HTML
+- Clear separation of concerns
+
+---
+
+## Token Hierarchy
+
+### Level 1: Raw Values
+
+```css
+--spacing-4: 1rem;
+--color-blue-600: #2563eb;
+--font-size-4xl: 2.25rem;
+```
+
+### Level 2: Semantic Tokens
+
+```css
+--text-heading-large: var(--font-size-4xl);
+--color-primary: var(--color-blue-600);
+--spacing-section: var(--spacing-4);
+```
+
+### Level 3: Component Tokens
+
+```css
+--button-padding-x: var(--spacing-section);
+--button-color-primary: var(--color-primary);
+--heading-size-section: var(--text-heading-large);
+```
+
+**Use Level 2 or 3 in components, never Level 1 directly.**
+
+---
+
+## Application to WDS
+
+### In Page Specifications
+
+**Specify semantic structure:**
+
+```yaml
+Page Structure:
+  - Section Heading (h2)
+  - Body text (p)
+  - Primary button (button)
+```
+
+**NOT visual styling:**
+
+```yaml
+# ❌ Don't do this
+Page Structure:
+  - Large blue bold text
+  - 16px gray text
+  - Blue rounded button
+```
+
+### In Design System
+
+**Specify visual styling:**
+
+```yaml
+Section Heading:
+  html_element: h2
+  design_token: heading-section
+
+Design Token Definition:
+  heading-section:
+    font-size: text-4xl
+    font-weight: bold
+    color: primary-600
+```
+
+---
+
+## Component-Type Instructions
+
+### Text Heading Example
+
+**When specifying a heading:**
+
+1. **Identify semantic level** (h1-h6)
+   - h1 = Page title
+   - h2 = Section heading
+   - h3 = Subsection heading
+   - etc.
+
+2. **Map to design token**
+   - h1 → display-large
+   - h2 → heading-section
+   - h3 → heading-subsection
+
+3. **Store separately**
+   - Page spec: `<h2>` (semantic)
+   - Design system: `heading-section` token (visual)
+
+**Example Output:**
+
+**Page Spec:**
+
+```yaml
+Hero Section:
+  heading:
+    element: h2
+    token: heading-section
+    content: 'Welcome to Our Product'
+```
+
+**Design System:**
+
+```yaml
+Tokens:
+  heading-section:
+    font-size: 2.25rem
+    font-weight: 700
+    line-height: 1.2
+    color: gray-900
+```
+
+---
+
+## Button Example
+
+**When specifying a button:**
+
+1. **Identify semantic element**
+   - `<button>` for actions
+   - `<a>` for navigation (even if styled as button)
+
+2. **Map to component**
+   - Action → Button component
+   - Navigation → Link component (button variant)
+
+3. **Store separately**
+   - Page spec: `<button>` + purpose
+   - Design system: Button component styling
+
+**Example Output:**
+
+**Page Spec:**
+
+```yaml
+Login Form:
+  submit_button:
+    element: button
+    type: submit
+    component: Button.primary
+    label: 'Log in'
+```
+
+**Design System:**
+
+```yaml
+Button Component:
+  variants:
+    primary:
+      background: primary-600
+      color: white
+      padding: spacing-2 spacing-4
+      border-radius: radius-md
+```
+
+---
+
+## Input Field Example
+
+**When specifying an input:**
+
+1. **Identify semantic type**
+   - `<input type="text">` for text
+   - `<input type="email">` for email
+   - `<input type="password">` for password
+
+2. **Map to component**
+   - Text input → Input Field component
+   - Email input → Input Field.email variant
+
+3. **Store separately**
+   - Page spec: Input type + validation + labels
+   - Design system: Input Field styling
+
+**Example Output:**
+
+**Page Spec:**
+
+```yaml
+Login Form:
+  email_field:
+    element: input
+    type: email
+    component: InputField.email
+    label: 'Email address'
+    placeholder: 'you@example.com'
+    required: true
+    validation: email_format
+```
+
+**Design System:**
+
+```yaml
+Input Field Component:
+  base_styling:
+    height: 2.5rem
+    padding: spacing-2 spacing-3
+    border: 1px solid gray-300
+    border-radius: radius-md
+    font-size: text-base
+
+  variants:
+    email:
+      icon: envelope
+      autocomplete: email
+```
+
+---
+
+## Why This Matters
+
+### For Designers
+
+✅ **Consistency:** All h2s can look the same without manual styling
+✅ **Flexibility:** Change all section headings by updating one token
+✅ **Clarity:** Semantic meaning preserved
+✅ **Scalability:** Easy to maintain as design system grows
+
+### For Developers
+
+✅ **Semantic HTML:** Proper HTML structure
+✅ **Accessibility:** Screen readers understand structure
+✅ **Maintainability:** Styling centralized
+✅ **Performance:** Reusable styles
+
+### For Design Systems
+
+✅ **Single Source of Truth:** Tokens define appearance
+✅ **Easy Updates:** Change tokens, not components
+✅ **Consistency:** Automatic consistency across pages
+✅ **Documentation:** Clear token → component mapping
+
+---
+
+## Common Mistakes
+
+### Mistake 1: Mixing Structure and Style
+
+**❌ Bad:**
+
+```yaml
+Page:
+  - "Large blue heading" (h2)
+```
+
+**✅ Good:**
+
+```yaml
+Page:
+  - Section heading (h2 → heading-section token)
+```
+
+### Mistake 2: Hardcoding Visual Values
+
+**❌ Bad:**
+
+```yaml
+Button:
+  background: #2563eb
+  padding: 16px
+```
+
+**✅ Good:**
+
+```yaml
+Button:
+  background: primary-600
+  padding: spacing-4
+```
+
+### Mistake 3: Using Visual Names for Semantic Elements
+
+**❌ Bad:**
+
+```yaml
+<h2 class="big-blue-text">
+```
+
+**✅ Good:**
+
+```yaml
+<h2 class="section-heading">
+```
+
+---
+
+## Token Naming Conventions
+
+### Colors
+
+```
+--color-{category}-{shade}
+--color-primary-600
+--color-gray-900
+--color-success-500
+```
+
+### Typography
+
+```
+--text-{size}
+--text-base
+--text-lg
+--text-4xl
+```
+
+### Spacing
+
+```
+--spacing-{scale}
+--spacing-2
+--spacing-4
+--spacing-8
+```
+
+### Component-Specific
+
+```
+--{component}-{property}-{variant}
+--button-padding-primary
+--input-border-error
+--card-shadow-elevated
+```
+
+---
+
+## Implementation in WDS
+
+### Phase 4: Page Specification
+
+**Agent specifies:**
+
+- Semantic HTML elements
+- Component references
+- Content and labels
+
+**Agent does NOT specify:**
+
+- Exact colors
+- Exact sizes
+- Exact spacing
+
+### Phase 5: Design System
+
+**Agent specifies:**
+
+- Design tokens
+- Component styling
+- Visual properties
+
+**Agent does NOT specify:**
+
+- Page-specific content
+- Semantic structure
+
+### Integration
+
+**Page spec references design system:**
+
+```yaml
+Hero:
+  heading:
+    element: h2
+    token: heading-hero  ← Reference to design system
+    content: 'Welcome'
+```
+
+**Design system defines token:**
+
+```yaml
+Tokens:
+  heading-hero:
+    font-size: 3rem
+    font-weight: 800
+    color: gray-900
+```
+
+---
+
+## Company Customization
+
+**Companies can fork WDS and customize tokens:**
+
+```
+Company Fork:
+├── data/design-system/
+│   ├── token-architecture.md (this file - keep principles)
+│   ├── company-tokens.md (company-specific token values)
+│   └── token-mappings.md (h2 → company-heading-large)
+```
+
+**Result:** Every project uses company's design tokens automatically.
+
+---
+
+## Further Reading
+
+- **Naming Conventions:** `naming-conventions.md`
+- **Component Boundaries:** `component-boundaries.md`
+- **State Management:** `state-management.md`
+
+---
+
+**This is a core principle. Reference this document from all component-type instructions.**

package/siesa-agents/wds/data/design-system/validation-patterns.md

@@ -0,0 +1,74 @@
+# Form Validation Patterns
+
+**Purpose:** Standard patterns for form validation and error handling.
+
+**Referenced by:** Input Field, Form component-type instructions
+
+---
+
+## Validation Types
+
+### Client-Side Validation
+
+**Required Fields:**
+
+```yaml
+validation:
+  required: true
+  message: 'This field is required'
+```
+
+**Format Validation:**
+
+```yaml
+validation:
+  type: email
+  pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+  message: 'Please enter a valid email address'
+```
+
+**Length Validation:**
+
+```yaml
+validation:
+  minLength: 8
+  maxLength: 100
+  message: 'Password must be 8-100 characters'
+```
+
+---
+
+## Error States
+
+**Visual Indicators:**
+
+- Red border
+- Error icon
+- Error message below field
+- Error color for label
+
+**Timing:**
+
+- Show on blur (after user leaves field)
+- Show on submit attempt
+- Clear on valid input
+
+---
+
+## Success States
+
+**Visual Indicators:**
+
+- Green border (optional)
+- Success icon (optional)
+- Success message (optional)
+
+**When to Show:**
+
+- After successful validation
+- For critical fields (password strength)
+- For async validation (username availability)
+
+---
+
+**Reference this when specifying form components.**

package/siesa-agents/wds/data/presentations/freya-how-i-help.md

@@ -0,0 +1,63 @@
+# How Freya Helps You Succeed with UX and Prototyping
+
+**Instructions:** Present each step one at a time. After each step, ask if the user
+wants to continue to the next step or is ready to get started working.
+
+---
+
+## Step 1: What I Do
+
+I turn strategy into experiences users can see and interact with. I create detailed
+specifications, interactive prototypes, and design systems — artifacts that developers
+can build from with confidence.
+
+**My core outputs:**
+- **Scenarios** — complete user journeys with page-by-page specs
+- **Prototypes** — interactive HTML that lets you experience the design
+- **Design systems** — reusable tokens and components (when needed)
+- **Validation** — checking that what was built matches the design
+
+---
+
+## Step 2: How I Work
+
+I start with WHY before WHAT. Before designing anything, I read the strategic
+context (Product Brief, Trigger Map) to understand what drives users and what
+the business needs.
+
+**My pattern:**
+1. Load strategic context (silently — I don't ask you for it)
+2. Discuss the scenario or feature with you
+3. Create specifications with logical explanations
+4. Build prototypes you can interact with
+5. Iterate based on your feedback
+
+Design without strategy is decoration. I make sure every choice connects back to a reason.
+
+---
+
+## Step 3: What I Need from You
+
+- **Strategic foundation** — Product Brief and Trigger Map (from Saga). I can work
+  without them, but the design will be stronger with them.
+- **Your vision** — what should users experience? What matters most?
+- **Feedback** — I'll show you specs and prototypes, tell me what works and what doesn't
+- **Decisions** — I'll present options with trade-offs, you pick the direction
+
+---
+
+## Step 4: What You Get
+
+After working with me, you'll have:
+
+- **Scenario specs** — complete page-by-page specifications with object IDs
+- **Interactive prototypes** — HTML files you can click through
+- **Sketches** — visual concepts for layout and interaction
+- **Design system** (optional) — tokens, components, and a brand book
+- **Test results** — validation that implementation matches design
+
+These specs are detailed enough for developers to build from without guessing.
+
+---
+
+**Ready to get started? Tell me what you want to design, or pick a workflow from my menu.**