@rific/auto-paper 0.6.4 → 0.8.0

package/src/components/Dialog.tsx

@@ -1,47 +1,83 @@
 import React, { useEffect, useRef, useState } from 'react'
-import { Animated, StyleSheet, TouchableWithoutFeedback, View } from 'react-native'
+import { Animated, BackHandler, Easing, Pressable, type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native'
 import { Dialog as PaperDialog, type DialogActionsProps, type DialogContentProps, type DialogProps as PaperDialogProps, type DialogScrollAreaProps, type DialogTitleProps, Portal, useTheme } from 'react-native-paper'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
 
 import { useBlur } from '../BlurContext'
 import { BlurView } from './BlurView'
 
-export type DialogProps = PaperDialogProps & {
+// `style` is narrowed to a plain ViewStyle: unlike react-native-paper's Dialog, the surface here is
+// never wrapped in Animated.View, so it can't drive an Animated-value style the way upstream's can.
+export type DialogProps = Omit<PaperDialogProps, 'style'> & {
   blur?: boolean
+  style?: StyleProp<ViewStyle>
 }
 
-function DialogComponent({ blur: blurProp, visible, onDismiss, children, style, ...rest }: DialogProps) {
+// Matches react-native-paper's Modal: DEFAULT_DURATION * theme.animation.scale, eased the same way,
+// so toggling blur never changes how the dialog animates in/out.
+const ANIMATION_DURATION = 220
+
+// Minimum breathing room between the card and the screen edge, clamped up from safe-area insets.
+const DIALOG_MARGIN = 32
+
+function DialogComponent({ blur: blurProp, dismissable = true, dismissableBackButton = dismissable, visible, onDismiss, children, style, testID = 'dialog' }: DialogProps) {
   const blur = useBlur(blurProp)
-  const { roundness, colors } = useTheme()
-  const opacity = useRef(new Animated.Value(0)).current
+  const theme = useTheme()
+  const { colors, isV3, roundness } = theme
+  const { scale } = theme.animation
+  const { bottom, left, right, top } = useSafeAreaInsets()
+  const opacity = useRef(new Animated.Value(visible ? 1 : 0)).current
   const [mounted, setMounted] = useState(visible)
 
   useEffect(() => {
     if (visible) {
       setMounted(true)
-      Animated.timing(opacity, { toValue: 1, duration: 200, useNativeDriver: true }).start()
+      Animated.timing(opacity, { duration: scale * ANIMATION_DURATION, easing: Easing.out(Easing.cubic), toValue: 1, useNativeDriver: true }).start()
     } else {
-      Animated.timing(opacity, { toValue: 0, duration: 150, useNativeDriver: true }).start(() => setMounted(false))
+      Animated.timing(opacity, { duration: scale * ANIMATION_DURATION, easing: Easing.out(Easing.cubic), toValue: 0, useNativeDriver: true }).start(({ finished }) => {
+        if (finished) setMounted(false)
+      })
     }
   }, [visible])
 
-  if (!blur) {
-    return (
-      <PaperDialog visible={visible} onDismiss={onDismiss} style={[styles.sized, style]} {...rest}>
-        {children}
-      </PaperDialog>
-    )
-  }
+  useEffect(() => {
+    if (!visible) return undefined
+    const onHardwareBackPress = () => {
+      if (dismissable || dismissableBackButton) onDismiss?.()
+      return true
+    }
+    const subscription = BackHandler.addEventListener('hardwareBackPress', onHardwareBackPress)
+    return () => subscription.remove()
+  }, [dismissable, dismissableBackButton, onDismiss, visible])
 
   if (!mounted) return null
 
+  // Mirrors react-native-paper's own Dialog: the first child gets extra top spacing so the
+  // header sits the same distance from the edge whether the surface is blurred or solid.
+  const content = React.Children.toArray(children)
+    .filter((child) => child != null && typeof child !== 'boolean')
+    .map((child, i) => {
+      if (isV3) {
+        if (i === 0 && React.isValidElement<DialogContentProps>(child)) {
+          return React.cloneElement(child, { style: [{ marginTop: 24 }, child.props.style] })
+        }
+      }
+      if (i === 0 && React.isValidElement<DialogContentProps>(child) && child.type === PaperDialog.Content) {
+        return React.cloneElement(child, { style: [{ paddingTop: 24 }, child.props.style] })
+      }
+      return child
+    })
+
+  const borderRadius = (isV3 ? 7 : 1) * roundness
+
   return (
     <Portal>
-      <Animated.View style={[StyleSheet.absoluteFill, { opacity }]} pointerEvents={visible ? 'box-none' : 'none'}>
-        <TouchableWithoutFeedback onPress={onDismiss}>
-          <View style={[StyleSheet.absoluteFill, { backgroundColor: colors.backdrop }]} />
-        </TouchableWithoutFeedback>
-        <View style={styles.wrapper} pointerEvents='box-none'>
-          <BlurView style={[styles.card, { borderRadius: roundness * 7 }]}>{children}</BlurView>
+      <Animated.View accessibilityLiveRegion='polite' accessibilityViewIsModal pointerEvents={visible ? 'box-none' : 'none'} style={[StyleSheet.absoluteFill, { opacity }]} testID={testID}>
+        <Pressable accessibilityLabel='Close modal' accessibilityRole='button' disabled={!dismissable} onPress={dismissable ? onDismiss : undefined} style={[StyleSheet.absoluteFill, { backgroundColor: colors.backdrop }]} testID={`${testID}-backdrop`} />
+        <View pointerEvents='box-none' style={[styles.wrapper, { marginBottom: bottom, marginTop: top, paddingHorizontal: Math.max(left, right, DIALOG_MARGIN) }]} testID={`${testID}-wrapper`}>
+          <BlurView blur={blur} style={[styles.card, { borderRadius }, style]} testID={`${testID}-surface`}>
+            {content}
+          </BlurView>
         </View>
       </Animated.View>
     </Portal>
@@ -58,6 +94,5 @@ export const Dialog = DialogComponent
 const styles = StyleSheet.create({
   // Width cap keeps dialogs card-sized on wide viewports (web/tablet); no effect on phones.
   card: { alignSelf: 'center', maxWidth: 400, overflow: 'hidden', width: '100%' },
-  sized: { alignSelf: 'center', maxWidth: 400, width: '100%' },
-  wrapper: { flex: 1, justifyContent: 'center', paddingHorizontal: 26 }
+  wrapper: { flex: 1, justifyContent: 'center', paddingVertical: DIALOG_MARGIN }
 })

package/src/components/PalettePicker.tsx

@@ -0,0 +1,117 @@
+import { useState } from 'react'
+import { StyleSheet, TouchableOpacity, View } from 'react-native'
+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'
+import { defaultColors } from './ColorPicker'
+import { Dialog } from './Dialog'
+
+const SIZE = 48
+
+export type PaletteWeights = { primary: number; secondary: number; tertiary: number }
+
+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%.
+// 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
+// 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) => {
+  const total = weights.primary + weights.secondary + weights.tertiary
+  const primary = (weights.primary / total) * 360
+  const secondary = (weights.secondary / total) * 360
+  const tertiary = (weights.tertiary / total) * 360
+
+  return [
+    { key: 'primary' as const, rotate: -primary / 2, share: primary },
+    { key: 'tertiary' as const, rotate: primary / 2, share: tertiary },
+    { key: 'secondary' as const, rotate: primary / 2 + tertiary, share: secondary }
+  ]
+}
+
+const Pie = ({ palette, weights = defaultWeights, size = SIZE }: { palette: TriadicPalette; weights?: PaletteWeights; size?: number }) => (
+  <View style={[styles.pie, { borderRadius: size / 2, height: size, width: size }]}>
+    {buildWedges(weights).map(({ key, rotate, share }) => (
+      <View key={key} style={[styles.rotator, { transform: [{ rotate: `${rotate}deg` }] }]}>
+        <View style={styles.halfMask}>
+          <View style={[styles.innerRotator, { transform: [{ rotate: `${share - 180}deg` }] }]}>
+            <View style={[styles.wedgeFill, { backgroundColor: palette[key] }]} />
+          </View>
+        </View>
+      </View>
+    ))}
+  </View>
+)
+
+type Props = {
+  value: string
+  onChange: (color: string) => void
+  harmony?: ColorHarmony
+  weights?: PaletteWeights
+  colors?: SeedColor[]
+  blur?: boolean
+}
+
+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)
+
+  return (
+    <>
+      <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, { borderRadius: SIZE / 2 }, getSwatchRing(value, false, themeColors.outlineVariant)]}>
+            <Icon source='palette' size={20} color={getContrastColor(value)} />
+          </View>
+        </View>
+      </TouchableRipple>
+
+      <Dialog blur={blur} visible={open} onDismiss={() => setOpen(false)}>
+        <Dialog.Content>
+          <View style={styles.swatches} onLayout={onLayout}>
+            {colors.map(({ value: hex }) => (
+              <TouchableOpacity
+                key={hex}
+                onPress={() => {
+                  onChange(hex)
+                  setOpen(false)
+                }}
+                style={[styles.swatch, { height: size, width: size }]}
+              >
+                <Pie palette={getTriadicPalette(hex, harmony)} weights={weights} size={size} />
+                <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>
+        </Dialog.Content>
+      </Dialog>
+    </>
+  )
+}
+
+const styles = StyleSheet.create({
+  halfMask: { height: '100%', left: '50%', overflow: 'hidden', position: 'absolute', top: 0, width: '50%' },
+  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%' },
+  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 },
+  triggerContent: { height: SIZE, width: SIZE },
+  triggerIcon: { alignItems: 'center', bottom: 0, justifyContent: 'center', left: 0, position: 'absolute', right: 0, top: 0 },
+  wedgeFill: { height: '100%', left: '50%', position: 'absolute', top: 0, width: '50%' }
+})

package/src/index.ts

@@ -1,5 +1,6 @@
 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 { BlurView } from './components/BlurView'
@@ -17,6 +18,8 @@ export type { IconButtonProps } from './components/IconButton'
 export { IconButton } from './components/IconButton'
 export type { MenuProps } from './components/Menu'
 export { Menu } from './components/Menu'
+export type { PaletteWeights } from './components/PalettePicker'
+export { PalettePicker } from './components/PalettePicker'
 export { TextInput } from './components/TextInput'
 export type { PaperDefaults } from './PaperDefaultsContext'
 export { usePaperDefaults } from './PaperDefaultsContext'
@@ -26,13 +29,17 @@ export type { ProviderProps } from './ThemeProvider'
 export { Provider } 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 { getTintTextColor } from './utils/getTintTextColor'
 export { getTonalColor } from './utils/getTonalColor'
 export type { ColorHarmony, TriadicPalette } from './utils/getTriadicPalette'

package/src/useComputedTheme.ts

@@ -3,46 +3,112 @@ import { Appearance } from 'react-native'
 import { MD3DarkTheme, MD3LightTheme, MD3Theme } from 'react-native-paper'
 
 import { getBlendedColor } from './utils/getBlendedColor'
-import { getTonalColor } from './utils/getTonalColor'
+import { getColorRoles } from './utils/getColorRoles'
 import { type ColorHarmony, getTriadicPalette } from './utils/getTriadicPalette'
-import { isDarkColor } from './utils/isDarkColor'
 
 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, harmony: ColorHarmony = 'split-complementary'): AutoPaperTheme | null {
+  const [theme, setTheme] = useState<AutoPaperTheme | null>(null)
 
   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
-
-    _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)
-
-    _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)
 
-    _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 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
+
+    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
+
+    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 tintSurface = (alpha: number) => getBlendedColor(blended, surface, alpha)

package/src/useSwatchGrid.ts

@@ -0,0 +1,18 @@
+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
+// 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
+
+// `fallback` is returned before the container's first layout pass reports a real width.
+export function useSwatchSize(fallback: number) {
+  const [width, setWidth] = useState(0)
+
+  const onLayout = ({ nativeEvent }: LayoutChangeEvent) => setWidth(nativeEvent.layout.width)
+  const size = width > 0 ? (width - SWATCH_GRID_GAP * (SWATCH_GRID_COLUMNS - 1)) / SWATCH_GRID_COLUMNS : fallback
+
+  return { onLayout, size }
+}

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