Skip to content

Tokens overview

The @otfdashkit/tokens design system — CSS variables, palettes, and runtime theme switching.

@otfdashkit/tokens is the source-of-truth for every visual decision in OTF. It ships as CSS custom properties for the web and as JS palettes for native. One source, two outputs.

What's in it

Token bucketExamples
Color--background, --foreground, --primary, --card, --border, --ring, --chart-1..5
Typography--font-sans, --font-heading, --font-mono, --font-size-{xs..4xl}, --font-weight-*, --line-height-*, --letter-spacing-*
Border radius--radius, --radius-sm, --radius-md, --radius-lg, --radius-xl
Spacing scaleTailwind's default scale, which matches the --space-* variables
MotionDefault ease curves + duration tokens

Every component reads exclusively from these variables. Never hardcode hex outside the tokens package — @otfdashkit/eslint-plugin-otf-design will flag it.

Web setup

Import the CSS once in your app's globals, before the component CSS:

app/globals.css
@import '@otfdashkit/tokens/web.css';
@import '@otfdashkit/ui/styles';

That's it. The tokens cascade onto :root and every component picks them up.

Native setup

Wrap your app once in <OTFProvider> from @otfdashkit/ui-native. It ships the default Tamagui-based theme config (light and dark), so no config file is needed:

app/_layout.tsx
import { Slot } from 'expo-router'
import { OTFProvider } from '@otfdashkit/ui-native'

export default function RootLayout() {
  return (
    <OTFProvider>
      <Slot />
    </OTFProvider>
  )
}

The four OTF palettes (Slate, Warm, Cosmic, Terminal) are exported as native color ramps. Import them from the package root to build your own themes:

import { otfThemes, slateDarkColors } from '@otfdashkit/tokens'

CSS theme classes

The web stylesheet documents four CSS theme classes, each with a light and dark variant. The tokens package also exports 17 named design-theme definitions from src/themes.ts; these are palette definitions, distinct from the four CSS classes shown below.

ClassVibeWhen to use
theme-slateCool slate, neutral graysDefault — works for almost any product
theme-warmWarm purple, cream backgroundsLifestyle / wellness / creator products
theme-cosmicMagenta-violet on near-blackEditorial / showcase / portfolio
theme-terminalPure mono — black on greenDeveloper tools / terminal-shaped apps

The fitness-kit defaults to its own brand override (warm orange) which is scoped to :root:not([class*="theme-"]) — i.e. it's the fallback when no theme-* class is set. Switching to any of the four shipped themes overrides the orange brand.

Switching themes at runtime

Set the class on <html>:

document.documentElement.className = 'theme-warm dark'

For zero-flicker first paint, do this before React hydrates:

app/layout.tsx
<script dangerouslySetInnerHTML={{ __html: `
  const t = localStorage.getItem('otf-theme') || 'theme-slate'
  const s = localStorage.getItem('otf-color-scheme') || 'dark'
  document.documentElement.className = \`\${t} \${s}\`
` }} />

The kits use <FloatingThemePicker /> (rendered globally) and <ThemeSwitch /> inside Settings to save + apply the choice.

Authoring a custom palette

Copy any of the four shipped palette blocks from packages/tokens/src/web.css and rename:

.theme-mybrand {
  --background:        0 0% 100%;
  --foreground:        220 8% 12%;
  --primary:           212 100% 47%;
  --primary-foreground: 0 0% 100%;
  --card:              0 0% 100%;
  --card-foreground:   220 8% 12%;
  --border:            220 8% 92%;
  --ring:              212 100% 47%;
  --chart-1:           212 100% 47%;
  --chart-2:           28 100% 56%;
  --chart-3:           160 70% 40%;
  --chart-4:           340 80% 56%;
  --chart-5:           260 60% 56%;
}

.theme-mybrand.dark,
.theme-mybrand .dark {
  --background:        220 12% 7%;
  --foreground:        0 0% 96%;
  --primary:           212 100% 60%;
  /* … */
}

Drop the file into your app's CSS, set document.documentElement.className = 'theme-mybrand dark', and every OTF component re-paints to the new palette.

Tailwind preset

For Tailwind CSS v3 projects, import the OTF preset to get token-aware utility classes (bg-background, text-foreground, border-border, bg-card, bg-primary, …). The components' dialog and menu animations also need the tailwindcss-animate plugin:

tailwind.config.ts
import animate from 'tailwindcss-animate'
import { otfPreset } from '@otfdashkit/tokens/tailwind-preset'

export default {
  presets: [otfPreset],
  plugins: [animate],
  content: [
    './app/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    './node_modules/@otfdashkit/ui/src/**/*.{ts,tsx}',
  ],
}

Use the /tailwind-preset path on the web. The package root also exports otfPreset, but it loads the native config too, so a web-only install fails with Cannot find module '@tamagui/core'.

The kits use these utility classes exclusively — never inline style={{ background: '#...' }}.

Charts

Charts always use chart tokens:

<BarChart
  data={data}
  dataKey={['issues', 'completed']}
  colors={['hsl(var(--chart-1))', 'hsl(var(--chart-3))']}
  stacked
/>

Each palette ships a chart-1 through chart-5. They're tuned for legibility against the palette's background, both light and dark.

Free with your email

Get the free AI configs pack

The AI files every kit ships with. Drop them in and your AI tool knows your project.

  • CLAUDE.mdProject context
  • .cursorrulesRules for Cursor
  • prompts/Task prompts

No spam. Unsubscribe any time.