Skip to content

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

TypeScript

feat(theme): syntax theme system with 11 community presets (#1217)

Cindy Zhangf3d27db8e96c
diff --git a/apps/storybook/package.json b/apps/storybook/package.json
index a621c3d1a1..0c5c5239d3 100644
--- a/apps/storybook/package.json
+++ b/apps/storybook/package.json
@@ -11,7 +11,8 @@
"react": "^19.2.4",
"react-dom": "^19.2.4",
"@xds/theme-default": "*",
- "@xds/theme-neutral": "*"
+ "@xds/theme-neutral": "*",
+ "@xds/theme-syntax": "*"
},
"devDependencies": {
"@storybook/addon-essentials": "^8.6.17",
diff --git a/apps/storybook/stories/CodeTheme.stories.tsx b/apps/storybook/stories/CodeTheme.stories.tsx
new file mode 100644
index 0000000000..37626e956f
--- /dev/null
+++ b/apps/storybook/stories/CodeTheme.stories.tsx
@@ -0,0 +1,279 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import React from 'react';
+import {XDSCodeBlock} from '@xds/core/CodeBlock';
+import {XDSSyntaxTheme as SyntaxThemeProvider} from '@xds/core/theme/syntax';
+import {
+ oneDarkPro,
+ dracula,
+ monokai,
+ nord,
+ tokyoNight,
+ catppuccinMocha,
+ githubLight,
+ solarizedLight,
+ oneLight,
+ catppuccinLatte,
+ tokyoNightLight,
+ allSyntaxPresets,
+} from '@xds/theme-syntax';
+
+const sampleCode = [
+ "import {useState, useEffect} from 'react';",
+ '',
+ 'interface User {',
+ ' id: string;',
+ ' name: string;',
+ ' roles: string[];',
+ '}',
+ '',
+ 'const API_URL = "https://api.example.com";',
+ 'const MAX_RETRIES = 3;',
+ '',
+ '// Fetch user data with retry logic',
+ 'async function fetchUser(id: string): Promise<User> {',
+ ' const response = await fetch(`${API_URL}/users/${id}`);',
+ ' if (!response.ok) {',
+ ' throw new Error(`HTTP ${response.status}`);',
+ ' }',
+ ' return response.json();',
+ '}',
+ '',
+ 'export function UserCard({id}: {id: string}) {',
+ ' const [user, setUser] = useState<User | null>(null);',
+ '',
+ ' useEffect(() => {',
+ ' fetchUser(id).then(setUser);',
+ ' }, [id]);',
+ '',
+ ' if (!user) return <div>Loading...</div>;',
+ '',
+ ' return (',
+ ' <div className="card">',
+ ' <h2>{user.name}</h2>',
+ ' <span>{user.roles.length} roles</span>',
+ ' </div>',
+ ' );',
+ '}',
+].join('\n');
+
+const meta: Meta = {
+ title: 'Theme/XDSSyntaxTheme',
+ tags: ['autodocs'],
+ parameters: {
+ docs: {
+ description: {
+ component:
+ 'Syntax theme provider for code components. Wraps XDSCodeBlock and XDSCodeEditor ' +
+ 'to apply community syntax color themes. 11 presets ship in @xds/theme-syntax.',
+ },
+ },
+ },
+};
+
+export default meta;
+
+// ---------------------------------------------------------------------------
+// Individual theme stories
+// ---------------------------------------------------------------------------
+
+export const OneDarkPro: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={oneDarkPro}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const Dracula: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={dracula}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const Monokai: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={monokai}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const Nord: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={nord}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const TokyoNight: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={tokyoNight}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const CatppuccinMocha: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={catppuccinMocha}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const GitHubLight: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={githubLight}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const SolarizedLight: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={solarizedLight}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const OneLight: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={oneLight}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const CatppuccinLatte: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={catppuccinLatte}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+export const TokyoNightLight: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={tokyoNightLight}>
+ <XDSCodeBlock
+ code={sampleCode}
+ language="typescript"
+ title="UserCard.tsx"
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ),
+};
+
+// ---------------------------------------------------------------------------
+// Gallery — all themes side by side
+// ---------------------------------------------------------------------------
+
+const shortCode = [
+ 'const greet = (name: string) => {',
+ ' // Say hello',
+ ' return `Hello, ${name}!`;',
+ '};',
+ '',
+ 'const result = greet("World");',
+ 'console.log(result); // Hello, World!',
+].join('\n');
+
+export const AllThemesGallery: StoryObj = {
+ render: () => (
+ <div style={{display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16}}>
+ {allSyntaxPresets.map((theme) => (
+ <SyntaxThemeProvider key={theme.name} theme={theme}>
+ <XDSCodeBlock
+ code={shortCode}
+ language="typescript"
+ title={theme.name}
+ hasLineNumbers
+ />
+ </SyntaxThemeProvider>
+ ))}
+ </div>
+ ),
+ parameters: {
+ layout: 'padded',
+ },
+};
+
+// ---------------------------------------------------------------------------
+// Nested override — provider sets base, inner provider overrides
+// ---------------------------------------------------------------------------
+
+export const NestedOverride: StoryObj = {
+ render: () => (
+ <SyntaxThemeProvider theme={nord}>
+ <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
+ <XDSCodeBlock
+ code="// Inherits Nord from provider"
+ language="typescript"
+ title="nord (from provider)"
+ />
+ <SyntaxThemeProvider theme={dracula}>
+ <XDSCodeBlock
+ code="// Inner provider overrides to Dracula"
+ language="typescript"
+ title="dracula (inner override)"
+ />
+ </SyntaxThemeProvider>
+ </div>
+ </SyntaxThemeProvider>
+ ),
+};
diff --git a/package.json b/package.json
index e2857de07b..5bc0e41e49 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 && yarn workspace @xds/theme-daily build && yarn workspace @xds/theme-whatsapp build && yarn workspace @xds/theme-meta 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-daily build && yarn workspace @xds/theme-whatsapp build && yarn workspace @xds/theme-meta build && yarn workspace @xds/theme-syntax build",
"dev": "yarn workspace @xds/storybook dev",
"test": "vitest run",
"test:watch": "vitest",
diff --git a/packages/core/package.json b/packages/core/package.json
index b0bc757422..d86dd63742 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -27,6 +27,12 @@
"import": "./dist/theme/tokens.stylex.mjs",
"require": "./dist/theme/tokens.stylex.js"
},
+ "./theme/syntax": {
+ "source": "./src/theme/syntax/index.ts",
+ "types": "./dist/theme/syntax/index.d.ts",
+ "import": "./dist/theme/syntax/index.mjs",
+ "require": "./dist/theme/syntax/index.js"
+ },
"./xds.md": "./xds.md",
"./AppShell": {
"source": "./src/AppShell/index.ts",
diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.tsx b/packages/core/src/CodeBlock/XDSCodeBlock.tsx
index d4dd08c7b5..f8452de3d8 100644
--- a/packages/core/src/CodeBlock/XDSCodeBlock.tsx
+++ b/packages/core/src/CodeBlock/XDSCodeBlock.tsx
@@ -46,7 +46,7 @@ const styles = stylex.create({
position: 'relative',
margin: 0,
borderRadius: radiusVars['--radius-element'],
- backgroundColor: colorVars['--color-background-muted'],
+ backgroundColor: 'var(--color-syntax-background)',
border: `${borderVars['--border-width']} solid ${colorVars['--color-border']}`,
overflow: 'hidden',
},
@@ -57,13 +57,13 @@ const styles = stylex.create({
paddingBlock: spacingVars['--spacing-2'],
paddingInline: spacingVars['--spacing-4'],
borderBottom: `${borderVars['--border-width']} solid ${colorVars['--color-border']}`,
- backgroundColor: colorVars['--color-background-surface'],
+ backgroundColor: 'var(--color-syntax-background)',
},
headerTitle: {
fontSize: textSizeVars['--font-size-sm'],
fontFamily: typographyVars['--font-family-code'],
fontWeight: fontWeightVars['--font-weight-medium'],
- color: colorVars['--color-text-secondary'],
+ color: 'var(--color-syntax-comment)',
margin: 0,
lineHeight: typeScaleVars['--text-supporting-leading'],
},
@@ -82,7 +82,7 @@ const styles = stylex.create({
paddingInlineEnd: spacingVars['--spacing-3'],
textAlign: 'end',
userSelect: 'none',
- color: colorVars['--color-text-disabled'],
+ color: 'var(--color-syntax-punctuation)',
borderRight: `${borderVars['--border-width']} solid ${colorVars['--color-border']}`,
},
gutterLine: {
@@ -96,7 +96,7 @@ const styles = stylex.create({
paddingInline: spacingVars['--spacing-4'],
margin: 0,
fontFamily: typographyVars['--font-family-code'],
- color: colorVars['--color-text-primary'],
+ color: 'var(--color-syntax-variable)',
tabSize: 2,
whiteSpace: 'pre',
wordBreak: 'normal',
@@ -140,7 +140,7 @@ const styles = stylex.create({
default: 'transparent',
':hover': colorVars['--color-overlay-hover'],
},
- color: colorVars['--color-text-secondary'],
+ color: 'var(--color-syntax-comment)',
cursor: 'pointer',
lineHeight: 0,
},
diff --git a/packages/core/src/theme/domainTokens/index.ts b/packages/core/src/theme/domainTokens/index.ts
index f6b110eb68..d50b0c6237 100644
--- a/packages/core/src/theme/domainTokens/index.ts
+++ b/packages/core/src/theme/domainTokens/index.ts
@@ -1,38 +1,22 @@
/**
* @file domainTokens/index.ts
* @input None (re-exports sub-modules)
- * @output domainTokenDefaults, DomainTokenName, and all sub-module exports
- * @position Token definitions; consumed by defineTheme for validation + autocomplete
+ * @output domainTokenDefaults, DomainTokenName
+ * @position Token aggregator; consumed by defineTheme for validation + autocomplete
*
- * Domain tokens are color tokens owned by specific feature areas (code
- * highlighting, data visualization, etc.) that don't belong in the core
- * color palette but still need to be theme-overridable.
- *
- * These are in a SEPARATE file from tokens.stylex.ts so they're
- * tree-shakeable — importing core components doesn't pull these in.
- * Only defineTheme and domain components reference this file.
- *
- * Sub-modules:
- * - syntaxTokens.ts — code syntax highlighting (used by CodeBlock)
- * - dataTokens.ts — data visualization palette (charts, graphs)
- *
- * SYNC: When adding a new domain, update:
- * - Add a new sub-module file here (e.g. mapTokens.ts)
- * - Re-export it below and merge into domainTokenDefaults
- * - Update DomainTokenName union
- * - /packages/core/src/theme/defineTheme.ts (XDSTokenName union picks this up automatically)
- * - /packages/core/src/theme/index.ts (re-export the new type if needed)
+ * Merges all domain token defaults into a single map for defineTheme.
+ * Actual token definitions live in their own directories (syntax/, dataviz/).
*/
-export {syntaxTokenDefaults} from './syntaxTokens';
-export type {SyntaxTokenName} from './syntaxTokens';
+export {syntaxTokenDefaults} from '../syntax/tokens';
+export type {SyntaxTokenName} from '../syntax/tokens';
export {dataTokenDefaults} from './dataTokens';
export type {DataTokenName} from './dataTokens';
-import {syntaxTokenDefaults} from './syntaxTokens';
+import {syntaxTokenDefaults} from '../syntax/tokens';
import {dataTokenDefaults} from './dataTokens';
-import type {SyntaxTokenName} from './syntaxTokens';
+import type {SyntaxTokenName} from '../syntax/tokens';
import type {DataTokenName} from './dataTokens';
/** All domain token defaults merged — used by defineTheme for validation */
diff --git a/packages/core/src/theme/domainTokens/syntaxTokens.ts b/packages/core/src/theme/domainTokens/syntaxTokens.ts
deleted file mode 100644
index 2aec1ea48d..0000000000
--- a/packages/core/src/theme/domainTokens/syntaxTokens.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-/**
- * @file syntaxTokens.ts
- * @input None (pure token definitions)
- * @output syntaxTokenDefaults, SyntaxTokenName
- * @position Domain token sub-module; re-exported from domainTokens/index.ts
- *
- * Code syntax highlighting tokens. Used by the CodeBlock component and any
- * consumer that renders highlighted source code.
- */
-
-export const syntaxTokenDefaults = {
- // keyword → accent (primary emphasis, control flow)
- '--color-syntax-keyword': 'light-dark(#0064E0, #2694FE)',
- // string → green-text
- '--color-syntax-string': 'light-dark(#09441F, #A5F690)',
- // comment → text-secondary (de-emphasized)
- '--color-syntax-comment': 'light-dark(#4E606F, #AAAFB5)',
- // number → orange-text (warm tone for constants)
- '--color-syntax-number': 'light-dark(#6B2203, #FDB876)',
- // function → blue-text (structural landmarks)
- '--color-syntax-function': 'light-dark(#042F97, #AFD7FF)',
- // type → purple-text (type system, interfaces)
- '--color-syntax-type': 'light-dark(#3E0697, #B3B0FE)',
- // variable → text-primary (neutral body text)
- '--color-syntax-variable': 'light-dark(#0A1317, #DFE2E5)',
- // operator → text-secondary
- '--color-syntax-operator': 'light-dark(#4E606F, #AAAFB5)',
- // constant → orange-text (true/false/null, same family as numbers)
- '--color-syntax-constant': 'light-dark(#6B2203, #FDB876)',
- // tag → red-text (HTML/JSX tags)
- '--color-syntax-tag': 'light-dark(#7B0210, #FFB2B8)',
- // attribute → orange-text (HTML/JSX attributes)
- '--color-syntax-attribute': 'light-dark(#6B2203, #FDB876)',
- // property → cyan-text (object properties, distinct from functions)
- '--color-syntax-property': 'light-dark(#006064, #B2EBF2)',
- // punctuation → text-disabled (most de-emphasized)
- '--color-syntax-punctuation': 'light-dark(#A4B0BC, #6F747C)',
-} as const;
-
-export type SyntaxTokenName = keyof typeof syntaxTokenDefaults;
diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.ts
index dfdcf2334d..3459e5a471 100644
--- a/packages/core/src/theme/index.ts
+++ b/packages/core/src/theme/index.ts
@@ -42,6 +42,22 @@ export type {SyntaxTokenName, DomainTokenName} from './domainTokens';
export {syntaxTokenDefaults, domainTokenDefaults} from './domainTokens';
+// Syntax theme API
+export {
+ defineSyntaxTheme,
+ syntaxThemeStyle,
+ syntaxThemeToCSS,
+} from './syntax';
+export type {
+ SyntaxTheme,
+ SyntaxThemeInput,
+ SyntaxThemeTokenKey,
+ SyntaxThemeTokenMap,
+} from './syntax';
+
+// XDSSyntaxTheme provider
+export {XDSSyntaxTheme, useSyntaxTheme} from './syntax';
+
export {expandTypeScale, generateTypeScaleComponents} from './expandTypeScale';
export type {XDSTypeScaleConfig, TypeScaleTokens} from './expandTypeScale';
diff --git a/packages/core/src/theme/syntax/XDSSyntaxTheme.tsx b/packages/core/src/theme/syntax/XDSSyntaxTheme.tsx
new file mode 100644
index 0000000000..3b939b0205
--- /dev/null
+++ b/packages/core/src/theme/syntax/XDSSyntaxTheme.tsx
@@ -0,0 +1,68 @@
+"use client";
+
+/**
+ * @file XDSSyntaxTheme.tsx
+ * @input XDSSyntaxTheme type from defineSyntaxTheme.ts
+ * @output XDSSyntaxTheme provider, useSyntaxTheme hook
+ * @position Provider component; wraps code surfaces to apply syntax coloring
+ *
+ * Sets syntax color tokens as CSS custom properties on a wrapper element.
+ * Any XDSCodeBlock or XDSCodeEditor inside inherits these colors via
+ * CSS variable cascade.
+ *
+ * Cascading priority (highest wins):
+ * 1. syntaxTheme prop on individual code components (inline style)
+ * 2. XDSSyntaxTheme provider (closer ancestor)
+ * 3. syntax field in defineTheme() (theme root)
+ * 4. Built-in XDS default syntax token values (CSS fallbacks)
+ *
+ * @see https://github.com/facebookexperimental/xds/issues/1148
+ */
+
+import React, {createContext, useContext, useMemo} from 'react';
+import {syntaxThemeStyle, type SyntaxTheme} from './defineSyntaxTheme';
+
+// =============================================================================
+// Context
+// =============================================================================
+
+const SyntaxThemeContext = createContext<SyntaxTheme | null>(null);
+
+/**
+ * Read the current syntax theme from context.
+ * Returns null if no XDSSyntaxTheme provider is present.
+ */
+export function useSyntaxTheme(): SyntaxTheme | null {
+ return useContext(SyntaxThemeContext);
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+interface XDSSyntaxThemeProps {
+ theme: SyntaxTheme;
+ children: React.ReactNode;
+}
+
+/**
+ * Syntax theme provider. Sets CSS custom properties on a wrapper div
+ * so child code components inherit via cascade. Also exposes the theme
+ * object via React context for programmatic access.
+ */
+export function XDSSyntaxTheme({
+ theme,
+ children,
+}: XDSSyntaxThemeProps): React.ReactElement {
+ const style = useMemo(() => syntaxThemeStyle(theme), [theme]);
+
+ return (
+ <SyntaxThemeContext.Provider value={theme}>
+ <div style={style} data-xds-syntax-theme={theme.name}>
+ {children}
+ </div>
+ </SyntaxThemeContext.Provider>
+ );
+}
+
+XDSSyntaxTheme.displayName = 'XDSSyntaxTheme';
diff --git a/packages/core/src/theme/syntax/defineSyntaxTheme.ts b/packages/core/src/theme/syntax/defineSyntaxTheme.ts
new file mode 100644
index 0000000000..0a5d8fd412
--- /dev/null
+++ b/packages/core/src/theme/syntax/defineSyntaxTheme.ts
@@ -0,0 +1,106 @@
+"use strict";
+
+/**
+ * @file defineSyntaxTheme.ts
+ * @input syntaxTokenDefaults from tokens.ts
+ * @output defineSyntaxTheme, SyntaxTheme, syntaxThemeStyle
+ * @position Syntax theme definition API; consumed by presets, XDSCodeTheme, defineTheme
+ *
+ * @see https://github.com/facebookexperimental/xds/issues/1148
+ */
+
+import {syntaxTokenDefaults, type SyntaxTokenName} from './tokens';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Human-readable syntax token name (without CSS custom property prefix). */
+export type SyntaxThemeTokenKey =
+ | 'keyword'
+ | 'string'
+ | 'comment'
+ | 'number'
+ | 'function'
+ | 'type'
+ | 'variable'
+ | 'operator'
+ | 'constant'
+ | 'tag'
+ | 'attribute'
+ | 'property'
+ | 'punctuation'
+ | 'background';
+
+/** A complete mapping of token names to CSS color values. */
+export type SyntaxThemeTokenMap = Record<SyntaxThemeTokenKey, string>;
+
+export interface SyntaxThemeInput {
+ name: string;
+ tokens: SyntaxThemeTokenMap;
+}
+
+/** A defined syntax theme. */
+export interface SyntaxTheme {
+ name: string;
+ tokens: SyntaxThemeTokenMap;
+}
+
+// =============================================================================
+// Token key <-> CSS property mapping
+// =============================================================================
+
+const CSS_PREFIX = '--color-syntax-';
+
+function toCSSProperty(key: SyntaxThemeTokenKey): SyntaxTokenName {
+ return (CSS_PREFIX + key) as SyntaxTokenName;
+}
+
+const ALL_KEYS: SyntaxThemeTokenKey[] = Object.keys(syntaxTokenDefaults)
+ .map(k => k.replace(CSS_PREFIX, '') as SyntaxThemeTokenKey);
+
+// =============================================================================
+// defineSyntaxTheme
+// =============================================================================
+
+/**
+ * Create a syntax theme from a complete token map.
+ *
+ * @example
+ * const dracula = defineSyntaxTheme({
+ * name: 'dracula',
+ * tokens: { keyword: '#ff79c6', string: '#f1fa8c', ... },
+ * });
+ */
+export function defineSyntaxTheme(input: SyntaxThemeInput): SyntaxTheme {
+ const missing = ALL_KEYS.filter(key => !(key in input.tokens));
+ if (missing.length > 0) {
+ console.warn(
+ '[XDS] defineSyntaxTheme("' + input.name + '"): missing tokens: ' +
+ missing.join(', ') + '. All 14 syntax tokens are required.',
+ );
+ }
+ return {name: input.name, tokens: {...input.tokens}};
+}
+
+// =============================================================================
+// Utilities
+// =============================================================================
+
+/** Generate a CSS custom property style object for React's style prop. */
+export function syntaxThemeStyle(
+ theme: SyntaxTheme,
+): Record<string, string> {
+ const vars: Record<string, string> = {};
+ for (const key of ALL_KEYS) {
+ vars[toCSSProperty(key)] = theme.tokens[key];
+ }
+ return vars;
+}
+
+/** Convert a syntax theme to CSS declarations (no selector wrapper). */
+export function syntaxThemeToCSS(theme: SyntaxTheme): string {
+ return ALL_KEYS
+ .map(key => toCSSProperty(key) + ': ' + theme.tokens[key] + ';')
+ .join('\n ');
+}
diff --git a/packages/core/src/theme/syntax/index.ts b/packages/core/src/theme/syntax/index.ts
new file mode 100644
index 0000000000..83c185bdb4
--- /dev/null
+++ b/packages/core/src/theme/syntax/index.ts
@@ -0,0 +1,19 @@
+'use client';
+
+/**
+ * @file syntax/index.ts
+ * @position Re-exports for the syntax theme subsystem
+ */
+
+export {syntaxTokenDefaults} from './tokens';
+export type {SyntaxTokenName} from './tokens';
+
+export {defineSyntaxTheme, syntaxThemeStyle, syntaxThemeToCSS} from './defineSyntaxTheme';
+export type {
+ SyntaxTheme,
+ SyntaxThemeInput,
+ SyntaxThemeTokenKey,
+ SyntaxThemeTokenMap,
+} from './defineSyntaxTheme';
+
+export {XDSSyntaxTheme, useSyntaxTheme} from './XDSSyntaxTheme';
diff --git a/packages/core/src/theme/syntax/tokens.ts b/packages/core/src/theme/syntax/tokens.ts
new file mode 100644
index 0000000000..8e7be26fe4
--- /dev/null
+++ b/packages/core/src/theme/syntax/tokens.ts
@@ -0,0 +1,47 @@
+/**
+ * @file syntaxTokens.ts
+ * @input None (pure token definitions)
+ * @output syntaxTokenDefaults, SyntaxTokenName
+ * @position Domain token sub-module; re-exported from domainTokens/index.ts
+ *
+ * Code syntax highlighting tokens. Used by the CodeBlock component and any
+ * consumer that renders highlighted source code.
+ *
+ * 14-token architecture validated against 11 community code themes.
+ * All themes map cleanly to these 14 slots.
+ *
+ * @see https://github.com/facebookexperimental/xds/issues/1148
+ */
+
+export const syntaxTokenDefaults = {
+ // keyword → accent (primary emphasis, control flow: if, return, const)
+ '--color-syntax-keyword': 'light-dark(#0064E0, #2694FE)',
+ // string → green-text (string literals)
+ '--color-syntax-string': 'light-dark(#09441F, #A5F690)',
+ // comment → subdued (passive annotations, deliberately muted)
+ '--color-syntax-comment': 'light-dark(#4E606F, #6B7D8D)',
+ // number → orange-text (warm tone for numeric literals)
+ '--color-syntax-number': 'light-dark(#6B2203, #FDB876)',
+ // function → blue-text (structural landmarks: function/method names)
+ '--color-syntax-function': 'light-dark(#042F97, #AFD7FF)',
+ // type → purple-text (type system: interfaces, classes, generics)
+ '--color-syntax-type': 'light-dark(#3E0697, #B3B0FE)',
+ // variable → text-primary (neutral identifiers, close to body text)
+ '--color-syntax-variable': 'light-dark(#0A1317, #DFE2E5)',
+ // operator → teal (active syntax: =, +, =>, &&, !==) — separated from comment
+ '--color-syntax-operator': 'light-dark(#006D75, #56C8D8)',
+ // constant → orange-text (true/false/null, same family as numbers)
+ '--color-syntax-constant': 'light-dark(#6B2203, #FDB876)',
+ // tag → red-text (HTML/JSX tags: <div>, <Button>)
+ '--color-syntax-tag': 'light-dark(#7B0210, #FFB2B8)',
+ // attribute → warm amber (HTML/JSX attributes) — separated from number
+ '--color-syntax-attribute': 'light-dark(#7A4F1A, #E8C580)',
+ // property → cyan-text (object properties, distinct from functions)
+ '--color-syntax-property': 'light-dark(#006064, #B2EBF2)',
+ // punctuation → muted (brackets, semicolons) — contrast fixed for light mode
+ '--color-syntax-punctuation': 'light-dark(#65737E, #6F747C)',
+ // background → code block surface color
+ '--color-syntax-background': 'light-dark(#FFFFFF, #1A1A1A)',
+} as const;
+
+export type SyntaxTokenName = keyof typeof syntaxTokenDefaults;
diff --git a/packages/core/tsup.config.ts b/packages/core/tsup.config.ts
index 9f4bde2d45..e2de972bde 100644
--- a/packages/core/tsup.config.ts
+++ b/packages/core/tsup.config.ts
@@ -15,7 +15,7 @@ import {defineConfig} from 'tsup';
import babel from 'esbuild-plugin-babel';
export default defineConfig({
- entry: ['src/index.ts', 'src/*/index.ts', 'src/theme/tokens.stylex.ts'],
+ entry: ['src/index.ts', 'src/*/index.ts', 'src/theme/tokens.stylex.ts', 'src/theme/syntax/index.ts'],
format: ['cjs', 'esm'],
dts: false,
splitting: true,
diff --git a/packages/themes/syntax/THIRD_PARTY_LICENSES.md b/packages/themes/syntax/THIRD_PARTY_LICENSES.md
new file mode 100644
index 0000000000..7501356a0d
--- /dev/null
+++ b/packages/themes/syntax/THIRD_PARTY_LICENSES.md
@@ -0,0 +1,57 @@
+# Third-Party Licenses
+
+This package contains syntax color palettes derived from the following
+open-source themes. All original themes are licensed under the MIT License.
+Only color values have been extracted — no source code from these projects
+is included.
+
+## One Dark Pro
+- Source: https://github.com/Binaryify/OneDark-Pro
+- Author: Binaryify
+- License: MIT
+- Original: Atom One Dark by GitHub (atom/one-dark-syntax)
+
+## Dracula
+- Source: https://github.com/dracula/visual-studio-code
+- Author: Zeno Rocha and contributors
+- License: MIT
+- Website: https://draculatheme.com
+
+## Monokai
+- Source: Built-in VS Code theme (https://github.com/microsoft/vscode)
+- Author: Microsoft Corporation
+- License: MIT
+- Original: Monokai by Wimer Hazenberg (monokai.nl)
+
+## Nord
+- Source: https://github.com/nordtheme/visual-studio-code
+- Author: Sven Greb (Arctic Ice Studio) and contributors
+- License: MIT
+- Website: https://www.nordtheme.com
+
+## Tokyo Night
+- Source: https://github.com/tokyo-night/tokyo-night-vscode-theme
+- Author: enkia and contributors
+- License: MIT
+
+## Catppuccin (Mocha + Latte)
+- Source: https://github.com/catppuccin/vscode
+- Author: Catppuccin contributors
+- License: MIT
+- Website: https://catppuccin.com
+
+## GitHub Light
+- Source: https://github.com/primer/github-vscode-theme
+- Author: GitHub (Primer team)
+- License: MIT
+
+## Solarized Light
+- Source: https://github.com/altercation/solarized
+- Author: Ethan Schoonover
+- License: MIT
+- Website: https://ethanschoonover.com/solarized
+
+## One Light
+- Source: https://github.com/atom/one-light-syntax
+- Author: GitHub (Atom team)
+- License: MIT
diff --git a/packages/themes/syntax/package.json b/packages/themes/syntax/package.json
new file mode 100644
index 0000000000..7c4ee12fa2
--- /dev/null
+++ b/packages/themes/syntax/package.json
@@ -0,0 +1,26 @@
+{
+ "name": "@xds/theme-syntax",
+ "version": "0.0.11",
+ "description": "Syntax highlighting theme presets for XDS \u2014 11 community themes mapped to the XDS 14-token syntax architecture",
+ "license": "MIT",
+ "sideEffects": false,
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.mjs",
+ "require": "./dist/index.js"
+ }
+ },
+ "files": [
+ "dist",
+ "src"
+ ],
+ "scripts": {
+ "build": "tsup"
+ },
+ "peerDependencies": {
+ "@xds/core": "*"
+ }
+}
diff --git a/packages/themes/syntax/src/index.ts b/packages/themes/syntax/src/index.ts
new file mode 100644
index 0000000000..d716e795aa
--- /dev/null
+++ b/packages/themes/syntax/src/index.ts
@@ -0,0 +1,32 @@
+/**
+ * @xds/theme-syntax — Community syntax theme presets for XDS
+ *
+ * 11 themes (6 dark, 5 light) mapped to the XDS 14-token syntax architecture.
+ * All original themes are MIT licensed. See THIRD_PARTY_LICENSES.md.
+ *
+ * @example
+ * import {dracula} from '@xds/theme-syntax';
+ * import {XDSCodeTheme} from '@xds/core/theme';
+ *
+ * <XDSCodeTheme theme={dracula}>
+ * <XDSCodeBlock code={code} />
+ * </XDSCodeTheme>
+ */
+
+// Dark themes
+export {oneDarkPro} from './presets';
+export {dracula} from './presets';
+export {monokai} from './presets';
+export {nord} from './presets';
+export {tokyoNight} from './presets';
+export {catppuccinMocha} from './presets';
+
+// Light themes
+export {githubLight} from './presets';
+export {solarizedLight} from './presets';
+export {oneLight} from './presets';
+export {catppuccinLatte} from './presets';
+export {tokyoNightLight} from './presets';
+
+// Collections
+export {darkSyntaxPresets, lightSyntaxPresets, allSyntaxPresets} from './presets';
diff --git a/packages/themes/syntax/src/presets.ts b/packages/themes/syntax/src/presets.ts
new file mode 100644
index 0000000000..76beb42c88
--- /dev/null
+++ b/packages/themes/syntax/src/presets.ts
@@ -0,0 +1,252 @@
+/**
+ * @file presets.ts
+ * @output 11 community syntax theme presets
+ *
+ * Color values sourced from each theme's official VS Code extension.
+ * All original themes are MIT licensed. Only color values are extracted.
+ * See THIRD_PARTY_LICENSES.md for full attribution.
+ *
+ * @see https://github.com/facebookexperimental/xds/issues/1148
+ */
+
+import {defineSyntaxTheme, type SyntaxTheme} from '@xds/core/theme/syntax';
+
+/** One Dark Pro (Binaryify) — MIT */
+export const oneDarkPro: SyntaxTheme = defineSyntaxTheme({
+ name: 'one-dark-pro',
+ tokens: {
+ keyword: '#c678dd',
+ string: '#98c379',
+ comment: '#5c6370',
+ number: '#d19a66',
+ function: '#61afef',
+ type: '#e5c07b',
+ variable: '#e06c75',
+ operator: '#56b6c2',
+ constant: '#d19a66',
+ tag: '#e06c75',
+ attribute: '#d19a66',
+ property: '#e06c75',
+ punctuation: '#abb2bf',
+ background: '#282c34',
+ },
+});
+
+/** Dracula (Zeno Rocha) — MIT */
+export const dracula: SyntaxTheme = defineSyntaxTheme({
+ name: 'dracula',
+ tokens: {
+ keyword: '#ff79c6',
+ string: '#f1fa8c',
+ comment: '#6272a4',
+ number: '#bd93f9',
+ function: '#50fa7b',
+ type: '#8be9fd',
+ variable: '#f8f8f2',
+ operator: '#ff79c6',
+ constant: '#bd93f9',
+ tag: '#ff79c6',
+ attribute: '#50fa7b',
+ property: '#66d9ef',
+ punctuation: '#f8f8f2',
+ background: '#282a36',
+ },
+});
+
+/** Monokai (Wimer Hazenberg, VS Code built-in) — MIT */
+export const monokai: SyntaxTheme = defineSyntaxTheme({
+ name: 'monokai',
+ tokens: {
+ keyword: '#f92672',
+ string: '#e6db74',
+ comment: '#75715e',
+ number: '#ae81ff',
+ function: '#a6e22e',
+ type: '#66d9ef',
+ variable: '#f8f8f2',
+ operator: '#f92672',
+ constant: '#ae81ff',
+ tag: '#f92672',
+ attribute: '#a6e22e',
+ property: '#66d9ef',
+ punctuation: '#f8f8f2',
+ background: '#272822',
+ },
+});
+
+/** Nord (Arctic Ice Studio / Sven Greb) — MIT */
+export const nord: SyntaxTheme = defineSyntaxTheme({
+ name: 'nord',
+ tokens: {
+ keyword: '#81a1c1',
+ string: '#a3be8c',
+ comment: '#616e88',
+ number: '#b48ead',
+ function: '#88c0d0',
+ type: '#8fbcbb',
+ variable: '#d8dee9',
+ operator: '#81a1c1',
+ constant: '#b48ead',
+ tag: '#81a1c1',
+ attribute: '#8fbcbb',
+ property: '#88c0d0',
+ punctuation: '#d8dee9',
+ background: '#2e3440',
+ },
+});
+
+/** Tokyo Night (enkia) — MIT */
+export const tokyoNight: SyntaxTheme = defineSyntaxTheme({
+ name: 'tokyo-night',
+ tokens: {
+ keyword: '#9d7cd8',
+ string: '#9ece6a',
+ comment: '#565f89',
+ number: '#ff9e64',
+ function: '#7aa2f7',
+ type: '#2ac3de',
+ variable: '#c0caf5',
+ operator: '#89ddff',
+ constant: '#ff9e64',
+ tag: '#f7768e',
+ attribute: '#bb9af7',
+ property: '#73daca',
+ punctuation: '#9abdf5',
+ background: '#1a1b26',
+ },
+});
+
+/** Catppuccin Mocha (Catppuccin contributors) — MIT */
+export const catppuccinMocha: SyntaxTheme = defineSyntaxTheme({
+ name: 'catppuccin-mocha',
+ tokens: {
+ keyword: '#cba6f7',
+ string: '#a6e3a1',
+ comment: '#6c7086',
+ number: '#fab387',
+ function: '#89b4fa',
+ type: '#f9e2af',
+ variable: '#cdd6f4',
+ operator: '#89dceb',
+ constant: '#fab387',
+ tag: '#f38ba8',
+ attribute: '#f9e2af',
+ property: '#94e2d5',
+ punctuation: '#bac2de',
+ background: '#1e1e2e',
+ },
+});
+
+/** GitHub Light (GitHub Primer team) — MIT */
+export const githubLight: SyntaxTheme = defineSyntaxTheme({
+ name: 'github-light',
+ tokens: {
+ keyword: '#cf222e',
+ string: '#0a3069',
+ comment: '#6e7781',
+ number: '#0550ae',
+ function: '#8250df',
+ type: '#953800',
+ variable: '#24292f',
+ operator: '#cf222e',
+ constant: '#0550ae',
+ tag: '#116329',
+ attribute: '#0550ae',
+ property: '#0550ae',
+ punctuation: '#24292f',
+ background: '#ffffff',
+ },
+});
+
+/** Solarized Light (Ethan Schoonover) — MIT */
+export const solarizedLight: SyntaxTheme = defineSyntaxTheme({
+ name: 'solarized-light',
+ tokens: {
+ keyword: '#859900',
+ string: '#2aa198',
+ comment: '#93a1a1',
+ number: '#d33682',
+ function: '#268bd2',
+ type: '#b58900',
+ variable: '#657b83',
+ operator: '#859900',
+ constant: '#cb4b16',
+ tag: '#268bd2',
+ attribute: '#b58900',
+ property: '#268bd2',
+ punctuation: '#586e75',
+ background: '#fdf6e3',
+ },
+});
+
+/** One Light (GitHub / Atom team) — MIT */
+export const oneLight: SyntaxTheme = defineSyntaxTheme({
+ name: 'one-light',
+ tokens: {
+ keyword: '#a626a4',
+ string: '#50a14f',
+ comment: '#a0a1a7',
+ number: '#986801',
+ function: '#4078f2',
+ type: '#c18401',
+ variable: '#e45649',
+ operator: '#0184bc',
+ constant: '#986801',
+ tag: '#e45649',
+ attribute: '#986801',
+ property: '#e45649',
+ punctuation: '#383a42',
+ background: '#fafafa',
+ },
+});
+
+/** Catppuccin Latte (Catppuccin contributors) — MIT */
+export const catppuccinLatte: SyntaxTheme = defineSyntaxTheme({
+ name: 'catppuccin-latte',
+ tokens: {
+ keyword: '#8839ef',
+ string: '#40a02b',
+ comment: '#9ca0b0',
+ number: '#fe640b',
+ function: '#1e66f5',
+ type: '#df8e1d',
+ variable: '#4c4f69',
+ operator: '#179299',
+ constant: '#fe640b',
+ tag: '#d20f39',
+ attribute: '#df8e1d',
+ property: '#179299',
+ punctuation: '#6c6f85',
+ background: '#eff1f5',
+ },
+});
+
+/** Tokyo Night Light (enkia) — MIT */
+export const tokyoNightLight: SyntaxTheme = defineSyntaxTheme({
+ name: 'tokyo-night-light',
+ tokens: {
+ keyword: '#8c4351',
+ string: '#485e30',
+ comment: '#9699a3',
+ number: '#965027',
+ function: '#34548a',
+ type: '#166775',
+ variable: '#343b58',
+ operator: '#34548a',
+ constant: '#965027',
+ tag: '#8c4351',
+ attribute: '#8f5e15',
+ property: '#33635c',
+ punctuation: '#343b58',
+ background: '#d5d6db',
+ },
+});
+
+/** All dark syntax theme presets */
+export const darkSyntaxPresets = [oneDarkPro, dracula, monokai, nord, tokyoNight, catppuccinMocha] as const;
+
+/** All light syntax theme presets */
+export const lightSyntaxPresets = [githubLight, solarizedLight, oneLight, catppuccinLatte, tokyoNightLight] as const;
+
+/** All syntax theme presets */
+export const allSyntaxPresets = [...darkSyntaxPresets, ...lightSyntaxPresets] as const;
diff --git a/packages/themes/syntax/tsup.config.ts b/packages/themes/syntax/tsup.config.ts
new file mode 100644
index 0000000000..5e3a45aff4
--- /dev/null
+++ b/packages/themes/syntax/tsup.config.ts
@@ -0,0 +1,8 @@
+import {defineConfig} from 'tsup';
+
+export default defineConfig({
+ entry: ['src/index.ts'],
+ format: ['cjs', 'esm'],
+ dts: true,
+ clean: true,
+});
diff --git a/scripts/sync-exports.js b/scripts/sync-exports.js
index 4257aa3462..106370deb6 100644
--- a/scripts/sync-exports.js
+++ b/scripts/sync-exports.js
@@ -50,6 +50,12 @@ const STATIC_EXPORTS = {
import: './dist/theme/tokens.stylex.mjs',
require: './dist/theme/tokens.stylex.js',
},
+ './theme/syntax': {
+ source: './src/theme/syntax/index.ts',
+ types: './dist/theme/syntax/index.d.ts',
+ import: './dist/theme/syntax/index.mjs',
+ require: './dist/theme/syntax/index.js',
+ },
'./xds.md': './xds.md',
};