Initial commit: Clean DSS implementation
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
This commit is contained in:
Digital Production Factory
622
docs/DEVELOPER_ONBOARDING.md
Normal file
622
docs/DEVELOPER_ONBOARDING.md
Normal file
@@ -0,0 +1,622 @@
|
||||
# Design System v1.0.0 - Developer Onboarding Guide
|
||||
|
||||
**Welcome!** This guide will help you get started with the design system v1.0.0.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start (5 minutes)
|
||||
|
||||
### 1. Install the Design System
|
||||
|
||||
```bash
|
||||
npm install @company/design-system@1.0.0
|
||||
```
|
||||
|
||||
### 2. Import Styles
|
||||
|
||||
```javascript
|
||||
// In your main application file
|
||||
import '@company/design-system/css/variants.css';
|
||||
import '@company/design-system/css/components.css';
|
||||
```
|
||||
|
||||
### 3. Use Components
|
||||
|
||||
```html
|
||||
<!-- Use any design system component -->
|
||||
<ds-button data-variant="primary">Click Me</ds-button>
|
||||
|
||||
<ds-input type="email" placeholder="Enter email" />
|
||||
|
||||
<ds-card>
|
||||
<h3>Card Title</h3>
|
||||
<p>Card content</p>
|
||||
</ds-card>
|
||||
```
|
||||
|
||||
That's it! You're now using the design system.
|
||||
|
||||
---
|
||||
|
||||
## Component Overview
|
||||
|
||||
The design system includes 9 production-ready components:
|
||||
|
||||
### Interactive Components
|
||||
- **DsButton** - Actions and form submissions
|
||||
- **DsInput** - Text input with multiple types
|
||||
- **DsActionBar** - Fixed action bar for primary actions
|
||||
|
||||
### Display Components
|
||||
- **DsCard** - Content containers
|
||||
- **DsBadge** - Status indicators
|
||||
- **DsToast** - Temporary notifications
|
||||
- **DsToastProvider** - Toast container
|
||||
|
||||
### Complex Components
|
||||
- **DsWorkflow** - Multi-step process visualization
|
||||
- **DsNotificationCenter** - Notification inbox
|
||||
|
||||
**Quick reference:** See [COMPONENT_API_REFERENCE.md](./COMPONENT_API_REFERENCE.md) for complete API documentation.
|
||||
|
||||
---
|
||||
|
||||
## Setting Up Your Project
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
your-project/
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ │ └── MyComponent.js
|
||||
│ ├── styles/
|
||||
│ │ └── custom.css
|
||||
│ ├── pages/
|
||||
│ └── App.js
|
||||
├── public/
|
||||
├── package.json
|
||||
└── index.html
|
||||
```
|
||||
|
||||
### Installation Steps
|
||||
|
||||
#### 1. Install npm package
|
||||
|
||||
```bash
|
||||
npm install @company/design-system@1.0.0
|
||||
```
|
||||
|
||||
#### 2. Import Design System CSS
|
||||
|
||||
```javascript
|
||||
// src/main.js or src/App.js
|
||||
import '@company/design-system/css/variants.css';
|
||||
import '@company/design-system/css/components.css';
|
||||
|
||||
// Your custom styles can come after
|
||||
import './styles/custom.css';
|
||||
```
|
||||
|
||||
#### 3. Create HTML Structure
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>My App</title>
|
||||
</head>
|
||||
<body>
|
||||
<div id="app"></div>
|
||||
<script type="module" src="src/main.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
#### 4. Configure CSS Variables (Optional)
|
||||
|
||||
```css
|
||||
/* src/styles/custom.css */
|
||||
:root {
|
||||
/* Override design tokens if needed */
|
||||
--primary: #your-custom-color;
|
||||
--space-4: 1.25rem;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using Components
|
||||
|
||||
### Basic Button Usage
|
||||
|
||||
```html
|
||||
<!-- Different variants -->
|
||||
<ds-button data-variant="primary">Primary</ds-button>
|
||||
<ds-button data-variant="secondary">Secondary</ds-button>
|
||||
<ds-button data-variant="destructive">Delete</ds-button>
|
||||
<ds-button data-variant="ghost">Ghost</ds-button>
|
||||
|
||||
<!-- Different sizes -->
|
||||
<ds-button data-size="sm">Small</ds-button>
|
||||
<ds-button data-size="default">Default</ds-button>
|
||||
<ds-button data-size="lg">Large</ds-button>
|
||||
|
||||
<!-- Icon buttons -->
|
||||
<ds-button data-variant="ghost" data-size="icon">🔍</ds-button>
|
||||
|
||||
<!-- Disabled state -->
|
||||
<ds-button disabled>Disabled</ds-button>
|
||||
```
|
||||
|
||||
### Form with Input
|
||||
|
||||
```html
|
||||
<form id="login-form">
|
||||
<label for="email">Email</label>
|
||||
<ds-input
|
||||
id="email"
|
||||
type="email"
|
||||
placeholder="you@example.com"
|
||||
aria-describedby="email-help"
|
||||
/>
|
||||
<small id="email-help">We'll never share your email</small>
|
||||
|
||||
<label for="password">Password</label>
|
||||
<ds-input
|
||||
id="password"
|
||||
type="password"
|
||||
placeholder="••••••"
|
||||
/>
|
||||
|
||||
<ds-button type="submit" data-variant="primary">
|
||||
Log In
|
||||
</ds-button>
|
||||
</form>
|
||||
|
||||
<script>
|
||||
document.getElementById('login-form').addEventListener('submit', (e) => {
|
||||
e.preventDefault();
|
||||
const email = document.getElementById('email').value;
|
||||
const password = document.getElementById('password').value;
|
||||
console.log('Form submitted:', { email, password });
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
### Toast Notifications
|
||||
|
||||
```javascript
|
||||
// Get the toast provider
|
||||
const toastProvider = document.querySelector('ds-toast-provider');
|
||||
|
||||
// Show different types of notifications
|
||||
toastProvider.showSuccess('Profile saved successfully!');
|
||||
toastProvider.showError('Failed to save profile');
|
||||
toastProvider.showWarning('This action cannot be undone');
|
||||
toastProvider.showInfo('New message received');
|
||||
|
||||
// Custom toast with duration
|
||||
const success = toastProvider.show('Operation complete', 'success', 4000);
|
||||
```
|
||||
|
||||
### Workflow/Multi-Step Process
|
||||
|
||||
```html
|
||||
<ds-workflow data-direction="vertical" data-current-step="1">
|
||||
<ds-workflow-step data-state="completed">Account Setup</ds-workflow-step>
|
||||
<ds-workflow-step data-state="active">Verify Email</ds-workflow-step>
|
||||
<ds-workflow-step data-state="pending">Enable 2FA</ds-workflow-step>
|
||||
<ds-workflow-step data-state="pending">Complete Profile</ds-workflow-step>
|
||||
</ds-workflow>
|
||||
|
||||
<script>
|
||||
const workflow = document.querySelector('ds-workflow');
|
||||
|
||||
document.getElementById('next-button').addEventListener('click', () => {
|
||||
workflow.nextStep();
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using Design Tokens
|
||||
|
||||
Design tokens are CSS variables that define colors, spacing, typography, and more.
|
||||
|
||||
### Common Tokens
|
||||
|
||||
```css
|
||||
/* Colors */
|
||||
--primary /* Main brand color */
|
||||
--secondary /* Secondary accent */
|
||||
--success, --warning, --destructive, --info
|
||||
|
||||
/* Spacing */
|
||||
--space-1 through --space-10 /* 4px to 48px */
|
||||
|
||||
/* Typography */
|
||||
--text-xs, --text-sm, --text-base, --text-lg, --text-xl
|
||||
|
||||
/* Other */
|
||||
--radius /* Border radius (8px) */
|
||||
--duration-normal /* Animation duration (0.2s) */
|
||||
--shadow-md /* Medium shadow */
|
||||
```
|
||||
|
||||
### Using Tokens in Your CSS
|
||||
|
||||
```css
|
||||
/* Always use tokens instead of hardcoded values */
|
||||
.my-component {
|
||||
background: var(--primary); /* ✅ Good */
|
||||
color: var(--foreground);
|
||||
padding: var(--space-4);
|
||||
border-radius: var(--radius);
|
||||
|
||||
/* ❌ Avoid hardcoded values */
|
||||
/* background: #3b82f6; */
|
||||
/* padding: 16px; */
|
||||
}
|
||||
|
||||
/* Responsive with tokens */
|
||||
@media (max-width: 768px) {
|
||||
.my-component {
|
||||
padding: var(--space-3); /* Reduce spacing on mobile */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Reading Tokens in JavaScript
|
||||
|
||||
```javascript
|
||||
// Get a token value
|
||||
function getPrimaryColor() {
|
||||
return getComputedStyle(document.documentElement)
|
||||
.getPropertyValue('--primary')
|
||||
.trim();
|
||||
}
|
||||
|
||||
// Set a token value
|
||||
document.documentElement.style.setProperty('--primary', '#ff0000');
|
||||
|
||||
// Within Web Components
|
||||
class MyComponent extends HTMLElement {
|
||||
getTokenValue(tokenName) {
|
||||
return getComputedStyle(this).getPropertyValue(tokenName).trim();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Full token reference:** See [DESIGN_TOKENS_GUIDE.md](./DESIGN_TOKENS_GUIDE.md)
|
||||
|
||||
---
|
||||
|
||||
## Dark Mode Support
|
||||
|
||||
The design system automatically supports light and dark modes.
|
||||
|
||||
### Enabling Dark Mode
|
||||
|
||||
```javascript
|
||||
// Enable dark mode
|
||||
document.documentElement.classList.add('dark');
|
||||
|
||||
// Disable dark mode
|
||||
document.documentElement.classList.remove('dark');
|
||||
|
||||
// Toggle dark mode
|
||||
document.documentElement.classList.toggle('dark');
|
||||
|
||||
// Save preference
|
||||
localStorage.setItem('theme', 'dark');
|
||||
```
|
||||
|
||||
### Complete Theme Switcher
|
||||
|
||||
```html
|
||||
<button id="theme-toggle">
|
||||
<span id="theme-icon">🌙</span> Toggle Theme
|
||||
</button>
|
||||
|
||||
<script>
|
||||
const button = document.getElementById('theme-toggle');
|
||||
const icon = document.getElementById('theme-icon');
|
||||
|
||||
// Load saved preference
|
||||
const savedTheme = localStorage.getItem('theme') || 'light';
|
||||
if (savedTheme === 'dark') {
|
||||
document.documentElement.classList.add('dark');
|
||||
icon.textContent = '☀️';
|
||||
}
|
||||
|
||||
// Toggle on click
|
||||
button.addEventListener('click', () => {
|
||||
const isDark = document.documentElement.classList.toggle('dark');
|
||||
icon.textContent = isDark ? '☀️' : '🌙';
|
||||
localStorage.setItem('theme', isDark ? 'dark' : 'light');
|
||||
});
|
||||
|
||||
// Respect system preference
|
||||
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
|
||||
document.documentElement.classList.add('dark');
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Accessibility Best Practices
|
||||
|
||||
The design system is WCAG 2.1 Level AA compliant. Here's how to maintain that:
|
||||
|
||||
### Form Labels
|
||||
|
||||
```html
|
||||
<!-- ✅ Good: Label associated with input -->
|
||||
<label for="email">Email Address</label>
|
||||
<ds-input id="email" type="email" />
|
||||
|
||||
<!-- ❌ Bad: No label -->
|
||||
<ds-input type="email" placeholder="Email" />
|
||||
```
|
||||
|
||||
### Error States
|
||||
|
||||
```html
|
||||
<!-- ✅ Good: aria-invalid and aria-describedby -->
|
||||
<label for="email">Email</label>
|
||||
<ds-input
|
||||
id="email"
|
||||
type="email"
|
||||
aria-invalid="true"
|
||||
aria-describedby="email-error"
|
||||
/>
|
||||
<span id="email-error" role="alert">Invalid email format</span>
|
||||
|
||||
<!-- ❌ Bad: No error indication -->
|
||||
<ds-input type="email" />
|
||||
```
|
||||
|
||||
### Button Labels
|
||||
|
||||
```html
|
||||
<!-- ✅ Good: Descriptive button label -->
|
||||
<ds-button aria-label="Close dialog">✕</ds-button>
|
||||
<ds-button>Save Profile</ds-button>
|
||||
|
||||
<!-- ❌ Bad: Icon-only without label -->
|
||||
<ds-button>✕</ds-button>
|
||||
<ds-button>OK</ds-button>
|
||||
```
|
||||
|
||||
### Keyboard Navigation
|
||||
|
||||
All design system components support keyboard navigation:
|
||||
|
||||
- **Button:** Enter or Space to activate
|
||||
- **Input:** Tab to focus, arrow keys for input types
|
||||
- **Toast:** Escape to dismiss
|
||||
- **Workflow:** Tab through steps
|
||||
|
||||
Test keyboard navigation in your app:
|
||||
1. Tab through all interactive elements
|
||||
2. Shift+Tab to go backwards
|
||||
3. Use arrow keys where applicable
|
||||
4. Press Escape to close modals/toasts
|
||||
5. Test Enter/Space to submit/activate
|
||||
|
||||
### Color Contrast
|
||||
|
||||
The design system ensures 4.5:1 minimum contrast ratio (WCAG AA). When customizing colors:
|
||||
|
||||
```css
|
||||
/* Use sufficient contrast */
|
||||
:root {
|
||||
--primary: #0066cc; /* ✅ 8.4:1 contrast on white */
|
||||
--foreground: #000000; /* ✅ 21:1 contrast on white */
|
||||
--muted-foreground: #666666; /* ✅ 5:1 contrast on white */
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Modal Dialog
|
||||
|
||||
```html
|
||||
<div id="modal" style="display: none">
|
||||
<div class="modal-backdrop"></div>
|
||||
<div class="modal-content" role="dialog" aria-labelledby="modal-title">
|
||||
<h2 id="modal-title">Confirm Action</h2>
|
||||
<p>Are you sure you want to proceed?</p>
|
||||
|
||||
<ds-action-bar>
|
||||
<ds-button data-variant="primary">Confirm</ds-button>
|
||||
<ds-button data-variant="ghost">Cancel</ds-button>
|
||||
</ds-action-bar>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
function openModal() {
|
||||
document.getElementById('modal').style.display = 'flex';
|
||||
document.querySelector('[role="dialog"]').focus();
|
||||
}
|
||||
|
||||
function closeModal() {
|
||||
document.getElementById('modal').style.display = 'none';
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
### Notification System
|
||||
|
||||
```html
|
||||
<ds-toast-provider data-position="top-right"></ds-toast-provider>
|
||||
|
||||
<script>
|
||||
const provider = document.querySelector('ds-toast-provider');
|
||||
|
||||
// API call with notification
|
||||
fetch('/api/save-profile', { method: 'POST' })
|
||||
.then(response => {
|
||||
if (response.ok) {
|
||||
provider.showSuccess('Profile saved!');
|
||||
} else {
|
||||
throw new Error('Save failed');
|
||||
}
|
||||
})
|
||||
.catch(error => {
|
||||
provider.showError(`Error: ${error.message}`);
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
### Search Input
|
||||
|
||||
```html
|
||||
<ds-input
|
||||
type="search"
|
||||
id="search"
|
||||
placeholder="Search..."
|
||||
aria-label="Search"
|
||||
aria-describedby="search-help"
|
||||
/>
|
||||
<small id="search-help">Press Enter to search</small>
|
||||
|
||||
<script>
|
||||
const input = document.getElementById('search');
|
||||
input.addEventListener('change', (e) => {
|
||||
const query = e.target.value;
|
||||
console.log('Search for:', query);
|
||||
// Perform search...
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues & Solutions
|
||||
|
||||
### Issue: Components not styled
|
||||
**Solution:** Make sure CSS is imported before using components
|
||||
```javascript
|
||||
import '@company/design-system/css/variants.css';
|
||||
import '@company/design-system/css/components.css';
|
||||
```
|
||||
|
||||
### Issue: Dark mode not working
|
||||
**Solution:** Add the `dark` class to the root element
|
||||
```javascript
|
||||
document.documentElement.classList.add('dark');
|
||||
```
|
||||
|
||||
### Issue: Custom colors not applying
|
||||
**Solution:** Use design tokens, not hardcoded colors
|
||||
```css
|
||||
/* ❌ Won't work */
|
||||
.my-button { background: #3b82f6; }
|
||||
|
||||
/* ✅ Works */
|
||||
.my-button { background: var(--primary); }
|
||||
```
|
||||
|
||||
### Issue: Accessibility warnings
|
||||
**Solution:** Always add labels and aria attributes
|
||||
```html
|
||||
<!-- ✅ Good -->
|
||||
<label for="email">Email</label>
|
||||
<ds-input id="email" type="email" />
|
||||
|
||||
<!-- ❌ Bad -->
|
||||
<ds-input type="email" placeholder="Email" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Components
|
||||
|
||||
### Unit Testing Example
|
||||
|
||||
```javascript
|
||||
// test.spec.js
|
||||
import '@company/design-system/css/variants.css';
|
||||
|
||||
describe('DsButton', () => {
|
||||
test('button renders with primary variant', () => {
|
||||
const button = document.createElement('ds-button');
|
||||
button.setAttribute('data-variant', 'primary');
|
||||
button.textContent = 'Click me';
|
||||
|
||||
document.body.appendChild(button);
|
||||
|
||||
expect(button.getAttribute('data-variant')).toBe('primary');
|
||||
expect(button.textContent).toBe('Click me');
|
||||
|
||||
document.body.removeChild(button);
|
||||
});
|
||||
|
||||
test('button emits click event', (done) => {
|
||||
const button = document.createElement('ds-button');
|
||||
document.body.appendChild(button);
|
||||
|
||||
button.addEventListener('click', () => {
|
||||
expect(true).toBe(true);
|
||||
document.body.removeChild(button);
|
||||
done();
|
||||
});
|
||||
|
||||
button.click();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Learning Resources
|
||||
|
||||
### Documentation Files
|
||||
- [Component API Reference](./COMPONENT_API_REFERENCE.md) - Complete API for all 9 components
|
||||
- [Design Tokens Guide](./DESIGN_TOKENS_GUIDE.md) - All 42 design tokens
|
||||
- [Theme System](./THEME_SYSTEM.md) - Theme customization guide
|
||||
- [Accessibility Guide](./ACCESSIBILITY_GUIDE.md) - WCAG 2.1 compliance details
|
||||
|
||||
### Getting Help
|
||||
- **Documentation:** https://design-system.yourcompany.com/docs
|
||||
- **Slack:** #design-system
|
||||
- **Email:** design-system@company.com
|
||||
- **Issues:** github.com/company/design-system/issues
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Install the package** - `npm install @company/design-system@1.0.0`
|
||||
2. **Import styles** - Add CSS imports to your main file
|
||||
3. **Try components** - Use 2-3 components in your app
|
||||
4. **Check docs** - Review component APIs as needed
|
||||
5. **Test themes** - Toggle dark mode to verify it works
|
||||
6. **Ask questions** - Reach out on Slack if stuck
|
||||
|
||||
---
|
||||
|
||||
## Version Information
|
||||
|
||||
- **Current Version:** 1.0.0
|
||||
- **Released:** December 7, 2025
|
||||
- **Components:** 9 production-ready components
|
||||
- **Tokens:** 42 design tokens
|
||||
- **Test Coverage:** 115+ tests (WCAG 2.1 AA)
|
||||
- **Browser Support:** Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
|
||||
|
||||
---
|
||||
|
||||
**Happy coding! 🎉**
|
||||
|
||||
Questions? Join us on Slack in #design-system or email design-system@company.com
|
||||
Reference in New Issue
Block a user