Colors

Tosui uses semantic color tokens that automatically adapt to light and dark modes. Instead of raw color values, you reference tokens by their purpose.

Semantic Philosophy

Use colors by meaning, not appearance:

// Good - semantic
<Box color="foreground-muted">Secondary text</Box>
<Box bg="primary-default">Brand element</Box>

// Avoid - hardcoded
<Box color="#666666">Secondary text</Box>
<Box bg="#0066cc">Brand element</Box>

Semantic tokens ensure your UI adapts correctly to dark mode without manual adjustments.

Token Categories

Surface & Text

For text content and backgrounds:

Token	Use
`foreground`	Primary text
`foreground-muted`	Secondary text, descriptions
`foreground-subtle`	Tertiary text, placeholders
`foreground-inverted`	Text on colored/dark backgrounds
`background`	Page background
`surface`	Card/panel backgrounds

<Box bg="surface" color="foreground">
  <Text>Primary content</Text>
  <Text color="foreground-muted">Supporting text</Text>
</Box>

When to Use `foreground-inverted`

Use foreground-inverted for text that appears on colored or dark backgrounds:

// Text on a colored background
<Box bg="primary-default" color="foreground-inverted" p={4}>
  White text on blue background
</Box>

// Text on success background
<Box bg="success-default" color="foreground-inverted" p={4}>
  White text on green background
</Box>

Border

For dividers and outlines:

Token	Use
`border`	Standard borders
`border-muted`	Subtle dividers

<Box border="thin" borderColor="border">
  Bordered container
</Box>

Brand Colors

Primary and accent colors for brand identity:

Token	Use
`primary-default`	Main brand actions, links
`primary-emphasis`	Hover/active states
`primary-subtle`	Backgrounds, highlights
`accent-default`	Secondary brand color
`accent-emphasis`	Hover/active states
`accent-subtle`	Backgrounds, highlights

Primary vs Accent:

Primary is your main brand color—use it for primary actions (main buttons, links, key UI elements)
Accent is a complementary color—use it for secondary highlights, decorative elements, or to draw attention to non-primary elements

// Primary for main actions
<Button>Submit</Button>  {/* Uses primary-default */}

// Subtle backgrounds for highlights
<Box bg="primary-subtle" p={4}>
  Highlighted section
</Box>

// Accent for secondary emphasis
<Box bg="accent-subtle" p={2} rounded="md">
  <Text color="accent-default">New feature</Text>
</Box>

Feedback Colors

For status and user feedback. Each category has three variants:

Variant	Purpose
`*-default`	Text, icons, solid elements
`*-emphasis`	Hover/active states
`*-subtle`	Background colors

Category	Use
`success-*`	Confirmations, completed actions
`warning-*`	Cautions, important notices
`error-*`	Errors, destructive actions
`info-*`	Informational messages

// Success message with subtle background
<Box bg="success-subtle" color="success-default" p={4} rounded="md">
  Operation completed successfully
</Box>

// Error indicator
<Box bg="error-subtle" color="error-default" p={4} rounded="md">
  Please fix the errors above
</Box>

// Warning notice
<Box bg="warning-subtle" color="warning-default" p={4} rounded="md">
  This action cannot be undone
</Box>

Color Props

Three props control colors on Box and components that accept Box props:

Prop	Description
`color`	Text color
`bg`	Background color
`borderColor`	Border color

<Box
  bg="surface"
  color="foreground"
  borderColor="border"
  border="thin"
>
  Styled box
</Box>

Dark Mode

Colors automatically adapt when:

System preference is dark (prefers-color-scheme: dark)
data-theme="dark" is set on the HTML element

No code changes needed—the same tokens work in both modes:

// This works correctly in both light and dark mode
<Box bg="surface" color="foreground">
  Content adapts automatically
</Box>

To force a specific theme:

<!-- Force light mode -->
<html data-theme="light">

<!-- Force dark mode -->
<html data-theme="dark">

<!-- Follow system (default) -->
<html data-theme="auto">

Common Patterns

Status Indicators

<Box display="flex" alignItems="center" gap={2}>
  <Box w="8px" h="8px" rounded="full" bg="success-default" />
  <Text>Online</Text>
</Box>

Highlighted Text

<Text>
  Check out our <Box as="span" color="primary-default">new feature</Box>
</Text>

Muted Secondary Content

<Box display="flex" flexDirection="column" gap={1}>
  <Text fontWeight="medium">John Doe</Text>
  <Text color="foreground-muted" fontSize="sm">john@example.com</Text>
</Box>

Status Message

<Box bg="info-subtle" color="info-default" p={4} rounded="md">
  <Text fontWeight="medium">Tip</Text>
  <Text>You can customize these colors in your theme.</Text>
</Box>

Token Reference

For the complete list of color tokens and their default values (light and dark mode), see the source: packages/react/src/styles/_color-scheme.css

Semantic Philosophy​

Token Categories​

Surface & Text​

When to Use foreground-inverted​

Border​

Brand Colors​

Feedback Colors​

Color Props​

Dark Mode​

Common Patterns​

Status Indicators​

Highlighted Text​

Muted Secondary Content​

Status Message​

Token Reference​