npm - @deepgram/styles - Versions diffs - 0.2.11 → 0.2.13 - Mend

@deepgram/styles 0.2.11 → 0.2.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (142) hide show

package/README.md +285 -317
package/design-system.yaml +3115 -3336
package/dist/deepgram.css +1 -1
package/dist/deepgram.expanded.css +741 -880
package/dist/react/ActionGroup.d.ts +4 -0
package/dist/react/ActionGroup.js +9 -0
package/dist/react/Alert.d.ts +34 -0
package/dist/react/Alert.js +71 -0
package/dist/react/Btn.d.ts +11 -0
package/dist/react/Btn.js +16 -0
package/dist/react/Card.d.ts +26 -0
package/dist/react/Card.js +51 -0
package/dist/react/CardHeading.d.ts +4 -0
package/dist/react/CardHeading.js +9 -0
package/dist/react/CardHeadings.d.ts +7 -0
package/dist/react/CardHeadings.js +16 -0
package/dist/react/Checkbox.d.ts +4 -0
package/dist/react/Checkbox.js +9 -0
package/dist/react/CheckboxDescription.d.ts +4 -0
package/dist/react/CheckboxDescription.js +9 -0
package/dist/react/CheckboxGroup.d.ts +4 -0
package/dist/react/CheckboxGroup.js +9 -0
package/dist/react/CheckboxLabel.d.ts +4 -0
package/dist/react/CheckboxLabel.js +9 -0
package/dist/react/CodeBlock.d.ts +7 -0
package/dist/react/CodeBlock.js +12 -0
package/dist/react/Columns.d.ts +25 -0
package/dist/react/Columns.js +44 -0
package/dist/react/ConstrainWidth.d.ts +4 -0
package/dist/react/ConstrainWidth.js +9 -0
package/dist/react/DragDropZone.d.ts +17 -0
package/dist/react/DragDropZone.js +38 -0
package/dist/react/Footer.d.ts +10 -0
package/dist/react/Footer.js +23 -0
package/dist/react/FormError.d.ts +4 -0
package/dist/react/FormError.js +9 -0
package/dist/react/FormField.d.ts +4 -0
package/dist/react/FormField.js +9 -0
package/dist/react/FormHelper.d.ts +4 -0
package/dist/react/FormHelper.js +9 -0
package/dist/react/FormLabel.d.ts +4 -0
package/dist/react/FormLabel.js +9 -0
package/dist/react/GridMobileStack.d.ts +4 -0
package/dist/react/GridMobileStack.js +9 -0
package/dist/react/Hero.d.ts +25 -0
package/dist/react/Hero.js +58 -0
package/dist/react/Icon.d.ts +5 -0
package/dist/react/Icon.js +10 -0
package/dist/react/Input.d.ts +6 -0
package/dist/react/Input.js +11 -0
package/dist/react/ItemTitle.d.ts +4 -0
package/dist/react/ItemTitle.js +9 -0
package/dist/react/Newsletter.d.ts +8 -0
package/dist/react/Newsletter.js +17 -0
package/dist/react/Option.d.ts +4 -0
package/dist/react/Option.js +9 -0
package/dist/react/PageHeading.d.ts +10 -0
package/dist/react/PageHeading.js +23 -0
package/dist/react/PageHeadings.d.ts +13 -0
package/dist/react/PageHeadings.js +30 -0
package/dist/react/Prose.d.ts +6 -0
package/dist/react/Prose.js +11 -0
package/dist/react/Radio.d.ts +4 -0
package/dist/react/Radio.js +9 -0
package/dist/react/RadioDescription.d.ts +7 -0
package/dist/react/RadioDescription.js +16 -0
package/dist/react/RadioGroup.d.ts +4 -0
package/dist/react/RadioGroup.js +9 -0
package/dist/react/RadioLabel.d.ts +4 -0
package/dist/react/RadioLabel.js +9 -0
package/dist/react/Section.d.ts +9 -0
package/dist/react/Section.js +14 -0
package/dist/react/SectionHeading.d.ts +4 -0
package/dist/react/SectionHeading.js +9 -0
package/dist/react/Select.d.ts +4 -0
package/dist/react/Select.js +9 -0
package/dist/react/Spinner.d.ts +7 -0
package/dist/react/Spinner.js +16 -0
package/dist/react/Status.d.ts +12 -0
package/dist/react/Status.js +17 -0
package/dist/react/TextUtilities.d.ts +4 -0
package/dist/react/TextUtilities.js +9 -0
package/dist/react/Textarea.d.ts +4 -0
package/dist/react/Textarea.js +9 -0
package/dist/react/Toggle.d.ts +4 -0
package/dist/react/Toggle.js +9 -0
package/dist/react/ToggleGroup.d.ts +4 -0
package/dist/react/ToggleGroup.js +9 -0
package/dist/react/ToggleLabel.d.ts +4 -0
package/dist/react/ToggleLabel.js +9 -0
package/dist/react/index.d.ts +43 -0
package/dist/react/index.js +43 -0
package/dist/utils.d.ts +16 -0
package/dist/utils.js +50 -0
package/lib/deepgram.css +531 -486
package/lib/tailwind-theme.css +0 -1
package/package.json +17 -2
package/src/react/ActionGroup.tsx +14 -0
package/src/react/Alert.tsx +130 -0
package/src/react/Btn.tsx +28 -0
package/src/react/Card.tsx +93 -0
package/src/react/CardHeading.tsx +14 -0
package/src/react/CardHeadings.tsx +27 -0
package/src/react/Checkbox.tsx +14 -0
package/src/react/CheckboxDescription.tsx +14 -0
package/src/react/CheckboxGroup.tsx +14 -0
package/src/react/CheckboxLabel.tsx +14 -0
package/src/react/CodeBlock.tsx +20 -0
package/src/react/Columns.tsx +82 -0
package/src/react/ConstrainWidth.tsx +14 -0
package/src/react/DragDropZone.tsx +68 -0
package/src/react/Footer.tsx +40 -0
package/src/react/FormError.tsx +14 -0
package/src/react/FormField.tsx +14 -0
package/src/react/FormHelper.tsx +14 -0
package/src/react/FormLabel.tsx +14 -0
package/src/react/GridMobileStack.tsx +14 -0
package/src/react/Hero.tsx +105 -0
package/src/react/Icon.tsx +16 -0
package/src/react/Input.tsx +18 -0
package/src/react/ItemTitle.tsx +14 -0
package/src/react/Newsletter.tsx +29 -0
package/src/react/Option.tsx +14 -0
package/src/react/PageHeading.tsx +40 -0
package/src/react/PageHeadings.tsx +53 -0
package/src/react/Prose.tsx +18 -0
package/src/react/Radio.tsx +14 -0
package/src/react/RadioDescription.tsx +27 -0
package/src/react/RadioGroup.tsx +14 -0
package/src/react/RadioLabel.tsx +14 -0
package/src/react/Section.tsx +24 -0
package/src/react/SectionHeading.tsx +14 -0
package/src/react/Select.tsx +14 -0
package/src/react/Spinner.tsx +27 -0
package/src/react/Status.tsx +30 -0
package/src/react/TextUtilities.tsx +14 -0
package/src/react/Textarea.tsx +14 -0
package/src/react/Toggle.tsx +14 -0
package/src/react/ToggleGroup.tsx +14 -0
package/src/react/ToggleLabel.tsx +14 -0
package/src/react/index.ts +43 -0
package/src/utils.ts +60 -0

