Design System — Use Across the Application
You do not need to build a new design system from scratch. PulseGate already has a common design system in place: shared tokens, components, and patterns. This page documents it so the whole application (and any future CRM or app) uses the same experience.
Do we need a common design system?
Yes — for consistency. You already have one; it lives in the dashboard codebase and CSS. Formalizing it here means:
- One place to look for colors, components, and patterns.
- Same UX across Dashboard, Leads, CRM, and any new feature.
- Faster builds — reuse instead of reinventing.
You do not need a separate design-system repo or npm package unless you have multiple applications (e.g. a separate marketing site or mobile app) that must share components. For a single dashboard + CRM, the current setup is enough; just treat this doc and the referenced code as the single source of truth.
What we already have
1. Design tokens (colors, radius, spacing)
Location: dashboard/src/index.css
| Token type | Where | Usage |
|---|---|---|
| Colors | @theme { ... } and `[data-theme="light | dark"], [data-color="..."]` |
| Radius | --radius-sm, --radius-md, --radius-lg, --radius-xl | Buttons, cards, inputs. |
| Theme mode | `data-theme="light" | "dark"` (or system) |
| Theme color | `data-color="neutral" | "zinc" |
Use these tokens via Tailwind (e.g. bg-primary, text-muted-foreground, border-border) or var(--color-*) in custom CSS. Do not hardcode hex/oklch in components; use semantic names so theme and brand stay consistent.
2. UI components (primitives)
Location: dashboard/src/components/ui/
| Component | File | Use |
|---|---|---|
| Button | button.tsx | All actions. Variants: default, secondary, outline, ghost, destructive. Sizes: default, sm, lg, icon. |
| Card | card.tsx | Card, CardHeader, CardTitle, CardContent — sections, list containers. |
| Input | input.tsx | Text inputs, search, numeric/date filters. |
| Badge | badge.tsx | Status, score, risk, counts. Variants: default, secondary, outline, destructive, plus score variants (e.g. cold, warm, hot, very-hot). |
| Checkbox | checkbox.tsx | Row selection, toggles. |
| Spinner | spinner.tsx | Loading states. |
| Tabs | tabs.tsx | Tabbed content. |
| Switch | switch.tsx | Boolean settings. |
| Collapsible | collapsible.tsx | Expand/collapse (e.g. sidebar groups). |
| Table | table.tsx | Table wrapper (optional); many pages use native <table> with Tailwind. |
| Chart | chart.tsx | Recharts wrapper for consistent chart styling. |
All use class-variance-authority (CVA) or cn() for consistent styling. Use these everywhere; do not add one-off styled buttons or cards.
3. Composite components (patterns)
Location: dashboard/src/components/ (and ui/)
| Component | File | Use |
|---|---|---|
| Pagination | ui/pagination.tsx | Below data tables. Page X of Y, 20/50/100 per page, Previous/Next. |
| QuickRangeFilter | ui/quick-range-filter.tsx | Date presets (Today, Past 7 days, etc.). |
| BulkActionsBar | ui/bulk-actions-bar.tsx | When rows are selected; “Clear selection” + actions. |
| ConfirmDestructiveModal | ui/confirm-destructive-modal.tsx | Confirm delete or irreversible actions. |
| DropdownOptionSelect | dropdown-option-select.tsx | Project, Source, etc. from API (dropdown options). |
These encode patterns (pagination, date filter, bulk actions, destructive confirm, option dropdown). Reuse them on every list/detail page that needs the same behaviour so the app feels consistent.
4. Layout and navigation
| Piece | Location | Use |
|---|---|---|
| Layout | components/layout.tsx | Sidebar + main content; wrap all authenticated pages. |
| Sidebar | components/sidebar.tsx | Nav groups, theme + theme-color, collapse. |
| ThemeProvider | lib/theme.tsx | Theme mode + theme color; wrap app. |
Use the same shell for Dashboard, Leads, CRM, and Settings so layout and navigation are identical.
5. Usage guidelines (UX)
Location: docs/ux/sales-crm-ux.md
That doc is the UX contract for list/detail, tables, side panel, filters, search, buttons, modals, and badges. When building any new feature (including CRM):
- Follow the page patterns (list + side panel, full detail).
- Use the component inventory listed there (and above).
- Match interaction rules (row click → panel, Escape → close, filters reset offset).
So: tokens + components = look; UX guide = behaviour and structure. Together they form the design system.
How to use this across the application
| Situation | What to do |
|---|---|
| New page in the dashboard | Use Layout, Sidebar, tokens (Tailwind classes), and components from @/components/ui and composite components. Follow Sales CRM UX for tables, filters, side panel. |
| New “app” in same repo (e.g. CRM) | Same as above. Reuse all components and patterns; no new design system. |
| Separate application (different repo) | Use this doc + Sales CRM UX as a spec: same tokens (copy or adapt index.css theme block), same component list and variants, same page patterns and behaviour. Reimplement in your stack so the experience stays consistent. |
| Changing brand or theme | Update only index.css (and any data-color presets). Components use semantic tokens, so they stay consistent. |
| Adding a new component | Add it under components/ui/ (or a composite in components/). Use CVA + cn(), use design tokens (Tailwind or CSS vars). Document it in this page and in the UX guide if it’s a pattern (e.g. a new modal type). |
Summary
- You already have a common design system: tokens in
index.css, UI components incomponents/ui/, composite components, Layout/Sidebar/Theme, and the Sales CRM UX guide. - You do not need to build a new one for a single app; you only need to use it consistently and treat this doc as the reference.
- To use the same UX across the application: use the same tokens, same components, and same patterns (documented in the UX guide). For a separate app, treat this as the spec and reimplement in that stack.
- When to go further (e.g. a shared npm package or design-system repo): when you have multiple apps that must share the exact same code (e.g. dashboard + marketing site + mobile). Until then, this lightweight “doc + existing code” design system is enough.