# Colors

> A comprehensive color system with light and dark mode support, semantic colors, and utility functions for consistent theming across your React Native app.

**BNA UI** — a React Native / Expo component library.
These components render through `react-native`, not the DOM: there are no HTML
elements, no Tailwind classes and no Radix primitives. Source is copied into your
project and imported through `@/components/ui/*`, `@/components/charts/*`,
`@/hooks/*` and `@/theme/*`. Colours come from the `useColor` hook rather than
hardcoded hex; sizing tokens (`HEIGHT`, `FONT_SIZE`, `BORDER_RADIUS`, `CORNERS`)
come from `@/theme/globals`.

- Docs: https://ui.ahmedbna.com/docs/theme/colors
- Markdown: https://ui.ahmedbna.com/docs/theme/colors.md
- Structured JSON (props, usage, source, examples): https://ui.ahmedbna.com/r/ai/colors.json
- Install payload (source plus every file it imports): https://ui.ahmedbna.com/r/colors.json
- Install: `npx bna-ui add colors`

---

## Installation

### CLI

```bash
npx bna-ui add colors
```

### Manual

**1.** Copy and paste the following code into your project.

```ts
// theme/colors.ts
const lightColors = {
  // Base colors
  background: '#FFFFFF',
  foreground: '#000000',

  // Card colors
  card: '#F2F2F7',
  cardForeground: '#000000',

  // Popover colors
  popover: '#F2F2F7',
  popoverForeground: '#000000',

  // Primary colors
  primary: '#18181b',
  primaryForeground: '#FFFFFF',

  // Secondary colors
  secondary: '#F2F2F7',
  secondaryForeground: '#18181b',

  // Muted colors
  muted: '#78788033',
  mutedForeground: '#71717a',

  // Accent colors
  accent: '#F2F2F7',
  accentForeground: '#18181b',

  // Destructive colors
  destructive: '#ef4444',
  destructiveForeground: '#FFFFFF',

  // Border and input
  border: '#C6C6C8',
  input: '#e4e4e7',
  ring: '#a1a1aa',

  // Text colors
  text: '#000000',
  textMuted: '#71717a',

  // Legacy support for existing components
  tint: '#18181b',
  icon: '#71717a',
  tabIconDefault: '#71717a',
  tabIconSelected: '#18181b',

  // Default buttons, links, Send button, selected tabs
  blue: '#007AFF',

  // Success states, FaceTime buttons, completed tasks
  green: '#34C759',

  // Delete buttons, error states, critical alerts
  red: '#FF3B30',

  // VoiceOver highlights, warning states
  orange: '#FF9500',

  // Notes app accent, Reminders highlights
  yellow: '#FFCC00',

  // Pink accent color for various UI elements
  pink: '#FF2D92',

  // Purple accent for creative apps and features
  purple: '#AF52DE',

  // Teal accent for communication features
  teal: '#5AC8FA',

  // Indigo accent for system features
  indigo: '#5856D6',

  // Semantic states
  success: '#22c55e',
  successForeground: '#ffffff',
  warning: '#f59e0b',
  warningForeground: '#ffffff',
  info: '#3b82f6',
  infoForeground: '#ffffff',
  error: '#ef4444',
  errorForeground: '#ffffff',
};

const darkColors = {
  // Base colors
  background: '#000000',
  foreground: '#FFFFFF',

  // Card colors
  card: '#1C1C1E',
  cardForeground: '#FFFFFF',

  // Popover colors
  popover: '#18181b',
  popoverForeground: '#FFFFFF',

  // Primary colors
  primary: '#e4e4e7',
  primaryForeground: '#18181b',

  // Secondary colors
  secondary: '#1C1C1E',
  secondaryForeground: '#FFFFFF',

  // Muted colors
  muted: '#78788033',
  mutedForeground: '#a1a1aa',

  // Accent colors
  accent: '#1C1C1E',
  accentForeground: '#FFFFFF',

  // Destructive colors
  destructive: '#dc2626',
  destructiveForeground: '#FFFFFF',

  // Border and input - using alpha values for better blending
  border: '#38383A',
  input: 'rgba(255, 255, 255, 0.15)',
  ring: '#71717a',

  // Text colors
  text: '#FFFFFF',
  textMuted: '#a1a1aa',

  // Legacy support for existing components
  tint: '#FFFFFF',
  icon: '#a1a1aa',
  tabIconDefault: '#a1a1aa',
  tabIconSelected: '#FFFFFF',

  // Default buttons, links, Send button, selected tabs
  blue: '#0A84FF',

  // Success states, FaceTime buttons, completed tasks
  green: '#30D158',

  // Delete buttons, error states, critical alerts
  red: '#FF453A',

  // VoiceOver highlights, warning states
  orange: '#FF9F0A',

  // Notes app accent, Reminders highlights
  yellow: '#FFD60A',

  // Pink accent color for various UI elements
  pink: '#FF375F',

  // Purple accent for creative apps and features
  purple: '#BF5AF2',

  // Teal accent for communication features
  teal: '#64D2FF',

  // Indigo accent for system features
  indigo: '#5E5CE6',

  // Semantic states
  success: '#16a34a',
  successForeground: '#ffffff',
  warning: '#d97706',
  warningForeground: '#ffffff',
  info: '#2563eb',
  infoForeground: '#ffffff',
  error: '#dc2626',
  errorForeground: '#ffffff',
};

export const Colors = {
  light: lightColors,
  dark: darkColors,
};

// Export individual color schemes for easier access
export { darkColors, lightColors };

// Utility type for color keys
export type ColorKeys = keyof typeof lightColors;

// Helper function to get color with opacity (useful for React Native)
export const withOpacity = (color: string, opacity: number) => {
  // Handle rgba colors
  if (color.startsWith('rgba')) {
    return color;
  }

  // Handle hex colors
  if (color.startsWith('#')) {
    const hex = color.replace('#', '');
    const r = parseInt(hex.substr(0, 2), 16);
    const g = parseInt(hex.substr(2, 2), 16);
    const b = parseInt(hex.substr(4, 2), 16);
    return `rgba(${r}, ${g}, ${b}, ${opacity})`;
  }

  return color;
};
```

