The Mode Object: Theme-Aware Styling Made Simple

// Without mode - scattered, inconsistent, hard to maintain
<Card className="rounded-lg border border-gray-200 bg-white dark:bg-gray-800">
  <Button className="rounded-md font-sans text-white bg-blue-500">
  <Input className="rounded border border-gray-300 font-mono">
</Card>

// With mode - centralized, consistent, maintainable
import { mode } from '@/design-system';
import { cn } from '@/lib/utils';

<Card className={cn('border border-border bg-card', mode.radius)}>
  <Button className={cn(mode.radius, mode.font, 'px-4 py-2')}>
  <Input className={cn('border border-border', mode.radius, mode.font)}>
</Card>

import { mode } from '@/design-system';

// That's it. Now use mode.* for theming.

// src/design-system/index.ts
export const mode = {
  // Border radius (dynamic via CSS variable)
  radius: 'rounded-dynamic',

  // Font family (monospace for terminal aesthetic)
  font: 'font-mono',

  // Background colors
  color: {
    bg: {
      base: 'bg-background',
      card: 'bg-card',
      muted: 'bg-muted',
      primary: 'bg-primary',
      secondary: 'bg-secondary',
      destructive: 'bg-destructive',
    },

    // Text colors
    text: {
      base: 'text-foreground',
      muted: 'text-muted-foreground',
      primary: 'text-primary',
      destructive: 'text-destructive',
      success: 'text-success',
    },

    // Border colors
    border: {
      base: 'border-border',
      primary: 'border-primary',
      destructive: 'border-destructive',
    },
  },

  // Spacing (8-point grid)
  spacing: {
    xs: 'p-1',  // 4px
    sm: 'p-2',  // 8px
    md: 'p-4',  // 16px
    lg: 'p-6',  // 24px
    xl: 'p-8',  // 32px
  },
};

/* globals.css */
@theme {
  --radius: 0.5rem;  /* Default radius */
}

/* Tailwind utility */
.rounded-dynamic {
  border-radius: var(--radius);
}

// Component usage
<Card className={cn('border border-border bg-card', mode.radius)}>
  Content with theme-aware radius
</Card>

/* Sharp corners (terminal, cyberpunk, matrix themes) */
[data-theme="terminal"] {
  --radius: 0;
}

/* Rounded corners (default, nord, catppuccin themes) */
[data-theme="default"] {
  --radius: 0.5rem;
}

/* Very rounded (soft, modern themes) */
[data-theme="modern"] {
  --radius: 1rem;
}

// Cards with complete borders
<Card className={cn('border border-border', mode.radius)}>

// Buttons
<Button className={cn(mode.radius, 'px-4 py-2')}>

// Input fields
<Input className={cn('border border-border', mode.radius)}>

// Modals and dialogs
<DialogContent className={cn('border border-border', mode.radius)}>

// Badges and tags
<Badge className={cn(mode.radius, 'px-2 py-1')}>

// Avatar containers
<Avatar className={cn('border border-border', mode.radius)}>

// Dropdown menus
<DropdownMenuContent className={cn('border border-border', mode.radius)}>

// Partial borders (top, bottom, left, right only)
<div className="border-b border-border">  {/* NO mode.radius */}
  Divider line should stay straight
</div>

// Table cells (radius breaks table layout)
<td className="border-b border-border px-4 py-2">  {/* NO mode.radius */}
  Table cell content
</td>

// Table headers
<th className="border-b border-border px-4 py-2">  {/* NO mode.radius */}
  Column header
</th>

// Switches (always pill-shaped)
<Switch className="rounded-full">  {/* Use rounded-full explicitly */}

// Progress bars (capsule shape)
<Progress className="rounded-full h-2">  {/* Use rounded-full */}

// Circular avatars
<Avatar className="rounded-full">  {/* Use rounded-full */}

import { mode } from '@/design-system';

// Apply monospace font explicitly
<p className={mode.font}>
  Terminal-styled text
</p>

