@stmarketing/design-system

v1.0.0

Published

19 days ago

Single Throw Marketing - Internal Tools Design System

0High
0Medium
0Low

singlethrow

design-system css ui components stm single-throw-marketing

STM Design System v2.0.0

A world-class, comprehensive design system for Single Throw Marketing internal tools and analytics dashboards.

What's This?

A production-ready design system with 40+ components built for marketing analytics tools. One import gives you everything you need to build professional, accessible, delightful user experiences.

Key Features:

40+ Components: From buttons to command palettes
Design Tokens: Consistent colors, typography, spacing, motion
Fully Responsive: Mobile-first, touch-optimized
Accessible: WCAG 2.1 Level AA compliant
Performance: <15KB gzipped, hardware-accelerated animations
Well-Documented: Examples, best practices, patterns

What's New in v2.0.0

✨ 32 new components (total 40+)
📊 Complete data display suite (tables, skeletons, empty states)
🎛️ Advanced form components (file upload, multi-step, toggles)
🗂️ Navigation patterns (sidebar, tabs, breadcrumbs)
💬 Rich feedback system (modals, toasts, tooltips)
♿ Enhanced accessibility across all components
📱 Mobile-optimized interactions
🚀 Performance improvements
📚 Comprehensive documentation

Quick Start

Installation

# Copy the design system to your project
cp -r stm-design-system/ your-project/src/

Usage in Next.js

// app/layout.tsx
import '@/stm-design-system/theme.css'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  )
}

Usage in React

// index.tsx or App.tsx
import 'stm-design-system/theme.css'

Basic Example

<button className="stm-btn stm-btn-primary">
  Click Me
</button>

<div className="stm-card stm-card-professional">
  <h3>Card Title</h3>
  <p>Card content goes here.</p>
</div>

Component Library

Basic Components (8)

Buttons

6 variants for different contexts:

<!-- Primary Action -->
<button className="stm-btn stm-btn-primary">Primary</button>

<!-- Secondary Action -->
<button className="stm-btn stm-btn-outline">Outline</button>

<!-- Destructive Action -->
<button className="stm-btn stm-btn-danger">Delete</button>

<!-- Ghost Button -->
<button className="stm-btn stm-btn-ghost">Ghost</button>

<!-- Link Style -->
<button className="stm-btn stm-btn-link">Link</button>

<!-- Sizes -->
<button className="stm-btn stm-btn-primary stm-btn-sm">Small</button>
<button className="stm-btn stm-btn-primary">Default</button>
<button className="stm-btn stm-btn-primary stm-btn-lg">Large</button>

<!-- States -->
<button className="stm-btn stm-btn-primary" disabled>Disabled</button>

Form Inputs

Complete form system with validation:

<!-- Text Input -->
<label className="stm-label">Email</label>
<input type="email" className="stm-input" placeholder="[email protected]" />
<span className="stm-helper">We'll never share your email.</span>

<!-- Error State -->
<input type="email" className="stm-input stm-input-error" />
<span className="stm-error-message">Please enter a valid email</span>

<!-- Success State -->
<input type="text" className="stm-input stm-input-success" />

<!-- Textarea -->
<textarea className="stm-input stm-textarea"></textarea>

<!-- Select -->
<select className="stm-input stm-select">
  <option>Choose an option</option>
  <option>Option 1</option>
</select>

Cards

3 card types for different use cases:

<!-- Professional Card -->
<div className="stm-card stm-card-professional">
  <h3>Card Title</h3>
  <p>Card content</p>
</div>

<!-- Stat Card -->
<div className="stm-card stm-card-stat">
  <div className="stm-card-label">Total Users</div>
  <div className="stm-card-value">1,234</div>
  <div className="stm-card-change">+12% from last month</div>
</div>

<!-- List Card -->
<div className="stm-card stm-card-list">
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
  </ul>
</div>

Badges

Status indicators with semantic colors:

<span className="stm-badge stm-badge-primary">New</span>
<span className="stm-badge stm-badge-success">Active</span>
<span className="stm-badge stm-badge-warning">Pending</span>
<span className="stm-badge stm-badge-error">Failed</span>
<span className="stm-badge stm-badge-outline">Draft</span>

