@rific/auto-paper 0.7.0 → 0.9.0

package/src/components/AppearancePicker.tsx

@@ -2,15 +2,35 @@ import { SegmentedButtons } from 'react-native-paper'
 
 import type { ThemeAppearance } from '../useComputedTheme'
 
-const APPEARANCES: { label: string; value: ThemeAppearance; icon: string }[] = [
-  { label: 'System', value: 'system', icon: 'brightness-auto' },
-  { label: 'Light', value: 'light', icon: 'white-balance-sunny' },
-  { label: 'Dark', value: 'dark', icon: 'weather-night' }
+const APPEARANCES: { label: string; value: ThemeAppearance }[] = [
+  { label: 'System', value: 'system' },
+  { label: 'Light', value: 'light' },
+  { label: 'Dark', value: 'dark' }
 ]
 
+export type AppearanceIcons = Partial<Record<ThemeAppearance, string>>
+
+// 'monitor' (a plain device/screen glyph) reads more clearly as "match my device" than
+// 'brightness-auto' (an exposure/brightness symbol). Swap via the `icons` prop for a different
+// convention, e.g. `theme-light-dark`'s half-sun/half-moon.
+const DEFAULT_ICONS: Record<ThemeAppearance, string> = {
+  system: 'monitor',
+  light: 'white-balance-sunny',
+  dark: 'weather-night'
+}
+
 type Props = {
   value: ThemeAppearance
   onChange: (appearance: ThemeAppearance) => void
+  // Hides the text label, leaving just the icon per segment, useful in tight layouts where
+  // "System" truncates. accessibilityLabel is always set regardless, so screen readers still
+  // announce the full word either way.
+  showLabels?: boolean
+  // Per-value icon overrides, merged over DEFAULT_ICONS: pass just the ones you want to change.
+  icons?: AppearanceIcons
 }
 
-export const AppearancePicker = ({ value, onChange }: Props) => <SegmentedButtons value={value} onValueChange={(v) => onChange(v as ThemeAppearance)} buttons={APPEARANCES.map((a) => ({ value: a.value, label: a.label, icon: a.icon }))} />
+export const AppearancePicker = ({ value, onChange, showLabels = true, icons }: Props) => {
+  const resolvedIcons = { ...DEFAULT_ICONS, ...icons }
+  return <SegmentedButtons value={value} onValueChange={(v) => onChange(v as ThemeAppearance)} buttons={APPEARANCES.map((a) => ({ value: a.value, label: showLabels ? a.label : undefined, icon: resolvedIcons[a.value], accessibilityLabel: a.label }))} />
+}

package/src/components/BlurView.tsx

@@ -2,21 +2,26 @@ import { type ComponentType, type ReactNode, type RefObject, useContext } from '
 import { type StyleProp, StyleSheet, View, type ViewProps, type ViewStyle } from 'react-native'
 import { useTheme } from 'react-native-paper'
 
+import { useBlurModule } from '../ThemeProvider'
 import { ThemeSettingsContext } from '../ThemeSettingsContext'
 
-// Minimal local shape of expo-blur covering only the member used below — avoids forcing
+// Minimal local shape of expo-blur covering only the member used below: avoids forcing
 // TypeScript to resolve the optional peer's real types for consumers who never installed it.
-interface ExpoBlurModule {
+// tint is deliberately loose (not expo-blur's real narrow BlurTint union) so the real module
+// stays structurally assignable to `<Provider expoBlur={...}>` without importing its types -
+// this component only ever passes it 'dark'/'light', both valid BlurTint members at runtime.
+export interface ExpoBlurModule {
   BlurView: ComponentType<{
     children?: ReactNode
     style?: StyleProp<ViewStyle>
-    tint?: string
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    tint?: any
     [key: string]: unknown
   }>
 }
 
-// Local mirror of expo-blur's public BlurViewProps (node_modules/expo-blur/build/BlurView.types.d.ts)
-// — same reason as ExpoBlurModule above: the peer's real type must never be imported unconditionally.
+// Local mirror of expo-blur's public BlurViewProps (node_modules/expo-blur/build/BlurView.types.d.ts),
+// same reason as ExpoBlurModule above: the peer's real type must never be imported unconditionally.
 type ExpoBlurTint = 'light' | 'dark' | 'default' | 'extraLight' | 'regular' | 'prominent' | 'systemUltraThinMaterial' | 'systemThinMaterial' | 'systemMaterial' | 'systemThickMaterial' | 'systemChromeMaterial' | 'systemUltraThinMaterialLight' | 'systemThinMaterialLight' | 'systemMaterialLight' | 'systemThickMaterialLight' | 'systemChromeMaterialLight' | 'systemUltraThinMaterialDark' | 'systemThinMaterialDark' | 'systemMaterialDark' | 'systemThickMaterialDark' | 'systemChromeMaterialDark'
 type ExpoBlurMethod = 'none' | 'dimezisBlurView' | 'dimezisBlurViewSdk31Plus'
 type ExpoBlurViewProps = {
@@ -28,15 +33,6 @@ type ExpoBlurViewProps = {
   tint?: ExpoBlurTint
 } & ViewProps
 
-// expo-blur is an optional peer — when absent, BlurView renders its solid (non-blur) fallback
-const ExpoBlurView = (() => {
-  try {
-    return (require('expo-blur') as ExpoBlurModule).BlurView
-  } catch {
-    return null
-  }
-})()
-
 const ELEVATION_OPACITY: Record<number, number> = { 0: 0, 1: 0.05, 2: 0.08, 3: 0.11, 4: 0.12, 5: 0.14 }
 const VARIANT_TINT_OPACITY = { light: 0.12, dark: 0.18 }
 
@@ -53,18 +49,19 @@ export type BlurViewProps = ExpoBlurViewProps & {
 export const BlurView = ({ blur = true, children, elevation, style, tintColor, tintOpacity, variant = 'surface', ...props }: BlurViewProps) => {
   const { dark, colors } = useTheme()
   const { settings } = useContext(ThemeSettingsContext)
+  const expoBlur = useBlurModule()
   const surfaceColor = variant === 'surfaceVariant' ? colors.surfaceVariant : colors.surface
   const variantColor = variant === 'primary' ? colors.primary : variant === 'secondary' ? colors.secondary : variant === 'tertiary' ? colors.tertiary : variant === 'error' ? colors.error : undefined
   const resolvedTintColor = tintColor ?? variantColor ?? (elevation !== undefined ? colors.primary : undefined)
   const resolvedTintOpacity = tintOpacity ?? (tintColor ? (dark ? 0.24 : 0.16) : variantColor ? (dark ? VARIANT_TINT_OPACITY.dark : VARIANT_TINT_OPACITY.light) : elevation !== undefined ? ELEVATION_OPACITY[elevation] : 0)
   const tint = resolvedTintColor && resolvedTintOpacity > 0 ? <View style={[StyleSheet.absoluteFill, { backgroundColor: resolvedTintColor, opacity: resolvedTintOpacity }]} /> : null
-  if (blur && ExpoBlurView)
+  if (blur && expoBlur)
     return (
-      <ExpoBlurView {...props} tint={dark ? 'dark' : 'light'} style={style}>
+      <expoBlur.BlurView {...props} tint={dark ? 'dark' : 'light'} style={style}>
         <View style={[StyleSheet.absoluteFill, { backgroundColor: surfaceColor, opacity: settings.blurTint }]} />
         {tint}
         {children}
-      </ExpoBlurView>
+      </expoBlur.BlurView>
     )
   return (
     <View {...props} style={[{ backgroundColor: surfaceColor }, style]}>

package/src/components/BottomNavigation.tsx

@@ -2,20 +2,20 @@ import React, { useEffect } from 'react'
 import { Platform } from 'react-native'
 import { BottomNavigation as PaperBottomNavigation, type BottomNavigationProps, type BottomNavigationRoute, useTheme } from 'react-native-paper'
 
-import { navigationBar, setNavigationBarStyle } from '../navigation-bar'
+import { setNavigationBarStyle } from '../navigation-bar'
 import { usePaperDefaults } from '../PaperDefaultsContext'
 import { useNavBarContext } from '../ThemeProvider'
 
 function useNavigationBarSync() {
   const theme = useTheme()
-  const { onNavBarChange } = useNavBarContext()
+  const { navigationBar, onNavBarChange } = useNavBarContext()
   useEffect(() => {
     if (Platform.OS !== 'android') return
     // An explicit onNavBarChange callback takes full control; otherwise sync the
-    // nav bar icon style automatically when expo-navigation-bar is installed.
+    // nav bar icon style automatically when expo-navigation-bar was injected via <Provider>.
     if (onNavBarChange) onNavBarChange(theme.colors.surface, theme.dark)
-    else if (navigationBar) setNavigationBarStyle(theme.dark)
-  }, [theme, onNavBarChange])
+    else if (navigationBar) setNavigationBarStyle(navigationBar, theme.dark)
+  }, [theme, onNavBarChange, navigationBar])
 }
 
 function BottomNavigationComponent<Route extends BottomNavigationRoute>(props: BottomNavigationProps<Route>) {

package/src/components/ColorPicker.tsx

@@ -1,9 +1,10 @@
 import { useState } from 'react'
 import { StyleSheet, TouchableOpacity, View } from 'react-native'
-import { Icon, TouchableRipple } from 'react-native-paper'
+import { Icon, TouchableRipple, useTheme } from 'react-native-paper'
 
 import { useBlur } from '../BlurContext'
 import { SWATCH_GRID_GAP, useSwatchSize } from '../useSwatchGrid'
+import { getContrastColor, getSwatchRing } from '../utils/getSwatchContrast'
 import { Dialog } from './Dialog'
 
 const SIZE = 48
@@ -42,13 +43,14 @@ type Props = {
 
 export const ColorPicker = ({ value, onChange, colors = defaultColors, blur: blurProp }: Props) => {
   const blur = useBlur(blurProp)
+  const { colors: themeColors } = useTheme()
   const [open, setOpen] = useState(false)
   const { onLayout, size } = useSwatchSize(SIZE)
 
   return (
     <>
-      <TouchableRipple onPress={() => setOpen(true)} style={[styles.trigger, { backgroundColor: value }]} borderless>
-        <Icon source='palette' size={20} color='white' />
+      <TouchableRipple onPress={() => setOpen(true)} style={[styles.trigger, { backgroundColor: value }, getSwatchRing(value, false, themeColors.outlineVariant)]} borderless>
+        <Icon source='palette' size={20} color={getContrastColor(value)} />
       </TouchableRipple>
 
       <Dialog blur={blur} visible={open} onDismiss={() => setOpen(false)}>
@@ -61,9 +63,9 @@ export const ColorPicker = ({ value, onChange, colors = defaultColors, blur: blu
                   onChange(hex)
                   setOpen(false)
                 }}
-                style={[styles.swatch, { backgroundColor: hex, borderRadius: size / 2, height: size, width: size }, value === hex && styles.selected]}
+                style={[styles.swatch, { backgroundColor: hex, borderRadius: size / 2, height: size, width: size }, getSwatchRing(hex, value === hex, themeColors.outlineVariant)]}
               >
-                {value === hex && <Icon source='check' size={20} color='white' />}
+                {value === hex && <Icon source='check' size={20} color={getContrastColor(hex)} />}
               </TouchableOpacity>
             ))}
           </View>
@@ -74,7 +76,6 @@ export const ColorPicker = ({ value, onChange, colors = defaultColors, blur: blu
 }
 
 const styles = StyleSheet.create({
-  selected: { borderColor: 'white', borderWidth: 3 },
   swatch: { alignItems: 'center', justifyContent: 'center' },
   swatches: { flexDirection: 'row', flexWrap: 'wrap', gap: SWATCH_GRID_GAP, paddingTop: 12 },
   trigger: { alignItems: 'center', alignSelf: 'flex-start', borderRadius: SIZE / 2, height: SIZE, justifyContent: 'center', width: SIZE }

package/src/components/PalettePicker.tsx

@@ -1,9 +1,10 @@
 import { useState } from 'react'
 import { StyleSheet, TouchableOpacity, View } from 'react-native'
-import { Icon, TouchableRipple } from 'react-native-paper'
+import { Icon, TouchableRipple, useTheme } from 'react-native-paper'
 
 import { useBlur } from '../BlurContext'
 import { SWATCH_GRID_GAP, useSwatchSize } from '../useSwatchGrid'
+import { getContrastColor, getSwatchRing } from '../utils/getSwatchContrast'
 import type { ColorHarmony, TriadicPalette } from '../utils/getTriadicPalette'
 import { getTriadicPalette } from '../utils/getTriadicPalette'
 import type { SeedColor } from './ColorPicker'
@@ -18,9 +19,9 @@ const defaultWeights: PaletteWeights = { primary: 2, secondary: 1, tertiary: 1 }
 
 // Each wedge = a static right-half mask, doubly rotated: an outer spin positions the slice's
 // leading edge around the circle, then an inner spin (its own share, minus 180deg) carves the
-// trailing edge — together covering exactly `share` of weights' total, for any share <= 50%.
+// trailing edge, together covering exactly `share` of weights' total, for any share <= 50%.
 // Both rotators are sized to exactly overlap the full circle so React Native's default
-// (own-center) rotation pivot is already correct — transformOrigin is intentionally avoided
+// (own-center) rotation pivot is already correct; transformOrigin is intentionally avoided
 // since it isn't reliably honored across RN renderers. Primary is centered at 12 o'clock,
 // tertiary fills clockwise from there (bottom-right), secondary fills the remainder (bottom-left).
 const buildWedges = (weights: PaletteWeights) => {
@@ -61,6 +62,7 @@ type Props = {
 
 export const PalettePicker = ({ value, onChange, harmony = 'split-complementary', weights, colors = defaultColors, blur: blurProp }: Props) => {
   const blur = useBlur(blurProp)
+  const { colors: themeColors } = useTheme()
   const [open, setOpen] = useState(false)
   const { onLayout, size } = useSwatchSize(SIZE)
 
@@ -69,8 +71,8 @@ export const PalettePicker = ({ value, onChange, harmony = 'split-complementary'
       <TouchableRipple onPress={() => setOpen(true)} style={styles.trigger} borderless>
         <View style={styles.triggerContent}>
           <Pie palette={getTriadicPalette(value, harmony)} weights={weights} />
-          <View pointerEvents='none' style={styles.triggerIcon}>
-            <Icon source='palette' size={20} color='white' />
+          <View pointerEvents='none' style={[styles.triggerIcon, { borderRadius: SIZE / 2 }, getSwatchRing(value, false, themeColors.outlineVariant)]}>
+            <Icon source='palette' size={20} color={getContrastColor(value)} />
           </View>
         </View>
       </TouchableRipple>
@@ -88,11 +90,9 @@ export const PalettePicker = ({ value, onChange, harmony = 'split-complementary'
                 style={[styles.swatch, { height: size, width: size }]}
               >
                 <Pie palette={getTriadicPalette(hex, harmony)} weights={weights} size={size} />
-                {value === hex && (
-                  <View pointerEvents='none' style={[styles.selectedRing, { borderRadius: size / 2 }]}>
-                    <Icon source='check' size={20} color='white' />
-                  </View>
-                )}
+                <View pointerEvents='none' style={[styles.ring, { borderRadius: size / 2 }, getSwatchRing(hex, value === hex, themeColors.outlineVariant)]}>
+                  {value === hex && <Icon source='check' size={20} color={getContrastColor(hex)} />}
+                </View>
               </TouchableOpacity>
             ))}
           </View>
@@ -107,7 +107,7 @@ const styles = StyleSheet.create({
   innerRotator: { height: '100%', left: '-100%', overflow: 'hidden', position: 'absolute', top: 0, width: '200%' },
   pie: { overflow: 'hidden' },
   rotator: { height: '100%', left: 0, overflow: 'hidden', position: 'absolute', top: 0, width: '100%' },
-  selectedRing: { alignItems: 'center', borderColor: 'white', borderWidth: 3, bottom: 0, justifyContent: 'center', left: 0, position: 'absolute', right: 0, top: 0 },
+  ring: { alignItems: 'center', bottom: 0, justifyContent: 'center', left: 0, position: 'absolute', right: 0, top: 0 },
   swatch: { alignItems: 'center', justifyContent: 'center' },
   swatches: { flexDirection: 'row', flexWrap: 'wrap', gap: SWATCH_GRID_GAP, paddingTop: 12 },
   trigger: { alignItems: 'center', alignSelf: 'flex-start', borderRadius: SIZE / 2, height: SIZE, justifyContent: 'center', width: SIZE },

package/src/index.ts

@@ -1,7 +1,8 @@
 export { useBlur } from './BlurContext'
 export { Appbar } from './components/Appbar'
+export type { AppearanceIcons } from './components/AppearancePicker'
 export { AppearancePicker } from './components/AppearancePicker'
-export type { BlurViewProps } from './components/BlurView'
+export type { BlurViewProps, ExpoBlurModule } from './components/BlurView'
 export { BlurView } from './components/BlurView'
 export { BottomNavigation } from './components/BottomNavigation'
 export { Button } from './components/Button'
@@ -20,21 +21,27 @@ export { Menu } from './components/Menu'
 export type { PaletteWeights } from './components/PalettePicker'
 export { PalettePicker } from './components/PalettePicker'
 export { TextInput } from './components/TextInput'
+export type { ExpoNavigationBarModule } from './navigation-bar'
 export type { PaperDefaults } from './PaperDefaultsContext'
 export { usePaperDefaults } from './PaperDefaultsContext'
 export type { ThemeState } from './redux/themeSlice'
 export { createThemeReducer, selectThemeAppearance, selectThemeBlur, selectThemeColor, selectThemeHarmony, themeActions, themeReducer } from './redux/themeSlice'
 export type { ProviderProps } from './ThemeProvider'
-export { Provider } from './ThemeProvider'
+export { Provider, useBlurModule, useNavBarContext } from './ThemeProvider'
 export type { ThemeSettings, ThemeSettingsContextType } from './ThemeSettingsContext'
 export { defaultThemeSettings, ThemeSettingsContext } from './ThemeSettingsContext'
-export type { ThemeAppearance } from './useComputedTheme'
-export { useComputedTheme } from './useComputedTheme'
+export type { AutoPaperTheme, SemanticColorRoles, ThemeAppearance } from './useComputedTheme'
+export { SEMANTIC_BASE_COLORS, useComputedTheme } from './useComputedTheme'
+export { useAutoPaperTheme } from './useTheme'
 export { useThemeSettings } from './useThemeSettings'
 export { getBlendedColor } from './utils/getBlendedColor'
+export type { ColorRoles } from './utils/getColorRoles'
+export { getColorRoles } from './utils/getColorRoles'
 export { getHex } from './utils/getHex'
 export type { RGB } from './utils/getRgb'
 export { getRgb } from './utils/getRgb'
+export { getContrastColor } from './utils/getSwatchContrast'
+export { getThirdColor } from './utils/getThirdColor'
 export { getTintTextColor } from './utils/getTintTextColor'
 export { getTonalColor } from './utils/getTonalColor'
 export type { ColorHarmony, TriadicPalette } from './utils/getTriadicPalette'

package/src/navigation-bar.ts

@@ -1,22 +1,14 @@
-// Minimal local shape of expo-navigation-bar covering only the members used below —
+// Minimal local shape of expo-navigation-bar covering only the members used below:
 // avoids forcing TypeScript to resolve the optional peer's real types for consumers
 // who never installed it.
-interface ExpoNavigationBarModule {
+export interface ExpoNavigationBarModule {
   NavigationBar: {
     setStyle: (style: 'light' | 'dark') => void
   }
 }
 
-export const navigationBar = (() => {
-  try {
-    return require('expo-navigation-bar') as ExpoNavigationBarModule
-  } catch {
-    return null
-  }
-})()
-
 /** Sets the Android navigation bar icon style (expo-navigation-bar >= 56, edge-to-edge API). */
-export const setNavigationBarStyle = (dark: boolean) => {
+export const setNavigationBarStyle = (navigationBar: ExpoNavigationBarModule | undefined, dark: boolean) => {
   if (!navigationBar) return
   navigationBar.NavigationBar.setStyle(dark ? 'light' : 'dark')
 }

package/src/redux/themeSlice.ts

@@ -1,12 +1,12 @@
 import { ThemeAppearance } from '../useComputedTheme'
-import type { ColorHarmony } from '../utils/getTriadicPalette'
+import type { ColorHarmony, TriadicPalette } from '../utils/getTriadicPalette'
 
 export type { ThemeAppearance }
 
 export type ThemeState = {
   appearance: ThemeAppearance
   blur: boolean
-  color: string
+  color: string | TriadicPalette
   harmony: ColorHarmony
 }
 
@@ -17,7 +17,7 @@ const defaultInitialState: ThemeState = {
   harmony: 'split-complementary'
 }
 
-// Hand-rolled slice — no @reduxjs/toolkit dependency. Action types and creator
+// Hand-rolled slice (no @reduxjs/toolkit dependency). Action types and creator
 // behavior match the previous createSlice implementation exactly, so this works
 // with RTK stores, vanilla Redux, or any reducer-based state container.
 type PayloadAction<P> = { payload: P; type: string }
@@ -32,7 +32,7 @@ const createAction = <P>(type: string) => {
 const initialize = createAction<Partial<ThemeState>>('theme/initialize')
 const setAppearance = createAction<ThemeAppearance>('theme/setAppearance')
 const setBlur = createAction<boolean>('theme/setBlur')
-const setColor = createAction<string>('theme/setColor')
+const setColor = createAction<string | TriadicPalette>('theme/setColor')
 const setHarmony = createAction<ColorHarmony>('theme/setHarmony')
 
 export const themeActions = { initialize, setAppearance, setBlur, setColor, setHarmony }

package/src/useComputedTheme.ts

@@ -3,54 +3,134 @@ import { Appearance } from 'react-native'
 import { MD3DarkTheme, MD3LightTheme, MD3Theme } from 'react-native-paper'
 
 import { getBlendedColor } from './utils/getBlendedColor'
-import { getTonalColor } from './utils/getTonalColor'
-import { type ColorHarmony, getTriadicPalette } from './utils/getTriadicPalette'
-import { isDarkColor } from './utils/isDarkColor'
+import { getColorRoles } from './utils/getColorRoles'
+import { getHex } from './utils/getHex'
+import { getRgb } from './utils/getRgb'
+import { type ColorHarmony, getTriadicPalette, type TriadicPalette } from './utils/getTriadicPalette'
+
+function normalizeExplicitColor(value: string): string {
+  if (!getRgb(value)) throw new Error(`Invalid color format: ${value}`)
+  return getHex(value) ?? value
+}
 
 export type ThemeAppearance = 'system' | 'light' | 'dark'
 
-export function useComputedTheme(appearance: ThemeAppearance, color: string, harmony: ColorHarmony = 'split-complementary'): MD3Theme | null {
-  const [theme, setTheme] = useState<MD3Theme | null>(null)
+// Fixed hue/saturation, like MD3's own `error` role (see LightTheme.tsx/DarkTheme.tsx: error is a
+// static Material palette constant, never derived from the seed color either). A "warning" amber
+// shouldn't drift toward the app's accent hue any more than the built-in danger red does; only
+// lightness adapts per light/dark mode below, via getColorRoles. #A15C00 (not the more obvious
+// goldenrod #B8860B) was picked because its onWarning text fails WCAG AA (3.05:1) against the base
+// color itself; see getColorRoles.test.ts's "onColor" caveat: the onColor heuristic (isDarkColor-
+// based binary lightness pick) isn't a verified guarantee like onContainer is, so the base hex
+// itself has to be chosen to land safely, not assumed to.
+//
+// `danger` is deliberately a separate namespace from MD3's own `error` (below, untouched) rather
+// than a fourth tier folded into it: react-native-paper's own components (TextInput's error state,
+// HelperText, Badge) read theme.colors.error/onError directly, so a consumer that wants a
+// getColorRoles-derived "high severity" color without changing what those components render needs
+// its own name. #B00020 already clears WCAG AA for both onDanger-vs-danger (6.16:1) and
+// dangerContainer/onDangerContainer (12–17:1 across modes), verified the same way as warning's
+// base above.
+export const SEMANTIC_BASE_COLORS = {
+  success: '#2E7D32',
+  warning: '#A15C00',
+  danger: '#B00020'
+}
+
+export type SemanticColorRoles = {
+  success: string
+  onSuccess: string
+  successContainer: string
+  onSuccessContainer: string
+  warning: string
+  onWarning: string
+  warningContainer: string
+  onWarningContainer: string
+  danger: string
+  onDanger: string
+  dangerContainer: string
+  onDangerContainer: string
+}
+
+// MD3Theme's `colors` is a closed `type` (not an `interface`), so it can't be widened via
+// TypeScript's declare-module augmentation: this is the extension point instead, meant to be used
+// with react-native-paper's own `useTheme<T>()` generic (see useTheme.ts's useAutoPaperTheme).
+export type AutoPaperTheme = Omit<MD3Theme, 'colors'> & { colors: MD3Theme['colors'] & SemanticColorRoles }
+
+export function useComputedTheme(appearance: ThemeAppearance, color: string | TriadicPalette, harmony: ColorHarmony = 'split-complementary'): AutoPaperTheme | null {
+  const [theme, setTheme] = useState<AutoPaperTheme | null>(null)
+
+  // Destructured to primitives (rather than depending on `color` itself below) so that passing a
+  // fresh `{ primary, secondary, tertiary }` object literal inline on every render, the natural
+  // way to use this mode, doesn't retrigger computeTheme unless a field actually changed.
+  const primaryInput = typeof color === 'string' ? color : color.primary
+  const secondaryInput = typeof color === 'string' ? null : color.secondary
+  const tertiaryInput = typeof color === 'string' ? null : color.tertiary
 
   const computeTheme = useCallback(() => {
     let resolved: string | null | undefined = appearance
     if (resolved === 'system') resolved = Appearance.getColorScheme()
     if (resolved === 'no-preference' || !resolved) resolved = 'light'
     const base = resolved === 'dark' ? MD3DarkTheme : MD3LightTheme
+    const surface = base.colors.surface
 
-    const _theme: MD3Theme = {
+    // error/onError/errorContainer/onErrorContainer are deliberately left untouched below (not run
+    // through getColorRoles like success/warning/primary/secondary/tertiary are): they're a fixed,
+    // Google-verified Material palette that react-native-paper's own components (TextInput's error
+    // state, HelperText, Badge) read directly, so re-deriving them would change form-validation
+    // colors across every consuming app and risk diverging from a contrast guarantee that's already
+    // correct as shipped.
+    const successRoles = getColorRoles(SEMANTIC_BASE_COLORS.success, surface)
+    const warningRoles = getColorRoles(SEMANTIC_BASE_COLORS.warning, surface)
+    const dangerRoles = getColorRoles(SEMANTIC_BASE_COLORS.danger, surface)
+
+    const _theme: AutoPaperTheme = {
       ...base,
       colors: {
         ...base.colors,
-        elevation: { ...base.colors.elevation }
+        elevation: { ...base.colors.elevation },
+        success: successRoles.color,
+        onSuccess: successRoles.onColor,
+        successContainer: successRoles.container,
+        onSuccessContainer: successRoles.onContainer,
+        warning: warningRoles.color,
+        onWarning: warningRoles.onColor,
+        warningContainer: warningRoles.container,
+        onWarningContainer: warningRoles.onContainer,
+        danger: dangerRoles.color,
+        onDanger: dangerRoles.onColor,
+        dangerContainer: dangerRoles.container,
+        onDangerContainer: dangerRoles.onContainer
       }
     }
 
-    const palette = getTriadicPalette(color, harmony)
-    const surface = base.colors.surface
+    const palette: TriadicPalette = secondaryInput !== null && tertiaryInput !== null ? { primary: normalizeExplicitColor(primaryInput), secondary: normalizeExplicitColor(secondaryInput), tertiary: normalizeExplicitColor(tertiaryInput) } : getTriadicPalette(primaryInput, harmony)
 
-    _theme.colors.primary = palette.primary
-    _theme.colors.onPrimary = getTonalColor(palette.primary, isDarkColor(palette.primary) ? 0.95 : 0.08)
-    _theme.colors.primaryContainer = getBlendedColor(palette.primary, surface, 0.15)
-    _theme.colors.onPrimaryContainer = getTonalColor(palette.primary, isDarkColor(_theme.colors.primaryContainer) ? 0.92 : 0.12)
+    const primaryRoles = getColorRoles(palette.primary, surface)
+    _theme.colors.primary = primaryRoles.color
+    _theme.colors.onPrimary = primaryRoles.onColor
+    _theme.colors.primaryContainer = primaryRoles.container
+    _theme.colors.onPrimaryContainer = primaryRoles.onContainer
 
-    _theme.colors.secondary = palette.secondary
-    _theme.colors.onSecondary = getTonalColor(palette.secondary, isDarkColor(palette.secondary) ? 0.95 : 0.08)
-    _theme.colors.secondaryContainer = getBlendedColor(palette.secondary, surface, 0.15)
-    _theme.colors.onSecondaryContainer = getTonalColor(palette.secondary, isDarkColor(_theme.colors.secondaryContainer) ? 0.92 : 0.12)
+    const secondaryRoles = getColorRoles(palette.secondary, surface)
+    _theme.colors.secondary = secondaryRoles.color
+    _theme.colors.onSecondary = secondaryRoles.onColor
+    _theme.colors.secondaryContainer = secondaryRoles.container
+    _theme.colors.onSecondaryContainer = secondaryRoles.onContainer
 
-    _theme.colors.tertiary = palette.tertiary
-    _theme.colors.onTertiary = getTonalColor(palette.tertiary, isDarkColor(palette.tertiary) ? 0.95 : 0.08)
-    _theme.colors.tertiaryContainer = getBlendedColor(palette.tertiary, surface, 0.15)
-    _theme.colors.onTertiaryContainer = getTonalColor(palette.tertiary, isDarkColor(_theme.colors.tertiaryContainer) ? 0.92 : 0.12)
+    const tertiaryRoles = getColorRoles(palette.tertiary, surface)
+    _theme.colors.tertiary = tertiaryRoles.color
+    _theme.colors.onTertiary = tertiaryRoles.onColor
+    _theme.colors.tertiaryContainer = tertiaryRoles.container
+    _theme.colors.onTertiaryContainer = tertiaryRoles.onContainer
 
-    const blended = getBlendedColor(color, palette.secondary, 0.5)
+    const blended = getBlendedColor(palette.primary, palette.secondary, 0.5)
     const tintSurface = (alpha: number) => getBlendedColor(blended, surface, alpha)
 
     _theme.colors.background = base.dark ? '#0F0F0F' : '#F0F0F0'
     _theme.colors.surface = surface
     _theme.colors.surfaceVariant = tintSurface(0.2)
-    _theme.colors.outline = getBlendedColor(color, base.colors.outline, 0.45)
+    _theme.colors.outline = getBlendedColor(palette.primary, base.colors.outline, 0.45)
 
     const grey = base.dark ? '#424242' : '#c2c2c2'
     const blendedGrey = getBlendedColor(blended, grey, 0.05)
@@ -64,7 +144,7 @@ export function useComputedTheme(appearance: ThemeAppearance, color: string, har
     }
 
     setTheme(_theme)
-  }, [appearance, color, harmony])
+  }, [appearance, primaryInput, secondaryInput, tertiaryInput, harmony])
 
   useEffect(() => {
     computeTheme()

package/src/useSwatchGrid.ts

@@ -2,7 +2,7 @@ import { useState } from 'react'
 import type { LayoutChangeEvent } from 'react-native'
 
 // Fixed column count so the swatch grid always fills complete rows, regardless of dialog width
-// (phone vs tablet vs web) — sizing the swatches to fit, rather than wrapping fixed-size swatches
+// (phone vs tablet vs web): sizing the swatches to fit, rather than wrapping fixed-size swatches
 // and hoping the total divides evenly into whatever column count the width happens to produce.
 export const SWATCH_GRID_COLUMNS = 5
 export const SWATCH_GRID_GAP = 12

package/src/useTheme.ts

@@ -0,0 +1,11 @@
+import { useTheme as usePaperTheme } from 'react-native-paper'
+
+import type { AutoPaperTheme } from './useComputedTheme'
+
+// react-native-paper's own useTheme is generic (`useTheme<T = MD3Theme>()`) specifically so
+// consumers can extend MD3Theme with their own fields: this is that extension point, so any
+// component can read theme.colors.success/warning (and their onX/Container variants) with full
+// type safety, without redeclaring the type parameter at every call site. Named distinctly from
+// react-native-paper's own `useTheme` (not re-exported under the same name) to avoid the two being
+// silently interchangeable at an import statement.
+export const useAutoPaperTheme = (): AutoPaperTheme => usePaperTheme<AutoPaperTheme>()

package/src/utils/getColorRoles.ts

@@ -0,0 +1,29 @@
+import { getBlendedColor } from './getBlendedColor'
+import { getTonalColor } from './getTonalColor'
+import { isDarkColor } from './isDarkColor'
+
+export type ColorRoles = {
+  color: string
+  onColor: string
+  container: string
+  onContainer: string
+}
+
+// The MD3 "color / onColor / container / onContainer" quadruple, generalized from the math
+// useComputedTheme already uses for primary/secondary/tertiary: onColor is tuned to sit on the
+// vivid color itself, container is base blended toward the theme's real surface (so it inherits
+// that surface's actual lightness rather than a fixed light/dark guess), and onContainer is tuned
+// against the *computed* container rather than a light/dark assumption, so it stays readable
+// whatever surface color it's handed. onContainer also reads safely directly on `surface` itself
+// (not just on `container`), since container is only lightly blended toward it.
+export const getColorRoles = (base: string, surface: string, containerAlpha = 0.15): ColorRoles => {
+  const container = getBlendedColor(base, surface, containerAlpha)
+  return {
+    color: base,
+    onColor: getTonalColor(base, isDarkColor(base) ? 0.95 : 0.08),
+    container,
+    onContainer: getTonalColor(base, isDarkColor(container) ? 0.92 : 0.12)
+  }
+}
+
+export default getColorRoles

package/src/utils/getSwatchContrast.ts

@@ -0,0 +1,26 @@
+import { isDarkColor } from './isDarkColor'
+
+// Width of the outline every swatch carries so its edge is defined against the surface behind it.
+const RING_WIDTH = 1
+// The selected swatch trades that outline for a thicker one in a contrasting colour.
+const SELECTED_RING_WIDTH = 3
+
+// Colour for content sitting directly on a fill of `color` (a check mark or a 20px icon). Plain
+// white/black rather than a tinted tone from getTonalColor, because this has to stay legible on
+// fully saturated fills and on pure black/white alike.
+export const getContrastColor = (color: string): string => (isDarkColor(color) ? '#ffffff' : '#000000')
+
+// Two different jobs, which is why the unselected and selected rings resolve against different
+// things:
+//
+// - Unselected: separate the swatch from the *surface* it sits on. A white swatch on a light
+//   dialog and a black swatch on a dark one are otherwise edgeless: invisible, not just subtle.
+//   The theme's outline colour tracks the surface, so it works in both appearances.
+// - Selected: read as a marker against the *swatch's own fill*. A hardcoded white ring vanished on
+//   the white swatch, so picking white gave no feedback that anything had been picked.
+export const getSwatchRing = (color: string, selected: boolean, outlineColor: string) => ({
+  borderColor: selected ? getContrastColor(color) : outlineColor,
+  borderWidth: selected ? SELECTED_RING_WIDTH : RING_WIDTH
+})
+
+export default getContrastColor