Skip to content

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

TypeScript

feat(example): add Vite + Tailwind example app (#2234)

Cindy Zhangb9454a25cecc
diff --git a/apps/example-vite-tailwind/.gitignore b/apps/example-vite-tailwind/.gitignore
new file mode 100644
index 0000000000..f06235c460
--- /dev/null
+++ b/apps/example-vite-tailwind/.gitignore
@@ -0,0 +1,2 @@
+node_modules
+dist
diff --git a/apps/example-vite-tailwind/index.html b/apps/example-vite-tailwind/index.html
new file mode 100644
index 0000000000..bdbbe21039
--- /dev/null
+++ b/apps/example-vite-tailwind/index.html
@@ -0,0 +1,14 @@
+<!-- Copyright (c) Meta Platforms, Inc. and affiliates. -->
+
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>XDS + Vite + Tailwind</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="/src/main.tsx"></script>
+ </body>
+</html>
diff --git a/apps/example-vite-tailwind/package.json b/apps/example-vite-tailwind/package.json
new file mode 100644
index 0000000000..0a4fd85186
--- /dev/null
+++ b/apps/example-vite-tailwind/package.json
@@ -0,0 +1,29 @@
+{
+ "name": "@xds/example-vite-tailwind",
+ "version": "0.0.1",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "vite build",
+ "preview": "vite preview"
+ },
+ "dependencies": {
+ "@xds/core": "*",
+ "@xds/theme-default": "*",
+ "react": "^19.2.6",
+ "react-dom": "^19.2.6"
+ },
+ "devDependencies": {
+ "@tailwindcss/vite": "^4",
+ "@types/react": "^19.2.14",
+ "@types/react-dom": "^19.2.3",
+ "@vitejs/plugin-react": "^4.3.0",
+ "tailwindcss": "^4",
+ "typescript": "^6.0.3",
+ "vite": "^6.4.2"
+ },
+ "browserslist": [
+ "last 1 Chrome version"
+ ]
+}
diff --git a/apps/example-vite-tailwind/src/App.tsx b/apps/example-vite-tailwind/src/App.tsx
new file mode 100644
index 0000000000..a24498f17a
--- /dev/null
+++ b/apps/example-vite-tailwind/src/App.tsx
@@ -0,0 +1,203 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {useState} from 'react';
+import {XDSTheme} from '@xds/core/theme';
+import {defaultTheme} from '@xds/theme-default/built';
+import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {XDSButton} from '@xds/core/Button';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+import {XDSTextInput} from '@xds/core/TextInput';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSCard} from '@xds/core/Card';
+import {XDSDivider} from '@xds/core/Divider';
+import {XDSAvatar} from '@xds/core/Avatar';
+
+/**
+ * XDS + Vite + Tailwind Example
+ *
+ * Demonstrates:
+ * - XDS components for UI (buttons, cards, inputs, badges)
+ * - Tailwind utilities for page layout and custom spacing
+ * - Tailwind Bridge: XDS tokens as native Tailwind utilities
+ * (bg-surface, text-primary, text-secondary, etc.)
+ */
+export default function App() {
+ const [email, setEmail] = useState('');
+ const [name, setName] = useState('');
+
+ return (
+ <XDSTheme theme={defaultTheme}>
+ <main className="min-h-screen bg-body p-8">
+ <div className="mx-auto max-w-3xl">
+ <XDSVStack gap={8}>
+ {/* Header */}
+ <XDSVStack gap={2}>
+ <XDSHeading level={1}>XDS + Vite + Tailwind</XDSHeading>
+ <XDSText type="body" color="secondary">
+ XDS handles components and design tokens. Tailwind handles page
+ layout and custom styling — powered by the token bridge.
+ </XDSText>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* Token Bridge — Tailwind using XDS tokens */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Token Bridge</XDSHeading>
+ <XDSText type="supporting" color="secondary">
+ XDS tokens available as Tailwind utilities via{' '}
+ <code className="rounded-sm bg-muted px-1 py-0.5 text-xs">
+ @xds/core/tailwind-theme.css
+ </code>
+ </XDSText>
+
+ {/* Semantic surfaces using bridge utilities */}
+ <div className="grid grid-cols-3 gap-3">
+ <div className="flex flex-col gap-1 rounded-lg bg-surface p-4 shadow-sm">
+ <XDSText type="label">bg-surface</XDSText>
+ <XDSText type="supporting" color="secondary">
+ Cards, panels
+ </XDSText>
+ </div>
+ <div className="flex flex-col gap-1 rounded-lg bg-body p-4 shadow-sm border border-border">
+ <XDSText type="label">bg-body</XDSText>
+ <XDSText type="supporting" color="secondary">
+ Page background
+ </XDSText>
+ </div>
+ <div className="flex flex-col gap-1 rounded-lg bg-muted p-4 shadow-sm">
+ <XDSText type="label">bg-muted</XDSText>
+ <XDSText type="supporting" color="secondary">
+ Subtle emphasis
+ </XDSText>
+ </div>
+ </div>
+
+ {/* Status colors */}
+ <div className="flex flex-wrap gap-3">
+ <div className="flex items-center gap-2 rounded-md bg-success/10 px-3 py-2">
+ <div className="h-2 w-2 rounded-full bg-success" />
+ <XDSText type="supporting" weight="bold">Success</XDSText>
+ </div>
+ <div className="flex items-center gap-2 rounded-md bg-error/10 px-3 py-2">
+ <div className="h-2 w-2 rounded-full bg-error" />
+ <XDSText type="supporting" weight="bold">Error</XDSText>
+ </div>
+ <div className="flex items-center gap-2 rounded-md bg-warning/10 px-3 py-2">
+ <div className="h-2 w-2 rounded-full bg-warning" />
+ <XDSText type="supporting" weight="bold">Warning</XDSText>
+ </div>
+ </div>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* Profile cards using XDS components in Tailwind grid */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Components + Layout</XDSHeading>
+ <XDSText type="supporting" color="secondary">
+ XDS components arranged with Tailwind grid utilities.
+ </XDSText>
+
+ <div className="grid grid-cols-2 gap-4">
+ <XDSCard>
+ <XDSVStack gap={3}>
+ <XDSHStack gap={2} vAlign="center">
+ <XDSAvatar name="Alice Chen" size="small" />
+ <XDSVStack gap={0}>
+ <XDSText type="label">Alice Chen</XDSText>
+ <XDSText type="supporting" color="secondary">
+ Design Engineer
+ </XDSText>
+ </XDSVStack>
+ </XDSHStack>
+ <XDSHStack gap={2}>
+ <XDSBadge variant="info" label="Design Systems" />
+ <XDSBadge variant="success" label="React" />
+ </XDSHStack>
+ <XDSButton label="View Profile" variant="secondary" />
+ </XDSVStack>
+ </XDSCard>
+
+ <XDSCard>
+ <XDSVStack gap={3}>
+ <XDSHStack gap={2} vAlign="center">
+ <XDSAvatar name="Bob Park" size="small" />
+ <XDSVStack gap={0}>
+ <XDSText type="label">Bob Park</XDSText>
+ <XDSText type="supporting" color="secondary">
+ Frontend Engineer
+ </XDSText>
+ </XDSVStack>
+ </XDSHStack>
+ <XDSHStack gap={2}>
+ <XDSBadge variant="info" label="TypeScript" />
+ <XDSBadge variant="warning" label="Infra" />
+ </XDSHStack>
+ <XDSButton label="View Profile" variant="secondary" />
+ </XDSVStack>
+ </XDSCard>
+ </div>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* Form section */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Contact Form</XDSHeading>
+ <XDSCard>
+ <XDSVStack gap={4}>
+ <div className="grid grid-cols-2 gap-4">
+ <XDSTextInput
+ label="Name"
+ placeholder="Your name"
+ value={name}
+ onChange={setName}
+ />
+ <XDSTextInput
+ label="Email"
+ placeholder="[email protected]"
+ value={email}
+ onChange={setEmail}
+ />
+ </div>
+ <XDSHStack gap={2}>
+ <XDSButton label="Submit" variant="primary" />
+ <XDSButton label="Cancel" variant="ghost" />
+ </XDSHStack>
+ </XDSVStack>
+ </XDSCard>
+ </XDSVStack>
+
+ <XDSDivider />
+
+ {/* Hue palette using bridge */}
+ <XDSVStack gap={3}>
+ <XDSHeading level={2}>Color Palette</XDSHeading>
+ <XDSText type="supporting" color="secondary">
+ Hue tokens from XDS, accessible as Tailwind utilities.
+ </XDSText>
+ <div className="grid grid-cols-5 gap-3">
+ <div className="rounded-md border border-blue-ring bg-blue-subtle p-3 text-center">
+ <XDSText type="supporting" weight="bold">Blue</XDSText>
+ </div>
+ <div className="rounded-md border border-green-ring bg-green-subtle p-3 text-center">
+ <XDSText type="supporting" weight="bold">Green</XDSText>
+ </div>
+ <div className="rounded-md border border-purple-ring bg-purple-subtle p-3 text-center">
+ <XDSText type="supporting" weight="bold">Purple</XDSText>
+ </div>
+ <div className="rounded-md border border-orange-ring bg-orange-subtle p-3 text-center">
+ <XDSText type="supporting" weight="bold">Orange</XDSText>
+ </div>
+ <div className="rounded-md border border-red-ring bg-red-subtle p-3 text-center">
+ <XDSText type="supporting" weight="bold">Red</XDSText>
+ </div>
+ </div>
+ </XDSVStack>
+ </XDSVStack>
+ </div>
+ </main>
+ </XDSTheme>
+ );
+}
diff --git a/apps/example-vite-tailwind/src/css.d.ts b/apps/example-vite-tailwind/src/css.d.ts
new file mode 100644
index 0000000000..bb74e7b7da
--- /dev/null
+++ b/apps/example-vite-tailwind/src/css.d.ts
@@ -0,0 +1,6 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+declare module '*.css' {
+ const content: string;
+ export default content;
+}
diff --git a/apps/example-vite-tailwind/src/index.css b/apps/example-vite-tailwind/src/index.css
new file mode 100644
index 0000000000..3794854764
--- /dev/null
+++ b/apps/example-vite-tailwind/src/index.css
@@ -0,0 +1,17 @@
+/* Copyright (c) Meta Platforms, Inc. and affiliates. */
+
+/*
+ * Layer order for XDS + Tailwind coexistence in Vite.
+ *
+ * Desired priority (lowest → highest):
+ * reset → theme → base → xds-base → xds-theme → components → utilities
+ */
+@layer reset, theme, base, xds-base, xds-theme, components, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "@xds/core/reset.css";
+@import "@xds/core/xds.css";
+@import "@xds/theme-default/theme.css";
+@import "@xds/core/tailwind-theme.css";
+@import "tailwindcss/utilities.css" layer(utilities);
diff --git a/apps/example-vite-tailwind/src/main.tsx b/apps/example-vite-tailwind/src/main.tsx
new file mode 100644
index 0000000000..832c649fc7
--- /dev/null
+++ b/apps/example-vite-tailwind/src/main.tsx
@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {StrictMode} from 'react';
+import {createRoot} from 'react-dom/client';
+import './index.css';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+ <StrictMode>
+ <App />
+ </StrictMode>,
+);
diff --git a/apps/example-vite-tailwind/tsconfig.json b/apps/example-vite-tailwind/tsconfig.json
new file mode 100644
index 0000000000..f1f466d60c
--- /dev/null
+++ b/apps/example-vite-tailwind/tsconfig.json
@@ -0,0 +1,24 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "useDefineForClassFields": true,
+ "lib": [
+ "ES2020",
+ "DOM",
+ "DOM.Iterable"
+ ],
+ "module": "ESNext",
+ "skipLibCheck": true,
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "isolatedModules": true,
+ "moduleDetection": "force",
+ "noEmit": true,
+ "jsx": "react-jsx",
+ "strict": true,
+ "verbatimModuleSyntax": false
+ },
+ "include": [
+ "src"
+ ]
+}
diff --git a/apps/example-vite-tailwind/vite.config.ts b/apps/example-vite-tailwind/vite.config.ts
new file mode 100644
index 0000000000..1a891b0cf5
--- /dev/null
+++ b/apps/example-vite-tailwind/vite.config.ts
@@ -0,0 +1,9 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {defineConfig} from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+ plugins: [tailwindcss(), react()],
+});
diff --git a/yarn.lock b/yarn.lock
index b005552c5c..7db0a1d829 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2914,6 +2914,15 @@
postcss "^8.5.10"
tailwindcss "4.3.0"
+"@tailwindcss/vite@^4":
+ version "4.3.0"
+ resolved "https://registry.yarnpkg.com/@tailwindcss/vite/-/vite-4.3.0.tgz#b2bbc069a4c700ea7aef5ee30416d84b7652e136"
+ integrity sha512-t6J3OrB5Fc0ExuhohouH0fWUGMYL6PTLhW+E7zIk/pdbnJARZDCwjBznFnkh5ynRnIRSI4YjtTH0t6USjJISrw==
+ dependencies:
+ "@tailwindcss/node" "4.3.0"
+ "@tailwindcss/oxide" "4.3.0"
+ tailwindcss "4.3.0"
+
"@testing-library/dom@^10.0.0":
version "10.4.1"
resolved "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz"