@deepgram/styles

v0.2.15

Published

2 months ago

Tailwind-based design system and styles library for Deepgram design system and demos

0High
0Medium
0Low

deepgramai

lukeoliff

deepgram-kiley

deepgram design-system styles css tailwind tailwindcss ui-components frontend

@deepgram/styles

A comprehensive, YAML-driven design system and CSS component library for building consistent Deepgram applications. Built on Tailwind CSS v4 with automatic light/dark mode, BEM methodology, and zero-config theming.

Quick Start

CDN

Add to your HTML <head>:

<!-- Deepgram Styles -->
<link rel="stylesheet" href="https://unpkg.com/@deepgram/styles/dist/deepgram.css">

<!-- Font Awesome for icons -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/all.min.css"
  integrity="sha512-z3gLpd7yknf1YoNbCzqRKc4qyor8gaKU1qmn+CShxbuBusANI9QpRohGBreCFkKxLhei6S9CQXFEbbKuqLg0DA=="
  crossorigin="anonymous" referrerpolicy="no-referrer">

jsDelivr alternative:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@deepgram/styles/dist/deepgram.css">

npm

npm install @deepgram/styles @fortawesome/fontawesome-free

Import in your JS/TS entry file:

import '@deepgram/styles';
import '@fortawesome/fontawesome-free/css/all.min.css';

Verify it works

Paste this into your page — you should see a styled green button:

<button class="dg-btn dg-btn--primary">
  <i class="fas fa-check"></i>
  It works!
</button>

Using the Stylesheet

BEM Naming

All classes use the dg- prefix with BEM methodology:

| Pattern | Purpose | Example | |---------|---------|---------| | .dg-{name} | Block (root component) | .dg-btn, .dg-card | | .dg-{name}__{element} | Element (child part) | .dg-card__header, .dg-card__body | | .dg-{name}--{modifier} | Modifier (variant) | .dg-btn--primary, .dg-card--compact |

Light/Dark Mode

The stylesheet uses CSS light-dark() for all color tokens — theme switching is automatic:

Automatic: Follows OS preference out of the box (color-scheme: light dark on :root)
No JS required: Pure CSS implementation — no class toggling

Force a mode:

:root { color-scheme: dark; }  /* Always dark */
:root { color-scheme: light; } /* Always light */

Or via JavaScript:

document.documentElement.style.colorScheme = 'dark';  // Force dark
document.documentElement.style.colorScheme = 'light'; // Force light
document.documentElement.style.removeProperty('color-scheme'); // System

Theme Utilities

For apps with a theme toggle and localStorage persistence:

import { setLight, setDark, setSystem, getTheme, restoreTheme, onThemeChange } from '@deepgram/styles/utils';

setLight();   // Force light (persists to localStorage)
setDark();    // Force dark
setSystem();  // Follow OS preference

const theme = getTheme();  // 'light' | 'dark' | 'system'

restoreTheme();  // Call in <head> to prevent flash of wrong theme

const unsubscribe = onThemeChange((theme) => {
  console.log('Theme changed to:', theme);
});

Brand Customization

Two CSS variables control the entire brand palette — gradients, glows, buttons, and links all derive from them:

:root {
  --dg-primary: #ff6b35;   /* Your primary color */
  --dg-secondary: #4ecdc4; /* Your secondary color */
}

In light mode, brand colors automatically switch to WCAG-compliant darker variants. You can scope to a section:

.partner-section {
  --dg-primary: #a855f7;
  --dg-secondary: #ec4899;
}

Base Font Size

Everything uses rem units. Change the base and everything scales:

:root {
  --dg-base-font-size: 18px;
}

Tailwind CSS v4 Integration

If your project uses Tailwind v4, import the theme for all design tokens as Tailwind utilities:

@import "@deepgram/styles/theme";

This provides --color-dg-*, --font-dg-*, --spacing-dg-* tokens, base styles, custom utilities, and includes @import "tailwindcss".

React Components

Typed React wrappers with boolean variant props, ref forwarding, and className merging.

Setup

npm install @deepgram/styles react @fortawesome/fontawesome-free

// Entry point — import CSS once
import '@deepgram/styles';
import '@fortawesome/fontawesome-free/css/all.min.css';

// Any component file
import { Btn, Card, CardHeader, CardBody, Prose } from '@deepgram/styles/react';

API