package/README.md CHANGED Viewed

@@ -2,315 +2,382 @@
 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.
-## Features
-### Automatic Light/Dark Mode
-Every color token uses the CSS `light-dark()` function, giving you automatic theme support with zero configuration:
-- **System-aware**: Follows the user's OS light/dark preference out of the box
-- **Overridable**: Force a specific mode with a single line of CSS (`color-scheme: dark`)
-- **No JS required**: Pure CSS implementation — no class toggling, no build-time config
-- **WCAG-compliant**: Light mode brand colors are tuned for AA contrast ratios on white
-### YAML-Driven Design Tokens
-All tokens, components, and examples are defined in a single `design-system.yaml` source of truth:
-- **Colors**: Brand, background, border, text, status, and gradient tokens — each with dark and light values
-- **Typography**: Font families, sizes, and weights with Tailwind integration
-- **Spacing**: Consistent spacing scale in `rem` units
-- **Border radius**: Rounded corner presets
-- **Shadows**: Elevation levels from subtle to prominent
-- **Logos**: 12 SVG logo variants (adaptive, light, dark) across wordmark, lettermark, square, and circle types
-### CSS Architecture
-- **Tailwind CSS v4**: CSS-first configuration with `@theme` custom properties
-- **BEM naming**: `.dg-{block}`, `.dg-{block}__{element}`, `.dg-{block}--{modifier}`
-- **Custom utilities**: `dg-gradient-border`, `dg-glow-cyan-green`, `dg-bg-reset`, `dg-shadow-subtle`
-- **Responsive**: Mobile-first breakpoints with progressive enhancement
-- **Adaptive contrast tokens**: `dg-solid` / `dg-on-solid` for elements that invert between modes
-### Customizable Brand Colors
-Two CSS variables control the entire brand palette — gradient borders, glow effects, buttons, links, and highlights all derive from them automatically:
-```css
-:root {
-  --dg-primary: #ff6b35;   /* Your primary brand color */
-  --dg-secondary: #4ecdc4; /* Your secondary brand color */
-}
-```
-### Logo Assets
-12 production-ready SVG logos included 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 CSS `@media (prefers-color-scheme)` to switch automatically.
----
 ## Quick Start
