Add IDE selection and optional learning material
- Added IDE selection question (Windsurf, VS Code, Cursor, Other) - Made learning material installation optional with confirm prompt - Success message now shows selected IDE name - Store IDE preference in config.yaml - Installer now has 5 questions (up from 3) User feedback: "IDE selection is crucial for the installer" and "ask if the learn section should be installed" Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Mårten Angner
parent
bbd6f4656a
commit
1ef7db0eec
|
|
@ -0,0 +1,723 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>WDS Design System Guide</title>
|
||||
<style>
|
||||
* {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
|
||||
line-height: 1.6;
|
||||
color: #1a1a1a;
|
||||
background: #f5f5f5;
|
||||
}
|
||||
|
||||
.container {
|
||||
max-width: 1200px;
|
||||
margin: 0 auto;
|
||||
padding: 2rem;
|
||||
}
|
||||
|
||||
header {
|
||||
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
|
||||
color: white;
|
||||
padding: 3rem 2rem;
|
||||
margin-bottom: 3rem;
|
||||
border-radius: 12px;
|
||||
box-shadow: 0 4px 20px rgba(0,0,0,0.1);
|
||||
}
|
||||
|
||||
h1 {
|
||||
font-size: 2.5rem;
|
||||
margin-bottom: 0.5rem;
|
||||
}
|
||||
|
||||
.subtitle {
|
||||
font-size: 1.2rem;
|
||||
opacity: 0.9;
|
||||
}
|
||||
|
||||
nav {
|
||||
background: white;
|
||||
padding: 1.5rem;
|
||||
border-radius: 8px;
|
||||
margin-bottom: 2rem;
|
||||
box-shadow: 0 2px 10px rgba(0,0,0,0.05);
|
||||
position: sticky;
|
||||
top: 1rem;
|
||||
z-index: 100;
|
||||
}
|
||||
|
||||
nav ul {
|
||||
list-style: none;
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 1rem;
|
||||
}
|
||||
|
||||
nav a {
|
||||
color: #667eea;
|
||||
text-decoration: none;
|
||||
font-weight: 500;
|
||||
padding: 0.5rem 1rem;
|
||||
border-radius: 6px;
|
||||
transition: all 0.2s;
|
||||
}
|
||||
|
||||
nav a:hover {
|
||||
background: #667eea;
|
||||
color: white;
|
||||
}
|
||||
|
||||
section {
|
||||
background: white;
|
||||
padding: 2rem;
|
||||
margin-bottom: 2rem;
|
||||
border-radius: 8px;
|
||||
box-shadow: 0 2px 10px rgba(0,0,0,0.05);
|
||||
}
|
||||
|
||||
h2 {
|
||||
color: #667eea;
|
||||
font-size: 2rem;
|
||||
margin-bottom: 1.5rem;
|
||||
padding-bottom: 0.5rem;
|
||||
border-bottom: 2px solid #667eea;
|
||||
}
|
||||
|
||||
h3 {
|
||||
color: #764ba2;
|
||||
font-size: 1.5rem;
|
||||
margin-top: 2rem;
|
||||
margin-bottom: 1rem;
|
||||
}
|
||||
|
||||
h4 {
|
||||
color: #555;
|
||||
font-size: 1.2rem;
|
||||
margin-top: 1.5rem;
|
||||
margin-bottom: 0.5rem;
|
||||
}
|
||||
|
||||
.hierarchy {
|
||||
display: flex;
|
||||
gap: 2rem;
|
||||
margin: 2rem 0;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.tier {
|
||||
flex: 1;
|
||||
min-width: 200px;
|
||||
padding: 1.5rem;
|
||||
border-radius: 8px;
|
||||
background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%);
|
||||
}
|
||||
|
||||
.tier h4 {
|
||||
color: #667eea;
|
||||
margin-top: 0;
|
||||
}
|
||||
|
||||
.tier ul {
|
||||
list-style: none;
|
||||
padding-left: 0;
|
||||
}
|
||||
|
||||
.tier li {
|
||||
padding: 0.5rem 0;
|
||||
border-bottom: 1px solid rgba(255,255,255,0.3);
|
||||
}
|
||||
|
||||
.example-box {
|
||||
background: #f8f9fa;
|
||||
border-left: 4px solid #667eea;
|
||||
padding: 1.5rem;
|
||||
margin: 1.5rem 0;
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
.component-demo {
|
||||
display: flex;
|
||||
gap: 2rem;
|
||||
margin: 2rem 0;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.demo-item {
|
||||
flex: 1;
|
||||
min-width: 250px;
|
||||
}
|
||||
|
||||
.demo-visual {
|
||||
background: white;
|
||||
border: 2px solid #e0e0e0;
|
||||
border-radius: 8px;
|
||||
padding: 2rem;
|
||||
margin-bottom: 1rem;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.demo-button {
|
||||
background: #667eea;
|
||||
color: white;
|
||||
border: none;
|
||||
padding: 0.75rem 1.5rem;
|
||||
border-radius: 6px;
|
||||
font-size: 1rem;
|
||||
cursor: pointer;
|
||||
transition: all 0.2s;
|
||||
}
|
||||
|
||||
.demo-button:hover {
|
||||
background: #5568d3;
|
||||
transform: translateY(-2px);
|
||||
box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
|
||||
}
|
||||
|
||||
.demo-button.secondary {
|
||||
background: white;
|
||||
color: #667eea;
|
||||
border: 2px solid #667eea;
|
||||
}
|
||||
|
||||
.demo-button.ghost {
|
||||
background: transparent;
|
||||
color: #667eea;
|
||||
border: none;
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
.anatomy-diagram {
|
||||
background: white;
|
||||
border: 2px dashed #667eea;
|
||||
padding: 2rem;
|
||||
margin: 1.5rem 0;
|
||||
border-radius: 8px;
|
||||
position: relative;
|
||||
}
|
||||
|
||||
.anatomy-label {
|
||||
position: absolute;
|
||||
background: #667eea;
|
||||
color: white;
|
||||
padding: 0.25rem 0.75rem;
|
||||
border-radius: 4px;
|
||||
font-size: 0.875rem;
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
code {
|
||||
background: #f4f4f4;
|
||||
padding: 0.2rem 0.5rem;
|
||||
border-radius: 3px;
|
||||
font-family: 'Courier New', monospace;
|
||||
color: #764ba2;
|
||||
}
|
||||
|
||||
pre {
|
||||
background: #1a1a1a;
|
||||
color: #f8f8f2;
|
||||
padding: 1.5rem;
|
||||
border-radius: 8px;
|
||||
overflow-x: auto;
|
||||
margin: 1rem 0;
|
||||
}
|
||||
|
||||
pre code {
|
||||
background: none;
|
||||
color: #f8f8f2;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 1.5rem 0;
|
||||
}
|
||||
|
||||
th, td {
|
||||
padding: 1rem;
|
||||
text-align: left;
|
||||
border-bottom: 1px solid #e0e0e0;
|
||||
}
|
||||
|
||||
th {
|
||||
background: #667eea;
|
||||
color: white;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
tr:hover {
|
||||
background: #f8f9fa;
|
||||
}
|
||||
|
||||
.key-principle {
|
||||
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
|
||||
color: white;
|
||||
padding: 1.5rem;
|
||||
border-radius: 8px;
|
||||
margin: 1.5rem 0;
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
.workflow-step {
|
||||
background: #f8f9fa;
|
||||
padding: 1rem;
|
||||
margin: 1rem 0;
|
||||
border-radius: 6px;
|
||||
border-left: 4px solid #764ba2;
|
||||
}
|
||||
|
||||
.workflow-step strong {
|
||||
color: #764ba2;
|
||||
}
|
||||
|
||||
footer {
|
||||
text-align: center;
|
||||
padding: 2rem;
|
||||
color: #666;
|
||||
margin-top: 3rem;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<header>
|
||||
<h1>WDS Design System Guide</h1>
|
||||
<p class="subtitle">Standards for Building Scalable, Consistent Component Libraries</p>
|
||||
</header>
|
||||
|
||||
<nav>
|
||||
<ul>
|
||||
<li><a href="#atomic-design">Atomic Design</a></li>
|
||||
<li><a href="#anatomy">Anatomy</a></li>
|
||||
<li><a href="#slots">Slots</a></li>
|
||||
<li><a href="#props">Props</a></li>
|
||||
<li><a href="#states">States</a></li>
|
||||
<li><a href="#variants">Variants</a></li>
|
||||
<li><a href="#specs">Specifications</a></li>
|
||||
<li><a href="#pattern-recognition">Pattern Recognition</a></li>
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
<!-- 1. Atomic Design -->
|
||||
<section id="atomic-design">
|
||||
<h2>1. Atomic Design Methodology</h2>
|
||||
|
||||
<p>Components are organized in three levels of complexity, inspired by atomic design principles:</p>
|
||||
|
||||
<div class="hierarchy">
|
||||
<div class="tier">
|
||||
<h4>⚛️ Atoms</h4>
|
||||
<p>Basic building blocks</p>
|
||||
<ul>
|
||||
<li>Button</li>
|
||||
<li>Input</li>
|
||||
<li>Icon</li>
|
||||
<li>Label</li>
|
||||
<li>Avatar</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="tier">
|
||||
<h4>🔗 Molecules</h4>
|
||||
<p>Combinations of atoms</p>
|
||||
<ul>
|
||||
<li>Search Bar (Input + Button)</li>
|
||||
<li>Form Field (Label + Input)</li>
|
||||
<li>Card (Image + Text + Button)</li>
|
||||
<li>Menu Item (Icon + Label)</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="tier">
|
||||
<h4>🏗️ Organisms</h4>
|
||||
<p>Complex components</p>
|
||||
<ul>
|
||||
<li>Navigation Bar</li>
|
||||
<li>Hero Section</li>
|
||||
<li>Product Grid</li>
|
||||
<li>Footer</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="example-box">
|
||||
<h4>Example: Building a Card Component</h4>
|
||||
<p><strong>Atoms used:</strong> Image, Heading, Paragraph, Button, Icon</p>
|
||||
<p><strong>Classification:</strong> Molecule (combines multiple atoms)</p>
|
||||
<p><strong>Can be used in:</strong> Organism (e.g., Product Grid contains multiple Cards)</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- 2. Component Anatomy -->
|
||||
<section id="anatomy">
|
||||
<h2>2. Component Anatomy</h2>
|
||||
|
||||
<p>Every component is broken down into its structural parts.</p>
|
||||
|
||||
<h3>Button Anatomy Example</h3>
|
||||
|
||||
<div class="anatomy-diagram">
|
||||
<button class="demo-button" style="position: relative; margin: 3rem auto; display: block;">
|
||||
<span style="margin-right: 0.5rem;">✓</span> Click Me
|
||||
</button>
|
||||
<div class="anatomy-label" style="top: 1rem; left: 1rem;">Container</div>
|
||||
<div class="anatomy-label" style="top: 5rem; left: 3rem;">Icon (optional)</div>
|
||||
<div class="anatomy-label" style="top: 5rem; right: 3rem;">Label</div>
|
||||
</div>
|
||||
|
||||
<h4>Anatomy Documentation Format:</h4>
|
||||
<pre><code>## Anatomy
|
||||
|
||||
**Parts:**
|
||||
1. **Container** - The button's outer wrapper
|
||||
2. **Icon** (optional) - Leading or trailing icon
|
||||
3. **Label** - The button text
|
||||
4. **Loading Indicator** (optional) - Replaces icon during loading state</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- 3. Slots -->
|
||||
<section id="slots">
|
||||
<h2>3. Slots (Content Placeholders)</h2>
|
||||
|
||||
<div class="key-principle">
|
||||
<strong>Key Principle:</strong> Structure is shared, content is page-specific.
|
||||
</div>
|
||||
|
||||
<p>Slots define <strong>where content goes</strong>, not what the content is.</p>
|
||||
|
||||
<h3>Card Component Slots Example</h3>
|
||||
|
||||
<div class="component-demo">
|
||||
<div class="demo-item">
|
||||
<div class="demo-visual" style="text-align: left;">
|
||||
<div style="background: #e0e0e0; height: 150px; margin-bottom: 1rem; border-radius: 4px;"></div>
|
||||
<h4>[title slot]</h4>
|
||||
<p style="color: #666; margin: 0.5rem 0;">[description slot]</p>
|
||||
<button class="demo-button" style="margin-top: 1rem;">[action slot]</button>
|
||||
</div>
|
||||
<p><strong>Structure</strong> (shared)</p>
|
||||
</div>
|
||||
|
||||
<div class="demo-item">
|
||||
<div class="demo-visual" style="text-align: left;">
|
||||
<div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); height: 150px; margin-bottom: 1rem; border-radius: 4px;"></div>
|
||||
<h4>Premium Plan</h4>
|
||||
<p style="color: #666; margin: 0.5rem 0;">Unlock all features</p>
|
||||
<button class="demo-button" style="margin-top: 1rem;">Subscribe</button>
|
||||
</div>
|
||||
<p><strong>Content</strong> (page-specific)</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h4>Slots Documentation Format:</h4>
|
||||
<pre><code>## Slots
|
||||
|
||||
1. **image** - Visual content (photo, illustration, icon)
|
||||
2. **title** - Main heading
|
||||
3. **description** - Supporting text
|
||||
4. **action** - Call-to-action button</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- 4. Props -->
|
||||
<section id="props">
|
||||
<h2>4. Props (Configuration Options)</h2>
|
||||
|
||||
<p>Props control <strong>how a component looks and behaves</strong>.</p>
|
||||
|
||||
<h3>Button Props Example</h3>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Prop</th>
|
||||
<th>Type</th>
|
||||
<th>Options</th>
|
||||
<th>Default</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>variant</code></td>
|
||||
<td>string</td>
|
||||
<td>primary | secondary | ghost</td>
|
||||
<td>primary</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>size</code></td>
|
||||
<td>string</td>
|
||||
<td>small | medium | large</td>
|
||||
<td>medium</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>disabled</code></td>
|
||||
<td>boolean</td>
|
||||
<td>true | false</td>
|
||||
<td>false</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>fullWidth</code></td>
|
||||
<td>boolean</td>
|
||||
<td>true | false</td>
|
||||
<td>false</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h4>Props Documentation Format:</h4>
|
||||
<pre><code>## Props
|
||||
|
||||
| Prop | Type | Options | Default | Description |
|
||||
|------|------|---------|---------|-------------|
|
||||
| variant | string | primary, secondary, ghost | primary | Visual style |
|
||||
| size | string | small, medium, large | medium | Button size |
|
||||
| disabled | boolean | true, false | false | Disable interactions |
|
||||
| fullWidth | boolean | true, false | false | Stretch to container width |</code></pre>
|
||||
</section>
|
||||
|
||||
<!-- 5. States -->
|
||||
<section id="states">
|
||||
<h2>5. States (Interactive Behavior)</h2>
|
||||
|
||||
<p>States define how components respond to user interaction.</p>
|
||||
|
||||
<h3>Button States Example</h3>
|
||||
|
||||
<div class="component-demo">
|
||||
<div class="demo-item">
|
||||
<div class="demo-visual">
|
||||
<button class="demo-button">Default</button>
|
||||
</div>
|
||||
<p><strong>Default</strong> - Idle state</p>
|
||||
</div>
|
||||
|
||||
<div class="demo-item">
|
||||
<div class="demo-visual">
|
||||
<button class="demo-button" style="background: #5568d3; transform: translateY(-2px); box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);">Hover</button>
|
||||
</div>
|
||||
<p><strong>Hover</strong> - Mouse over</p>
|
||||
</div>
|
||||
|
||||
<div class="demo-item">
|
||||
<div class="demo-visual">
|
||||
<button class="demo-button" style="opacity: 0.5; cursor: not-allowed;">Disabled</button>
|
||||
</div>
|
||||
<p><strong>Disabled</strong> - Not interactive</p>
|
||||
</div>
|
||||
|
||||
<div class="demo-item">
|
||||
<div class="demo-visual">
|
||||
<button class="demo-button">
|
||||
<span style="display: inline-block; animation: spin 1s linear infinite;">⏳</span> Loading
|
||||
</button>
|
||||
</div>
|
||||
<p><strong>Loading</strong> - Processing</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h4>Common States:</h4>
|
||||
<ul>
|
||||
<li><code>default</code> - Idle/resting state</li>
|
||||
<li><code>hover</code> - Mouse/pointer over component</li>
|
||||
<li><code>active</code> - Currently pressed/clicked</li>
|
||||
<li><code>focus</code> - Keyboard focus (accessibility)</li>
|
||||
<li><code>disabled</code> - Not interactive</li>
|
||||
<li><code>loading</code> - Awaiting response</li>
|
||||
<li><code>error</code> - Invalid/failed state</li>
|
||||
<li><code>success</code> - Completed successfully</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- 6. Variants -->
|
||||
<section id="variants">
|
||||
<h2>6. Variants (Visual Styles)</h2>
|
||||
|
||||
<p>Variants are different visual styles of the same component structure.</p>
|
||||
|
||||
<h3>Button Variants Example</h3>
|
||||
|
||||
<div class="component-demo">
|
||||
<div class="demo-item">
|
||||
<div class="demo-visual">
|
||||
<button class="demo-button">Primary</button>
|
||||
</div>
|
||||
<p><strong>Primary</strong> - Main actions</p>
|
||||
</div>
|
||||
|
||||
<div class="demo-item">
|
||||
<div class="demo-visual">
|
||||
<button class="demo-button secondary">Secondary</button>
|
||||
</div>
|
||||
<p><strong>Secondary</strong> - Less emphasis</p>
|
||||
</div>
|
||||
|
||||
<div class="demo-item">
|
||||
<div class="demo-visual">
|
||||
<button class="demo-button ghost">Ghost</button>
|
||||
</div>
|
||||
<p><strong>Ghost</strong> - Minimal style</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="example-box">
|
||||
<h4>When to Create Variants</h4>
|
||||
<p><strong>Same structure, different appearance</strong></p>
|
||||
<ul>
|
||||
<li>✅ Primary vs Secondary button (same anatomy, different colors)</li>
|
||||
<li>✅ Card with shadow vs Card without shadow</li>
|
||||
<li>✅ Input with border vs Input with underline only</li>
|
||||
</ul>
|
||||
<p><strong>Different structure = Different component</strong></p>
|
||||
<ul>
|
||||
<li>❌ Button with icon vs Button without icon → Use props/slots</li>
|
||||
<li>❌ Horizontal nav vs Vertical nav → Separate components</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- 7. Specifications -->
|
||||
<section id="specs">
|
||||
<h2>7. Specifications (Technical Measurements)</h2>
|
||||
|
||||
<p>Precise measurements for implementation.</p>
|
||||
|
||||
<h3>Button Specifications Example</h3>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Property</th>
|
||||
<th>Small</th>
|
||||
<th>Medium</th>
|
||||
<th>Large</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Height</strong></td>
|
||||
<td>32px</td>
|
||||
<td>40px</td>
|
||||
<td>48px</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Padding (horizontal)</strong></td>
|
||||
<td>12px</td>
|
||||
<td>16px</td>
|
||||
<td>24px</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Font Size</strong></td>
|
||||
<td>14px</td>
|
||||
<td>16px</td>
|
||||
<td>18px</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Border Radius</strong></td>
|
||||
<td>4px</td>
|
||||
<td>6px</td>
|
||||
<td>8px</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Icon Size</strong></td>
|
||||
<td>16px</td>
|
||||
<td>20px</td>
|
||||
<td>24px</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h4>Specification Categories:</h4>
|
||||
<ul>
|
||||
<li><strong>Dimensions</strong> - Width, height, min/max sizes</li>
|
||||
<li><strong>Spacing</strong> - Padding, margin, gap between elements</li>
|
||||
<li><strong>Typography</strong> - Font size, weight, line height</li>
|
||||
<li><strong>Colors</strong> - Background, text, border colors (reference to color system)</li>
|
||||
<li><strong>Effects</strong> - Border radius, shadows, transitions</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- 8. Pattern Recognition -->
|
||||
<section id="pattern-recognition">
|
||||
<h2>8. Pattern Recognition (Freya's Workflow)</h2>
|
||||
|
||||
<div class="key-principle">
|
||||
<strong>Rule:</strong> Document a component in the design system on its <strong>SECOND occurrence</strong>.
|
||||
</div>
|
||||
|
||||
<h3>Incremental Building Process</h3>
|
||||
|
||||
<div class="workflow-step">
|
||||
<strong>Page 1.1:</strong> Uses Button (first occurrence)
|
||||
<p>→ Freya notes it, continues without creating design system entry</p>
|
||||
</div>
|
||||
|
||||
<div class="workflow-step">
|
||||
<strong>Page 1.2:</strong> Uses Button again (second occurrence)
|
||||
<p>→ Freya: "I've used 'Button' twice now. Should I document this in the design system?"</p>
|
||||
<p>→ User: "Yes"</p>
|
||||
<p>→ Freya creates E-Design-System/atoms/button/ with full documentation</p>
|
||||
</div>
|
||||
|
||||
<div class="workflow-step">
|
||||
<strong>Page 1.3:</strong> Uses Button + Card
|
||||
<p>→ Button: Already documented, reference existing spec</p>
|
||||
<p>→ Card: Second occurrence → Ask to document</p>
|
||||
</div>
|
||||
|
||||
<div class="workflow-step">
|
||||
<strong>Page 2.1:</strong> Uses Button (primary variant) + new Ghost variant
|
||||
<p>→ Freya: "New variant detected! I'll add 'Ghost' to the Button variants."</p>
|
||||
<p>→ Updates E-Design-System/atoms/button/05-variants.md</p>
|
||||
</div>
|
||||
|
||||
<h3>Why Second Occurrence?</h3>
|
||||
|
||||
<div class="example-box">
|
||||
<h4>Prevents Premature Abstraction</h4>
|
||||
<p><strong>❌ Problem with "first occurrence":</strong> You document something that never gets reused.</p>
|
||||
<p><strong>✅ Solution with "second occurrence":</strong> You only document actual patterns.</p>
|
||||
|
||||
<h4 style="margin-top: 1.5rem;">Natural Pattern Emergence</h4>
|
||||
<p>Components earn their place in the design system by being <strong>actually reused</strong>, not by being <strong>potentially reusable</strong>.</p>
|
||||
</div>
|
||||
|
||||
<h3>Freya's Tracking System</h3>
|
||||
|
||||
<pre><code>Component Usage Tracking:
|
||||
|
||||
Button:
|
||||
- Page 1.1 (first occurrence)
|
||||
- Page 1.2 (second occurrence) ← TRIGGER: Create design system entry
|
||||
- Page 1.3 (third occurrence) ← Reference existing
|
||||
|
||||
Card:
|
||||
- Page 1.2 (first occurrence)
|
||||
- Page 1.3 (second occurrence) ← TRIGGER: Create design system entry
|
||||
|
||||
Input:
|
||||
- Page 2.1 (first occurrence)
|
||||
[No second occurrence yet, no design system entry]</code></pre>
|
||||
</section>
|
||||
|
||||
<footer>
|
||||
<p><strong>WDS Design System Standards</strong> | Whiteport Design Studio v0.3.0</p>
|
||||
<p>Reference: <code>_wds/docs/design-system/00-design-system.md</code></p>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
<style>
|
||||
@keyframes spin {
|
||||
from { transform: rotate(0deg); }
|
||||
to { transform: rotate(360deg); }
|
||||
}
|
||||
</style>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,916 @@
|
|||
# WDS Design System Standards
|
||||
|
||||
**Version:** 1.0
|
||||
**For:** Freya UX Designer Agent
|
||||
**Purpose:** Complete reference for creating project design systems following WDS methodology
|
||||
|
||||
---
|
||||
|
||||
## 1. Atomic Design Methodology
|
||||
|
||||
Design systems are built using atomic design principles - organizing components by complexity.
|
||||
|
||||
### Hierarchy
|
||||
|
||||
```
|
||||
Design Tokens (colors, typography, spacing)
|
||||
↓
|
||||
Atoms (basic building blocks)
|
||||
↓
|
||||
Molecules (simple combinations of atoms)
|
||||
↓
|
||||
Organisms (complex combinations of atoms + molecules)
|
||||
↓
|
||||
Patterns (page-level compositions)
|
||||
```
|
||||
|
||||
### Atoms
|
||||
|
||||
**Definition:** Basic building blocks that cannot be broken down further without losing meaning.
|
||||
|
||||
**Examples:**
|
||||
- Button
|
||||
- Input field
|
||||
- Icon
|
||||
- Label
|
||||
- Badge
|
||||
- Avatar
|
||||
- Link
|
||||
|
||||
**Characteristics:**
|
||||
- Single-purpose elements
|
||||
- No child components
|
||||
- Highly reusable
|
||||
- Configured through props
|
||||
|
||||
### Molecules
|
||||
|
||||
**Definition:** Simple combinations of atoms that work together as a unit.
|
||||
|
||||
**Examples:**
|
||||
- Form Field (Label + Input + Helper text)
|
||||
- Search Field (Input + Search icon + Clear button)
|
||||
- Message Bubble (Avatar + Text + Timestamp)
|
||||
- Nav Item (Icon + Label)
|
||||
- Stat Card (Label + Value + Icon/Badge)
|
||||
|
||||
**Characteristics:**
|
||||
- Combine 2-4 atoms
|
||||
- Single functional purpose
|
||||
- Reusable across contexts
|
||||
- Document which atoms used (composition)
|
||||
|
||||
### Organisms
|
||||
|
||||
**Definition:** Complex components combining atoms and molecules into distinct sections.
|
||||
|
||||
**Examples:**
|
||||
- Card (Header + Media + Content + Actions)
|
||||
- Chat Interface (Header + Message Bubbles + Input Field)
|
||||
- Navigation Header (Logo + Nav Items + User Menu)
|
||||
- Modal (Overlay + Card + Actions)
|
||||
- Data Table (Headers + Rows + Pagination)
|
||||
|
||||
**Characteristics:**
|
||||
- Combine atoms + molecules
|
||||
- Complex functionality
|
||||
- Often context-specific
|
||||
- Document complete composition tree
|
||||
|
||||
### Patterns
|
||||
|
||||
**Definition:** Page-level compositions and recurring design solutions.
|
||||
|
||||
**Examples:**
|
||||
- Navigation patterns (header nav, sidebar nav, mobile menu)
|
||||
- Form patterns (single-step, multi-step, inline validation)
|
||||
- Layout patterns (dashboard, list-detail, content+sidebar)
|
||||
|
||||
**Characteristics:**
|
||||
- Combine organisms
|
||||
- Solve specific UX problems
|
||||
- Context-dependent
|
||||
- Document usage guidelines
|
||||
|
||||
---
|
||||
|
||||
## 2. Component Anatomy
|
||||
|
||||
Anatomy describes the structural parts that make up a component.
|
||||
|
||||
### Anatomy Documentation
|
||||
|
||||
Every component should document its anatomy:
|
||||
|
||||
**Example: Button Anatomy**
|
||||
|
||||
```
|
||||
┌─────────────────────────────┐
|
||||
│ [icon] Label Text [badge] │ ← Container
|
||||
└─────────────────────────────┘
|
||||
↑ ↑ ↑
|
||||
Leading Label Trailing
|
||||
icon text element
|
||||
```
|
||||
|
||||
**Parts:**
|
||||
1. **Container** - Clickable surface (padding, background, border)
|
||||
2. **Leading Icon** (optional) - Icon before label
|
||||
3. **Label** (required) - Text describing action
|
||||
4. **Trailing Element** (optional) - Icon, badge, or indicator after label
|
||||
|
||||
### Anatomy Standards
|
||||
|
||||
**Part Naming:**
|
||||
- Use descriptive names (header, content, actions - not top, middle, bottom)
|
||||
- Indicate optionality (required vs optional parts)
|
||||
- Use consistent terminology across components
|
||||
|
||||
**Visual Representation:**
|
||||
- Use ASCII diagrams for structure
|
||||
- Label each part clearly
|
||||
- Show hierarchy (container > children)
|
||||
|
||||
**Documentation:**
|
||||
- List all parts
|
||||
- Describe purpose of each
|
||||
- Note which are required vs optional
|
||||
- Include spacing between parts
|
||||
|
||||
---
|
||||
|
||||
## 3. Slots (Content Placeholders)
|
||||
|
||||
**Key Principle:** Structure is shared, content is page-specific.
|
||||
|
||||
### What Are Slots?
|
||||
|
||||
Slots are flexible content placeholders within components. The component defines WHERE content goes (slot architecture), but each page fills those slots with DIFFERENT content.
|
||||
|
||||
**Example: Button**
|
||||
|
||||
```yaml
|
||||
# Component structure (shared):
|
||||
Button:
|
||||
anatomy:
|
||||
- container
|
||||
- leadingIcon slot
|
||||
- label slot
|
||||
- trailingIcon slot
|
||||
|
||||
# Page 1 usage (content page-specific):
|
||||
slots:
|
||||
label: "Download Report"
|
||||
leadingIcon: download-icon
|
||||
|
||||
# Page 2 usage (different content, same structure):
|
||||
slots:
|
||||
label: "Submit"
|
||||
trailingIcon: arrow-right-icon
|
||||
```
|
||||
|
||||
The button anatomy/structure never changes. Only the slot content changes per page.
|
||||
|
||||
### Slot Documentation Format
|
||||
|
||||
```markdown
|
||||
## Slots
|
||||
|
||||
### 1. [Slot Name] (required/optional)
|
||||
- **Type:** Text | Icon | Image | Component
|
||||
- **Position:** [Where in anatomy]
|
||||
- **Purpose:** [What it's for]
|
||||
- **Examples:**
|
||||
- Page 1: [example content]
|
||||
- Page 2: [example content]
|
||||
```
|
||||
|
||||
### Slot Naming Conventions
|
||||
|
||||
**Content Slots:**
|
||||
- `label` - Primary text content
|
||||
- `title` - Heading text
|
||||
- `body` - Paragraph content
|
||||
- `description` - Supporting text
|
||||
|
||||
**Media Slots:**
|
||||
- `media` - Image, video, or chart area
|
||||
- `icon` - Icon placeholder
|
||||
- `avatar` - User image
|
||||
- `thumbnail` - Preview image
|
||||
|
||||
**Positional Slots:**
|
||||
- `leadingIcon` / `trailingIcon` - Icons before/after content
|
||||
- `header` / `footer` - Top/bottom sections
|
||||
- `actions` - Button/link area
|
||||
|
||||
**Complex Slots:**
|
||||
- `children` - Default slot for nested content
|
||||
- `items` - Array/list of content
|
||||
- `[role]Content` - Role-specific content (e.g., `headerContent`)
|
||||
|
||||
### Slots vs Nested Components
|
||||
|
||||
**Slots:** Placeholders for content (text, icons, images)
|
||||
**Nested Components:** When one component contains another component
|
||||
|
||||
Example - Card organism:
|
||||
- **Slots:** title (text), body (text), media (image)
|
||||
- **Nested Components:** contains Button atoms in actions area
|
||||
|
||||
---
|
||||
|
||||
## 4. Props (Configuration)
|
||||
|
||||
**Key Principle:** Props configure HOW a component looks and behaves (not WHAT content it shows).
|
||||
|
||||
### Props vs Slots
|
||||
|
||||
| Aspect | Props | Slots |
|
||||
|--------|-------|-------|
|
||||
| **Purpose** | Configure appearance/behavior | Fill with content |
|
||||
| **Type** | Boolean, string, number, enum | Text, elements, components |
|
||||
| **Example** | `size="large"`, `disabled=true` | `label="Submit"`, `icon=checkmark` |
|
||||
| **Shared?** | Define available options | Content varies per usage |
|
||||
|
||||
### Standard Props
|
||||
|
||||
#### Visual Props
|
||||
- `variant` - Visual style (primary, secondary, ghost, outlined, filled)
|
||||
- `size` - Size variation (small, medium, large)
|
||||
- `color` - Color theme (default, accent, success, warning, error)
|
||||
|
||||
#### State Props
|
||||
- `disabled` - Boolean, disables interaction
|
||||
- `loading` - Boolean, shows loading state
|
||||
- `error` - Boolean, shows error state
|
||||
- `active` - Boolean, active/selected state
|
||||
|
||||
#### Layout Props
|
||||
- `fullWidth` - Boolean, expand to container width
|
||||
- `padding` - Spacing inside component
|
||||
- `margin` - Spacing outside component
|
||||
- `alignment` - Text/content alignment
|
||||
|
||||
#### Behavior Props
|
||||
- `onClick` - Function, click handler
|
||||
- `onChange` - Function, change handler
|
||||
- `placeholder` - String, placeholder text
|
||||
- `required` - Boolean, required field
|
||||
|
||||
### Props Documentation Format
|
||||
|
||||
```markdown
|
||||
## Props
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
|
||||
| size | 'small' \| 'medium' \| 'large' | 'medium' | Component size |
|
||||
| disabled | boolean | false | Disables interaction |
|
||||
| fullWidth | boolean | false | Expand to container width |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. States
|
||||
|
||||
Interactive states show how components respond to user interaction.
|
||||
|
||||
### Standard States
|
||||
|
||||
#### Default State
|
||||
- Initial appearance
|
||||
- No user interaction yet
|
||||
- Resting state
|
||||
|
||||
#### Hover State
|
||||
- Mouse over component
|
||||
- Visual feedback (color shift, elevation)
|
||||
- Indicates interactivity
|
||||
|
||||
#### Active/Pressed State
|
||||
- User clicking/tapping
|
||||
- Visual depression or color change
|
||||
- Confirms interaction received
|
||||
|
||||
#### Focused State
|
||||
- Keyboard focus
|
||||
- Visible focus ring/outline
|
||||
- Critical for accessibility
|
||||
|
||||
#### Disabled State
|
||||
- Component non-interactive
|
||||
- Reduced opacity/color
|
||||
- Cursor: not-allowed
|
||||
- No hover/active states
|
||||
|
||||
#### Loading State
|
||||
- Async action in progress
|
||||
- Spinner or skeleton
|
||||
- Disabled interaction
|
||||
- Indicates wait time
|
||||
|
||||
#### Error State
|
||||
- Validation failure
|
||||
- Red color, error icon
|
||||
- Error message shown
|
||||
- Highlights problem area
|
||||
|
||||
#### Success State
|
||||
- Action completed successfully
|
||||
- Green color, check icon
|
||||
- Confirmation message
|
||||
- Positive feedback
|
||||
|
||||
### State Documentation
|
||||
|
||||
```markdown
|
||||
## States
|
||||
|
||||
### Default
|
||||
- Background: [color]
|
||||
- Text: [color]
|
||||
- Border: [style]
|
||||
- Elevation: [value]
|
||||
|
||||
### Hover
|
||||
- Background: [color + overlay]
|
||||
- Elevation: [increased]
|
||||
- Cursor: pointer
|
||||
|
||||
### Active
|
||||
- Background: [color + overlay]
|
||||
- Elevation: [decreased]
|
||||
- Scale: [slightly smaller]
|
||||
|
||||
### Disabled
|
||||
- Background: [muted color]
|
||||
- Text: [reduced opacity]
|
||||
- Cursor: not-allowed
|
||||
- No hover/active states
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Variants
|
||||
|
||||
Variants are visual style variations of the same component.
|
||||
|
||||
### When to Create Variants
|
||||
|
||||
**Create variant when:**
|
||||
- Visual style differs significantly
|
||||
- Semantic meaning differs (primary vs secondary action)
|
||||
- Context requires different emphasis
|
||||
|
||||
**Don't create variant when:**
|
||||
- Only content changes (use slots instead)
|
||||
- Only size changes (use size prop instead)
|
||||
- Could be handled by props/states
|
||||
|
||||
### Standard Variant Types
|
||||
|
||||
#### Button Variants
|
||||
- `primary` - Main actions (filled, high emphasis)
|
||||
- `secondary` - Secondary actions (outlined, medium emphasis)
|
||||
- `ghost` - Tertiary actions (text only, low emphasis)
|
||||
- `text` - Minimal actions (no background)
|
||||
|
||||
#### Card Variants
|
||||
- `elevated` - Shadow/elevation for depth
|
||||
- `outlined` - Border, no shadow
|
||||
- `filled` - Background color, no border/shadow
|
||||
|
||||
#### Alert/Badge Variants
|
||||
- `info` - Informational (blue)
|
||||
- `success` - Positive outcome (green)
|
||||
- `warning` - Caution needed (yellow)
|
||||
- `error` - Problem/failure (red)
|
||||
|
||||
### Variant Documentation
|
||||
|
||||
```markdown
|
||||
## Variants
|
||||
|
||||
### Primary
|
||||
- **Use:** Main call-to-action
|
||||
- **Visual:** Filled background, brand color
|
||||
- **Example:** "Submit", "Get Started", "Buy Now"
|
||||
|
||||
### Secondary
|
||||
- **Use:** Secondary actions
|
||||
- **Visual:** Outlined, no fill
|
||||
- **Example:** "Cancel", "Learn More", "Back"
|
||||
|
||||
### Ghost
|
||||
- **Use:** Tertiary/subtle actions
|
||||
- **Visual:** No background or border, text only
|
||||
- **Example:** "Skip", "Dismiss", "Not now"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Specifications
|
||||
|
||||
Technical measurements and implementation details.
|
||||
|
||||
### What to Specify
|
||||
|
||||
#### Dimensions
|
||||
- Width (fixed, min, max, or fluid)
|
||||
- Height (fixed, min, max, or auto)
|
||||
- Aspect ratio (for media)
|
||||
|
||||
#### Spacing
|
||||
- Padding (internal spacing)
|
||||
- Margin (external spacing)
|
||||
- Gap (space between child elements)
|
||||
|
||||
#### Typography
|
||||
- Font family
|
||||
- Font size
|
||||
- Font weight
|
||||
- Line height
|
||||
- Letter spacing
|
||||
|
||||
#### Colors
|
||||
- Background colors
|
||||
- Text colors
|
||||
- Border colors
|
||||
- State color overlays
|
||||
|
||||
#### Borders
|
||||
- Border width
|
||||
- Border radius (corner rounding)
|
||||
- Border style (solid, dashed, none)
|
||||
|
||||
#### Elevation
|
||||
- Box shadow
|
||||
- Z-index
|
||||
- Layering order
|
||||
|
||||
### Specifications Documentation
|
||||
|
||||
```markdown
|
||||
## Specifications
|
||||
|
||||
### Dimensions
|
||||
- Min width: 64px
|
||||
- Height: 40px (medium), 32px (small), 48px (large)
|
||||
- Padding: 16px horizontal, 8px vertical
|
||||
|
||||
### Typography
|
||||
- Font: Body-Medium
|
||||
- Size: 14px
|
||||
- Weight: 500
|
||||
- Letter spacing: 0.1px
|
||||
|
||||
### Colors
|
||||
- Background (primary): brand-500
|
||||
- Text (primary): white
|
||||
- Border: none
|
||||
- Hover overlay: black 8% opacity
|
||||
|
||||
### Border
|
||||
- Radius: 4px
|
||||
- Width: 0px (no border for primary variant)
|
||||
|
||||
### Elevation
|
||||
- Default: 0dp
|
||||
- Hover: 2dp shadow
|
||||
- Active: 0dp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Pattern Recognition (Freya's Workflow)
|
||||
|
||||
How Freya builds the design system incrementally during page design.
|
||||
|
||||
### Second-Occurrence Trigger
|
||||
|
||||
**Rule:** Document a component in the design system when it appears for the **second time** across pages.
|
||||
|
||||
**Rationale:**
|
||||
- First occurrence: Might be one-off, wait and see
|
||||
- Second occurrence: Pattern emerging, worth documenting
|
||||
- Prevents premature abstraction
|
||||
|
||||
### Pattern Recognition Workflow
|
||||
|
||||
```
|
||||
Page 1.1: Uses Button component
|
||||
→ Freya: Notes first occurrence, continues
|
||||
|
||||
Page 1.2: Uses Button again (second occurrence)
|
||||
→ Freya: "I've used 'Button' twice now. Should I document this in the design system?"
|
||||
→ User: "Yes"
|
||||
→ Freya: Creates atoms/button/ with complete documentation
|
||||
|
||||
Page 1.3: Uses Button + Card
|
||||
→ Button: Already documented
|
||||
→ Card: Second occurrence
|
||||
→ Freya: "Card appears second time, adding to design system..."
|
||||
→ Creates organisms/card/
|
||||
|
||||
Page 1.4: Uses Button + Card + Input
|
||||
→ Button: Already documented
|
||||
→ Card: Already documented
|
||||
→ Input: Second occurrence
|
||||
→ Freya: Documents Input component
|
||||
```
|
||||
|
||||
### Component Classification
|
||||
|
||||
**Determining atom vs molecule vs organism:**
|
||||
|
||||
**Atom if:**
|
||||
- Cannot be broken down further
|
||||
- Single-purpose element
|
||||
- No child components
|
||||
- Examples: Button, Input, Icon, Label
|
||||
|
||||
**Molecule if:**
|
||||
- Combines 2-4 atoms
|
||||
- Simple functional unit
|
||||
- Clear single purpose
|
||||
- Examples: Form Field (Label + Input), Search Field (Input + Icon + Button)
|
||||
|
||||
**Organism if:**
|
||||
- Combines atoms + molecules
|
||||
- Complex functionality
|
||||
- Multiple purposes/sections
|
||||
- Examples: Card, Chat Interface, Navigation Header
|
||||
|
||||
**When uncertain:**
|
||||
- Start with molecule
|
||||
- Can promote to organism if complexity increases
|
||||
- Better to start simpler, increase complexity as needed
|
||||
|
||||
### Incremental Documentation
|
||||
|
||||
**First documentation (second occurrence):**
|
||||
- Create folder structure
|
||||
- Document anatomy
|
||||
- Document slots
|
||||
- Document basic props/states
|
||||
- Create 00-overview, 01-anatomy, 02-slots
|
||||
|
||||
**Subsequent occurrences:**
|
||||
- Add new variants discovered
|
||||
- Add new states observed
|
||||
- Refine prop definitions
|
||||
- Add usage examples
|
||||
- Update existing files
|
||||
|
||||
### Documentation Checklist
|
||||
|
||||
When documenting a component on second occurrence:
|
||||
|
||||
- [ ] Create component folder (atoms/molecules/organisms/[component-name]/)
|
||||
- [ ] Create 00-[name].md (overview)
|
||||
- [ ] Create 01-anatomy.md (structural breakdown)
|
||||
- [ ] Create 02-slots.md (content placeholders)
|
||||
- [ ] Create 03-props.md or 03-composition.md
|
||||
- Atoms: props (configuration)
|
||||
- Molecules/Organisms: composition (which atoms/molecules used)
|
||||
- [ ] Create 04-states.md (interactive states)
|
||||
- [ ] Create 05-variants.md (visual variations)
|
||||
- [ ] Create 06-specs.md (measurements) - if needed
|
||||
- [ ] Update component index (04-components.md)
|
||||
|
||||
---
|
||||
|
||||
## 9. Component Documentation Template
|
||||
|
||||
### Atoms Template
|
||||
|
||||
```markdown
|
||||
# [Component Name]
|
||||
|
||||
## Overview
|
||||
[Brief description - what it is, primary purpose]
|
||||
|
||||
## Anatomy
|
||||
[ASCII diagram showing structural parts]
|
||||
|
||||
**Parts:**
|
||||
1. **[Part name]** (required/optional) - [Purpose]
|
||||
2. **[Part name]** (required/optional) - [Purpose]
|
||||
|
||||
## Slots
|
||||
|
||||
### 1. [Slot Name] (required/optional)
|
||||
- **Type:** [Text | Icon | Image | Component]
|
||||
- **Position:** [Where in anatomy]
|
||||
- **Purpose:** [What it's for]
|
||||
- **Examples:**
|
||||
- [Example 1]
|
||||
- [Example 2]
|
||||
|
||||
## Props
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| [prop] | [type] | [default] | [description] |
|
||||
|
||||
## States
|
||||
|
||||
### [State Name]
|
||||
- Background: [value]
|
||||
- Text: [value]
|
||||
- Border: [value]
|
||||
- [Other properties]
|
||||
|
||||
## Variants
|
||||
|
||||
### [Variant Name]
|
||||
- **Use:** [When to use]
|
||||
- **Visual:** [How it looks]
|
||||
- **Example:** [Example usage]
|
||||
|
||||
## Specifications
|
||||
|
||||
### Dimensions
|
||||
- Width: [value]
|
||||
- Height: [value]
|
||||
- Padding: [value]
|
||||
|
||||
### Typography
|
||||
- Font: [value]
|
||||
- Size: [value]
|
||||
- Weight: [value]
|
||||
|
||||
### Colors
|
||||
- Background: [value]
|
||||
- Text: [value]
|
||||
|
||||
### Border
|
||||
- Radius: [value]
|
||||
- Width: [value]
|
||||
|
||||
### Elevation
|
||||
- Shadow: [value]
|
||||
```
|
||||
|
||||
### Molecules/Organisms Template
|
||||
|
||||
Same as atoms template, but add:
|
||||
|
||||
```markdown
|
||||
## Composition
|
||||
|
||||
This [molecule/organism] combines the following components:
|
||||
|
||||
### Atoms Used
|
||||
| Atom | From | Role |
|
||||
|------|------|------|
|
||||
| [Component] | atoms/[name]/ | [Purpose in this molecule] |
|
||||
|
||||
### Molecules Used (organisms only)
|
||||
| Molecule | From | Role |
|
||||
|----------|------|------|
|
||||
| [Component] | molecules/[name]/ | [Purpose in this organism] |
|
||||
|
||||
## Composition Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ [Molecule/Organism] │
|
||||
│ ├─ [Atom 1] │
|
||||
│ ├─ [Atom 2] │
|
||||
│ └─ [Molecule 1] │
|
||||
│ ├─ [Atom 3] │
|
||||
│ └─ [Atom 4] │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Complete Examples
|
||||
|
||||
### Example 1: Button (Atom)
|
||||
|
||||
**File:** `atoms/button/02-slots.md`
|
||||
|
||||
```markdown
|
||||
# Button Slots
|
||||
|
||||
## Overview
|
||||
|
||||
Slots are content placeholders. Button structure is shared, content is page-specific.
|
||||
|
||||
## Slot Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────┐
|
||||
│ [leadingIcon] [label] [trailingIcon] │
|
||||
└─────────────────────────────┘
|
||||
↑ ↑ ↑
|
||||
Slot 1 Slot 2 Slot 3
|
||||
```
|
||||
|
||||
## Available Slots
|
||||
|
||||
### 1. leadingIcon (optional)
|
||||
- **Type:** Icon
|
||||
- **Position:** Before label
|
||||
- **Purpose:** Visual context for action
|
||||
- **Examples:**
|
||||
- Download button: Download icon
|
||||
- Delete button: Trash icon
|
||||
- Submit button: Checkmark icon
|
||||
|
||||
### 2. label (required)
|
||||
- **Type:** Text
|
||||
- **Position:** Center
|
||||
- **Purpose:** Describes the action
|
||||
- **Examples:**
|
||||
- "Get Personalized Advice"
|
||||
- "Submit"
|
||||
- "Cancel"
|
||||
|
||||
### 3. trailingIcon (optional)
|
||||
- **Type:** Icon or Badge
|
||||
- **Position:** After label
|
||||
- **Purpose:** Additional context
|
||||
- **Examples:**
|
||||
- External link: Arrow-out icon
|
||||
- Loading: Spinner
|
||||
- Badge: Notification count
|
||||
|
||||
## Implementation
|
||||
|
||||
**Structure is shared:**
|
||||
- Button anatomy (container, padding, border radius)
|
||||
- States (hover, active, disabled)
|
||||
- Visual style (colors, typography)
|
||||
|
||||
**Content is page-specific:**
|
||||
- Each page fills slots with different content
|
||||
- Same button component, different label/icons
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Form Field (Molecule)
|
||||
|
||||
**File:** `molecules/form-field/03-composition.md`
|
||||
|
||||
```markdown
|
||||
# Form Field Composition
|
||||
|
||||
## Overview
|
||||
|
||||
Form Field is a **molecule** that combines 3 atoms into a functional input unit.
|
||||
|
||||
## Composition Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ Form Field (molecule) │
|
||||
│ ├─ Label (atom) │
|
||||
│ ├─ Input (atom) │
|
||||
│ └─ Helper Text (atom) │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Components Used
|
||||
|
||||
### Atoms
|
||||
| Atom | From | Role |
|
||||
|------|------|------|
|
||||
| **Label** | `atoms/label/` | Field name, required indicator |
|
||||
| **Input** | `atoms/input/` | Text entry field |
|
||||
| **Helper Text** | `atoms/typography/` | Instructions or error messages |
|
||||
|
||||
## Composition Rules
|
||||
|
||||
1. **Label** is always above Input
|
||||
2. **Helper Text** appears below Input
|
||||
3. Spacing: 4px between Label and Input, 4px between Input and Helper
|
||||
4. Error state: Helper Text turns red, Input gets red border
|
||||
|
||||
## Variants
|
||||
|
||||
### Standard
|
||||
- Label + Input + Helper text (optional)
|
||||
|
||||
### Required
|
||||
- Label + Required indicator (*) + Input + Helper text
|
||||
|
||||
### Error
|
||||
- Label + Input (red border) + Error message (red)
|
||||
|
||||
### Disabled
|
||||
- All atoms use disabled state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Card (Organism)
|
||||
|
||||
**File:** `organisms/card/02-slots.md`
|
||||
|
||||
```markdown
|
||||
# Card Slots
|
||||
|
||||
## Overview
|
||||
|
||||
Card structure is reusable. Content filling each slot is page-specific.
|
||||
|
||||
## Slot Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ [header] │ ← Slot 1
|
||||
├─────────────────────────────────┤
|
||||
│ [media] │ ← Slot 2
|
||||
├─────────────────────────────────┤
|
||||
│ [title] │ ← Slot 3
|
||||
│ [body] │ ← Slot 4
|
||||
├─────────────────────────────────┤
|
||||
│ [actions] │ ← Slot 5
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Available Slots
|
||||
|
||||
### 1. header (optional)
|
||||
- **Type:** Component (Avatar + Title + Subtitle + Menu)
|
||||
- **Content Examples:**
|
||||
- User profile: Avatar, "John Doe", "2 hours ago"
|
||||
- Article card: Category badge, "Investments", "5 min read"
|
||||
|
||||
### 2. media (optional)
|
||||
- **Type:** Image, Chart, or Video
|
||||
- **Content Examples:**
|
||||
- Portfolio card: Performance chart
|
||||
- Article card: Hero image
|
||||
|
||||
### 3. title (required)
|
||||
- **Type:** Text (Headline)
|
||||
- **Content Examples:**
|
||||
- "Your Recommended Allocation"
|
||||
- "Getting Started with Investing"
|
||||
|
||||
### 4. body (optional)
|
||||
- **Type:** Text (Paragraph)
|
||||
- **Content Examples:**
|
||||
- "Based on your goals, we recommend..."
|
||||
- "Learn the fundamentals..."
|
||||
|
||||
### 5. actions (optional)
|
||||
- **Type:** Buttons
|
||||
- **Content Examples:**
|
||||
- Single: ["Learn More"]
|
||||
- Dual: ["Dismiss", "View Details"]
|
||||
|
||||
## Key Principle
|
||||
|
||||
**Shared:**
|
||||
- Card anatomy (container, spacing, elevation)
|
||||
- Visual style (colors, borders, shadows)
|
||||
- Behavior (clickable, states)
|
||||
|
||||
**Page-Specific:**
|
||||
- Content filling each slot
|
||||
- Which slots are used
|
||||
- How actions behave
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
### Core Principles
|
||||
|
||||
1. **Atomic Design** - Organize by complexity (atoms → molecules → organisms)
|
||||
2. **Anatomy** - Document structural parts clearly
|
||||
3. **Slots** - Structure shared, content page-specific
|
||||
4. **Props** - Configure appearance/behavior
|
||||
5. **States** - Document all interactive states
|
||||
6. **Variants** - Visual style variations
|
||||
7. **Specifications** - Technical measurements
|
||||
8. **Pattern Recognition** - Second occurrence triggers documentation
|
||||
9. **Templates** - Use consistent documentation format
|
||||
10. **Examples** - Learn from complete examples
|
||||
|
||||
### For Freya
|
||||
|
||||
**When designing pages:**
|
||||
- Use components from existing design system
|
||||
- Track component usage
|
||||
- On second occurrence → ask to document
|
||||
- Classify as atom/molecule/organism
|
||||
- Document comprehensively using templates
|
||||
- Extract design tokens (colors, typography, spacing)
|
||||
- Build design system incrementally as patterns emerge
|
||||
|
||||
**Goal:** Every project gets a complete, well-documented design system that grows naturally from the actual page designs created.
|
||||
|
||||
---
|
||||
|
||||
**End of WDS Design System Standards**
|
||||
|
|
@ -22,7 +22,7 @@ module.exports = {
|
|||
const result = await installer.install(config);
|
||||
|
||||
if (result && result.success) {
|
||||
ui.displaySuccess(config.wdsFolder);
|
||||
ui.displaySuccess(config.wdsFolder, config.ide);
|
||||
process.exit(0);
|
||||
}
|
||||
} catch (error) {
|
||||
|
|
|
|||
|
|
@ -111,14 +111,16 @@ class Installer {
|
|||
throw error;
|
||||
}
|
||||
|
||||
// Step 5: Copy learning & reference material (always included)
|
||||
const learnSpinner = ora('Copying learning & reference material...').start();
|
||||
try {
|
||||
await this.copyLearningMaterial(projectDir);
|
||||
learnSpinner.succeed('Learning material added to _wds-learn/ (safe to remove when no longer needed)');
|
||||
} catch (error) {
|
||||
learnSpinner.fail('Failed to copy learning material');
|
||||
throw error;
|
||||
// Step 5: Copy learning & reference material (optional)
|
||||
if (config.install_learning !== false) {
|
||||
const learnSpinner = ora('Copying learning & reference material...').start();
|
||||
try {
|
||||
await this.copyLearningMaterial(projectDir);
|
||||
learnSpinner.succeed('Learning material added to _wds-learn/ (safe to remove when no longer needed)');
|
||||
} catch (error) {
|
||||
learnSpinner.fail('Failed to copy learning material');
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
return { success: true, wdsDir, projectDir };
|
||||
|
|
@ -178,6 +180,7 @@ class Installer {
|
|||
document_output_language: 'en',
|
||||
output_folder: config.root_folder || 'design-process',
|
||||
wds_folder: config.wdsFolder,
|
||||
ide: config.ide || 'windsurf',
|
||||
};
|
||||
|
||||
const yamlStr = yaml.dump(configData, { lineWidth: -1 });
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ class UI {
|
|||
console.log(chalk.white(` Target: ${chalk.cyan(projectDir)}`));
|
||||
console.log(chalk.dim(` Agents and workflows will be installed in ${chalk.white('_wds/')}\n`));
|
||||
|
||||
// Minimal 3-question installer
|
||||
// 5-question installer
|
||||
const answers = await inquirer.prompt([
|
||||
{
|
||||
type: 'input',
|
||||
|
|
@ -58,6 +58,24 @@ class UI {
|
|||
],
|
||||
default: 'brief',
|
||||
},
|
||||
{
|
||||
type: 'list',
|
||||
name: 'ide',
|
||||
message: 'Which IDE are you using?',
|
||||
choices: [
|
||||
{ name: 'Windsurf', value: 'windsurf' },
|
||||
{ name: 'VS Code', value: 'vscode' },
|
||||
{ name: 'Cursor', value: 'cursor' },
|
||||
{ name: 'Other', value: 'other' },
|
||||
],
|
||||
default: 'windsurf',
|
||||
},
|
||||
{
|
||||
type: 'confirm',
|
||||
name: 'install_learning',
|
||||
message: 'Install learning & reference material? (You can remove it later)',
|
||||
default: true,
|
||||
},
|
||||
]);
|
||||
|
||||
return {
|
||||
|
|
@ -71,13 +89,20 @@ class UI {
|
|||
/**
|
||||
* Display success message with next steps
|
||||
*/
|
||||
displaySuccess(wdsFolder) {
|
||||
displaySuccess(wdsFolder, ide = 'windsurf') {
|
||||
const ideName = {
|
||||
windsurf: 'Windsurf',
|
||||
vscode: 'VS Code',
|
||||
cursor: 'Cursor',
|
||||
other: 'your IDE',
|
||||
}[ide] || 'your IDE';
|
||||
|
||||
console.log('');
|
||||
console.log(chalk.green.bold(' ✨ Installation complete!'));
|
||||
console.log('');
|
||||
console.log(chalk.white.bold(' Get Started with Your Product Brief'));
|
||||
console.log('');
|
||||
console.log(chalk.white(' 1. Open this folder in Windsurf or VS Code'));
|
||||
console.log(chalk.white(` 1. Open this folder in ${ideName}`));
|
||||
console.log('');
|
||||
console.log(chalk.white(' 2. Locate the chat window in your IDE and type:'));
|
||||
console.log('');
|
||||
|
|
|
|||
Loading…
Reference in New Issue