Boolean variant props: <Btn primary> renders .dg-btn.dg-btn--primary
className merging: Pass className to add your own classes
Ref forwarding: All components use forwardRef
Native props: All extra props spread onto the underlying HTML element

// HTML
<button class="dg-btn dg-btn--primary dg-btn--sm">Save</button>

// React
<Btn primary sm>Save</Btn>

// With extras
<Btn primary sm className="my-class" onClick={handleSave} disabled={loading}>
  Save
</Btn>

Component Reference

| Component | CSS Class | Variant Props | |-----------|-----------|---------------| | Btn | .dg-btn | primary, secondary, ghost, dangerGhost, iconOnly, sm, collapse | | Card | .dg-card | structured, compact, spacious, bordered | | CardImage | .dg-card__image | Use className="dg-card__image--medium" etc. | | CardHeader | .dg-card__header | — | | CardBody | .dg-card__body | — | | CardFooter | .dg-card__footer | — | | Section | .dg-section | compact, spacious, bordered, elevated, fieldset | | SectionHeading | .dg-section-heading | — | | PageHeading | .dg-page-heading | — | | Input | .dg-input | inline | | Textarea | .dg-textarea | — | | Checkbox | .dg-checkbox | — | | Select | .dg-select | — | | Radio | .dg-radio | — | | Toggle | .dg-toggle | — | | FormField | .dg-form-field | error, success | | FormLabel | .dg-form-label | — | | FormHelper | .dg-form-helper | — | | Alert | .dg-alert | info, success, warning, danger | | Status | .dg-status | info, success, warning, error, primary, secondary | | Spinner | .dg-spinner | — | | Prose | .dg-prose | large, small, block | | Hero | .dg-hero | — | | CodeBlock | .dg-code-block | compact, tall, noScroll — add prismjs for syntax highlighting | | Footer | .dg-footer | — | | Newsletter | .dg-newsletter-container | — | | ActionGroup | .dg-action-group | — | | ConstrainWidth | .dg-constrain-width | — | | GridMobileStack | .dg-grid-mobile-stack | — |

Sub-components for Card, Hero, Alert, DragDropZone, Columns, Footer, and Newsletter are also exported — see full exports.

CodeBlock with Syntax Highlighting

The CodeBlock component provides container styling. For syntax highlighting, add prismjs:

npm install prismjs

import { CodeBlock } from '@deepgram/styles/react';
import Prism from 'prismjs';
import 'prismjs/components/prism-javascript';
import 'prismjs/themes/prism-tomorrow.css';
import { useEffect } from 'react';

function CodeExample({ code, language }: { code: string; language: string }) {
  useEffect(() => { Prism.highlightAll(); }, [code]);

  return (
    <CodeBlock>
      <pre><code className={`language-${language}`}>{code}</code></pre>
    </CodeBlock>
  );
}

prismjs is optional — you can use any highlighting library (Shiki, Highlight.js, etc.).

Theme Toggle in React

import { Btn, ActionGroup } from '@deepgram/styles/react';
import { setLight, setDark, setSystem, getTheme, onThemeChange } from '@deepgram/styles/utils';
import { useState, useEffect } from 'react';

function ThemeToggle() {
  const [theme, setTheme] = useState(getTheme());
  useEffect(() => onThemeChange(setTheme), []);

  return (
    <ActionGroup>
      <Btn primary={theme === 'light'} ghost={theme !== 'light'} sm onClick={setLight}>Light</Btn>
      <Btn primary={theme === 'dark'} ghost={theme !== 'dark'} sm onClick={setDark}>Dark</Btn>
      <Btn primary={theme === 'system'} ghost={theme !== 'system'} sm onClick={setSystem}>System</Btn>
    </ActionGroup>
  );
}

Web Components (Experimental)

Auto-generated custom elements with Shadow DOM, built from the same YAML source.

<script type="module">
  import '@deepgram/styles/dist/components/web-components/btn.js';
</script>

<dg-btn primary>Get Started</dg-btn>

Tag names match YAML keys with dg- prefix: btn → <dg-btn>
Variants become boolean attributes: <dg-btn primary sm>
Content projected via <slot> elements

Note: Web Components are currently experimental. For production, use CSS classes or React components.

MCP Server (AI Agent Integration)

The package includes a built-in Model Context Protocol server that gives AI coding agents direct access to the design system — component names, BEM classes, rendered HTML examples, and design tokens.

Setup

Install the package, then configure your AI tool:

Claude Code (CLI or .mcp.json):

