npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@titan-design/react-ui

v0.23.1

Published

Cross-platform design system built on Gluestack UI

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-ui

Peer Dependencies

# For web
pnpm add react react-dom react-native-web lucide-react

# For React Native
pnpm add react react-native lucide-react-native

Setup

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:

  1. npm install react-native-web and npm install -D tailwindcss autoprefixer postcss nativewind (nativewind is needed only at build time, by the titan preset)
  2. Add resolve.alias: { 'react-native': 'react-native-web' } to your Vite config
  3. 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. Reaches react-native-body-highlighter (and transitively react-native-svg) — install both as peer dependencies if you import from this subpath.

    For a web build via Vite, react-native-body-highlighter ships untranspiled JSX in a CommonJS dist that neither Rollup nor Vite's default transform can parse, and its own require('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 in packages/ui/vite-rn-svg-plugins.ts: one that resolves react-native-svg's relative imports to their .web.js siblings (Node resolvers don't honor RN's platform-extension convention), and one that pre-bundles react-native-body-highlighter to a single ESM module with esbuild (jsx: 'automatic', react-native-svg aliased to its web entry, react left external). That esbuild pass needs an explicit require shim banner — a small snippet defining a require(id) that returns React for "react" and throws otherwise — because esbuild's own dynamic-require helper only throws when nothing supplies require, and a plain vite build bundle 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 /bodymap for web needs the same two plugins; see packages/ui/vite-rn-svg-plugins.ts in 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, a MotionProvider on a seekClock publishes window.__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-* vs status-* 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 bare border utility sets borderColor: currentColor (often black), which overrides the token color unreliably. Use style={{ 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 storybook

Open http://localhost:6006 to view component documentation.

Testing

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

Story audit

pnpm audit:stories

Audits the stories your diff touches for overflow, clipping and contrast; see docs/audit-stories.md.

Build

pnpm build

Guardrails

  • pnpm lint enforces that every Storybook story's title starts with an approved top-level group (Foundations, Components, Custom, Shell, Pages, Lab, Docs — see eslint-rules/story-title-prefix.js), so a new story can't invent an unlisted sidebar root.
  • pnpm test runs src/arch/arch-graph.freshness.test.ts, which fails CI when a .tsx file the ui, custom or shell barrels re-export has no node in src/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/cli CLI (unpublished, see AW-118) and sibling checkouts of every consumer in scripts/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 with pnpm arch:graph -- --reindex in a commit of its own so the diff stays reviewable. src/arch/component-catalog.json derives from arch-graph.json, so run pnpm catalog after 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 --add for 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.ts derives them from the nodes, so two PRs that each add a component merge in either order. Then run pnpm 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).