// Usually unnecessary since body has font-mono globally
// But useful for overriding parent styles
<div className="font-sans">
  <p>This is sans-serif text</p>
  <code className={mode.font}>This is back to monospace</code>
</div>

// app/layout.tsx
import { JetBrains_Mono } from 'next/font/google';

const mono = JetBrains_Mono({
  subsets: ['latin'],
  variable: '--font-mono',
});

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={mono.variable}>
      <body className="font-mono antialiased">
        {children}
      </body>
    </html>
  );
}

import { mode } from '@/design-system';

// Primary action backgrounds (buttons, highlights)
<button className={mode.color.bg.primary}>
  Primary Button
</button>

// Secondary/subtle backgrounds
<div className={mode.color.bg.secondary}>
  Secondary content area
</div>

// Muted backgrounds (labels, badges, inactive states)
<span className={mode.color.bg.muted}>
  [LABEL]
</span>

// Card backgrounds (elevated content)
<div className={mode.color.bg.card}>
  Card content
</div>

// Destructive actions (delete, remove)
<button className={mode.color.bg.destructive}>
  Delete
</button>

// Page backgrounds
<div className={mode.color.bg.base}>
  Page content
</div>

// Primary text (high contrast, main content)
<h1 className={mode.color.text.base}>
  Main heading
</h1>

// Muted text (secondary, supporting content)
<p className={mode.color.text.muted}>
  Supporting description text
</p>

// Primary/accent text (links, highlights)
<span className={mode.color.text.primary}>
  Highlighted or linked text
</span>

// Error/destructive text
<span className={mode.color.text.destructive}>
  Error: Something went wrong
</span>

// Success text
<span className={mode.color.text.success}>
  Success: Operation completed
</span>

// Default borders (cards, inputs, dividers)
<div className={cn('border', mode.color.border.base)}>
  Standard border
</div>

// Primary/accent borders (focused inputs, highlights)
<div className={cn('border-2', mode.color.border.primary)}>
  Highlighted border
</div>

// Error state borders
<input className={cn('border', mode.color.border.destructive)} />

import { mode } from '@/design-system';

// Extra small padding (4px) - tight spaces, inline elements
<span className={mode.spacing.xs}>
  Tight padding for inline badges
</span>

// Small padding (8px) - compact components
<Badge className={mode.spacing.sm}>
  Standard badge padding
</Badge>

// Medium padding (16px) - default card padding
<Card className={mode.spacing.md}>
  Standard card content padding
</Card>

// Large padding (24px) - sections, generous spacing
<section className={mode.spacing.lg}>
  Section with comfortable padding
</section>

// Extra large padding (32px) - hero sections, major divisions
<div className={mode.spacing.xl}>
  Hero section with significant padding
</div>

// Grid with consistent spacing
<div className="grid grid-cols-3 gap-4">  {/* Matches mode.spacing.md */}
  <Card className={mode.spacing.md}>...</Card>
  <Card className={mode.spacing.md}>...</Card>
  <Card className={mode.spacing.md}>...</Card>
</div>

// src/lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

import { cn } from '@/lib/utils';
import { mode } from '@/design-system';

// Basic combination
<Card className={cn('border border-border', mode.radius)}>

// Conditional classes
<Button className={cn(
  mode.radius,
  mode.font,
  'px-4 py-2',
  isDisabled && 'opacity-50 cursor-not-allowed',
  isActive ? 'bg-primary' : 'bg-secondary'
)}>

// Overriding defaults (twMerge handles conflicts)
<Card className={cn(
  mode.radius,      // Default radius from mode
  'rounded-none'    // Override: twMerge removes mode.radius
)}>

// With className prop for composition
<Button className={cn(
  mode.radius,
  mode.font,
  'bg-primary text-primary-foreground',
  className  // Allow parent to override
)}>

// Without twMerge - both classes applied, unpredictable result
className="rounded-lg rounded-none"

// With twMerge via cn() - conflict resolved, rounded-none wins
cn('rounded-lg', 'rounded-none')  // Returns 'rounded-none'