Navigation Components (6)

Sidebar Navigation

Collapsible sidebar with nested items:

<aside className="stm-sidebar">
  <div className="stm-sidebar-header">
    <div className="stm-sidebar-logo">STM Tools</div>
    <button className="stm-sidebar-toggle">☰</button>
  </div>
  
  <nav className="stm-sidebar-content">
    <div className="stm-nav-section">
      <div className="stm-nav-section-title">Main</div>
      <ul className="stm-nav-items">
        <li className="stm-nav-item">
          <a href="/" className="stm-nav-link stm-nav-link-active">
            <span className="stm-nav-icon">📊</span>
            Dashboard
          </a>
        </li>
        <li className="stm-nav-item">
          <a href="/analytics" className="stm-nav-link">
            <span className="stm-nav-icon">📈</span>
            Analytics
          </a>
        </li>
      </ul>
    </div>
  </nav>
</aside>

Tabs

Default and pill-style tabs:

<!-- Default Tabs -->
<div className="stm-tabs">
  <div className="stm-tabs-list">
    <button className="stm-tabs-trigger stm-tabs-trigger-active">Overview</button>
    <button className="stm-tabs-trigger">Details</button>
    <button className="stm-tabs-trigger">Settings</button>
  </div>
  
  <div className="stm-tabs-content">
    <!-- Tab content here -->
  </div>
</div>

<!-- Pill Tabs -->
<div className="stm-tabs stm-tabs-pill">
  <div className="stm-tabs-list">
    <button className="stm-tabs-trigger stm-tabs-trigger-active">Tab 1</button>
    <button className="stm-tabs-trigger">Tab 2</button>
  </div>
</div>

Breadcrumbs

Page navigation hierarchy:

<nav className="stm-breadcrumbs">
  <div className="stm-breadcrumb-item">
    <a href="/" className="stm-breadcrumb-link">Home</a>
    <span className="stm-breadcrumb-separator">/</span>
  </div>
  <div className="stm-breadcrumb-item">
    <a href="/analytics" className="stm-breadcrumb-link">Analytics</a>
    <span className="stm-breadcrumb-separator">/</span>
  </div>
  <div className="stm-breadcrumb-item">
    <span className="stm-breadcrumb-current">Campaign Performance</span>
  </div>
</nav>

Page Header

Consistent page header pattern:

<header className="stm-page-header">
  <div className="stm-page-header-top">
    <!-- Breadcrumbs here -->
  </div>
  
  <div className="stm-page-header-main">
    <div className="stm-page-header-content">
      <h1 className="stm-page-title">Campaign Performance</h1>
      <p className="stm-page-description">View and analyze campaign metrics</p>
    </div>
    
    <div className="stm-page-header-actions">
      <button className="stm-btn stm-btn-outline">Export</button>
      <button className="stm-btn stm-btn-primary">New Campaign</button>
    </div>
  </div>
</header>

Dropdown Menus

Context-aware action menus:

<div className="stm-dropdown stm-dropdown-open">
  <button className="stm-dropdown-trigger stm-btn stm-btn-outline">
    Actions ▾
  </button>
  
  <div className="stm-dropdown-content">
    <button className="stm-dropdown-item">Edit</button>
    <button className="stm-dropdown-item">Duplicate</button>
    <div className="stm-dropdown-separator"></div>
    <button className="stm-dropdown-item stm-dropdown-item-danger">Delete</button>
  </div>
</div>

Feedback Components (12)

Modals

5 sizes with mobile bottom sheet:

<div className="stm-modal-overlay stm-modal-overlay-open"></div>

<div className="stm-modal-wrapper">
  <div className="stm-modal stm-modal-md stm-modal-open">
    <div className="stm-modal-header">
      <h2 className="stm-modal-title">Modal Title</h2>
      <button className="stm-modal-close">×</button>
    </div>
    
    <div className="stm-modal-content">
      <p className="stm-modal-description">Modal content goes here.</p>
    </div>
    
    <div className="stm-modal-footer">
      <button className="stm-btn stm-btn-outline">Cancel</button>
      <button className="stm-btn stm-btn-primary">Confirm</button>
    </div>
  </div>
</div>

