whiteport-design-studio 0.1.0

package/docs/tools/figma.md

@@ -0,0 +1,212 @@
+# Figma
+
+**Category:** Design Tool  
+**Purpose:** Visual design refinement and design system documentation  
+**Website:** <https://figma.com>
+
+---
+
+## What It Is
+
+Figma is a collaborative design tool used in WDS for visual design refinement when prototypes need polish. It's where designers refine components extracted from HTML prototypes and define design tokens.
+
+---
+
+## Why WDS Recommends It
+
+**Visual Design Refinement:**
+- Polish components extracted from prototypes
+- Define design tokens (colors, spacing, typography)
+- Create component variants and states
+- Document design decisions
+
+**Collaboration:**
+- Real-time collaboration with team
+- Share designs with stakeholders
+- Comment and feedback system
+- Version history
+
+**WDS Integration:**
+- MCP server integration for component injection
+- Bidirectional sync with design system
+- Page structure mirrors WDS specifications
+- Component traceability via Object IDs
+
+---
+
+## Setup Instructions
+
+### 1. Account Creation
+
+1. Go to <https://figma.com>
+2. Sign up for free account
+3. Install desktop app (recommended) or use web version
+
+### 2. WDS Project Setup
+
+Create Figma file structure:
+
+```
+[Project Name] Design Refinement
+├── 01-Customer-Onboarding/
+│   ├── 1.1-Start-Page
+│   ├── 1.2-Sign-In
+│   └── 1.3-Sign-Up
+├── 02-Product-Catalog/
+│   ├── 2.1-Product-List
+│   └── 2.2-Product-Detail
+└── Components/
+    ├── Buttons
+    ├── Inputs
+    └── Cards
+```
+
+### 3. Design Tokens Setup
+
+Create Figma variables:
+
+**Colors:**
+```
+Collection: Colors
+├── primary/50
+├── primary/600
+├── primary/700
+├── neutral/50
+└── neutral/900
+```
+
+**Spacing:**
+```
+Collection: Spacing
+├── xs = 4px
+├── sm = 8px
+├── md = 16px
+└── lg = 24px
+```
+
+**Typography:**
+```
+Styles: Typography
+├── Heading/1
+├── Heading/2
+├── Body/Regular
+└── Body/Bold
+```
+
+---
+
+## WDS Best Practices
+
+### DO ✅
+
+**1. Match WDS Structure**
+- Page names: `[Scenario-Number]-[Scenario-Name] / [Page-Number]-[Page-Name]`
+- Example: `01-Customer-Onboarding / 1.2-Sign-In`
+- Mirrors `docs/C-Scenarios/` structure
+
+**2. Preserve Object IDs**
+- Include Object IDs in layer names
+- Example: Layer name "btn-login-submit"
+- Maintains traceability to code
+
+**3. Use Design Tokens**
+- Always use variables for colors
+- Use variables for spacing
+- Apply text styles consistently
+- Don't hardcode values
+
+**4. Document Decisions**
+- Add descriptions to components
+- Document when to use each variant
+- Note accessibility requirements
+- Include usage examples
+
+### DON'T ❌
+
+**1. Don't Diverge from Specs**
+- If design changes, update specification
+- Keep Figma and specs in sync
+- Notify team of design evolution
+
+**2. Don't Skip Component Documentation**
+- Always add WDS component ID
+- Document variants and states
+- Include usage guidelines
+
+**3. Don't Hardcode Values**
+- Use variables, not hex colors
+- Use spacing variables
+- Apply text styles
+
+---
+
+## WDS-Specific Workflows
+
+### Receiving Components from Freya
+
+1. Freya injects components via MCP server
+2. Components appear in designated page
+3. Layer names include Object IDs
+4. Basic styling applied
+
+### Refining Components
+
+1. Apply design tokens (colors, spacing, typography)
+2. Create component variants (primary, secondary, etc.)
+3. Define states (default, hover, active, disabled)
+4. Add visual polish (shadows, borders, effects)
+5. Document in component description
+
+### Sending Back to WDS
+
+1. Notify Freya when refinement complete
+2. Freya reads components via MCP server
+3. Design tokens extracted automatically
+4. Design system updated
+5. Prototype re-rendered with refined design
+
+---
+
+## Keyboard Shortcuts
+
+**Essential for WDS:**
+
+| Action | Shortcut |
+|--------|----------|
+| Frame | F |
+| Component | Ctrl/Cmd+Alt+K |
+| Text | T |
+| Rectangle | R |
+| Duplicate | Ctrl/Cmd+D |
+| Group | Ctrl/Cmd+G |
+| Auto Layout | Shift+A |
+| Copy Properties | Ctrl/Cmd+Alt+C |
+| Paste Properties | Ctrl/Cmd+Alt+V |
+
+---
+
+## Troubleshooting
+
+### Issue: Components not syncing with WDS
+
+**Solution:**
+- Check Object IDs in layer names
+- Verify Figma file ID in project config
+- Ensure MCP server configured
+- Check Figma API access token
+
+---
+
+## Resources
+
+- Help Center: <https://help.figma.com>
+- Community: <https://forum.figma.com>
+- API Documentation: <https://www.figma.com/developers/api>
+
+**Related WDS Documentation:**
+- [Figma MCP](figma-mcp.md) - Automated integration
+- Figma Designer Guide: `workflows/5-design-system/figma-integration/figma-designer-guide.md`
+
+---
+
+[← Back to Tools](wds-tools-guide.md)