// This matters for component composition
cn(mode.radius, className)  // User's className can override mode.radius

import { mode } from '@/design-system';
import { cn } from '@/lib/utils';

<div className={cn(
  'border border-border bg-card p-4',
  mode.radius,
  mode.font
)}>
  <span className="text-muted-foreground text-xs uppercase">
    [ CARD TITLE ]
  </span>
  <p className="text-foreground mt-2">
    Terminal-styled card content
  </p>
</div>

<button className={cn(
  'bg-primary text-primary-foreground px-4 py-2',
  'hover:bg-primary/90 transition-colors',
  'focus:ring-2 focus:ring-primary focus:ring-offset-2',
  mode.radius,
  mode.font,
  'text-xs uppercase'
)}>
  &gt; SUBMIT
</button>

<input
  className={cn(
    'border border-border bg-background px-3 py-2',
    'focus:ring-2 focus:ring-primary focus:outline-none',
    'placeholder:text-muted-foreground',
    mode.radius,
    mode.font,
    'text-sm'
  )}
  placeholder="Enter value..."
/>

<div className="space-y-2">
  <label className={cn(
    'text-xs uppercase',
    mode.font,
    mode.color.text.muted
  )}>
    EMAIL ADDRESS
  </label>
  <input
    type="email"
    className={cn(
      'w-full border border-border bg-background px-3 py-2',
      'focus:ring-2 focus:ring-primary focus:border-primary',
      mode.radius,
      mode.font
    )}
  />
  <p className={cn('text-xs', mode.color.text.muted)}>
    We'll never share your email
  </p>
</div>

// components/ui/card.tsx
import { mode } from '@/design-system';
import { cn } from '@/lib/utils';

interface CardProps extends React.HTMLAttributes<HTMLDivElement> {}

export function Card({ className, ...props }: CardProps) {
  return (
    <div
      className={cn(
        'border border-border bg-card',
        mode.radius,
        className
      )}
      {...props}
    />
  );
}

// Usage - theming is automatic
<Card className="p-4">
  Content with automatic theme-aware radius
</Card>

// Override if needed
<Card className="rounded-none p-4">
  Content with sharp corners (overrides mode.radius)
</Card>

import { mode } from '@/design-system';
import { cn } from '@/lib/utils';

interface StatCardProps {
  label: string;
  value: string;
  trend?: 'up' | 'down';
  className?: string;
}

export function StatCard({ label, value, trend, className }: StatCardProps) {
  return (
    <div className={cn(
      'border border-border bg-card p-4',
      mode.radius,
      className  // Allow overrides
    )}>
      <span className={cn(
        'text-xs uppercase',
        mode.font,
        mode.color.text.muted
      )}>
        [ {label} ]
      </span>
      <div className="flex items-baseline gap-2 mt-2">
        <p className={cn('text-2xl font-semibold', mode.color.text.base)}>
          {value}
        </p>
        {trend && (
          <span className={cn(
            'text-xs',
            trend === 'up' ? mode.color.text.success : mode.color.text.destructive
          )}>
            {trend === 'up' ? '↑' : '↓'}
          </span>
        )}
      </div>
    </div>
  );
}

// Theme switcher component
function ThemeSwitcher() {
  const setTheme = (theme: string) => {
    document.documentElement.setAttribute('data-theme', theme);
    localStorage.setItem('theme', theme);
  };

  return (
    <Select onValueChange={setTheme}>
      <SelectItem value="dracula">Dracula</SelectItem>
      <SelectItem value="nord">Nord</SelectItem>
      <SelectItem value="tokyo-night">Tokyo Night</SelectItem>
      {/* ... 18 themes total */}
    </Select>
  );
}

// NEVER do this - breaks theming
<div className="bg-gray-800">  // ❌ Hardcoded
<div className="bg-white">     // ❌ Hardcoded
<div className="bg-[#1a1a2e]"> // ❌ Arbitrary value
<span className="text-gray-400"> // ❌ Hardcoded

