@titan-design/react-ui
v0.23.1
Published
Cross-platform design system built on Gluestack UI
Maintainers
Readme
@titan-design/react-ui
A cross-platform design system built on React Native primitives with NativeWind (Tailwind CSS). Works on web and React Native.
Features
- Cross-platform: Components work on web (via react-native-web) and React Native
- Dark mode first: Dark theme by default with light mode support
- Accessible: Built with accessibility in mind (WCAG 2.1 AA)
- Customizable: Theme tokens and component styles are easy to override
- Type-safe: Full TypeScript support with strict mode
- Compound components: Flexible composition following Gluestack patterns
Installation
pnpm add @titan-design/react-uiPeer Dependencies
# For web
pnpm add react react-dom react-native-web lucide-react
# For React Native
pnpm add react react-native lucide-react-nativeSetup
1. Import Global CSS
// App.tsx or entry point
import '@titan-design/react-ui/theme/global.css'2. Configure Tailwind
Titan's components style themselves with token classes such as bg-surface-elevated. Tailwind
only generates those classes when it uses titan's config as a preset and scans titan's dist.
// tailwind.config.js
const titanConfig = require('@titan-design/react-ui/tailwind.config.js')
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
'./src/**/*.{js,jsx,ts,tsx}',
'./node_modules/@titan-design/react-ui/dist/**/*.{js,mjs}',
],
presets: [titanConfig],
darkMode: 'class',
}The titanConfig preset includes nativewind/preset, so do not add that preset separately.
3. Web Setup (Vite)
Titan's web dist includes a built-in JSX runtime that handles className-to-CSS conversion automatically. No NativeWind runtime or special Vite config is needed. See the full guide: Web Consumer Setup
Quick summary:
npm install react-native-webandnpm install -D tailwindcss autoprefixer postcss nativewind(nativewindis needed only at build time, by the titan preset)- Add
resolve.alias: { 'react-native': 'react-native-web' }to your Vite config - Configure Tailwind as in step 2: titan's config as a preset and titan's dist in
content
Usage
import {
Button,
ButtonText,
ButtonIcon,
Typography,
Card,
CardHeader,
CardTitle,
CardContent,
Input,
InputGroup,
} from '@titan-design/react-ui'
import { Plus } from 'lucide-react'
function App() {
return (
<Card variant="elevated">
<CardHeader>
<CardTitle>Welcome</CardTitle>
</CardHeader>
<CardContent className="gap-4">
<Typography variant="body1">This is a cross-platform card component.</Typography>
<InputGroup>
<Input placeholder="Enter your email" label="Email" />
</InputGroup>
<Button color="primary" variant="solid">
<ButtonIcon as={Plus} />
<ButtonText>Get Started</ButtonText>
</Button>
</CardContent>
</Card>
)
}Components
Core UI Components
| Component | Description | | -------------- | ------------------------------------------------------------------- | | Button | Primary action component with variants: solid, outline, ghost, link | | Input | Text input with label, helper text, and error states | | Card | Container component with header, content, footer | | Badge | Status indicator labels | | Spinner | Loading indicator | | Avatar | User/entity representation | | Divider | Visual separator | | Checkbox | Boolean input with group support | | Switch | Toggle input | | Modal | Dialog/overlay component | | Typography | Consistent text styling (h1-h6, body, caption, etc.) | | Table | Data table with sorting and pagination | | EmptyState | Placeholder for empty data states |
Custom Components
| Component | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| Sidebar | Navigation sidebar with collapsible support |
| GoalLiftCard | One lift's goal state — next milestone, status pill, committed/stretch progress (workout subpath) |
| GoalMuscleCard | A muscle priority's rollup card, built on MuscleGlyph (bodymap subpath — see Subpaths) |
Subpaths
Four exports stay off the root barrel, so @titan-design/react-ui itself never pulls
their heavier runtime dependencies or the code of a domain it does not need:
@titan-design/react-ui/bodymap—BodyMap,BodyMapDetailPanel,TrainingStatusPage,MuscleGlyph,GoalMuscleCard, the muscle taxonomy (MuscleGroup,SimpleMuscleGroup, …), and related types. Reachesreact-native-body-highlighter(and transitivelyreact-native-svg) — install both as peer dependencies if you import from this subpath.For a web build via Vite,
react-native-body-highlighterships untranspiled JSX in a CommonJS dist that neither Rollup nor Vite's default transform can parse, and its ownrequire('react-native-svg')would load that package's native Flow sources instead of the web build. Titan's own Storybook and test config solve this with two Vite plugins inpackages/ui/vite-rn-svg-plugins.ts: one that resolvesreact-native-svg's relative imports to their.web.jssiblings (Node resolvers don't honor RN's platform-extension convention), and one that pre-bundlesreact-native-body-highlighterto a single ESM module with esbuild (jsx: 'automatic',react-native-svgaliased to its web entry,reactleft external). That esbuild pass needs an explicitrequireshim banner — a small snippet defining arequire(id)that returns React for"react"and throws otherwise — because esbuild's own dynamic-require helper only throws when nothing suppliesrequire, and a plainvite buildbundle has nothing to supply it (Node's CJS interop hides the gap in a vitest run, which is why it can look unnecessary until you build for the browser). A consumer building/bodymapfor web needs the same two plugins; seepackages/ui/vite-rn-svg-plugins.tsin this repo for the working pattern.@titan-design/react-ui/pages— page-level organisms (ActiveWorkoutPage,ExerciseDetailPage,ProgramPlanningPage) kept off the root as reference implementations.@titan-design/react-ui/workout— the Workout family (custom/Workout:ExerciseCard,SetRow,VelocityStrip, the goal and meso cards, …) and the workout-app chrome that composes it (WorkoutShell,WorkoutTopBar,PinnedLiveStrip,DeviceMenu, …), with their types. Moved off the root in 0.22.0.@titan-design/react-ui/motion— the motion kit (MotionProvider,Beat,useLocalTime,interpolate,spring,stagger,sequence, the easing curves,noise2D,random,MOTION). Moved off the root in 0.22.0. On web, aMotionProvideron aseekClockpublisheswindow.__titanMotion(TitanMotionApi:seek,ready,duration) for a frame-capture renderer. It also carries the video-only components and utils (EvidenceChip,elideSource), which never shipped on the root.
Component API
Button
<Button
variant="solid" | "outline" | "ghost" | "link"
color="primary" | "secondary" | "success" | "error" | "warning" | "info"
size="sm" | "md" | "lg"
isDisabled={false}
isLoading={false}
onPress={() => {}}
>
<ButtonIcon as={IconComponent} />
<ButtonText>Button Text</ButtonText>
</Button>Input
<Input
label="Field Label"
placeholder="Placeholder text"
helperText="Helper text"
errorMessage="Error message"
variant="outline" | "filled" | "underline"
size="sm" | "md" | "lg"
isDisabled={false}
isInvalid={false}
isReadOnly={false}
isRequired={false}
value={value}
onChangeText={setValue}
/>Typography
<Typography
variant="h1" | "h2" | "h3" | "h4" | "h5" | "h6" |
"body1" | "body2" | "subtitle1" | "subtitle2" | "caption" | "overline" |
"button" | "mono" | "monoLabel" | "microLabel" | "boldLabel"
color="primary" | "secondary" | "tertiary" | "disabled" | "inverse" |
"success" | "error" | "warning" | "info" | "inherit"
>
Text content
</Typography>Card
<Card variant="elevated" | "outline" | "filled" | "accent" | "subtle">
<CardHeader>
<CardTitle>Title</CardTitle>
</CardHeader>
<CardContent>
Content here
</CardContent>
<CardFooter>
<Button>
<ButtonText>Action</ButtonText>
</Button>
</CardFooter>
</Card>Theme
Building a component in this package? Read TOKENS.md first — which palette for which meaning (
result-*vsstatus-*vs the categorical palette), how to resolve a colour in code, and the type/spacing scales. Also in Storybook as Foundations → Choosing Tokens.
The design system uses CSS custom properties for theming. Dark mode is the default.
Using the Theme
Import the global CSS in your app:
import '@titan-design/react-ui/theme/global.css'Switching Themes
Add the light class to your root element for light mode:
// Dark mode (default)
<div>
{/* Your app */}
</div>
// Light mode
<div className="light">
{/* Your app */}
</div>Programmatic Theme Switching
function toggleTheme() {
document.documentElement.classList.toggle('light')
}Design Tokens
The design system uses a two-tier token system following DTCG conventions:
Token Categories
| Category | Pattern | Description |
| --------------- | ----------------------------------------------------------------- | --------------------- |
| brand-* | brand-primary, brand-secondary | Brand identity colors |
| status-* | status-success, status-error, status-warning, status-info | Feedback colors |
| text-* | text-primary, text-secondary, text-tertiary | Text hierarchy |
| surface-* | surface-base, surface-elevated, surface-raised | Container backgrounds |
| background-* | background-base, background-default | Page backgrounds |
| border-* | border-default, border-subtle, border-strong | Border colors |
| interactive-* | interactive-hover, interactive-focus, interactive-active | State colors |
Using Tokens
import { Text, View } from 'react-native'
// In components
;<View
className="bg-surface-elevated rounded-lg"
style={{ borderWidth: 1, borderColor: '#1F1F1F' }}
>
<Text className="text-text-primary">Primary text</Text>
<Text className="text-text-secondary">Secondary text</Text>
</View>Note: Do not combine
border+border-border-*classes for colored borders. The bareborderutility setsborderColor: currentColor(often black), which overrides the token color unreliably. Usestyle={{ borderWidth: 1, borderColor: '...' }}instead. See Common Pitfalls below.
Common Pitfalls
Border Styling
The bare border Tailwind utility sets both borderWidth: 1 and borderColor: currentColor. When combined with a border-border-* color class, the color assignment order is not guaranteed in NativeWind/React Native, which can produce black borders instead of the intended theme color.
// WRONG — border sets currentColor, may render black on native
<View className="border border-hairline" />
// WRONG — same problem with any border-* color class
<View className="border border-border-input" />import { View } from 'react-native'
import { resolveColor } from '@titan-design/react-ui/theme'
// RIGHT — explicit inline style; resolveColor returns the CSS variable on web and the resolved hex on native
export const Explicit = () => (
<View style={{ borderWidth: 1, borderColor: resolveColor('hairline-default') }} />
)
// RIGHT on web only — border-hairline (no bare 'border') resolves to the CSS variable
export const WebOnly = () => <View className="border-[1px] border-hairline" />The arch test src/arch/default-suffix-class.test.ts fails on a *-default token class such as
border-border-default in source components; Tailwind never generates one, so the element falls back
to currentColor. Use the suffix-less DEFAULT class (border-border). Run it alone with
pnpm exec vitest run --project threads src/arch/default-suffix-class.test.ts in packages/ui. It does
not flag a bare border; review those by hand.
For full token reference and additional pitfalls, see TOKENS.md.
Development
Storybook
pnpm storybookOpen http://localhost:6006 to view component documentation.
Testing
# Run tests
pnpm test
# Run tests with coverage
pnpm test:coverageStory audit
pnpm audit:storiesAudits the stories your diff touches for overflow, clipping and contrast; see docs/audit-stories.md.
Build
pnpm buildGuardrails
pnpm lintenforces that every Storybook story'stitlestarts with an approved top-level group (Foundations,Components,Custom,Shell,Pages,Lab,Docs— seeeslint-rules/story-title-prefix.js), so a new story can't invent an unlisted sidebar root.pnpm testrunssrc/arch/arch-graph.freshness.test.ts, which fails CI when a.tsxfile theui,customorshellbarrels re-export has no node insrc/arch/arch-graph.json(the catalog never lists a component without one), or when a node names a file that no longer exists (delete that block by hand). Full regeneration doesn't run in CI itself: it needs the@codewatch/cliCLI (unpublished, see AW-118) and sibling checkouts of every consumer inscripts/arch.config.json, neither of which a CI runner has; running it there would silently score every consumer as zero usage instead of failing loudly. The per-component metrics (exports,dependsOn,storyRefs,leak,tier,libDependents,xproj,verdict) are advisory for the same reason: they come from the codewatch index and the consumer checkouts, a full regen takes about two minutes, and the freshness test cannot recompute them. They can drift between barrel changes without failing CI; regenerate withpnpm arch:graph -- --reindexin a commit of its own so the diff stays reviewable.src/arch/component-catalog.jsonderives fromarch-graph.json, so runpnpm catalogafter every arch-graph regen and commit its output too.- A feature PR adds a missing node without a full regen:
pnpm arch:graph -- --add packages/ui/src/components/ui/kbd/Kbd.tsx(repeat--addfor more files) indexes fresh, then writes only those nodes' blocks; every other node keeps its committed bytes. The file stores no edge list, totals, dead lists or barrel hash:src/arch/arch-graph-derived.tsderives them from the nodes, so two PRs that each add a component merge in either order. Then runpnpm catalog. It needs the same codewatch CLI as a full regen (CODEWATCH_CLI=node <codewatch>/packages/cli/dist/index.js).
Storybook Configuration
This package uses Storybook 10 with @storybook/react-native-web-vite for proper NativeWind support. Key configuration:
// .storybook/main.ts
framework: {
name: '@storybook/react-native-web-vite',
options: {
pluginReactOptions: {
jsxImportSource: 'nativewind',
},
},
}See the Storybook Setup Guide for detailed configuration.
Cross-Platform Notes
React Native Primitives
All components use React Native primitives for cross-platform compatibility:
| Web Element | React Native Equivalent |
| ----------- | ----------------------- |
| div | View |
| span, p | Text |
| button | Pressable |
| input | TextInput |
| img | Image |
Platform-Specific Styles
Use NativeWind platform modifiers when needed:
<View className="p-4 web:hover:bg-gray-100 native:active:opacity-80">License
MIT
The /motion entry ports or follows MIT, BSD and Apache-2.0 licensed work, each noticed in a LICENSE* file beside
the code in src/components/ui/motion/: simplex-noise, Theatre.js, @remotion/paths and its sources, and
rough-notation with roughjs (the Annotate marks and roughLine / roughEllipse).