claude mcp add deepgram-styles --scope project -- npx -y -p @deepgram/styles mcp

Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), or Windsurf (.windsurf/mcp.json):

{
  "mcpServers": {
    "deepgram-styles": {
      "command": "npx",
      "args": ["-y", "-p", "@deepgram/styles", "mcp"]
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | list_components | List all components with metadata, tags, and counts. Filter by category. | | get_component | Full details for a component: BEM classes, variants, rendered HTML examples. | | get_design_tokens | Design tokens (colors, spacing, fonts, shadows, border-radius). | | search_components | Keyword search across names, titles, tags, and descriptions. |

Custom YAML

To point the server at a custom design system YAML:

{
  "mcpServers": {
    "deepgram-styles": {
      "command": "npx",
      "args": ["-y", "-p", "@deepgram/styles", "mcp", "--yaml", "./path/to/design-system.yaml"]
    }
  }
}

Testing

Use the MCP Inspector to test interactively:

npx @modelcontextprotocol/inspector npx -y -p @deepgram/styles mcp

Package Exports

| Import | Description | |--------|-------------| | @deepgram/styles | Minified production CSS (default) | | @deepgram/styles/expanded | Non-minified CSS for debugging | | @deepgram/styles/theme | Tailwind v4 theme CSS with all tokens | | @deepgram/styles/source | Source CSS with @apply directives | | @deepgram/styles/react | Typed React components | | @deepgram/styles/utils | Theme utility functions | | @deepgram/styles/design-system | Raw YAML design tokens | | @deepgram/styles/mcp | MCP server for AI agent integration | | @deepgram/styles/logo/* | 12 SVG logo variants |

Design Tokens

All tokens are CSS custom properties and Tailwind utilities (bg-dg-*, text-dg-*, border-dg-*, etc.).

Colors

| Token | Variable | Dark | Light | |-------|----------|------|-------| | dg-primary | --dg-primary | #13ef95 | #047857 | | dg-secondary | --dg-secondary | #149afb | #0369a1 | | dg-background | --color-dg-background | #0b0b0c | #ffffff | | dg-almost-black | --color-dg-almost-black | #050506 | #f8f9fa | | dg-charcoal | --color-dg-charcoal | #1a1a1f | #f3f4f6 | | dg-solid | --color-dg-solid | #ffffff | #000000 | | dg-text | --color-dg-text | #fbfbff | #111827 | | dg-fog | --color-dg-fog | #edede2 | #1f2937 | | dg-platinum | --color-dg-platinum | #e1e1e5 | #374151 | | dg-muted | --color-dg-muted | #949498 | #6b7280 | | dg-on-solid | --color-dg-on-solid | #000000 | #ffffff | | dg-border | --color-dg-border | #2c2c33 | #d1d5db | | dg-pebble | --color-dg-pebble | #4e4e52 | #9ca3af | | dg-slate | --color-dg-slate | #949498 | #6b7280 | | dg-success | --color-dg-success | #12b76a | #15803d | | dg-warning | --color-dg-warning | #fec84b | #a16207 | | dg-danger | --color-dg-danger | #f04438 | #b91c1c |

Spacing

| Token | Value | CSS Variable | Tailwind | |-------|-------|-------------|----------| | xs | 0.25rem | --spacing-dg-xs | p-dg-xs, m-dg-xs, gap-dg-xs | | sm | 0.5rem | --spacing-dg-sm | p-dg-sm, m-dg-sm, gap-dg-sm | | md | 1rem | --spacing-dg-md | p-dg-md, m-dg-md, gap-dg-md | | lg | 1.5rem | --spacing-dg-lg | p-dg-lg, m-dg-lg, gap-dg-lg | | xl | 2rem | --spacing-dg-xl | p-dg-xl, m-dg-xl, gap-dg-xl | | 2xl | 3rem | --spacing-dg-2xl | p-dg-2xl, m-dg-2xl, gap-dg-2xl |

Border Radius

| Token | Value | CSS Variable | Tailwind | |-------|-------|-------------|----------| | sm | 0.25rem | --radius-dg-sm | rounded-dg-sm | | md | 0.5rem | --radius-dg-md | rounded-dg-md | | lg | 0.75rem | --radius-dg-lg | rounded-dg-lg | | xl | 1rem | --radius-dg-xl | rounded-dg-xl |

Shadows

| Token | CSS Variable | Tailwind | |-------|-------------|----------| | sm | --shadow-dg-sm | shadow-dg-sm | | md | --shadow-dg-md | shadow-dg-md | | lg | --shadow-dg-lg | shadow-dg-lg |

Components

All components use BEM naming with the dg- prefix. Browse the Component Showcase for live examples.

Buttons

<button class="dg-btn dg-btn--primary">Primary</button>
<button class="dg-btn dg-btn--secondary">Secondary</button>
<button class="dg-btn dg-btn--ghost">Ghost</button>
<button class="dg-btn dg-btn--danger-ghost">Danger</button>
<button class="dg-btn dg-btn--icon-only"><i class="fas fa-play"></i></button>
<button class="dg-btn dg-btn--primary dg-btn--sm">Small</button>

Cards

<div class="dg-card dg-card--structured">
  <div class="dg-card__image dg-card__image--medium">
    <img src="image.jpg" alt="Description" />
  </div>
  <div class="dg-card__header">
    <h3 class="dg-card-heading">Card Title</h3>
  </div>
  <div class="dg-card__body">
    <p class="dg-prose">Card content.</p>
  </div>
  <div class="dg-card__footer dg-card__footer--bordered">
    <button class="dg-btn dg-btn--primary">Action</button>
  </div>
</div>

Forms

<div class="dg-form-field">
  <label class="dg-form-label">Email</label>
  <input type="email" class="dg-input" placeholder="[email protected]" />
  <p class="dg-form-helper">We'll never share your email.</p>
</div>

Layout

| Class | Description | |-------|-------------| | .dg-section | Content section (--compact, --spacious, --bordered, --elevated, --fieldset) | | .dg-constrain-width | Max-width container (60rem) | | .dg-center-h | Center content horizontally | | .dg-grid-mobile-stack | Responsive grid, stacks on mobile | | .dg-action-group | Button group container |

Typography

| Class | Description | |-------|-------------| | .dg-hero-title | Large gradient hero title | | .dg-section-heading | Section heading | | .dg-card-heading | Card heading | | .dg-item-title | Item title | | .dg-prose | Body text (--large, --small, --block) | | .dg-text-tagline | Centered tagline | | .dg-text-subtitle | Subtitle text |

Feedback

| Class | Description | |-------|-------------| | .dg-alert | Alert (--info, --success, --warning, --error) | | .dg-status | Status badge (--info, --success, --warning, --error, --primary, --secondary) | | .dg-spinner | Loading spinner | | .dg-modal-overlay | Modal backdrop |

Custom Utilities

| Utility | Description | |---------|-------------| | dg-gradient-border | Gradient border using brand colors | | dg-glow-cyan-green | Box shadow glow with brand colors | | dg-bg-reset | Reset background-image (for hover states) | | dg-shadow-subtle | Subtle box shadow |

Logo Assets

12 SVG logos as package exports:

| Type | Adaptive | Light | Dark | |------|----------|-------|------| | Wordmark | @deepgram/styles/logo/wordmark | @deepgram/styles/logo/wordmark-light | @deepgram/styles/logo/wordmark-dark | | Lettermark | @deepgram/styles/logo/lettermark | @deepgram/styles/logo/lettermark-light | @deepgram/styles/logo/lettermark-dark | | Square | @deepgram/styles/logo/lettermark-square | @deepgram/styles/logo/lettermark-square-light | @deepgram/styles/logo/lettermark-square-dark | | Circle | @deepgram/styles/logo/lettermark-circle | @deepgram/styles/logo/lettermark-circle-light | @deepgram/styles/logo/lettermark-circle-dark |

Adaptive variants use embedded @media (prefers-color-scheme) to switch automatically.

Browser Support

Chrome 123+, Firefox 120+, Safari 17.5+, Edge 123+
Requires: CSS Grid, Flexbox, Custom Properties, light-dark() function

License

ISC

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@deepgram/styles

Quick Start

CDN

npm

Verify it works

Using the Stylesheet

BEM Naming

Light/Dark Mode

Theme Utilities

Brand Customization

Base Font Size

Tailwind CSS v4 Integration

React Components

Setup

API

Component Reference

CodeBlock with Syntax Highlighting

Theme Toggle in React

Web Components (Experimental)

MCP Server (AI Agent Integration)

Setup

Available Tools

Custom YAML

Testing

Package Exports

Design Tokens

Colors

Spacing

Border Radius

Shadows

Components

Buttons

Cards

Forms

Layout

Typography

Feedback

Custom Utilities

Logo Assets

Browser Support

License

Links