// ALWAYS do this - theme-aware
<div className="bg-background">   // ✓ Token
<div className="bg-card">         // ✓ Token
<div className={mode.color.bg.card}> // ✓ Mode object
<span className="text-muted-foreground"> // ✓ Token

// src/design-system/types.ts
export interface ModeConfig {
  radius: string;
  font: string;
  color: {
    bg: Record<'base' | 'card' | 'muted' | 'primary' | 'secondary' | 'destructive', string>;
    text: Record<'base' | 'muted' | 'primary' | 'destructive' | 'success', string>;
    border: Record<'base' | 'primary' | 'destructive', string>;
  };
  spacing: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', string>;
}

// src/design-system/index.ts
export const mode: ModeConfig = {
  // ... implementation
};

import { mode } from '@/design-system';

// TypeScript autocomplete works
mode.color.text.primary  // ✓ Autocomplete suggests valid keys
mode.color.text.invalid  // ✗ Type error: 'invalid' is not a valid key
mode.colors              // ✗ Type error: Property 'colors' does not exist

// Check that --radius CSS variable is defined
// In browser DevTools, inspect the element:
// computed styles should show border-radius with a value

// Common fix: ensure globals.css is imported
// app/layout.tsx
import '@/app/globals.css';

// Check that rounded-dynamic class is defined in your CSS
// globals.css
.rounded-dynamic {
  border-radius: var(--radius);
}

// Ensure you're using semantic tokens, not hardcoded colors
// Bad
<div className="bg-gray-800">  // ❌ Won't change with theme

// Good
<div className="bg-card">  // ✓ Changes with theme

// Check that data-theme attribute is set on html/body
<html data-theme="dracula">  // Theme must be set

// Verify CSS variables are defined for your theme
[data-theme="dracula"] {
  --background: oklch(0.17 0.02 280);
  --card: oklch(0.20 0.02 280);
  // etc.
}

// Ensure you're passing strings, not undefined
const className = condition ? 'extra-class' : undefined;

// Bad - undefined can cause issues
cn(mode.radius, className)  // If className is undefined

// Good - filter out falsy values
cn(mode.radius, condition && 'extra-class')

// cn() handles false/null/undefined, but be explicit
cn(mode.radius, className || '')  // Explicit empty string

// Class order matters - later classes win (when using cn())
cn('rounded-lg', mode.radius)  // mode.radius wins
cn(mode.radius, 'rounded-lg')  // rounded-lg wins

// For component APIs, put className last
<Button className={cn(
  mode.radius,
  mode.font,
  'bg-primary',
  className  // User's className can override defaults
)}>

import { mode } from '@/design-system';
import { cn } from '@/lib/utils';

// Correct - full border
<Card className={cn('border border-border', mode.radius)}>

// Correct - no radius on partial border
<div className="border-b border-border">

// Incorrect - radius on partial border
<div className={cn('border-b border-border', mode.radius)}>  // ❌

// Correct
<Button className={cn(mode.radius, mode.font, 'px-4')}>

// Incorrect - template literals don't handle conflicts
<Button className={`${mode.radius} ${mode.font} px-4`}>  // ❌

// Apply mode classes at the component level, not deep inside
export function Card({ className, children }) {
  return (
    <div className={cn(
      'border border-border bg-card',
      mode.radius,
      className
    )}>
      {children}  {/* Children inherit, don't need mode */}
    </div>
  );
}

// Since body has font-mono, most elements inherit it
// Only use mode.font when explicitly needed

// Unnecessary - inherits from body
<p className={mode.font}>Text</p>  // Usually redundant

// Necessary - overriding a parent
<div className="font-sans">
  <span className={mode.font}>Back to monospace</span>
</div>

// Correct - semantic, theme-aware
<span className={mode.color.text.destructive}>Error</span>

// Incorrect - hardcoded, breaks theming
<span className="text-red-500">Error</span>  // ❌