-You'll need two things: the Deepgram Styles package and [Font Awesome](https://fontawesome.com/search?o=r&m=free) for icons. Choose between CDN (fastest setup) or npm (production-ready).
+### CDN
-### Option 1: CDN
-Add these lines to your HTML `<head>`:
+Add to your HTML `<head>`:
 ```html
 <!-- 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">
+<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">
 ```
-Or use jsDelivr for Deepgram Styles:
+jsDelivr alternative:
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@deepgram/styles/dist/deepgram.css">
 ```
-### Option 2: NPM (Production)
-Install both packages:
+### npm
 ```bash
 npm install @deepgram/styles @fortawesome/fontawesome-free
 ```
-Then import in your JavaScript/TypeScript entry file:
+Import in your JS/TS entry file:
 ```javascript
 import '@deepgram/styles';
 import '@fortawesome/fontawesome-free/css/all.min.css';
 ```
-That's it. Light/dark mode works automatically based on the user's OS preference.
-## Usage
+### Verify it works
-Browse the [Component Showcase](https://design.dx.deepgram.com), copy the markup, and use it in your project:
-```html
-<button class="dg-btn dg-btn--primary">Get Started</button>
-```
-Components use [Font Awesome](https://fontawesome.com/search?o=r&m=free) icons:
+Paste this into your page — you should see a styled green button:
 ```html
 <button class="dg-btn dg-btn--primary">
-  <i class="fas fa-play"></i>
-  Start Recording
+  <i class="fas fa-check"></i>
+  It works!
 </button>
 ```
-### Pre-built CSS
+---
-The default import provides a minified, production-ready stylesheet:
+## Using the Stylesheet
-```javascript
-import "@deepgram/styles";
+### 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:
+```css
+:root { color-scheme: dark; }  /* Always dark */
+:root { color-scheme: light; } /* Always light */
 ```