Toast Notifications

Auto-dismissing notifications:

<div className="stm-toast-container stm-toast-top-right">
  <div className="stm-toast stm-toast-success">
    <div className="stm-toast-icon">✓</div>
    <div className="stm-toast-content">
      <div className="stm-toast-title">Success</div>
      <div className="stm-toast-message">Your changes have been saved.</div>
    </div>
    <button className="stm-toast-close">×</button>
  </div>
</div>

Alerts

Inline alert messages:

<div className="stm-alert stm-alert-info">
  <div className="stm-alert-icon">ℹ</div>
  <div className="stm-alert-content">
    <div className="stm-alert-title">Did you know?</div>
    <div className="stm-alert-message">You can export data to CSV.</div>
  </div>
  <button className="stm-alert-close">×</button>
</div>

Tooltips

Contextual help:

<div className="stm-tooltip-wrapper">
  <button className="stm-btn stm-btn-outline">Hover me</button>
  <div className="stm-tooltip stm-tooltip-top stm-tooltip-visible">
    Helpful tooltip text
  </div>
</div>

Data Display Components (8)

Tables

Sortable, selectable tables with pagination:

<div className="stm-table-wrapper">
  <table className="stm-table">
    <thead className="stm-table-header">
      <tr className="stm-table-header-row">
        <th className="stm-table-header-cell stm-table-header-cell-sortable">
          Name
        </th>
        <th className="stm-table-header-cell">Email</th>
        <th className="stm-table-header-cell">Status</th>
        <th className="stm-table-header-cell stm-table-cell-actions">Actions</th>
      </tr>
    </thead>
    <tbody>
      <tr className="stm-table-body-row">
        <td className="stm-table-cell">John Doe</td>
        <td className="stm-table-cell">[email protected]</td>
        <td className="stm-table-cell">
          <span className="stm-badge stm-badge-success">Active</span>
        </td>
        <td className="stm-table-cell stm-table-cell-actions">
          <div className="stm-table-actions">
            <button className="stm-btn stm-btn-sm">Edit</button>
          </div>
        </td>
      </tr>
    </tbody>
  </table>
  
  <div className="stm-table-footer">
    <div className="stm-table-pagination-info">Showing 1-10 of 100</div>
    <div className="stm-table-pagination">
      <button className="stm-table-pagination-button" disabled>Previous</button>
      <button className="stm-table-pagination-button">Next</button>
    </div>
  </div>
</div>

Empty States

User-friendly empty content:

<div className="stm-empty-state">
  <div className="stm-empty-state-icon">📭</div>
  <h3 className="stm-empty-state-title">No campaigns yet</h3>
  <p className="stm-empty-state-description">
    Get started by creating your first marketing campaign.
  </p>
  <div className="stm-empty-state-action">
    <button className="stm-btn stm-btn-primary">Create Campaign</button>
  </div>
</div>

Loading Skeletons

Content placeholders:

<div className="stm-skeleton stm-skeleton-title"></div>
<div className="stm-skeleton stm-skeleton-text"></div>
<div className="stm-skeleton stm-skeleton-text stm-skeleton-text-medium"></div>
<div className="stm-skeleton stm-skeleton-text stm-skeleton-text-short"></div>

Progress Bars

Visual progress indicators:

<div className="stm-progress">
  <div className="stm-progress-bar" style="width: 75%"></div>
</div>

<!-- With label -->
<div className="stm-progress-with-label">
  <span className="stm-progress-label">75%</span>
  <div className="stm-progress">
    <div className="stm-progress-bar" style="width: 75%"></div>
  </div>
</div>

<!-- Indeterminate -->
<div className="stm-progress stm-progress-indeterminate">
  <div className="stm-progress-bar"></div>
</div>

Data Cards

Metric display cards:

<div className="stm-data-card">
  <div className="stm-data-card-header">
    <span className="stm-data-card-label">Total Revenue</span>
    <div className="stm-data-card-icon">💰</div>
  </div>
  <div className="stm-data-card-value">$24,500</div>
  <div className="stm-data-card-footer">
    <span className="stm-data-card-change stm-data-card-change-positive">
      ↑ 12%
    </span>
    <span className="stm-data-card-period">vs last month</span>
  </div>
