# Design System

> This skill should be used when the user asks about "dark theme for report site", "presentation website styling", "report-to-web design system", "professional dark theme", "site theme tokens", "interactive component styling", "customize report website colors", "report site accessibility", "shadcn theme", "tailwind tokens", or needs guidance on the dark professional visual design system used by report-to-web generated sites, including color palettes, typography, spacing, animation patterns, responsive design, accessibility, component styling, and theme/registry selection.

- Skill: `reggiechan74/design-system` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add reggiechan74/design-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reggiechan74/design-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: reggiechan74 (https://skillmd.com/u/reggiechan74)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/reggiechan74/design-system

---


# Dark Professional Design System for Report Websites

Apply a distinctive dark professional visual identity to generated research report websites using Tailwind CSS v4 + shadcn/ui. This design system creates sites that feel like a premium data terminal crossed with a high-end law publication — dense with information yet elegant and readable.

## Design Philosophy

**Tone**: Sophisticated, authoritative, data-rich. Think Bloomberg Terminal meets The Economist's digital edition.

**Differentiation**: The signature element is the warm amber accent system against deep cool backgrounds — every interactive element glows with intention. Typography pairs a refined serif display face with a crisp humanist sans-serif body, creating tension between editorial authority and modern clarity.

**Theme System**: Color accents are swappable via theme presets (8 built-in options) or community registries, while layout, typography, and animations remain consistent.

## Color System

Colors are defined as Tailwind `@theme` tokens in `app.css` and can be overridden by theme preset CSS files. Use Tailwind utility classes for all color references — never hardcode color values.

### Core Palette

```
bg-bg-primary       → #0f1117   Deep space — main background
bg-bg-secondary     → #161922   Elevated surface — cards, panels
bg-bg-tertiary      → #1c1f2e   Recessed areas — code blocks, inputs
bg-bg-hover         → #232738   Hover state for interactive surfaces

text-text-primary    → #e8e6e1   Warm white — body text
text-text-secondary  → #9a9690   Muted warm — secondary text, labels
text-text-tertiary   → #5e5a55   Dim — disabled text, timestamps

text-accent-primary  → #d4a853   Amber gold — primary actions, highlights
text-accent-secondary → #2d9e8f  Teal — secondary interactive elements
text-accent-tertiary → #6366f1   Indigo — links, tertiary actions

border-border-primary → #2a2d3a  Subtle borders between sections
border-border-accent  → rgba(212, 168, 83, 0.2)  Amber border at 20% opacity
```

### shadcn Semantic Tokens

These map to the dark theme by default and are overridden by theme presets:

```
--color-primary          → accent-primary (gold by default)
--color-primary-foreground → bg-primary
--color-secondary        → bg-tertiary
--color-muted            → bg-tertiary
--color-muted-foreground → text-secondary
--color-destructive      → error
--color-border           → border-primary
--color-ring             → accent-primary
```

## Typography

### Font Stack

Load from Google Fonts:
- **Display/Headings**: `font-display` → `"DM Serif Display", Georgia, serif` — Elegant, authoritative serif
- **Body/UI**: `font-body` → `"IBM Plex Sans", "Helvetica Neue", sans-serif` — Crisp, professional
- **Code/Data**: `font-mono` → `"IBM Plex Mono", "Consolas", monospace` — Clean monospace for numbers

### Type Treatments

- **Headings**: `font-display text-text-primary` with tracking-tight
- **Body**: `font-body text-text-primary` with `leading-[1.7] max-w-[72ch]`
- **Labels/Captions**: `text-xs uppercase tracking-wide text-text-secondary`
- **Data/Numbers**: `font-mono text-accent-primary tabular-nums`
- **Blockquotes**: `italic text-text-secondary border-l-3 border-l-accent-primary bg-bg-secondary`

## Spacing

Use Tailwind's spacing scale. Key layout patterns:
- Between sections (H3): `mb-16`
- Inside cards/panels: `p-5` or `space-y-5`
- Tab bar height: `py-4` (maps to `--tab-bar-height: 4rem`)
- Page horizontal padding: `px-6`
- Max content width: `max-w-[var(--max-content-width)]` (1200px), centered with `mx-auto`

## Component Styling

All components use Tailwind utility classes + shadcn UI primitives. Import `cn` from `@/lib/utils` for conditional class merging.

### Tabbed Navigation (TabbedLayout)

- Background: `bg-bg-secondary`
- Bottom border: `border-b border-border-primary`
- Active tab: `text-accent-primary` + animated indicator via `bg-gradient-tab-indicator`
- Inactive tab: `text-text-tertiary hover:text-text-secondary`
- Glassmorphism on scroll: `glass shadow-lg` utility class
- Tab labels: `text-sm font-medium uppercase tracking-[0.08em]`
- Presentation toggle: shadcn `Button` variant="outline"

### Cards and Panels

- Use shadcn `Card` / `CardContent` components
- Calculator: `border-l-3 border-l-accent-primary bg-gradient-gold-subtle shadow-md`
- Scenario slider: `border-l-3 border-l-accent-secondary bg-gradient-teal-subtle shadow-md`
- Hover lift: framer-motion `whileHover={{ y: -2 }}`

### Interactive Elements (Calculators, Sliders)

- Input fields: shadcn `Input` with `font-mono bg-bg-primary border-border-primary shadow-inset`
- Focus: `focus-visible:border-accent-primary focus-visible:ring-[rgba(212,168,83,0.15)]`
- Labels: shadcn `Label` with `text-xs uppercase tracking-wide text-text-secondary`
- Dividers: shadcn `Separator` with `bg-border-primary`
- Result display: `font-mono text-[length:var(--font-size-hero)] text-accent-primary tabular-nums`
- Range slider: Native `<input type="range">` with `.scenario-slider` CSS class (custom styling in app.css)

### Tables (ComparisonTable)

- Use shadcn `Table`, `TableHeader`, `TableBody`, `TableHead`, `TableRow`, `TableCell`
- Header row: `bg-bg-tertiary text-xs uppercase tracking-wide font-semibold`
- Hover row: inline style `background: var(--color-bg-hover)`
- Filter buttons: shadcn `Button` with variant toggling
- Highlighted column: `text-accent-primary` + subtle gradient background

### Citations (CitationCard)

- Use shadcn `Collapsible` + `Badge`
- Number badge: `font-mono text-xs text-accent-tertiary` in a shadcn Badge variant="outline"
- Left border: `border-l-3 border-l-accent-tertiary`
- Links: `text-accent-tertiary text-xs font-mono bg-bg-tertiary` with hover lift

### Knowledge Vault (KnowledgeVault)

- Use shadcn `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`
- Search input: shadcn `Input` with `pl-12 font-mono shadow-inset`
- Expand all: shadcn `Button` variant="outline"
- Section items: AccordionItem with conditional border/shadow classes

### Badges (SectionRenderer)

- Use shadcn `Badge` variant="outline" with semantic color classes
- VERIFIED: `text-success border-[rgba(52,211,153,0.25)]`
- ESTIMATE: `text-warning border-[rgba(251,191,36,0.25)]`
- ILLUSTRATIVE: `text-info border-[rgba(96,165,250,0.25)]`

## Animation Patterns

Use framer-motion for React. Animation tokens are in `src/theme/motion.js`. Keep animations purposeful and restrained.

### Tab Transitions

- Content fade + slide: 300ms, `opacity: 0 → 1`, `y: 8 → 0`
- Use `AnimatePresence` with `mode="wait"` for clean tab switches

### Content Reveals

- Sections animate in on first view with `useInView` and staggered delays (50ms between siblings)
- Cards: `opacity: 0 → 1`, `y: 16 → 0`, 400ms
- Tables: rows stagger in at 30ms intervals
- Numbers/stats: count-up animation over 600ms

### Interactive Feedback

- Calculator results: brief scale pulse (1.0 → 1.02 → 1.0) on value change
- Slider: real-time update, no animation delay
- Hover on cards: framer-motion `whileHover={{ y: -2 }}`
- Button press: framer-motion `whileTap={{ scale: 0.95 }}`

### Presentation Mode (if enabled)

- Auto-advance tabs every 8 seconds
- Progress bar under tabs shows timing
- Section content types in with stagger

## Custom Tailwind Utilities

Defined in `app.css` via `@utility` blocks:

```
bg-gradient-surface       — Surface gradient (secondary → tertiary)
bg-gradient-gold-subtle   — Calculator background tint
bg-gradient-teal-subtle   — Scenario slider background tint
bg-gradient-timeline      — Timeline line gradient (gold → teal → indigo)
bg-gradient-tab-indicator — Tab underline gradient (gold → teal)
bg-gradient-hero-text     — Hero title text gradient
bg-gradient-accent-line   — 60px heading accent line
glass                     — Glassmorphism (bg + backdrop-filter)
scrollbar-none            — Hide scrollbar
```

## Responsive Design

### Breakpoints

```
Mobile: < 768px
Tablet: 768px - 1023px
Desktop: >= 1024px
```

### Mobile Adaptations

- Tabs become a horizontal scrollable row (`overflow-x-auto scrollbar-none`)
- Tables use horizontal scroll
- Calculator inputs stack vertically
- Font sizes reduce: `--font-size-hero: 2.5rem` on mobile
- Page padding: `px-4`

### Desktop Enhancements

- Tabs are full-width with even spacing
- Comparison tables show all columns
- Page padding: `px-6`

## Accessibility

- All color combinations meet WCAG AA contrast ratios (4.5:1 for text, 3:1 for large text)
- Tab navigation is keyboard accessible (arrow keys, Enter, Tab) via `role="tablist"` and `role="tab"`
- Interactive elements have visible focus indicators (`focus-visible:` with accent-primary outline)
- Animations respect `prefers-reduced-motion` — all durations reduced to 0.01ms
- All icons have `aria-hidden="true"` with descriptive text nearby
- Semantic HTML: `<nav>`, `<main>`, `<header>`, `<section>`
- shadcn components include built-in ARIA attributes (Accordion, Collapsible, etc.)

**Note:** This design system is dark-mode only by design. Light mode is not supported. The dark professional aesthetic is core to the brand identity of generated report sites.

## Theme Presets

8 built-in color presets are available in `${CLAUDE_PLUGIN_ROOT}/templates/src/themes/`. Each overrides only semantic color tokens, leaving layout and animation intact. See `${CLAUDE_PLUGIN_ROOT}/skills/design-system/references/registry-guide.md` for details.

## Reference Files

For framer-motion animation tokens, see `${CLAUDE_PLUGIN_ROOT}/templates/src/theme/motion.js`.
For the Tailwind v4 stylesheet with all tokens, see `${CLAUDE_PLUGIN_ROOT}/templates/src/app.css`.
For the full token definitions, see `${CLAUDE_PLUGIN_ROOT}/skills/design-system/references/tokens-reference.md`.
For registry/theme selection, see `${CLAUDE_PLUGIN_ROOT}/skills/design-system/references/registry-guide.md`.