# 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
Click Me
Card Title
Card content
```
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
My App
```
#### 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
PrimarySecondaryDeleteGhostSmallDefaultLarge🔍Disabled
```
### Form with Input
```html
```
### 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
Account SetupVerify EmailEnable 2FAComplete Profile
```
---
## 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
```
---
## Accessibility Best Practices
The design system is WCAG 2.1 Level AA compliant. Here's how to maintain that:
### Form Labels
```html
```
### Error States
```html
Invalid email format
```
### Button Labels
```html
✕Save Profile✕OK
```
### 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
Confirm Action
Are you sure you want to proceed?
ConfirmCancel
```
### Notification System
```html
```
### Search Input
```html
Press Enter to search
```
---
## 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
```
---
## 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