Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(theme): add WhatsApp theme (#911)

rubyycheungb816ec126765
diff --git a/apps/sandbox/package.json b/apps/sandbox/package.json
index 6abb694771..e50120a35d 100644
--- a/apps/sandbox/package.json
+++ b/apps/sandbox/package.json
@@ -15,6 +15,7 @@
"@xds/theme-default": "*",
"@xds/theme-neutral": "*",
"@xds/theme-brutalist": "*",
+ "@xds/theme-whatsapp": "*",
"next": "^15.5.14",
"react": "^19.2.4",
"react-dom": "^19.2.4"
diff --git a/apps/sandbox/src/app/providers.tsx b/apps/sandbox/src/app/providers.tsx
index d2d22a1e2a..8c6ba35f7a 100644
--- a/apps/sandbox/src/app/providers.tsx
+++ b/apps/sandbox/src/app/providers.tsx
@@ -5,12 +5,14 @@ import {XDSTheme} from '@xds/core/theme';
import {defaultTheme} from '@xds/theme-default';
import {neutralTheme} from '@xds/theme-neutral';
import {brutalistTheme} from '@xds/theme-brutalist';
+import {whatsappTheme} from '@xds/theme-whatsapp';
import type {XDSDefinedTheme, ThemeMode} from '@xds/core/theme';
const themes: Record<string, XDSDefinedTheme> = {
default: defaultTheme,
neutral: neutralTheme,
brutalist: brutalistTheme,
+ whatsapp: whatsappTheme,
};
type ThemeContextValue = {
diff --git a/package.json b/package.json
index 37b893c3a2..62807e6c16 100644
--- a/package.json
+++ b/package.json
@@ -9,7 +9,7 @@
"internal/*"
],
"scripts": {
- "build": "yarn workspace @xds/core build && yarn workspace @xds/theme-default build && yarn workspace @xds/theme-neutral build && yarn workspace @xds/theme-brutalist build",
+ "build": "yarn workspace @xds/core build && yarn workspace @xds/theme-default build && yarn workspace @xds/theme-neutral build && yarn workspace @xds/theme-brutalist build && yarn workspace @xds/theme-whatsapp build",
"dev": "yarn workspace @xds/storybook dev",
"test": "vitest run",
"test:watch": "vitest",
diff --git a/packages/themes/whatsapp/CHANGELOG.md b/packages/themes/whatsapp/CHANGELOG.md
new file mode 100644
index 0000000000..aba46acffe
--- /dev/null
+++ b/packages/themes/whatsapp/CHANGELOG.md
@@ -0,0 +1,7 @@
+# @xds/theme-whatsapp
+
+## 0.0.8
+
+### Patch Changes
+
+- Initial release — WhatsApp theme for XDS
diff --git a/packages/themes/whatsapp/package.json b/packages/themes/whatsapp/package.json
new file mode 100644
index 0000000000..db1545246e
--- /dev/null
+++ b/packages/themes/whatsapp/package.json
@@ -0,0 +1,33 @@
+{
+ "name": "@xds/theme-whatsapp",
+ "version": "0.0.8",
+ "private": true,
+ "description": "WhatsApp theme for XDS — green accent, warm grays, Roboto, rounded surfaces",
+ "license": "MIT",
+ "sideEffects": false,
+ "main": "./dist/index.js",
+ "module": "./dist/index.mjs",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.mjs",
+ "require": "./dist/index.js"
+ },
+ "./theme.css": "./dist/theme.css"
+ },
+ "files": [
+ "dist",
+ "src"
+ ],
+ "scripts": {
+ "build": "xds theme build src/whatsappTheme.ts -o dist/theme.css && tsup && rm -f dist/whatsapp.js dist/whatsapp.d.ts"
+ },
+ "peerDependencies": {
+ "@xds/core": "*",
+ "react": ">=19"
+ },
+ "devDependencies": {
+ "@xds/cli": "*"
+ }
+}
diff --git a/packages/themes/whatsapp/src/icons.tsx b/packages/themes/whatsapp/src/icons.tsx
new file mode 100644
index 0000000000..6940a5cc15
--- /dev/null
+++ b/packages/themes/whatsapp/src/icons.tsx
@@ -0,0 +1,55 @@
+/**
+ * WhatsApp theme icon registry
+ *
+ * Reuses Heroicons (same as the default theme). WhatsApp internally uses
+ * Material Design-style icons (WDS icons), but those aren't open source.
+ * Heroicons provide a clean, consistent alternative.
+ */
+
+import React from 'react';
+import type {XDSIconRegistry} from '@xds/core/Icon';
+
+import {
+ XMarkIcon,
+ ChevronDownIcon,
+ ChevronLeftIcon,
+ ChevronRightIcon,
+ CheckIcon,
+ CalendarDaysIcon,
+ ClockIcon,
+ InformationCircleIcon,
+ Bars3Icon,
+ EllipsisHorizontalIcon,
+ MagnifyingGlassIcon,
+} from '@heroicons/react/24/outline';
+
+import {
+ CheckCircleIcon,
+ XCircleIcon,
+ ExclamationTriangleIcon,
+ ArrowTopRightOnSquareIcon,
+} from '@heroicons/react/24/solid';
+
+const iconProps = {
+ width: '1em',
+ height: '1em',
+ 'aria-hidden': true as const,
+};
+
+export const whatsappIconRegistry: XDSIconRegistry = {
+ close: <XMarkIcon {...iconProps} />,
+ chevronDown: <ChevronDownIcon {...iconProps} />,
+ chevronLeft: <ChevronLeftIcon {...iconProps} />,
+ chevronRight: <ChevronRightIcon {...iconProps} />,
+ check: <CheckIcon {...iconProps} />,
+ checkCircle: <CheckCircleIcon {...iconProps} />,
+ xCircle: <XCircleIcon {...iconProps} />,
+ warning: <ExclamationTriangleIcon {...iconProps} />,
+ info: <InformationCircleIcon {...iconProps} />,
+ calendar: <CalendarDaysIcon {...iconProps} />,
+ clock: <ClockIcon {...iconProps} />,
+ externalLink: <ArrowTopRightOnSquareIcon {...iconProps} />,
+ menu: <Bars3Icon {...iconProps} />,
+ moreHorizontal: <EllipsisHorizontalIcon {...iconProps} />,
+ search: <MagnifyingGlassIcon {...iconProps} />,
+};
diff --git a/packages/themes/whatsapp/src/index.ts b/packages/themes/whatsapp/src/index.ts
new file mode 100644
index 0000000000..7aee7a9699
--- /dev/null
+++ b/packages/themes/whatsapp/src/index.ts
@@ -0,0 +1,2 @@
+export {whatsappTheme} from './whatsappTheme';
+export {whatsappIconRegistry} from './icons';
diff --git a/packages/themes/whatsapp/src/whatsappTheme.ts b/packages/themes/whatsapp/src/whatsappTheme.ts
new file mode 100644
index 0000000000..1b8938b8e8
--- /dev/null
+++ b/packages/themes/whatsapp/src/whatsappTheme.ts
@@ -0,0 +1,307 @@
+/**
+ * WhatsApp Theme for XDS
+ *
+ * Derived from WhatsApp's internal design system (WDS). Colors are mapped
+ * from WDS semantic tokens (WDSThemes.js) to XDS token names. Typography
+ * uses Roboto — WhatsApp's primary typeface. Radius is slightly rounder
+ * than XDS defaults to match WhatsApp's soft, approachable feel.
+ *
+ * Color palette source: WDS BaseColor + systemThemeTokenValue
+ * Light mode: warm grays (warmGray50–800) for surfaces, green500 accent
+ * Dark mode: neutral grays (neutralGray850–1000) for surfaces, green450 accent
+ *
+ * Key WDS design decisions preserved:
+ * - Alpha-based text colors (blackAlpha60 / whiteAlpha60 for secondary)
+ * - Warm gray tint in light mode surfaces (not pure white backgrounds)
+ * - Green accent that shifts slightly between light/dark (500 → 450)
+ * - on-accent flips: white in light mode, near-black in dark mode
+ * - Pill-shaped primary buttons
+ * - Generous border radius (16px containers, 8px elements)
+ */
+
+import {defineTheme} from '@xds/core/theme';
+import {whatsappIconRegistry} from './icons';
+
+export const whatsappTheme = defineTheme({
+ name: 'whatsapp',
+
+ // Typography: Roboto — WhatsApp's primary typeface across all platforms.
+ // WDS uses a non-geometric type scale (Body1=16, Body2=14, Body3=12,
+ // Headline1=24, Headline2=22, LargeTitle1=32, LargeTitle2=28).
+ // base=14 ratio=1.2 produces a close approximation.
+ typography: {
+ scale: {base: 14, ratio: 1.2},
+ body: {
+ family: 'Roboto',
+ fallbacks:
+ '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
+ url: 'https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap',
+ },
+ heading: {
+ weight: 'medium',
+ },
+ code: {
+ family: 'Roboto Mono',
+ fallbacks: '"SF Mono", Monaco, Consolas, monospace',
+ url: 'https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@400;500;600;700&display=swap',
+ },
+ },
+
+ // Radius: WDS uses 8px default (borderRadiusSingle), 16px for containers
+ // (borderRadiusDouble), 24px+ for large panels. multiplier=2 scales XDS's
+ // base-4 system to match: radius-1=8, radius-2=16, radius-3=24, radius-4=32.
+ radius: {base: 4, multiplier: 2},
+
+ // Motion: WhatsApp feels snappy but not jarring.
+ // Slightly faster than XDS default, with ease-out for natural deceleration.
+ motion: {fast: 150, medium: 350, ratio: 0.75},
+
+ tokens: {
+ // =========================================================================
+ // Colors — derived from WDS systemThemeTokenValue (WDSThemes.js)
+ // =========================================================================
+
+ // Core accent: WDS green500 (light) / green450 (dark)
+ '--color-accent': ['#1DAA61', '#21C063'],
+ '--color-accent-muted': [
+ 'rgba(29, 170, 97, 0.2)',
+ 'rgba(33, 192, 99, 0.25)',
+ ],
+
+ // On-accent: WDS flips contrast — white on green (light), black on green (dark)
+ '--color-on-accent': ['#FFFFFF', '#0A0A0A'],
+ '--color-on-success': ['#FFFFFF', '#0A0A0A'],
+ '--color-on-error': ['#FFFFFF', '#0A0A0A'],
+ '--color-on-warning': ['#0A0A0A', '#0A0A0A'],
+ '--color-on-dark': ['#FFFFFF', '#FFFFFF'],
+ '--color-on-light': ['#000000', '#000000'],
+
+ // Neutral: WDS surface-highlight (warmGray300Alpha15 / whiteAlpha10)
+ '--color-neutral':
+ 'light-dark(rgba(194, 189, 184, 0.15), rgba(255, 255, 255, 0.1))',
+
+ // Surfaces: WDS uses warm grays in light, neutral grays in dark
+ // surface-default: whiteOpaque / neutralGray900
+ '--color-background-surface': ['#FFFFFF', '#161717'],
+ // background-wash: warmGray75 / neutralGray900
+ '--color-background-body': ['#F7F5F3', '#161717'],
+ // surface-elevated-default: whiteOpaque / neutralGray850
+ '--color-background-card': ['#FFFFFF', '#1D1F1F'],
+ // surface-elevated-default (same as card for popovers)
+ '--color-background-popover': ['#FFFFFF', '#1D1F1F'],
+ // background-muted: warmGray75 / neutralGray850
+ '--color-background-muted': ['#F7F5F3', '#1D1F1F'],
+
+ // Overlay: WDS background-dimmer
+ '--color-overlay': ['rgba(0, 0, 0, 0.32)', 'rgba(0, 0, 0, 0.32)'],
+ '--color-overlay-hover': [
+ 'rgba(0, 0, 0, 0.05)',
+ 'rgba(255, 255, 255, 0.05)',
+ ],
+ '--color-overlay-pressed': [
+ 'rgba(0, 0, 0, 0.2)',
+ 'rgba(255, 255, 255, 0.2)',
+ ],
+
+ // Text: WDS content-default (neutralGray1000/neutralGray50),
+ // content-deemphasized (blackAlpha60/whiteAlpha60),
+ // content-disabled (neutralGray300/neutralGray700)
+ '--color-text-primary': ['#0A0A0A', '#FAFAFA'],
+ '--color-text-secondary': [
+ 'rgba(0, 0, 0, 0.6)',
+ 'rgba(255, 255, 255, 0.6)',
+ ],
+ '--color-text-disabled': ['#BDBDBD', '#424445'],
+ // content-action-emphasized: green600 / green450
+ '--color-text-accent': ['#1B8755', '#21C063'],
+
+ // Icons: follow same pattern as text
+ '--color-icon-accent': ['#1DAA61', '#21C063'],
+ '--color-icon-primary': ['#0A0A0A', '#FAFAFA'],
+ '--color-icon-secondary': [
+ 'rgba(0, 0, 0, 0.6)',
+ 'rgba(255, 255, 255, 0.6)',
+ ],
+ '--color-icon-disabled': ['#BDBDBD', '#424445'],
+
+ // Status: WDS secondary-negative (red), secondary-positive (green),
+ // secondary-warning (yellow)
+ '--color-success': ['#1DAA61', '#71EB85'],
+ '--color-success-muted': [
+ 'rgba(29, 170, 97, 0.2)',
+ 'rgba(113, 235, 133, 0.25)',
+ ],
+ '--color-error': ['#EA0038', '#FB5061'],
+ '--color-error-muted': ['rgba(234, 0, 56, 0.2)', 'rgba(251, 80, 97, 0.25)'],
+ '--color-warning': ['#FFB938', '#FFD279'],
+ '--color-warning-muted': [
+ 'rgba(255, 185, 56, 0.2)',
+ 'rgba(255, 210, 121, 0.25)',
+ ],
+
+ // Border: WDS lines-divider (blackAlpha10/whiteAlpha10),
+ // lines-outline-default (neutralGray400/neutralGray500)
+ '--color-border': ['rgba(0, 0, 0, 0.1)', 'rgba(255, 255, 255, 0.1)'],
+ '--color-border-emphasized': ['#959393', '#757778'],
+
+ // Effects
+ '--color-skeleton': ['#EEEEEE', '#424445'],
+ '--color-shadow': ['rgba(0, 0, 0, 0.1)', 'rgba(0, 0, 0, 0.3)'],
+ '--color-tint-hover': ['black', 'white'],
+
+ // =========================================================================
+ // Semantic color palette — mapped from WDS BaseColor
+ // =========================================================================
+
+ // Blue (WDS cobalt)
+ '--color-background-blue': [
+ 'rgba(0, 123, 252, 0.2)',
+ 'rgba(0, 123, 252, 0.2)',
+ ],
+ '--color-border-blue': ['#007BFC', '#53A6FD'],
+ '--color-icon-blue': ['#0063CB', '#53A6FD'],
+ '--color-text-blue': ['#073D76', '#99CAFE'],
+
+ // Cyan (WDS skyBlue)
+ '--color-background-cyan': [
+ 'rgba(0, 157, 226, 0.2)',
+ 'rgba(0, 157, 226, 0.2)',
+ ],
+ '--color-border-cyan': ['#009DE2', '#53BDEB'],
+ '--color-icon-cyan': ['#027EB5', '#53BDEB'],
+ '--color-text-cyan': ['#074B6A', '#93D7F5'],
+
+ // Gray (WDS warmGray/neutralGray)
+ '--color-background-gray': [
+ 'rgba(10, 10, 10, 0.05)',
+ 'rgba(255, 255, 255, 0.1)',
+ ],
+ '--color-border-gray': ['#9F9891', '#757778'],
+ '--color-icon-gray': ['#7C7771', '#858586'],
+ '--color-text-gray': ['#0A0A0A', '#FAFAFA'],
+
+ // Green (WDS green — the signature WhatsApp green)
+ '--color-background-green': [
+ 'rgba(29, 170, 97, 0.2)',
+ 'rgba(29, 170, 97, 0.2)',
+ ],
+ '--color-border-green': ['#1DAA61', '#71EB85'],
+ '--color-icon-green': ['#1DAA61', '#71EB85'],
+ '--color-text-green': ['#15603E', '#ACFCAC'],
+
+ // Orange (WDS orange)
+ '--color-background-orange': [
+ 'rgba(250, 101, 51, 0.2)',
+ 'rgba(250, 101, 51, 0.2)',
+ ],
+ '--color-border-orange': ['#FA6533', '#FC9775'],
+ '--color-icon-orange': ['#C4532D', '#FC9775'],
+ '--color-text-orange': ['#6B3424', '#FDC1AD'],
+
+ // Pink (WDS pink)
+ '--color-background-pink': [
+ 'rgba(255, 46, 116, 0.2)',
+ 'rgba(255, 46, 116, 0.2)',
+ ],
+ '--color-border-pink': ['#FF2E74', '#FF72A1'],
+ '--color-icon-pink': ['#D42A66', '#FF72A1'],
+ '--color-text-pink': ['#6D1E3E', '#FFABC7'],
+
+ // Purple (WDS purple)
+ '--color-background-purple': [
+ 'rgba(127, 102, 255, 0.2)',
+ 'rgba(127, 102, 255, 0.2)',
+ ],
+ '--color-border-purple': ['#7F66FF', '#A791FF'],
+ '--color-icon-purple': ['#5E47DE', '#A791FF'],
+ '--color-text-purple': ['#3A327B', '#D1C4FF'],
+
+ // Red (WDS red)
+ '--color-background-red': [
+ 'rgba(234, 0, 56, 0.2)',
+ 'rgba(251, 80, 97, 0.2)',
+ ],
+ '--color-border-red': ['#EA0038', '#FB5061'],
+ '--color-icon-red': ['#B80531', '#FB5061'],
+ '--color-text-red': ['#61182E', '#FA99A4'],
+
+ // Teal (WDS teal)
+ '--color-background-teal': [
+ 'rgba(2, 166, 152, 0.2)',
+ 'rgba(2, 166, 152, 0.2)',
+ ],
+ '--color-border-teal': ['#02A698', '#42C7B8'],
+ '--color-icon-teal': ['#028377', '#42C7B8'],
+ '--color-text-teal': ['#074D4A', '#95DBD4'],
+
+ // Yellow (WDS yellow)
+ '--color-background-yellow': [
+ 'rgba(255, 185, 56, 0.2)',
+ 'rgba(255, 210, 121, 0.2)',
+ ],
+ '--color-border-yellow': ['#FFB938', '#FFD279'],
+ '--color-icon-yellow': ['#C58730', '#FFD279'],
+ '--color-text-yellow': ['#6D4E26', '#FFE4AF'],
+
+ // =========================================================================
+ // Shadows — soft, WhatsApp-style elevation
+ // =========================================================================
+ '--shadow-low':
+ '0 1px 3px rgba(0, 0, 0, 0.08), 0 2px 6px light-dark(rgba(0, 0, 0, 0.06), rgba(0, 0, 0, 0.2))',
+ '--shadow-med':
+ '0 2px 6px rgba(0, 0, 0, 0.08), 0 4px 12px light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.25))',
+ // WDS popoverShadow: 0 12px 16px -4px rgb(10 10 10 / 0.1)
+ '--shadow-high':
+ '0 4px 8px rgba(0, 0, 0, 0.06), 0 12px 16px -4px light-dark(rgba(10, 10, 10, 0.1), rgba(0, 0, 0, 0.35))',
+ },
+
+ components: {
+ // =========================================================================
+ // Button — pill-shaped primary, signature WhatsApp style
+ // =========================================================================
+ button: {
+ base: {
+ borderRadius: '9999px',
+ fontWeight: '500',
+ },
+ 'variant:secondary': {
+ backgroundColor:
+ 'light-dark(rgba(194, 189, 184, 0.15), rgba(255, 255, 255, 0.1))',
+ },
+ 'variant:ghost': {
+ borderRadius: '9999px',
+ },
+ },
+
+ // =========================================================================
+ // Badge — rounded, WhatsApp-green tinted
+ // =========================================================================
+ badge: {
+ base: {
+ fontWeight: '500',
+ },
+ },
+
+ // =========================================================================
+ // Card — clean, no heavy borders, elevation via shadow
+ // =========================================================================
+ card: {
+ base: {
+ borderColor:
+ 'light-dark(rgba(0, 0, 0, 0.06), rgba(255, 255, 255, 0.06))',
+ },
+ },
+
+ // =========================================================================
+ // Divider — subtle, WDS-style thin divider
+ // =========================================================================
+ divider: {
+ base: {
+ borderTopColor:
+ 'light-dark(rgba(0, 0, 0, 0.1), rgba(255, 255, 255, 0.1))',
+ },
+ },
+ },
+
+ icons: whatsappIconRegistry,
+});
diff --git a/packages/themes/whatsapp/tsup.config.ts b/packages/themes/whatsapp/tsup.config.ts
new file mode 100644
index 0000000000..176795f3bb
--- /dev/null
+++ b/packages/themes/whatsapp/tsup.config.ts
@@ -0,0 +1,9 @@
+import {defineConfig} from 'tsup';
+
+export default defineConfig({
+ entry: ['src/index.ts'],
+ format: ['cjs', 'esm'],
+ dts: true,
+ clean: false, // Don't clean — xds build-theme already put theme.css in dist/
+ external: ['@xds/core', 'react'],
+});