-Or link directly in HTML:
+Or via JavaScript:
-```html
-<link rel="stylesheet" href="node_modules/@deepgram/styles/dist/deepgram.css" />
+```javascript
+document.documentElement.style.colorScheme = 'dark';  // Force dark
+document.documentElement.style.colorScheme = 'light'; // Force light
+document.documentElement.style.removeProperty('color-scheme'); // System
 ```
-### Expanded CSS (Non-minified)
+### Theme Utilities
-For development or easier debugging:
+For apps with a theme toggle and localStorage persistence:
 ```javascript
-import "@deepgram/styles/expanded";
+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);
+});
 ```
-### Using with Tailwind CSS v4
+### Brand Customization
-If you're using Tailwind CSS v4 in your project, import the Deepgram theme CSS in your main stylesheet:
+Two CSS variables control the entire brand palette — gradients, glows, buttons, and links all derive from them:
 ```css
-/* Import Deepgram theme (includes @import "tailwindcss") */
-@import "@deepgram/styles/theme";
+:root {
+  --dg-primary: #ff6b35;   /* Your primary color */
+  --dg-secondary: #4ecdc4; /* Your secondary color */
+}
 ```
-This provides all Deepgram design tokens (`--color-dg-*`, `--font-dg-*`, `--spacing-dg-*`, etc.), base styles, and custom utilities via Tailwind v4's CSS-first configuration.
+In light mode, brand colors automatically switch to WCAG-compliant darker variants. You can scope to a section:
+```css
+.partner-section {
+  --dg-primary: #a855f7;
+  --dg-secondary: #ec4899;
+}
+```
-### Importing Source Files
+### Base Font Size
-To customize and build the styles yourself:
+Everything uses `rem` units. Change the base and everything scales:
 ```css
-@import "@deepgram/styles/source";
+:root {
+  --dg-base-font-size: 18px;
+}
 ```
-### Design System YAML
+### Tailwind CSS v4 Integration
-Access the raw design tokens programmatically:
+If your project uses Tailwind v4, import the theme for all design tokens as Tailwind utilities:
-```javascript
-import tokens from "@deepgram/styles/design-system";
+```css
+@import "@deepgram/styles/theme";
 ```
+This provides `--color-dg-*`, `--font-dg-*`, `--spacing-dg-*` tokens, base styles, custom utilities, and includes `@import "tailwindcss"`.
 ---