**2.** Update the import paths to match your project setup.

## Usage

```tsx
import { Colors, withOpacity } from '@/theme/colors';
```

```tsx
export function ThemedComponent() {
  const colorScheme = useColorScheme();
  const colors = Colors[colorScheme ?? 'light'];

  return (
    <View style={{ backgroundColor: colors.background }}>
      <Text style={{ color: colors.text }}>Hello World</Text>
    </View>
  );
}
```

## Color Scheme

### Light Mode Colors

The light color scheme provides a clean, modern appearance with high contrast for optimal readability.

#### Base Colors

- `background`: Primary background color (#FFFFFF)
- `foreground`: Primary text color (#000000)
- `card`: Card background color (#F2F2F7)
- `cardForeground`: Card text color (#000000)

#### Interactive Colors

- `primary`: Primary brand color (#18181b)
- `primaryForeground`: Primary text on brand color (#FFFFFF)
- `secondary`: Secondary background (#F2F2F7)
- `secondaryForeground`: Secondary text color (#18181b)

#### System Colors

- `blue`: Default buttons, links (#007AFF)
- `green`: Success states, completed tasks (#34C759)
- `red`: Delete buttons, error states (#FF3B30)
- `orange`: Warning states (#FF9500)
- `yellow`: Notes app accent (#FFCC00)
- `pink`: Pink accent color (#FF2D92)
- `purple`: Purple accent (#AF52DE)
- `teal`: Communication features (#5AC8FA)
- `indigo`: System features (#5856D6)

#### Semantic Colors

- `success` / `successForeground`: Status indicators for successful operations (#22c55e)
- `warning` / `warningForeground`: Status indicators for cautionary states (#f59e0b)
- `info` / `infoForeground`: Status indicators for informational messages (#3b82f6)
- `error` / `errorForeground`: Status indicators for failed operations (#ef4444)

### Dark Mode Colors

The dark color scheme provides a comfortable viewing experience in low-light conditions.

#### Base Colors

- `background`: Primary background color (#000000)
- `foreground`: Primary text color (#FFFFFF)
- `card`: Card background color (#1C1C1E)
- `cardForeground`: Card text color (#FFFFFF)

#### Interactive Colors

- `primary`: Primary brand color (#e4e4e7)
- `primaryForeground`: Primary text on brand color (#18181b)
- `secondary`: Secondary background (#1C1C1E)
- `secondaryForeground`: Secondary text color (#FFFFFF)

#### System Colors

- `blue`: Default buttons, links (#0A84FF)
- `green`: Success states, completed tasks (#30D158)
- `red`: Delete buttons, error states (#FF453A)
- `orange`: Warning states (#FF9F0A)
- `yellow`: Notes app accent (#FFD60A)
- `pink`: Pink accent color (#FF375F)
- `purple`: Purple accent (#BF5AF2)
- `teal`: Communication features (#64D2FF)
- `indigo`: System features (#5E5CE6)

#### Semantic Colors

- `success` / `successForeground`: Status indicators for successful operations (#16a34a)
- `warning` / `warningForeground`: Status indicators for cautionary states (#d97706)
- `info` / `infoForeground`: Status indicators for informational messages (#2563eb)
- `error` / `errorForeground`: Status indicators for failed operations (#dc2626)

## API Reference

### Colors

Main color export containing light and dark color schemes.

```tsx
const Colors = {
  light: lightColors,
  dark: darkColors,
};
```

### withOpacity

Utility function to add opacity to colors.

#### Parameters

| Name      | Type     | Description                   |
| --------- | -------- | ----------------------------- |
| `color`   | `string` | The color to add opacity to   |
| `opacity` | `number` | Opacity value between 0 and 1 |

#### Returns

| Type     | Description                              |
| -------- | ---------------------------------------- |
| `string` | Color with opacity applied (rgba format) |

#### Example

```tsx
import { withOpacity, Colors } from '@/theme/colors';

const semi_transparent_blue = withOpacity(Colors.light.blue, 0.5);
// Returns: "rgba(0, 122, 255, 0.5)"
```

### ColorKeys

TypeScript type for all available color keys.

```tsx
type ColorKeys = keyof typeof lightColors;
```

## Usage Examples

### Basic Themed Component

```tsx
import { Colors } from '@/theme/colors';
import { useColorScheme } from '@/hooks/useColorScheme';

export function BasicThemedComponent() {
  const colorScheme = useColorScheme();
  const colors = Colors[colorScheme ?? 'light'];

  return (
    <View style={{ backgroundColor: colors.background, padding: 16 }}>
      <Text style={{ color: colors.text, fontSize: 18 }}>
        Welcome to the app
      </Text>
      <View
        style={{
          backgroundColor: colors.card,
          padding: 12,
          borderRadius: 8,
          marginTop: 16,
        }}
      >
        <Text style={{ color: colors.cardForeground }}>
          This is a card component
        </Text>
      </View>
    </View>
  );
}
```

### Using withOpacity Utility

```tsx
import { Colors, withOpacity } from '@/theme/colors';
import { useColorScheme } from '@/hooks/useColorScheme';

export function OverlayComponent() {
  const colorScheme = useColorScheme();
  const colors = Colors[colorScheme ?? 'light'];

  return (
    <View style={{ position: 'relative' }}>
      <Image source={{ uri: 'https://example.com/image.jpg' }} />
      <View
        style={{
          position: 'absolute',
          top: 0,
          left: 0,
          right: 0,
          bottom: 0,
          backgroundColor: withOpacity(colors.background, 0.8),
          justifyContent: 'center',
          alignItems: 'center',
        }}
      >
        <Text style={{ color: colors.text, fontSize: 24 }}>
          Overlay Content
        </Text>
      </View>
    </View>
  );
}
```

## Best Practices

### Color Consistency

Always use the color system instead of hardcoded colors to ensure consistency across your app and proper support for both light and dark modes.

```tsx
// ✅ Good - uses theme colors
const styles = StyleSheet.create({
  container: {
    backgroundColor: colors.background,
  },
  text: {
    color: colors.text,
  },
});

// ❌ Bad - hardcoded colors
const styles = StyleSheet.create({
  container: {
    backgroundColor: '#FFFFFF',
  },
  text: {
    color: '#000000',
  },
});
```

### Semantic Usage

Use semantic colors for status indicators and system feedback to maintain consistency with platform conventions.

```tsx
// ✅ Good - semantic colors, resolved for the active theme
<Text style={{ color: colors.success }}>
  Operation completed successfully
</Text>

// ❌ Bad - arbitrary green, and ignores the active theme
<Text style={{ color: '#00FF00' }}>
  Operation completed successfully
</Text>
```

`success`, `warning`, `info`, and `error` (plus their `*Foreground`
counterparts) live directly on `Colors.light`/`Colors.dark` alongside every
other token, so they also work with the `useColor` hook:

```tsx
import { useColor } from '@/hooks/useColor';

const successColor = useColor('success');
```

### Performance Considerations

The color objects are static and can be safely memoized or cached. Consider using React.memo for components that only change based on color scheme.

```tsx
const ThemedComponent = React.memo(({ colorScheme }) => {
  const colors = Colors[colorScheme];
  // Component implementation
});
```

## Accessibility

The color system is designed with accessibility in mind, providing sufficient contrast ratios between foreground and background colors. The semantic colors also follow platform conventions for better user experience.

When creating custom color combinations, ensure they maintain proper contrast ratios for accessibility compliance (minimum 4.5:1 for normal text, 3:1 for large text).

## Platform Compatibility

The color system follows iOS design guidelines and adapts automatically to system-level appearance changes. Colors are optimized for both light and dark modes across all supported platforms.