</div>

Advanced Form Components (10)

Toggle Switches

On/off controls:

<div className="stm-toggle-wrapper">
  <div className="stm-toggle stm-toggle-checked">
    <div className="stm-toggle-thumb"></div>
  </div>
  <span className="stm-toggle-label">Enable notifications</span>
</div>

Radio Groups

Single selection from options:

<div className="stm-radio-group">
  <label className="stm-radio-item">
    <div className="stm-radio stm-radio-checked"></div>
    <span className="stm-radio-label">Option 1</span>
  </label>
  <label className="stm-radio-item">
    <div className="stm-radio"></div>
    <span className="stm-radio-label">Option 2</span>
  </label>
</div>

Checkbox Groups

Multiple selections:

<div className="stm-checkbox-group">
  <label className="stm-checkbox-item">
    <div className="stm-checkbox stm-checkbox-checked"></div>
    <span className="stm-checkbox-label">Option 1</span>
  </label>
  <label className="stm-checkbox-item">
    <div className="stm-checkbox"></div>
    <span className="stm-checkbox-label">Option 2</span>
  </label>
</div>

File Upload

Drag & drop file upload:

<div className="stm-file-upload">
  <div className="stm-file-upload-dropzone">
    <div className="stm-file-upload-icon">📁</div>
    <div className="stm-file-upload-text">
      <div className="stm-file-upload-title">Click to upload or drag and drop</div>
      <div className="stm-file-upload-subtitle">PDF, PNG, JPG up to 10MB</div>
    </div>
  </div>
  
  <div className="stm-file-list">
    <div className="stm-file-item">
      <div className="stm-file-icon">📄</div>
      <div className="stm-file-info">
        <div className="stm-file-name">document.pdf</div>
        <div className="stm-file-size">2.4 MB</div>
      </div>
      <button className="stm-file-remove">×</button>
    </div>
  </div>
</div>

Multi-Step Forms

Wizard-style forms:

<div className="stm-stepper">
  <div className="stm-step stm-step-completed">
    <div className="stm-step-number">1</div>
    <div className="stm-step-label">Account</div>
  </div>
  <div className="stm-step stm-step-active">
    <div className="stm-step-number">2</div>
    <div className="stm-step-label">Profile</div>
  </div>
  <div className="stm-step">
    <div className="stm-step-number">3</div>
    <div className="stm-step-label">Review</div>
  </div>
</div>

<div className="stm-step-content">
  <!-- Step content -->
</div>

<div className="stm-step-actions">
  <button className="stm-btn stm-btn-outline">Back</button>
  <button className="stm-btn stm-btn-primary">Continue</button>
</div>

Complex Interaction Components (10)

Accordions

Collapsible content sections:

<div className="stm-accordion">
  <div className="stm-accordion-item stm-accordion-item-open">
    <button className="stm-accordion-trigger">
      <span>Section 1</span>
      <span className="stm-accordion-icon">▼</span>
    </button>
    <div className="stm-accordion-content">
      <div className="stm-accordion-content-inner">
        Content for section 1
      </div>
    </div>
  </div>
</div>

Command Palette

Keyboard-driven command menu:

<div className="stm-command-overlay stm-command-overlay-open">
  <div className="stm-command-palette stm-command-palette-open">
    <div className="stm-command-search">
      <span className="stm-command-search-icon">🔍</span>
      <input type="text" className="stm-command-input" placeholder="Type a command..." />
    </div>
    
    <div className="stm-command-list">
      <div className="stm-command-group">
        <div className="stm-command-group-heading">Actions</div>
        <button className="stm-command-item">
          <span className="stm-command-item-icon">➕</span>
          <span className="stm-command-item-content">Create Campaign</span>
          <span className="stm-command-item-shortcut">
            <kbd className="stm-command-kbd">⌘</kbd>
            <kbd className="stm-command-kbd">N</kbd>
          </span>
        </button>
      </div>
    </div>
  </div>
</div>

Design Tokens

Colors

Brand Colors

--stm-single: #1A5276;    /* Primary blue */
--stm-throw: #6B8F71;      /* Secondary green */
--stm-marketing: #6E6F71;  /* Neutral gray */

