Theming — MeoNode UI

Context-based theming with automatic value resolution. Define your theme object, wrap your app with ThemeProvider, and reference theme tokens anywhere using string paths—no prop drilling required.

---

Theme Structure

Every theme requires two root properties:

type Theme = {
  mode: 'light' | 'dark' | string
  system: {
    primary: { default: string; content: string }
    secondary: { default: string; content: string }
    accent: { default: string; content: string }
    warning: { default: string; content: string }
    base: { default: string; content: string; accent?: string }
    // Add custom tokens as needed
  }
} & Partial<{
  [key: string]: string | number | boolean | Theme | Record<string, any>
}>

Required:

• mode — Theme mode identifier (light, dark, or custom)
• system — Design tokens (colors, spacing, typography, etc.)

Example Theme:

export const lightTheme: Theme = {
  mode: 'light',
  system: {
    primary: {
      default: '#FF6B6B',
      content: '#4A0000',
    },
    secondary: {
      default: '#6BCB77',
      content: '#0A3B0F',
    },
    accent: {
      default: '#4ECDC4',
      content: '#1A4A47',
    },
    warning: {
      default: '#FFE66D',
      content: '#665A00',
    },
    base: {
      default: '#F8F8F8',
      content: '#333333',
      accent: '#88B04B',
    },
  },
  // Add custom properties for your design system
}

---

ThemeProvider

Wrap your app with ThemeProvider to enable theme access throughout the component tree:

import { ThemeProvider, Column, H1, Text } from '@meonode/ui'
import { lightTheme } from './theme'

const AppContent = () =>
  Column({
    padding: 20,
    children: [
      H1('Themed Application', {
        color: 'theme​.primary',
        fontSize: '2.5rem',
      }),
      Text('Automatic theme resolution', {
        backgroundColor: 'theme​.base',
        color: 'theme​.base.content',
        padding: 10,
      }),
    ],
  }).render()

const App = () =>
  ThemeProvider({
    theme: lightTheme,
    children: AppContent(),
  }).render()

All MeoNode components inside ThemeProvider automatically access the theme—no prop passing required.

---

Accessing Theme Values

String Path Notation

Reference theme tokens using dot-separated paths prefixed with theme​.:

import { Column, Button } from '@meonode/ui'

Column({
  backgroundColor: 'theme​.primary',
  padding: 'theme​.base.accent',
  children: Button('Submit', {
    backgroundColor: 'theme​.secondary',
    color: 'theme​.secondary.content',
  }),
})

Default Key Resolution:
Partial paths (e.g., 'theme​.primary') automatically resolve to the default key within that object. If no default exists, it throws an error.

// These are equivalent:
backgroundColor: 'theme​.primary'
backgroundColor: 'theme​.primary.default'

Direct Object Access

Use the useTheme hook for direct access with full TypeScript support:

import { useTheme, Column, Text } from '@meonode/ui'

const ThemedComponent = () => {
  const { theme } = useTheme()

  return Column({
    padding: theme.system.accent.default,
    backgroundColor: theme.system.base.default,
    children: Text('Direct access', {
      color: theme.system.base.content,
    }),
  }).render()
}

Theme Functions in css Prop

Pass functions to css prop properties for dynamic theme-based computations:

import { Div } from '@meonode/ui'
import tinycolor from 'tinycolor2'

Div({
  backgroundColor: 'theme​.primary',
  css: {
    // Simple theme access
    color: theme => theme.system.primary.content,

    // Computed values
    boxShadow: theme => `0 4px 14px 0 ${tinycolor(theme.system.primary.default).setAlpha(0.38).toString()}`,
  },
})

This provides maximum flexibility for complex styling logic based on theme tokens.

---

Function Children

Function children automatically inherit theme context:

import { ThemeProvider, Column } from '@meonode/ui'

ThemeProvider({
  theme: myTheme,
  children: () =>
    Column({
      color: 'theme​.accent',
      padding: 'theme​.spacing.md',
    }),
})