-## Configuration
+## React Components
-### Light/Dark Mode
+Typed React wrappers with boolean variant props, ref forwarding, and className merging.
-The stylesheet sets `color-scheme: light dark` on `:root`, so it follows the OS preference automatically. To force a specific mode:
+### Setup
-```css
-/* Force dark mode */
-:root { color-scheme: dark; }
+```bash
+npm install @deepgram/styles react @fortawesome/fontawesome-free
+```
+```tsx
+// Entry point — import CSS once
+import '@deepgram/styles';
+import '@fortawesome/fontawesome-free/css/all.min.css';
-/* Force light mode */
-:root { color-scheme: light; }
+// Any component file
+import { Btn, Card, CardHeader, CardBody, Prose } from '@deepgram/styles/react';
 ```
-Or toggle via JavaScript:
+### API
-```javascript
-// Follow system preference (default)
-document.documentElement.style.removeProperty('color-scheme');
+- **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
-// Force dark
-document.documentElement.style.colorScheme = 'dark';
+```tsx
+// HTML
+<button class="dg-btn dg-btn--primary dg-btn--sm">Save</button>
-// Force light
-document.documentElement.style.colorScheme = 'light';
-```
+// React
+<Btn primary sm>Save</Btn>
-### Base Font Size
+// With extras
+<Btn primary sm className="my-class" onClick={handleSave} disabled={loading}>
+  Save
+</Btn>
+```
-The entire design system uses `rem` units that scale relative to the root font size:
+### 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`](https://www.npmjs.com/package/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](./src/react/index.ts).
+### CodeBlock with Syntax Highlighting
+The `CodeBlock` component provides container styling. For syntax highlighting, add `prismjs`:
-```css
-:root {
-  --dg-base-font-size: 18px; /* Scale everything up */
-}
+```bash
+npm install prismjs
+```
-@media (max-width: 768px) {
-  :root {
-    --dg-base-font-size: 14px; /* Smaller on mobile */
-  }
+```tsx
+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>
+  );
 }
 ```
-### Brand Colors
+`prismjs` is optional — you can use any highlighting library (Shiki, Highlight.js, etc.).
-Two variables control the entire brand palette:
+### Theme Toggle in React
-```css
-:root {
-  --dg-primary: #13ef95;  /* Deepgram green */
-  --dg-secondary: #149afb; /* Deepgram blue */
+```tsx
+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>
+  );
 }
 ```
-In light mode, brand colors automatically switch to WCAG-compliant darker variants (`#047857` and `#0369a1` by default). Gradient borders, glow effects, buttons, links, and highlights all derive from these two variables.
+---
-```css
-/* Theme variations */
-.theme-purple {
-  --dg-primary: #a855f7;
-  --dg-secondary: #ec4899;
-}
+## Web Components (Experimental)
-.theme-ocean {
-  --dg-primary: #16a085;
-  --dg-secondary: #3498db;
-}
+Auto-generated custom elements with Shadow DOM, built from the same YAML source.
+```html
+<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
-## Color Tokens
+> **Note**: Web Components are currently experimental. For production, use CSS classes or React components.
-All color tokens are available as CSS custom properties and Tailwind utilities:
+---
-### Background Colors
+## Package Exports
-| Token | Variable | Dark | Light |
-|-------|----------|------|-------|
-| `dg-almost-black` | `--color-dg-almost-black` | `#050506` | `#f8f9fa` |
-| `dg-background` | `--color-dg-background` | `#0b0b0c` | `#ffffff` |
-| `dg-charcoal` | `--color-dg-charcoal` | `#1a1a1f` | `#f3f4f6` |
-| `dg-solid` | `--color-dg-solid` | `#ffffff` | `#000000` |
+| 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/logo/*` | 12 SVG logo variants |
-### Border Colors
+---
-| Token | Variable | Dark | Light |
-|-------|----------|------|-------|
-| `dg-border` | `--color-dg-border` | `#2c2c33` | `#d1d5db` |
-| `dg-pebble` | `--color-dg-pebble` | `#4e4e52` | `#9ca3af` |
-| `dg-slate` | `--color-dg-slate` | `#949498` | `#6b7280` |
+## Design Tokens
+All tokens are CSS custom properties and Tailwind utilities (`bg-dg-*`, `text-dg-*`, `border-dg-*`, etc.).
-### Text Colors
+### 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` |
-### Status Colors
-| Token | Variable | Dark | Light |
-|-------|----------|------|-------|
+| `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` |
-### Brand Colors
+### Spacing
-| Token | Variable | Dark | Light |
-|-------|----------|------|-------|
-| `dg-primary` | `--dg-primary` | `#13ef95` | `#047857` |
-| `dg-secondary` | `--dg-secondary` | `#149afb` | `#0369a1` |
+| 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
-All tokens work with standard Tailwind utility prefixes: `bg-dg-*`, `text-dg-*`, `border-dg-*`, `ring-dg-*`, etc.
+| 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.
+All components use BEM naming with the `dg-` prefix. Browse the [Component Showcase](https://design.dx.deepgram.com) for live examples.
 ### Buttons
 ```html
-<button class="dg-btn dg-btn--primary">Primary Action</button>
+<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">Delete</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>
 ```
-| Class | Description |
-|-------|-------------|
-| `.dg-btn` | Base button with flexbox centering, font styles, and disabled states |
-| `.dg-btn--primary` | Gradient border with brand colors and glow effect |
-| `.dg-btn--secondary` | Solid contrasting fill (white on dark, black on light) |
-| `.dg-btn--ghost` | Transparent with border, text adapts to theme |
-| `.dg-btn--danger-ghost` | Transparent with danger-colored border |
-| `.dg-btn--icon-only` | Square button for icons |
-| `.dg-btn--sm` | Small variant (2.25rem height) |
-| `.dg-btn--collapse` | Full-width on mobile, inline on desktop |
 ### Cards
 ```html
@@ -324,74 +391,32 @@ All components use BEM naming with the `dg-` prefix.
   <div class="dg-card__body">
     <p class="dg-prose">Card content.</p>
   </div>
-  <div class="dg-card__footer">
+  <div class="dg-card__footer dg-card__footer--bordered">
     <button class="dg-btn dg-btn--primary">Action</button>
   </div>
 </div>
 ```
-| Class | Description |
-|-------|-------------|
-| `.dg-card` | Base card with border, background, and padding |
-| `.dg-card--compact` | Reduced padding |
-| `.dg-card--spacious` | Increased padding |
-| `.dg-card--bordered` | Enhanced border |
-| `.dg-card--structured` | Optimized for image/header/body/footer layout |
-| `.dg-card__image` | Image container with `--small`, `--medium`, `--large`, `--aspect-4-3` sizes |
-| `.dg-card__icon` | Icon container with `--left`, `--center`, `--right` alignment |
-| `.dg-card__header` | Header section |
-| `.dg-card__body` | Body content section |
-| `.dg-card__footer` | Footer actions section with optional `--bordered` |
+### Forms
+```html
+<div class="dg-form-field">
+  <label class="dg-form-label">Email</label>
+  <input type="email" class="dg-input" placeholder="you@example.com" />
+  <p class="dg-form-helper">We'll never share your email.</p>
+</div>
+```
 ### Layout
 | Class | Description |
 |-------|-------------|
-| `.dg-section` | Content section with margin and padding |
-| `.dg-section--compact` | Reduced spacing |
-| `.dg-section--spacious` | Increased spacing |
-| `.dg-section--bordered` | Border and background |
-| `.dg-section--elevated` | Shadow elevation |
-| `.dg-section--fieldset` | Fieldset-style with legend |
+| `.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 |
-### Multi-Column Layout
-```html
-<div class="dg-layout-three-column">
-  <header class="dg-layout-three-column__header">...</header>
-  <div class="dg-layout-three-column__main">
-    <div class="dg-layout-three-column__left-main-wrapper">
-      <div class="dg-layout-three-column__sidebar-left">...</div>
-      <div class="dg-layout-three-column__content">...</div>
-    </div>
-    <div class="dg-layout-three-column__sidebar-right">...</div>
-  </div>
-</div>
-```
-### Hero Section
-```html
-<section class="dg-hero">
-  <div class="dg-hero__content">
-    <a href="#" class="dg-hero__announcement">
-      <span class="dg-hero__announcement-text">New feature announcement</span>
-      <span class="dg-hero__announcement-cta">Learn More</span>
-    </a>
-    <h1 class="dg-hero-title">Your Hero Title</h1>
-    <p class="dg-hero__body">Your hero description text.</p>
-    <div class="dg-hero__actions">
-      <button class="dg-btn dg-btn--primary">Get Started</button>
-      <button class="dg-btn dg-btn--ghost">Learn More</button>
-    </div>
-  </div>
-</section>
-```
 ### Typography
 | Class | Description |
@@ -400,111 +425,54 @@ All components use BEM naming with the `dg-` prefix.
 | `.dg-section-heading` | Section heading |
 | `.dg-card-heading` | Card heading |
 | `.dg-item-title` | Item title |
-| `.dg-prose` | Body text (max-width 65ch) |
-| `.dg-prose--large` | Larger prose |
-| `.dg-prose--small` | Smaller prose |
-| `.dg-prose--block` | Full-width prose (no max-width) |
+| `.dg-prose` | Body text (`--large`, `--small`, `--block`) |
 | `.dg-text-tagline` | Centered tagline |
 | `.dg-text-subtitle` | Subtitle text |
-| `.dg-text-heading` | Standard heading |
-| `.dg-text-legal` | Fine print |
-### Forms
-```html
-<div class="dg-form-field">
-  <label class="dg-form-label">Email</label>
-  <input type="email" class="dg-input" placeholder="you@example.com" />
-  <p class="dg-form-helper">We'll never share your email.</p>
-</div>
-```
-| Class | Description |
-|-------|-------------|
-| `.dg-input` | Text input with focus/disabled states |
-| `.dg-input--inline` | Inline input (min-width 12.5rem) |
-| `.dg-textarea` | Multi-line text input |
-| `.dg-checkbox` | Custom styled checkbox with animation |
-| `.dg-checkbox-label` | Checkbox label wrapper |
-| `.dg-checkbox-description` | Checkbox with description |
-| `.dg-form-field` | Field container (label + input + helper) |
-| `.dg-form-field--error` | Error validation state |
-| `.dg-form-field--success` | Success validation state |
-| `.dg-form-label` | Form label |
-| `.dg-form-helper` | Helper/validation text |
-| `.dg-drag-drop-zone` | File upload drag-and-drop area |
 ### Feedback
 | Class | Description |
 |-------|-------------|
-| `.dg-alert` | Alert container with `--info`, `--success`, `--warning`, `--error` variants |
-| `.dg-status` | Status badge with `--info`, `--success`, `--warning`, `--error`, `--primary`, `--secondary` |
-| `.dg-spinner` | Loading spinner animation |
+| `.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 |
-| `.dg-modal-content` | Modal content container |
-### Code
-| Class | Description |
-|-------|-------------|
-| `.dg-code-block` | Scrollable code block with monospace font |
-| `.dg-code-block--compact` | Reduced height |
-| `.dg-code-block--tall` | Increased height |
-| `.dg-code-block--no-scroll` | No scroll/height limit |
-### Navigation
-| Class | Description |
-|-------|-------------|
-| `.dg-navbar` | Top navigation bar |
-| `.dg-link` | Styled link with hover effect |
-| `.dg-footer` | Page footer |
-### Newsletter
-| Class | Description |
-|-------|-------------|
-| `.dg-newsletter-container` | Newsletter section container |
-| `.dg-newsletter-form` | Form with standard/compact/inline variants |
-| `.dg-newsletter-header` | Header with content and actions areas |
-| `.dg-logo-container` | Centered logo container |
-| `.dg-social-links` | Social links container |
-| `.dg-social-link` | Individual social link |
 ### Custom Utilities
 | Utility | Description |
 |---------|-------------|
-| `.dg-gradient-border` | Gradient border using brand colors (adaptive fill) |
-| `.dg-glow-cyan-green` | Box shadow glow with brand colors |
-| `.dg-bg-reset` | Reset background-image properties |
-| `.dg-shadow-subtle` | Subtle box shadow |
+| `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 |
 ---
-## Responsive Design
+## 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` |
-All components are mobile-first with progressive breakpoints:
+Adaptive variants use embedded `@media (prefers-color-scheme)` to switch automatically.
-- **Mobile** (default): Single column, stacked layouts
-- **Tablet** (`640px`): Two column layouts, expanded spacing
-- **Desktop** (`1024px`): Multi-column layouts, full features
+---
 ## Browser Support
-- Chrome, Firefox, Safari, Edge (latest 2 versions)
+- Chrome 123+, Firefox 120+, Safari 17.5+, Edge 123+
 - Requires: CSS Grid, Flexbox, Custom Properties, `light-dark()` function
-- `light-dark()` is supported in Chrome 123+, Firefox 120+, Safari 17.5+
 ## License
 ISC
-## Contributing
-See the [main repository](https://github.com/deepgram/dx-design) for contribution guidelines.
 ## Links
 - [Component Showcase](https://design.dx.deepgram.com) — Live preview of all components