Theming Guide: MD3 to NativeWind Migration

Status: Active - use for Phase 2+ component migrations.

Goals

• Preserve MD3 color semantics while moving to NativeWind classes.
• Keep tokens centralized and consistent across apps.
• Align legacy palettes with the gluestack token set.

Source Of Truth (Current)

• apps/scl/scl-mobile/src/app/App.tsx (SCL MD3 overrides)
• apps/messaging/messaging_mobile/src/app/theme/ThemeProvider.tsx (default MD3 light/dark)
• apps/teetime/teetime-country-club/src/core/App.tsx (default MD3)
• apps/teetime/teetime-mobile/src/core/App.tsx (palette validation view)
• libs/ui/gluestack-ui/src/theme/tokens.ts (baseline token set)
• libs/ui/gluestack-ui/src/theme/tailwind.config.js (shared theme defaults)
• libs/ui/tee-time-ui-mobile/src/lib/theme/tokens.ts (TeeTime palette)
• apps/*/tailwind.config.js (per-app overrides)

Migration Principle

Use a single Gluestack provider and keep palette values aligned with legacy MD3 colors via Tailwind tokens:

import { DigiwedgeUIProvider } from '@digiwedge/gluestack-ui';

<DigiwedgeUIProvider>{children}</DigiwedgeUIProvider>

Gluestack/NativeWind components should use Tailwind classes backed by the same color values as the legacy MD3 palette.

Token Mapping (MD3 -> NativeWind)

MD3 Token	Tailwind Token / Class	Notes
primary	primary-500	Main brand color
onPrimary	text-white or primary-50	Choose contrast
primaryContainer	primary-100	Light container
onPrimaryContainer	text-primary-900	Contrast on container
secondary	secondary-500	Accent color
secondaryContainer	secondary-100	Light accent
tertiary	tertiary-500	Optional
tertiaryContainer	tertiary-100	Optional
background	background	App background
surface	surface	Cards/sheets
surfaceVariant	surface-variant	Optional
error	error-500	Error color
errorContainer	error-100	Optional
outline	outline	Borders/dividers
onBackground	text-foreground	Define if needed

If a token is used in Paper but not present in Tailwind, add it to apps/<app>/tailwind.config.js under theme.extend.colors.

Per-App Overrides

TeeTime Mobile (priority)

TeeTime Mobile uses the green brand palette centralized in libs/ui/tee-time-ui-mobile/src/lib/theme/tokens.ts. Mirror those values into apps/teetime/teetime-mobile/tailwind.config.js:

• Primary: #6aae43
• Primary light: #f8ffea
• Special/secondary: #1e3a5f
• Warning: #fbc02d
• Neutrals: #3f4739, #30323d, #274156, #f3f8f2, #e0e0e0

If a screen relies on a hard-coded color, prefer mapping it to a Tailwind token and using classes instead of inline hex values.

SCL (custom MD3 theme)

SCL overrides MD3 colors in apps/scl/scl-mobile/src/app/App.tsx. Mirror those values into apps/scl/scl-mobile/tailwind.config.js so Paper and Gluestack render consistently.

Example:

extend: {
  colors: {
    primary: { 500: '#0ea5e9', 100: '#e0f2fe' },
    secondary: { 500: '#f59e0b', 100: '#fef3c7' },
    tertiary: { 500: '#6366f1', 100: '#e0e7ff' },
    error: { 500: '#dc2626', 100: '#fee2e2' },
    background: '#f8fafc',
    surface: '#ffffff',
    surfaceVariant: '#f1f5f9',
    outline: '#94a3b8',
  },
},

Messaging + TeeTime CC

Messaging uses the default gluestack tokens. TeeTime Country Club mirrors the TeeTime palette in apps/teetime/teetime-country-club/tailwind.config.js. Use baseline tokens from libs/ui/gluestack-ui/src/theme/tokens.ts until brand-specific overrides are introduced.

Typography + Spacing

Use Gluestack defaults for now. If we need to mirror MD3 typography or spacing, add tokens in tailwind.config.js under theme.extend and align with existing MD3 usage in the affected screens.

Dark Mode

NativeWind is configured with darkMode: 'class'. When we add runtime theme switching, set the root class to dark (or use NativeWind's useColorScheme helpers) and provide dark equivalents for tokens.

Notes

• Keep nativewind-env.d.ts auto-generated files. They are expected.
• Avoid TypeScript path aliases; use workspace deps only.