package/docs/tools/git.md

@@ -0,0 +1,285 @@
+# Git
+
+**Category:** Version Control  
+**Purpose:** Track changes, collaborate, maintain project history  
+**Website:** <https://git-scm.com>
+
+---
+
+## What It Is
+
+Git is a distributed version control system that tracks changes to your WDS project files. It enables collaboration, maintains history, and allows you to experiment safely with branches.
+
+---
+
+## Why WDS Recommends It
+
+**Version Control:**
+- Track all specification changes
+- Maintain prototype history
+- Document design system evolution
+- Rollback if needed
+
+**Collaboration:**
+- Multiple team members can work simultaneously
+- Review changes before merging
+- Track who changed what and when
+
+**WDS Workflow Integration:**
+- Commit after each phase completion
+- Branch for experimental designs
+- Tag releases and milestones
+
+---
+
+## Setup Instructions
+
+### 1. Installation
+
+**Windows:**
+```bash
+# Download from https://git-scm.com
+# Or use winget
+winget install Git.Git
+```
+
+**macOS:**
+```bash
+# Using Homebrew
+brew install git
+```
+
+**Linux:**
+```bash
+# Ubuntu/Debian
+sudo apt-get install git
+
+# Fedora
+sudo dnf install git
+```
+
+### 2. Initial Configuration
+
+```bash
+# Set your identity
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+
+# Set default branch name
+git config --global init.defaultBranch main
+
+# Set default editor
+git config --global core.editor "code --wait"
+
+# Enable color output
+git config --global color.ui auto
+```
+
+### 3. WDS-Specific Configuration
+
+Create `.gitignore` for WDS projects:
+
+```gitignore
+# Node modules
+node_modules/
+npm-debug.log*
+
+# Build outputs
+dist/
+build/
+*.log
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Temporary files
+*.tmp
+.cache/
+```
+
+---
+
+## WDS Best Practices
+
+### DO ✅
+
+**1. Commit Frequently**
+```bash
+# After completing each phase
+git add docs/C-Scenarios/01-Customer-Onboarding/
+git commit -m "feat: Complete customer onboarding scenario specification"
+
+# After design system updates
+git add D-Design-System/
+git commit -m "feat: Add button component to design system"
+```
+
+**2. Use Descriptive Commit Messages**
+```bash
+# Good
+git commit -m "feat: Add login page specification with multi-language support"
+git commit -m "fix: Correct button hover state in design system"
+git commit -m "docs: Update prototype-to-figma workflow guide"
+
+# Bad
+git commit -m "updates"
+git commit -m "fix stuff"
+git commit -m "wip"
+```
+
+**3. Branch for Experiments**
+```bash
+# Create branch for design exploration
+git checkout -b design/hero-section-variants
+
+# Experiment with different approaches
+# ...
+
+# Merge if successful
+git checkout main
+git merge design/hero-section-variants
+
+# Or discard if not
+git branch -D design/hero-section-variants
+```
+
+**4. Tag Milestones**
+```bash
+# Tag completed phases
+git tag -a v1.0-phase4-complete -m "Phase 4: UX Design complete"
+
+# Tag releases
+git tag -a v1.0-launch -m "Production launch"
+```
+
+### DON'T ❌
+
+**1. Don't Commit Generated Files**
+- Add build outputs to `.gitignore`
+- Don't commit `node_modules/`
+- Don't commit temporary files
+
+**2. Don't Force Push to Main**
+```bash
+# Never do this on shared branches
+git push --force origin main  # ❌
+```
+
+**3. Don't Commit Secrets**
+- Never commit API keys
+- Never commit passwords
+- Use environment variables
+- Add `.env` to `.gitignore`
+
+---
+
+## Common WDS Workflows
+
+### Starting a New WDS Project
+
+```bash
+# Initialize repository
+git init
+
+# Add WDS files
+git add .
+
+# Initial commit
+git commit -m "chore: Initialize WDS project structure"
+
+# Connect to remote
+git remote add origin https://github.com/username/project.git
+git push -u origin main
+```
+
+### Daily Workflow
+
+```bash
+# Start of day - get latest changes
+git pull
+
+# Work on specifications
+# ...
+
+# Stage and commit changes
+git add docs/C-Scenarios/
+git commit -m "feat: Add product detail page specification"
+
+# Push to remote
+git push
+```
+
+### Collaboration Workflow
+
+```bash
+# Create feature branch
+git checkout -b feature/checkout-flow
+
+# Work on feature
+# ...
+
+# Commit changes
+git add .
+git commit -m "feat: Add checkout flow specifications"
+
+# Push branch
+git push -u origin feature/checkout-flow
+
+# Create pull request on GitHub/GitLab
+# Team reviews
+# Merge when approved
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Merge conflicts
+
+**Solution:**
+```bash
+# Pull latest changes
+git pull
+
+# Resolve conflicts in files
+# Edit files to resolve conflicts
+
+# Mark as resolved
+git add <conflicted-files>
+git commit -m "chore: Resolve merge conflicts"
+```
+
+### Issue: Accidentally committed wrong files
+
+**Solution:**
+```bash
+# Undo last commit, keep changes
+git reset --soft HEAD~1
+
+# Or remove specific file from commit
+git reset HEAD <file>
+git checkout -- <file>
+```
+
+---
+
+## Resources
+
+- Documentation: <https://git-scm.com/doc>
+- Pro Git Book: <https://git-scm.com/book>
+- GitHub Guides: <https://guides.github.com>
+
+---
+
+[← Back to Tools](wds-tools-guide.md)

package/docs/tools/html-to-design.md

@@ -0,0 +1,185 @@
+# html.to.design
+
+**Category:** Conversion Tool  
+**Purpose:** Convert HTML prototypes to Figma (fallback method)  
+**Website:** <https://html.to.design>
+
+---
+
+## What It Is
+
+html.to.design is a web-based tool that converts HTML/CSS to Figma files. In WDS, it serves as a fallback method when MCP server is unavailable for extracting prototypes to Figma.
+
+---
+
+## Why WDS Recommends It
+
+**Fallback Option:**
+- When MCP server not configured
+- For full-page extraction
+- Quick one-off conversions
+- Exploring design possibilities
+
+**Conversion Capabilities:**
+- HTML structure → Figma frames
+- CSS styles → Figma styling
+- Layout (Flexbox/Grid) → Auto Layout
+- Text content → Text layers
+
+---
+
+## Setup Instructions
+
+### 1. Access
+
+No installation required - web-based tool:
+1. Go to <https://html.to.design>
+2. No account needed for basic use
+3. Premium features available with account
+
+### 2. Prepare Prototype
+
+Before uploading:
+
+```html
+<!-- Ensure clean HTML structure -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Page Title</title>
+  <style>
+    /* Include all CSS inline or in <style> tag */
+  </style>
+</head>
+<body>
+  <!-- Semantic HTML -->
+  <header data-object-id="header-main">
+    <h1 data-object-id="heading-title">Title</h1>
+  </header>
+  <!-- Use Flexbox/Grid for layouts -->
+</body>
+</html>
+```
+
+---
+
+## WDS Best Practices
+
+### DO ✅
+
+**1. Clean HTML Before Upload**
+- Use semantic HTML elements
+- Remove debug code
+- Simplify complex nesting
+- Use Flexbox/Grid layouts
+
+**2. Include Object IDs for Figma Layer Naming**
+```html
+<!-- For Figma layer naming, use aria-label attributes -->
+<button aria-label="btn-login-submit" class="btn-primary">Log In</button>
+```
+
+**Note:** The html.to.design MCP server and browser extension use `aria-label` attributes to name Figma layers. For production code, these should be temporary. See: [Prepare for Figma Export](prepare-for-figma-export.md)
+
+**3. Use Standard CSS**
+- Avoid complex positioning
+- Use standard properties
+- Keep selectors simple
+
+### DON'T ❌
+
+**1. Don't Use When MCP Available**
+- MCP server is preferred method
+- Better Object ID preservation
+- Automated workflow integration
+
+**2. Don't Expect Perfect Conversion**
+- Manual cleanup may be needed
+- Complex layouts may not convert perfectly
+- Review and refine in Figma
+
+---
+
+## Usage Workflow
+
+### 1. Upload HTML
+
+```
+1. Go to https://html.to.design
+2. Upload HTML file
+3. Include associated CSS
+4. Select target: Figma
+```
+
+### 2. Configure
+
+```
+Options:
+- Preserve layout structure: Yes
+- Convert to components: Yes (if available)
+```
+
+### 3. Download and Import
+
+```
+1. Download Figma file
+2. Open in Figma
+3. Verify layer names match Object IDs (from aria-label attributes)
+4. Begin refinement
+```
+
+**For Multiple Viewport Capture:**
+
+The browser extension method allows capturing mobile, tablet, and desktop simultaneously. See: [Prepare for Figma Export - Browser Extension Method](prepare-for-figma-export.md#variation-b-browser-extension-export-multiple-viewports)
+
+---
+
+## Limitations
+
+### What Works Well
+
+- Standard layouts
+- Flexbox and Grid
+- Text content
+- Basic styling
+
+### What May Need Manual Adjustment
+
+- Complex animations
+- JavaScript-driven content
+- Custom SVG graphics
+- Advanced CSS effects
+
+---
+
+## When to Use
+
+### Use html.to.design when:
+
+- MCP server not configured
+- Need full-page extraction
+- Quick one-off conversion
+- Exploring design possibilities
+
+### Use MCP server instead when:
+
+- MCP server available
+- Need component-level precision
+- Require Object ID traceability
+- Planning iterative refinement
+
+---
+
+## Resources
+
+- Website: <https://html.to.design>
+- Documentation: Check website for latest guides
+
+**Related WDS Documentation:**
+- [Figma MCP](figma-mcp.md) - Recommended automated method
+- Prototype to Figma Workflow: `workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md`
+
+---
+
+[← Back to Tools](wds-tools-guide.md)