Theming

Overview

Docyrus UI Native uses Tailwind CSS v4 via Uniwind for component styling. Static styles are expressed as className using Tailwind utility classes and semantic color tokens (bg-card, text-foreground, border-border). Dynamic values that can't be expressed as className (DocyrusIcon colors, platform shadows, runtime color lookups) are accessed via the useDocyTheme() hook.

Two sources of truth, kept in sync by value:

• CSS tokens (styles/docyrus-native/index.css, installed by the CLI) — what every className resolves against. Required; see Design Tokens.
• JS palette (useDocyTheme().colors) — the same colors as raw strings, for props that need one.

Setup

Import the design tokens from your Uniwind CSS entry (see Installation):

@import "tailwindcss";
@import "uniwind";
@import "./docyrus-native/index.css";

Then wrap your app root with DocyThemeProvider:

import '../src/styles/global.css';

import { DocyThemeProvider } from '@/lib/docyrus/theme';

export default function RootLayout() {
  return (
    <DocyThemeProvider defaultMode="system" defaultColorScheme="docyrus">
      {/* Your app content */}
    </DocyThemeProvider>
  );
}

Provider Props

Design Tokens

index.css declares the tokens as Uniwind themes — one @variant light and one @variant dark block inside @layer theme { :root { … } }, with the identical variable set in both. Uniwind follows the device appearance (DocyThemeProvider's mode drives it through Appearance.setColorScheme), and Uniwind.setTheme('light' | 'dark' | 'system') forces one. Each --color-<name> becomes every color utility: bg-<name>, text-<name>, border-<name>, ring-<name>, bg-<name>/10, …

Core colors

Extended tokens

Non-color tokens

Overriding tokens

Don't edit the installed file — docyrus update rewrites it. Redefine tokens after the import in your own global.css, keeping the Uniwind structure and defining each token in both variants:

@import "tailwindcss";
@import "uniwind";
@import "./docyrus-native/index.css";

@layer theme {
  :root {
    @variant light {
      --color-primary: hsl(221.2, 83.2%, 53.3%);
    }

    @variant dark {
      --color-primary: hsl(217.2, 91.2%, 59.8%);
    }
  }
}

Use plain CSS colors (hsl(h, s%, l%), hsla(…), rgba(…), hex). Uniwind logs Theme X is missing variable … when a variable is declared in one theme but not in the others.

Styling with Tailwind className

All components accept a className prop for Tailwind-based styling. Use semantic color tokens for theme-aware colors:

import { View, Text } from 'react-native';

function MyCard() {
  return (
    <View className="bg-card rounded-lg border border-border p-4">
      <Text className="text-foreground font-semibold">Card title</Text>
      <Text className="text-muted-foreground text-sm mt-1">Description</Text>
    </View>
  );
}

className vs style Decision Guide

useDocyTheme Hook

Access theme values for dynamic use cases only — static styling should use Tailwind className:

import { useDocyTheme } from '@/lib/docyrus/theme';
import { DocyrusIcon } from '@/components/docyrus-native/docyrus-icon';

function MyComponent() {
  const { colors, isDark } = useDocyTheme();

  return (
    <View className="flex-row items-center gap-2 p-4 bg-card rounded-lg">
      {/* DocyrusIcon needs raw color string — can't use className */}
      <DocyrusIcon icon="fal circle-check" size="default" color={colors.success} />
      <Text className="text-foreground font-medium">Verified</Text>
    </View>
  );
}

Theme Object

const theme = useDocyTheme();

theme.colors        // ThemeColors — semantic + Tailwind palette
theme.spacing       // ThemeSpacing — numeric scale
theme.borderRadius  // ThemeBorderRadius
theme.fieldHeight   // ThemeFieldHeight
theme.fontFamily    // ThemeFontFamily
theme.isDark        // boolean — for conditional logic
theme.colorScheme   // 'docyrus' | 'slate' | 'gray' | 'zinc' | ...
theme.mode          // 'light' | 'dark' | 'system'
theme.lang          // 'en' | 'tr'
theme.brand         // Custom brand object
theme.messages      // i18n messages

Color Schemes

Docyrus UI Native ships with 13 color schemes, each providing light and dark variants:

Base Schemes (Neutral)

Accent Schemes

<DocyThemeProvider colorScheme="blue" mode="dark">
  <App />
</DocyThemeProvider>

colorScheme switches the JS palette (useDocyTheme().colors). The className tokens come from CSS: index.css ships only the default docyrus scheme. The other 12 are opt-in Uniwind custom themes in color-schemes.css (installed next to index.css), named <scheme>-light / <scheme>-dark, with the same variable set:

1. Import it after index.css, by relative path:

   @import "tailwindcss";
   @import "uniwind";
   @import "./docyrus-native/index.css";
   @import "./docyrus-native/color-schemes.css";

2. Register the theme names in Metro — Tailwind rejects an @variant it doesn't know, so every scheme in the file must be listed. Restart Metro with --clear afterwards:

   const schemes = ['slate', 'gray', 'zinc', 'stone', 'neutral', 'red', 'rose', 'orange', 'green', 'blue', 'yellow', 'violet'];
   
   module.exports = withUniwindConfig(config, {
     cssEntryFile: './src/styles/global.css',
     polyfills: { rem: 14 },
     extraThemes: schemes.flatMap(scheme => [`${scheme}-light`, `${scheme}-dark`])
   });

3. Switch at runtime, keeping the JS palette in step:

   import { Uniwind } from 'uniwind';
   
   const { setColorScheme, isDark } = useDocyTheme();
   
   function applyScheme(scheme: ColorScheme) {
     setColorScheme(scheme);
     Uniwind.setTheme(scheme === 'docyrus' ? 'system' : `${scheme}-${isDark ? 'dark' : 'light'}`);
   }

   A custom theme is not adaptive — switch between <scheme>-light and <scheme>-dark yourself when the appearance changes, and note that dark: utilities only apply under the built-in dark theme.

Core colors in color-schemes.css mirror the JS palettes; the extended surface / field tokens reuse the default Docyrus values.

Semantic Color Tokens

Every color scheme provides these semantic tokens, available as both Tailwind classes and colors.* values (the full class-only list is in Design Tokens):

Use Tailwind classes for static colors (className="bg-card text-foreground"). Use colors.* only when a raw color string is needed (DocyrusIcon, chart libraries, cardShadow(), runtime lookups).

Tailwind Color Palette

In addition to semantic tokens, colors includes the full Tailwind palette (50–950 shades):

const { colors } = useDocyTheme();

// Only needed for dynamic runtime lookups — prefer className for static colors
colors.blue[500]    // '#3b82f6'
colors.red[600]     // '#dc2626'
colors.emerald[400] // '#34d399'

Available palettes: red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.

Dark Mode

With Tailwind Classes

Components support dark mode variants via Tailwind:

<View className="bg-muted dark:bg-background">
  <Text className="text-foreground">Adapts to dark mode</Text>
</View>

System-Based (Default)

<DocyThemeProvider mode="system">

The theme automatically follows the device's appearance. isDark reflects the resolved state.

Manual Control

function SettingsScreen() {
  const [mode, setMode] = useState<ThemeMode>('system');

  return (
    <DocyThemeProvider mode={mode}>
      <Button onPress={() => setMode('dark')}>Dark</Button>
      <Button onPress={() => setMode('light')}>Light</Button>
      <Button onPress={() => setMode('system')}>System</Button>
    </DocyThemeProvider>
  );
}

Checking Dark Mode

Use isDark for logic that can't be expressed as className (platform shadows, conditional rendering):

const { isDark, colors } = useDocyTheme();

// Platform shadows need style prop — no Tailwind equivalent
<View style={cardShadow(isDark, colors.border)}>

Custom Fonts

Override the default font family:

<DocyThemeProvider
  fontFamily={{
    light: 'Inter-Light',
    regular: 'Inter-Regular',
    medium: 'Inter-Medium',
    semiBold: 'Inter-SemiBold',
    bold: 'Inter-Bold',
    extraBold: 'Inter-ExtraBold',
  }}
>

With Expo, load fonts first using expo-font:

import { useFonts } from 'expo-font';

function App() {
  const [fontsLoaded] = useFonts({
    'Inter-Regular': require('./assets/fonts/Inter-Regular.ttf'),
    'Inter-Bold': require('./assets/fonts/Inter-Bold.ttf'),
  });

  if (!fontsLoaded) return null;

  return (
    <DocyThemeProvider fontFamily={{ regular: 'Inter-Regular', bold: 'Inter-Bold' }}>
      <App />
    </DocyThemeProvider>
  );
}

Brand Colors

Add custom brand-specific colors available throughout the theme:

type MyBrand = {
  accentBlue: string;
  accentGold: string;
  headerBg: string;
};

<DocyThemeProvider<MyBrand>
  brand={{
    accentBlue: '#1E90FF',
    accentGold: '#FFD700',
    headerBg: '#0A1128',
  }}
>

Access brand colors in components:

const { brand } = useDocyTheme<MyBrand>();

// Brand colors are dynamic — use style prop
<View style={{ backgroundColor: brand?.headerBg }}>

Localization

The provider stores the active language (lang / defaultLang) and an optional messages bag for your own app code:

<DocyThemeProvider lang="tr">

const { lang, messages } = useDocyTheme();

Docyrus native components do not read lang or messages for their built-in copy. Every component renders an English fallback and looks up ui.<group>.<key> through <UiTranslationProvider> — the same keys as the web package, so one translation catalog covers both platforms. Explicit copy props (label, cancelLabel, messages, …) always win.

Web vs Native Comparison