@advui/theme 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@advui/theme",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Design tokens, color presets and the Tamagui config factory for Adv UI.",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./material": {
+      "types": "./dist/material.d.ts",
+      "default": "./dist/material.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -31,11 +35,12 @@
     "access": "public"
   },
   "dependencies": {
+    "@advui/utils": "0.2.0",
+    "@material/material-color-utilities": "0.3.0",
     "@tamagui/animations-css": "2.7.7",
     "@tamagui/animations-react-native": "2.7.7",
     "@tamagui/colors": "2.7.7",
-    "@tamagui/web": "2.7.7",
-    "@advui/utils": "0.1.0"
+    "@tamagui/web": "2.7.7"
   },
   "peerDependencies": {
     "react": ">=19",
@@ -43,9 +48,9 @@
     "tamagui": "^2.7.7"
   },
   "devDependencies": {
-    "@types/react": "~19.2.2",
     "@advui/eslint-config": "0.1.0",
     "@advui/tsconfig": "0.1.0",
+    "@types/react": "~19.2.2",
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "react-native": "0.86.3",

package/src/config.ts

@@ -4,19 +4,44 @@ import { type FontFamilies, type FontScale, createUniversalFonts } from './fonts
 import { media, mediaQueryDefaultActive } from './media'
 import { type ThemePresetName, themePresets } from './presets'
 import { shorthands } from './shorthands'
-import { type ThemeColorsInput, createThemeColors } from './themes'
-import { type RadiusScale, createUniversalTokens } from './tokens'
+import { type GeneratedThemes, type ThemeColorsInput, createThemeColors } from './themes'
+import { type RadiusInput, createUniversalTokens } from './tokens'
 
 export interface UniversalConfigOptions {
   /** Starting color preset. Individual `colors` win over the preset. Default: `indigo`. */
   preset?: ThemePresetName
   /** Brand and intent colors — scale names (`'violet'`) or any color string (`'#6366f1'`). */
   colors?: ThemeColorsInput
-  /** Corner roundness for every component. Default: `md` (8px base). */
-  radius?: RadiusScale | number
+  /**
+   * Corner roundness for every component: a scale name or base in px (default
+   * `md`, 8px), or exact values per token, e.g. `{ button: 9999 }`.
+   */
+  radius?: RadiusInput
   /** Global type scale. Default: `default`. */
   fontScale?: FontScale | number
   fonts?: FontFamilies
+  /**
+   * Complete light and dark themes, e.g. from `material()` in
+   * `@advui/theme/material`. Replaces `preset` and `colors`.
+   */
+  themes?: GeneratedThemes
+  /**
+   * Android only: pressing a button, chip, tab or list row shows the native
+   * ripple instead of darkening it. `material()` turns it on. Default: false.
+   */
+  androidRipple?: boolean
+}
+
+/** Adv UI settings that are not Tamagui's, such as `androidRipple`. */
+export interface UniversalSettings {
+  androidRipple: boolean
+}
+
+const defaultSettings: UniversalSettings = { androidRipple: false }
+
+/** The Adv UI settings stored on a config from `createUniversalConfig()`. */
+export function getUniversalSettings(config: object): UniversalSettings {
+  return (config as { advui?: UniversalSettings }).advui ?? defaultSettings
 }
 
 /**
@@ -28,9 +53,9 @@ export interface UniversalConfigOptions {
  */
 export function createUniversalConfig(options: UniversalConfigOptions = {}) {
   const { preset = 'indigo', colors, radius = 'md', fontScale = 'default', fonts } = options
-  const themes = createThemeColors({ ...themePresets[preset].colors, ...colors })
+  const themes = options.themes ?? createThemeColors({ ...themePresets[preset].colors, ...colors })
 
-  return createTamagui({
+  const config = createTamagui({
     tokens: createUniversalTokens({ radius }),
     themes,
     fonts: createUniversalFonts({ scale: fontScale, families: fonts }),
@@ -50,6 +75,10 @@ export function createUniversalConfig(options: UniversalConfigOptions = {}) {
       styleCompat: 'web',
     },
   })
+  // Stored on the config object, which components reach from anywhere with
+  // getConfig(), including native portals that do not carry React context.
+  const advui: UniversalSettings = { androidRipple: options.androidRipple ?? false }
+  return Object.assign(config, { advui })
 }
 
 export type UniversalConfig = ReturnType<typeof createUniversalConfig>

package/src/index.ts

@@ -1,5 +1,11 @@
 export { animations } from './animations'
-export { createUniversalConfig, type UniversalConfig, type UniversalConfigOptions } from './config'
+export {
+  createUniversalConfig,
+  getUniversalSettings,
+  type UniversalConfig,
+  type UniversalConfigOptions,
+  type UniversalSettings,
+} from './config'
 export { createUniversalFonts, fontScales, type FontFamilies, type FontScale } from './fonts'
 export { breakpoints, media, mediaQueryDefaultActive } from './media'
 export {
@@ -33,5 +39,8 @@ export {
   size,
   space,
   zIndex,
+  type RadiusInput,
+  type RadiusOverrides,
   type RadiusScale,
+  type RadiusToken,
 } from './tokens'

package/src/material.ts

@@ -0,0 +1,268 @@
+/**
+ * Material 3 for Adv UI: color roles generated from one seed color with
+ * Google's material-color-utilities (the algorithm behind Android dynamic
+ * color), plus Material's shape scale and fonts. It lives in its own entry,
+ * `@advui/theme/material`, so apps that do not use it never ship the library.
+ *
+ * Material roles are mapped onto Adv UI's roles, so every component works
+ * unchanged: `primaryContainer` → `$primarySoft`, `secondaryContainer` →
+ * `$secondary` (Material's tonal button), `outline` → `$input`, and so on.
+ */
+import {
+  type DynamicScheme,
+  Hct,
+  SchemeTonalSpot,
+  argbFromHex,
+  customColor,
+  hexFromArgb,
+} from '@material/material-color-utilities'
+import { ensureContrast, parseColor, toHex, withAlpha } from '@advui/utils'
+import type { UniversalConfigOptions } from './config'
+import type { FontFamilies } from './fonts'
+import type { ColorMode, GeneratedThemes, ThemeValues } from './themes'
+import type { RadiusOverrides } from './tokens'
+
+/** Material's baseline purple, used when no seed is given. */
+export const MATERIAL_BASELINE_SEED = '#6750A4'
+
+export interface MaterialOptions {
+  /** Seed color the whole palette is generated from. Default: Material baseline purple. */
+  seed?: string
+  /**
+   * Status colors Material does not define. They are harmonized toward the
+   * seed (a slight hue shift) so they sit well with it.
+   */
+  colors?: { success?: string; warning?: string; info?: string }
+  /** Escape hatch: override any generated value per mode. */
+  overrides?: Partial<Record<ColorMode, Partial<ThemeValues>>>
+  /** Android: show the native ripple when something is pressed. Default: true. */
+  androidRipple?: boolean
+}
+
+const defaultStatus = { success: '#2e7d32', warning: '#b26a00', info: '#0061a4' }
+
+// Material state-layer opacities: hover 8%, focus and press 10%.
+const HOVER = 0.08
+const PRESS = 0.1
+
+/** Paints `overlay` over `base` at `opacity`, like a Material state layer (sRGB). */
+function layer(base: string, overlay: string, opacity: number): string {
+  const b = parseColor(base)
+  const o = parseColor(overlay)
+  if (!b || !o) throw new Error(`Invalid color: ${!b ? base : overlay}`)
+  const c = (x: number, y: number) => x * (1 - opacity) + y * opacity
+  return toHex({ r: c(b.r, o.r), g: c(b.g, o.g), b: c(b.b, o.b), a: 1 })
+}
+
+// Neutral tones behind Tamagui's color1…color12 (lightest to strongest text).
+const NEUTRAL_TONES = {
+  light: [99, 98, 96, 94, 92, 90, 87, 80, 60, 50, 30, 10],
+  dark: [6, 10, 12, 17, 22, 24, 30, 40, 60, 70, 80, 90],
+} as const
+
+function buildMode(
+  s: DynamicScheme,
+  mode: ColorMode,
+  status: Record<'success' | 'warning' | 'info', ReturnType<typeof customColor>>,
+): ThemeValues {
+  const hex = hexFromArgb
+  const isDark = mode === 'dark'
+  const surface = hex(s.surface)
+  const onSurface = hex(s.onSurface)
+  const popover = hex(s.surfaceContainerHigh)
+  const muted = hex(s.surfaceContainerHigh)
+  const tone = (step: number) => hex(s.neutralPalette.tone(NEUTRAL_TONES[mode][step]!))
+
+  const primary = hex(s.primary)
+  const onPrimary = hex(s.onPrimary)
+  const primaryContainer = hex(s.primaryContainer)
+  const onPrimaryContainer = hex(s.onPrimaryContainer)
+  const secondaryContainer = hex(s.secondaryContainer)
+  const onSecondaryContainer = hex(s.onSecondaryContainer)
+  const error = hex(s.error)
+  const onError = hex(s.onError)
+  const errorContainer = hex(s.errorContainer)
+  const onErrorContainer = hex(s.onErrorContainer)
+  const outline = hex(s.outline)
+  const outlineVariant = hex(s.outlineVariant)
+
+  const intent = (group: ReturnType<typeof customColor>) => {
+    const g = isDark ? group.dark : group.light
+    return {
+      solid: hex(g.color),
+      foreground: hex(g.onColor),
+      soft: hex(g.colorContainer),
+      softForeground: ensureContrast(hex(g.onColorContainer), hex(g.colorContainer)),
+      border: layer(hex(g.colorContainer), hex(g.color), 0.35),
+    }
+  }
+  const success = intent(status.success)
+  const warning = intent(status.warning)
+  const info = intent(status.info)
+
+  return {
+    background: surface,
+    backgroundHover: layer(surface, onSurface, HOVER),
+    backgroundPress: layer(surface, onSurface, PRESS),
+    backgroundFocus: layer(surface, onSurface, PRESS),
+    backgroundStrong: hex(s.surfaceContainer),
+    backgroundTransparent: withAlpha(surface, 0),
+    color: onSurface,
+    colorHover: onSurface,
+    colorPress: hex(s.onSurfaceVariant),
+    colorFocus: onSurface,
+    colorTransparent: withAlpha(onSurface, 0),
+    borderColor: outlineVariant,
+    borderColorHover: outline,
+    borderColorPress: outline,
+    borderColorFocus: primary,
+    placeholderColor: hex(s.onSurfaceVariant),
+    outlineColor: primary,
+    shadowColor: isDark ? 'rgba(0, 0, 0, 0.5)' : 'rgba(0, 0, 0, 0.12)',
+    shadowColorStrong: isDark ? 'rgba(0, 0, 0, 0.7)' : 'rgba(0, 0, 0, 0.24)',
+    color1: tone(0),
+    color2: tone(1),
+    color3: tone(2),
+    color4: tone(3),
+    color5: tone(4),
+    color6: tone(5),
+    color7: tone(6),
+    color8: tone(7),
+    color9: tone(8),
+    color10: tone(9),
+    color11: tone(10),
+    color12: tone(11),
+
+    foreground: onSurface,
+    muted,
+    mutedForeground: ensureContrast(hex(s.onSurfaceVariant), muted),
+    card: hex(s.surfaceContainerLow),
+    cardForeground: onSurface,
+    popover,
+    popoverForeground: onSurface,
+    overlay: withAlpha(hex(s.scrim), 0.32),
+
+    border: outlineVariant,
+    borderStrong: outline,
+    input: outline,
+    ring: primary,
+
+    primary,
+    primaryHover: layer(primary, onPrimary, HOVER),
+    primaryPress: layer(primary, onPrimary, PRESS),
+    primaryForeground: onPrimary,
+    primaryText: ensureContrast(primary, surface),
+    inversePrimary: ensureContrast(hex(s.inversePrimary), onSurface),
+    primarySoft: primaryContainer,
+    primarySoftHover: layer(primaryContainer, onPrimaryContainer, HOVER),
+    primarySoftForeground: onPrimaryContainer,
+    // Material's tonal button.
+    secondary: secondaryContainer,
+    secondaryHover: layer(secondaryContainer, onSecondaryContainer, HOVER),
+    secondaryPress: layer(secondaryContainer, onSecondaryContainer, PRESS),
+    secondaryForeground: onSecondaryContainer,
+    // Hover highlight for menu items and ghost buttons: a state layer over the
+    // menu surface, so it reads on both the page and the menu.
+    accent: layer(popover, onSurface, HOVER),
+    accentHover: layer(popover, onSurface, 0.12),
+    accentForeground: onSurface,
+
+    destructive: error,
+    destructiveHover: layer(error, onError, HOVER),
+    destructivePress: layer(error, onError, PRESS),
+    destructiveForeground: onError,
+    destructiveSoft: errorContainer,
+    destructiveSoftForeground: onErrorContainer,
+    success: success.solid,
+    successForeground: success.foreground,
+    successSoft: success.soft,
+    successSoftForeground: success.softForeground,
+    successBorder: success.border,
+    warning: warning.solid,
+    warningForeground: warning.foreground,
+    warningSoft: warning.soft,
+    warningSoftForeground: warning.softForeground,
+    warningBorder: warning.border,
+    error,
+    errorForeground: onError,
+    errorSoft: errorContainer,
+    errorSoftForeground: onErrorContainer,
+    errorBorder: layer(errorContainer, error, 0.35),
+    info: info.solid,
+    infoForeground: info.foreground,
+    infoSoft: info.soft,
+    infoSoftForeground: info.softForeground,
+    infoBorder: info.border,
+  }
+}
+
+/**
+ * Light and dark themes with Material 3 color roles (the "tonal spot" scheme
+ * Android uses for dynamic color), generated from `seed`.
+ */
+export function createMaterialThemes(options: MaterialOptions = {}): GeneratedThemes {
+  const seed = options.seed ?? MATERIAL_BASELINE_SEED
+  const source = argbFromHex(toHex(seed))
+  const colors = { ...defaultStatus, ...options.colors }
+  const status = {
+    success: customColor(source, {
+      name: 'success',
+      value: argbFromHex(colors.success),
+      blend: true,
+    }),
+    warning: customColor(source, {
+      name: 'warning',
+      value: argbFromHex(colors.warning),
+      blend: true,
+    }),
+    info: customColor(source, { name: 'info', value: argbFromHex(colors.info), blend: true }),
+  }
+  const scheme = (isDark: boolean) => new SchemeTonalSpot(Hct.fromInt(source), isDark, 0)
+  return {
+    light: { ...buildMode(scheme(false), 'light', status), ...options.overrides?.light },
+    dark: { ...buildMode(scheme(true), 'dark', status), ...options.overrides?.dark },
+  }
+}
+
+/**
+ * Material 3 shape scale on Adv UI's radius tokens: pill buttons, 4px fields,
+ * 12px cards and 28px dialogs and sheets.
+ */
+export const materialShape: RadiusOverrides = {
+  xs: 2,
+  sm: 4,
+  md: 4,
+  lg: 8,
+  xl: 12,
+  '2xl': 16,
+  '3xl': 28,
+  button: 9999,
+  buttonLg: 9999,
+  dialog: 28,
+}
+
+const roboto =
+  'Roboto, "Roboto Flex", -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif'
+
+/** Roboto on web (load it in your app); the platform font on iOS and Android. */
+export const materialFonts: FontFamilies = { body: roboto, heading: roboto }
+
+/**
+ * Options for `createUniversalConfig` that give every component the Material 3
+ * look: color roles from `seed`, Material's shapes, Roboto and, on Android,
+ * the press ripple.
+ *
+ * @example
+ * import { createUniversalConfig } from '@advui/theme'
+ * import { material } from '@advui/theme/material'
+ *
+ * export const config = createUniversalConfig(material({ seed: '#6750A4' }))
+ */
+export function material(options: MaterialOptions = {}): UniversalConfigOptions {
+  return {
+    themes: createMaterialThemes(options),
+    radius: materialShape,
+    fonts: materialFonts,
+    androidRipple: options.androidRipple ?? true,
+  }
+}

package/src/themes.ts

@@ -65,6 +65,8 @@ export type ThemeValues = {
   primaryForeground: string
   /** Primary-colored text/links on the page background (≥4.5:1). `primary` is a fill color. */
   primaryText: string
+  /** Primary-colored text on inverse surfaces (`$foreground` as a background), e.g. a snackbar action. */
+  inversePrimary: string
   primarySoft: string
   primarySoftHover: string
   primarySoftForeground: string
@@ -240,6 +242,10 @@ function buildMode(mode: ColorMode, input: Required<Omit<ThemeColorsInput, 'over
     primaryPress: primary.press,
     primaryForeground: primary.foreground,
     primaryText: input.monochrome ? n[11] : ensureContrast(primaryScale[10], background),
+    // The other mode's text step reads on the inverted surface.
+    inversePrimary: input.monochrome
+      ? background
+      : ensureContrast(resolveScale(input.primary)[isDark ? 'light' : 'dark'][10], n[11]),
     primarySoft: primaryScale[2],
     primarySoftHover: primaryScale[3],
     primarySoftForeground: ensureContrast(primaryScale[10], primaryScale[3]),

package/src/tokens.ts

@@ -71,15 +71,28 @@ export const radiusScales = {
 
 export type RadiusScale = keyof typeof radiusScales
 
+export type RadiusToken =
+  'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'button' | 'buttonLg' | 'dialog'
+
+/** Exact values for some radius tokens, on top of a base (`md` if omitted). */
+export type RadiusOverrides = { base?: RadiusScale | number } & Partial<Record<RadiusToken, number>>
+
+export type RadiusInput = RadiusScale | number | RadiusOverrides
+
 /**
  * Radius tokens derived from a single base value so the whole library can be
  * made sharper or rounder at once. Components pick semantic steps:
- * controls `$md`, menus/popovers `$lg`, cards/dialogs `$xl`, pills `$full`.
+ * controls `$md`, menus/popovers `$lg`, cards `$xl`, pills `$full`, and role
+ * tokens a design system can reshape on their own: `$button` / `$buttonLg`
+ * (buttons, icon buttons, toggles) and `$dialog` (dialogs and sheets).
  */
-export function createRadius(scale: RadiusScale | number = 'md') {
+export function createRadius(input: RadiusInput = 'md') {
+  const overrides = typeof input === 'object' ? input : {}
+  const scale = typeof input === 'object' ? (input.base ?? 'md') : input
   const base = typeof scale === 'number' ? scale : radiusScales[scale]
   const r = (factor: number) => Math.round(base * factor)
-  return {
+  const { base: _base, ...exact } = overrides
+  const tokens = {
     0: 0,
     xs: r(0.25),
     sm: r(0.5),
@@ -89,8 +102,12 @@ export function createRadius(scale: RadiusScale | number = 'md') {
     '2xl': r(2),
     '3xl': r(3),
     full: 9999,
-    true: r(0.75),
+    button: r(0.75),
+    buttonLg: r(1),
+    dialog: r(1.5),
+    ...exact,
   }
+  return { ...tokens, true: tokens.md }
 }
 
 export const zIndex = {
@@ -112,7 +129,7 @@ export const colorTokens = {
   transparent: 'rgba(0, 0, 0, 0)',
 } as const
 
-export function createUniversalTokens({ radius = 'md' }: { radius?: RadiusScale | number } = {}) {
+export function createUniversalTokens({ radius = 'md' }: { radius?: RadiusInput } = {}) {
   return createTokens({
     space,
     size,