Semantic Colors

--stm-primary: var(--stm-single);
--stm-secondary: var(--stm-throw);
--stm-success: #059669;
--stm-warning: #F59E0B;
--stm-error: #DC2626;

Typography

Font Families

--stm-font-headline: system-ui, sans-serif;
--stm-font-body: system-ui, sans-serif;
--stm-font-mono: 'SF Mono', Monaco, monospace;

Font Sizes

--stm-text-xs: 0.75rem;    /* 12px */
--stm-text-sm: 0.875rem;   /* 14px */
--stm-text-base: 1rem;     /* 16px */
--stm-text-lg: 1.125rem;   /* 18px */
--stm-text-xl: 1.25rem;    /* 20px */
--stm-text-2xl: 1.5rem;    /* 24px */
--stm-text-3xl: 1.875rem;  /* 30px */
--stm-text-4xl: 2.25rem;   /* 36px */

Spacing

Scale (8-point grid)

--stm-space-1: 0.25rem;  /* 4px */
--stm-space-2: 0.5rem;   /* 8px */
--stm-space-3: 0.75rem;  /* 12px */
--stm-space-4: 1rem;     /* 16px */
--stm-space-6: 1.5rem;   /* 24px */
--stm-space-8: 2rem;     /* 32px */
--stm-space-10: 2.5rem;  /* 40px */
--stm-space-12: 3rem;    /* 48px */

Motion

Animation Timing

--stm-duration-fast: 150ms;     /* Hover, focus */
--stm-duration-normal: 300ms;   /* Modals, transitions */
--stm-duration-slow: 500ms;     /* Page transitions */

--stm-ease-out: cubic-bezier(0, 0, 0.2, 1);

Customization

Override CSS variables to customize the theme:

/* In your global CSS */
:root {
  /* Brand colors */
  --stm-primary: #your-brand-color;
  --stm-secondary: #your-secondary-color;
  
  /* Typography */
  --stm-font-headline: 'Your Font', sans-serif;
  --stm-text-base: 18px;  /* Larger base font */
  
  /* Spacing */
  --stm-space-4: 1.25rem;  /* Adjust spacing scale */
  
  /* Border radius */
  --stm-radius-lg: 12px;  /* Rounder corners */
  
  /* Motion */
  --stm-duration-fast: 100ms;  /* Faster animations */
}

Accessibility

All components follow WCAG 2.1 Level AA standards:

Keyboard Navigation: All interactive elements are keyboard accessible
Focus Management: Clear focus indicators on all controls
Screen Readers: Proper ARIA labels and semantic HTML
Color Contrast: 4.5:1 minimum ratio for text
Touch Targets: 44px minimum for mobile interactions
Motion: Respects prefers-reduced-motion

Performance

CSS Size: ~6,000 lines unminified
Gzipped: ~15KB
Tree-shakeable: Import only what you need
Hardware Accelerated: Animations use transform and opacity
No Dependencies: Pure CSS, no JavaScript required
Critical CSS: Consider inlining tokens for fastest load

Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+
iOS Safari 14+
Android Chrome 90+

Migration from v1.0

Breaking Changes

None! v2.0 is fully backward compatible.

New Features

All v1.0 components work unchanged. 32 new components are additive.

Recommended Updates

Update theme.css import
Use new navigation components (sidebar, tabs)
Replace custom modals with design system modals
Adopt data display components (tables, cards)

Best Practices

Do's ✅

Use semantic HTML elements
Follow the spacing scale consistently
Apply focus states to interactive elements
Test with keyboard navigation
Use loading skeletons for async content
Provide meaningful alt text for images
Use proper heading hierarchy
Test with screen readers

Don'ts ❌

Don't override with !important
Don't mix spacing systems
Don't use only color to convey meaning
Don't forget hover states
Don't block keyboard navigation
Don't use generic "click here" text
Don't skip heading levels

Contributing

This is an internal STM tool. For updates:

Discuss changes in #design-system Slack channel
Follow the component structure pattern
Document new components in README
Update CHANGELOG.md
Test accessibility
Update preview.html

Support

Internal: #design-system Slack channel
Email: [email protected]
Docs: /docs/design-system