The child function's returned nodes receive the theme automatically.

---

Complete Example

import { ThemeProvider, Column, H1, Button, Text } from '@meonode/ui'

const lightTheme = {
  mode: 'light',
  system: {
    primary: { default: '#3B82F6', content: '#FFFFFF' },
    secondary: { default: '#10B981', content: '#FFFFFF' },
    base: { default: '#F9FAFB', content: '#1F2937' },
    spacing: { sm: 8, md: 16, lg: 24 },
  },
}

const ThemedApp = () =>
  Column({
    padding: 'theme​.spacing.lg',
    backgroundColor: 'theme​.base',
    children: [
      H1('MeoNode Theming', {
        color: 'theme​.primary',
        marginBottom: 'theme​.spacing.md',
      }),
      Text('Context-based theme system with automatic resolution', {
        color: 'theme​.base.content',
        marginBottom: 'theme​.spacing.md',
      }),
      Button('Primary Action', {
        backgroundColor: 'theme​.primary',
        color: 'theme​.primary.content',
        padding: '12px 24px',
        borderRadius: 8,
      }),
    ],
  }).render()

const App = () =>
  ThemeProvider({
    theme: lightTheme,
    children: ThemedApp(),
  }).render()

export default App

---

Multiple Themes

Switch themes dynamically or nest ThemeProvider for different theme contexts:

import { useState } from 'react'
import { ThemeProvider, Column, Button } from '@meonode/ui'

const darkTheme = {
  mode: 'dark',
  system: {
    primary: { default: '#60A5FA', content: '#1E3A8A' },
    base: { default: '#1F2937', content: '#F9FAFB' },
  },
}

const App = () => {
  const [theme, setTheme] = useState(lightTheme)

  return ThemeProvider({
    theme,
    children: Column({
      children: [
        Button('Toggle Theme', {
          onClick: () => setTheme(theme.mode === 'light' ? darkTheme : lightTheme),
        }),
      ],
    }),
  }).render()
}

---

Best Practices

Structure system Property
Organize design tokens logically: colors, spacing, typography, shadows, borders.

Use Semantic Names
primary, secondary, success, warning over blue, green.

Default Keys for Variants
Use default as the base value, add content, hover, active for variants.

system: {
  primary: {
    default: '#3B82F6',
    content: '#FFFFFF',
    hover: '#2563EB',
    active: '#1D4ED8'
  }
}

TypeScript for Type Safety
Define theme types for autocomplete and compile-time validation.

Function-Based Computations
Use theme functions in css prop for dynamic color transformations or complex calculations.

---

Common Patterns

Color System

system: {
  // Core colors
  primary: { default: '#3B82F6', content: '#FFFFFF' },
  secondary: { default: '#10B981', content: '#FFFFFF' },

  // Semantic colors
  success: { default: '#10B981', content: '#FFFFFF' },
  warning: { default: '#F59E0B', content: '#78350F' },
  error: { default: '#EF4444', content: '#FFFFFF' },

  // Surface colors
  base: { default: '#FFFFFF', content: '#1F2937' },
  surface: { default: '#F9FAFB', content: '#374151' },
  overlay: { default: 'rgba(0, 0, 0, 0.5)', content: '#FFFFFF' }
}

Spacing Scale

system: {
  spacing: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 32,
    '2xl': 48
  }
}

Typography

system: {
  typography: {
    fontFamily: {
      sans: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto',
      mono: 'ui-monospace, SFMono-Regular, Menlo'
    },
    fontSize: {
      sm: '0.875rem',
      base: '1rem',
      lg: '1.125rem',
      xl: '1.25rem',
      '2xl': '1.5rem'
    },
    fontWeight: {
      normal: 400,
      medium: 500,
      semibold: 600,
      bold: 700
    }
  }
}

---

Next Steps

• Framework Integration — Next.js, Vite, Remix configuration
• FAQ — Common patterns, troubleshooting, migration strategies
• Release Notes — Changelog, breaking changes, upgrade guides