# 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
