Skip to main content

UI Preset System

1. Context & Overview​

The Framework M UI Preset System provides progressive visual skinning across core applications and m-plugins. Applications built on Framework M can adopt complete design systems (e.g., Frappe UI v15, Material Design, Ant Design) by injecting a declarative UIPreset into the root application shell without modifying component markup or Tamagui foundations.

2. Building Block View​

UI Preset System Architecture

Core Components​

  1. UIPreset Contract (libs/framework-m-ui/src/theme/types.ts): Interface specifying token scale overrides (color, radius, size, space) and theme overrides (light, dark).
  2. frappePreset (libs/framework-m-ui/src/theme/presets/frappePreset.ts): Official preset implementing Frappe UI v15 visual metrics (solid black primary buttons #111827, pure black dark mode #121212, 6px border radii).
  3. buildMThemeConfig(preset?) (libs/framework-m-ui/src/theme/mThemeConfig.ts): Dynamic Tamagui configuration generator that merges preset overrides over base Framework M design tokens.
  4. MProvider (libs/framework-m-ui/src/theme/MProvider.tsx): Root theme container providing TamaguiProvider and auto-supplying ThemeProvider if not present.

3. Design Decisions & Token Invariants​

Decision 1: Zero Hardcoded Colors in Components​

UI components in @framework-m/ui and @framework-m/desk must never specify literal hex strings (#ffffff, #000000, #8b5cf6), RGB colors, or static fallbacks in JSX style props or CSS definitions.

Decision 2: Dynamic Token Pairs for Contrast Inversion​

  • Primary background action buttons consume $primary.
  • Foreground text and icons inside primary elements consume $primaryColor (which dynamically flips between #ffffff in Light Mode and #121212 in Dark Mode under frappePreset).

Decision 3: Component Token Mapping Table​

Visual ElementTamagui Theme Token
Primary Action Button Background$primary
Primary Action Button Foreground (Text/Icon)$primaryColor
Page / Shell Background$background
Card / Panel Background$backgroundSecondary
Input Fill$backgroundSecondary
Focus Ring Outer Outline$focusRing
Active Navigation Sidebar Card$sidebarItemActiveBg
Default Text Color$color
Muted Text / Subtitles$colorMuted
Primary Border Lines$borderColor