bruno/dss

Files

Digital Production Factory 276ed71f31 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

2025-12-09 18:45:48 -03:00

14 KiB

Raw Blame History

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

npm install @company/design-system@1.0.0

2. Import Styles

// In your main application file
import '@company/design-system/css/variants.css';
import '@company/design-system/css/components.css';

3. Use Components

<!-- 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 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

npm install @company/design-system@1.0.0

2. Import Design System CSS

// 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

<!-- 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)

/* src/styles/custom.css */
:root {
  /* Override design tokens if needed */
  --primary: #your-custom-color;
  --space-4: 1.25rem;
}

Using Components

Basic Button Usage

<!-- 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

<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

// 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

<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

/* 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

/* 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

// 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

Dark Mode Support

The design system automatically supports light and dark modes.

Enabling Dark Mode

// 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

<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

<!-- ✅ 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

<!-- ✅ 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

<!-- ✅ 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>

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:

Tab through all interactive elements
Shift+Tab to go backwards
Use arrow keys where applicable
Press Escape to close modals/toasts
Test Enter/Space to submit/activate

Color Contrast

The design system ensures 4.5:1 minimum contrast ratio (WCAG AA). When customizing colors:

/* 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

<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

<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

<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

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

document.documentElement.classList.add('dark');

Issue: Custom colors not applying

Solution: Use design tokens, not hardcoded colors

/* ❌ Won't work */
.my-button { background: #3b82f6; }

/* ✅ Works */
.my-button { background: var(--primary); }

Issue: Accessibility warnings

Solution: Always add labels and aria attributes

<!-- ✅ Good -->
<label for="email">Email</label>
<ds-input id="email" type="email" />

<!-- ❌ Bad -->
<ds-input type="email" placeholder="Email" />

Testing Components

Unit Testing Example

// 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 - Complete API for all 9 components
Design Tokens Guide - All 42 design tokens
Theme System - Theme customization guide
Accessibility Guide - 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

Install the package - npm install @company/design-system@1.0.0
Import styles - Add CSS imports to your main file
Try components - Use 2-3 components in your app
Check docs - Review component APIs as needed
Test themes - Toggle dark mode to verify it works
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

14 KiB Raw Blame History