@trendhunter/design-system
v0.2.0
Published
McClatchy shared design system — tokens, Tailwind preset, and CSS custom properties for consistent visual identity across all products
Downloads
699
Readme
@trendhunter/design-system
Shared design tokens, Tailwind CSS preset, and CSS custom properties for consistent visual identity across all products.
Overview
This design system provides a unified set of design tokens for building consistent, theme-aware interfaces. It supports three integration paths depending on your stack:
| Path | Best for | Import |
|------|----------|--------|
| TypeScript tokens | Direct programmatic access | @trendhunter/design-system |
| Tailwind preset | Tailwind CSS projects | @trendhunter/design-system/tailwind-preset |
| CSS custom properties | Vanilla HTML/CSS, Cloudflare Worker dashboards | @trendhunter/design-system/css/variables.css |
Installation
npm install @trendhunter/design-systemUsage
Tailwind CSS (recommended)
Add the preset to your Tailwind config. This gives you the full token set as Tailwind utilities — semantic colors, typography, spacing, radii, and shadows — with no additional configuration.
// tailwind.config.ts
import { mcclatchyPreset } from '@trendhunter/design-system/tailwind-preset'
export default {
presets: [mcclatchyPreset],
content: ['./src/**/*.{ts,tsx,html}'],
}Then use semantic classes in your markup:
<div class="bg-surface text-foreground border border-border rounded-xl p-4">
<h2 class="text-accent font-semibold">Dashboard</h2>
<p class="text-foreground-muted">Semantic tokens resolve automatically.</p>
</div>CSS Custom Properties
For non-Tailwind projects (e.g., static HTML dashboards, Cloudflare Workers sites), import the CSS file directly:
@import '@trendhunter/design-system/css/variables.css';Then reference tokens as CSS variables:
.card {
background: var(--ds-surface);
color: var(--ds-foreground);
border: 1px solid var(--ds-border);
border-radius: 12px;
}Add class="dark" to <html> to activate dark mode — all --ds-* variables switch automatically.
TypeScript Tokens (direct import)
For programmatic access to raw token values:
import { darkMode, lightMode, blue, fontFamily, spacing } from '@trendhunter/design-system'
// Semantic tokens
console.log(darkMode.background) // '#0f0f1a'
console.log(lightMode.accent) // '#2563eb'
// Primitive palette
console.log(blue[500]) // '#3b82f6'
// Typography
console.log(fontFamily.sans) // "'Inter', -apple-system, ..."Token Reference
Color Palettes
| Palette | Description | Stops |
|---------|-------------|-------|
| slate | Dark mode text hierarchy backbone | 50–950 |
| navy | Deep blue-black surfaces | 50–1000 |
| gray | Light mode surfaces and text | 50–950 |
| blue | Primary accent | 400–700 |
| indigo | Secondary accent | 400–700 |
| violet | Gradient and decorative use | 300–700 |
| emerald | Success / high scores | 300–800 |
| amber | Warning / medium scores, CTA gradients | 300–900 |
| red | Error / low scores | 300–900 |
Semantic Tokens
Semantic tokens adapt to light/dark mode. Available as both TypeScript exports (lightMode.*, darkMode.*) and CSS variables (--ds-*).
| Token | Light | Dark | CSS Variable |
|-------|-------|------|-------------|
| background | #ffffff | #0f0f1a | --ds-background |
| foreground | gray-900 | slate-50 | --ds-foreground |
| foregroundMuted | gray-600 | slate-400 | --ds-foreground-muted |
| surface | #ffffff | navy-800 | --ds-surface |
| surfaceRaised | gray-50 | navy-700 | --ds-surface-raised |
| border | gray-200 | navy-600 | --ds-border |
| accent | blue-600 | blue-500 | --ds-accent |
| accentSecondary | indigo-500 | indigo-500 | --ds-accent-secondary |
Typography
| Token | Value |
|-------|-------|
| fontFamily.sans | Inter with system fallback |
| fontFamily.mono | JetBrains Mono with fallback |
| textSize.body | 12px |
| textSize.interactive | 14px |
| textSize.heading3 | 18px |
| textSize.heading1 | 24px |
The full size scale runs from micro (9px) to stat (32px), optimized for data-dense interfaces.
Line heights: tight (1.25), normal (1.5), comfortable (1.6), relaxed (1.7).
Spacing
4px base unit. Scale: 0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 60px.
Semantic aliases (space.*) provide consistent padding for badges, buttons, inputs, cards, and page-level layout.
Border Radius
| Token | Value | Use |
|-------|-------|-----|
| sm | 4px | Tags, badges |
| md | 6px | Buttons, inputs |
| lg | 8px | Inner panels |
| xl | 12px | Cards |
| 2xl | 16px | Modals |
| pill | 20px | Pill buttons |
| full | 9999px | Circles |
Shadows
Shadows are used sparingly — depth is achieved through surface color layering. Only score indicator glows and CTA buttons use shadows.
Animations
Minimal, functional transitions only. All transitions respect prefers-reduced-motion.
| Token | Duration | Use |
|-------|----------|-----|
| micro | 150ms | Snappy card hover, border changes |
| fast | 200ms | Interactive elements |
| medium | 300ms | State changes |
| data | 500ms | Animated bars, progress fills, score indicators |
| background | 200ms | Button backgrounds |
| border | 200ms | Focus/hover borders |
Dark Mode
The design system supports light and dark modes out of the box.
- Tailwind: The preset sets
darkMode: 'class'. Addclass="dark"to<html>. - CSS: Dark mode activates under
.dark— all--ds-*variables switch automatically. - TypeScript: Import
lightModeanddarkModeobjects for programmatic access.
Score and Status Colors
Traffic-light score colors (high/medium/low) and status badge colors (new/reviewing/approved/declined) are provided as both TypeScript exports and CSS variables. These remain constant across light and dark modes.
Credits
Created by Jason A. Smith (LinkedIn) and Rajiv Pant (LinkedIn).
Built with synthesis engineering — the discipline of designing human-AI collaborative systems — and synthesis coding, the craft of writing software in collaboration with AI.