Skip to content

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

TypeScript

fix: add typography styles to storybook and fix sandbox build config (#292)

Cindy Zhang72c0a8704ade
diff --git a/README.md b/README.md
index 51f07ff9bc..1233d427c0 100644
--- a/README.md
+++ b/README.md
@@ -25,37 +25,44 @@ npm install @xds/core
yarn add @xds/core
```
-### 1. Set Up the Theme Provider
+### 1. Import Base Styles
-Wrap your application with the `Theme` component. This sets up CSS custom properties used by all XDS components.
+Import the reset and typography stylesheets at the root of your application. These provide a clean cross-browser baseline and prose styles for native HTML elements.
```tsx
-import {Theme, defaultTheme} from '@xds/core';
+// In your root layout or entry point
+import '@xds/core/reset.css'; // Base reset — box-sizing, margins, etc.
+import '@xds/core/typography.css'; // Prose styles — headings, lists, code, etc.
+```
+
+The reset uses `@layer reset` and typography uses `@layer typography`, so they won't conflict with component styles.
+
+### 2. Set Up the Theme Provider
+
+Wrap your application with the `XDSTheme` component. This sets up CSS custom properties used by all XDS components and typography styles.
+
+```tsx
+import {XDSTheme} from '@xds/core';
+import {defaultTheme} from '@xds/theme-default';
function App() {
return (
- <Theme theme={defaultTheme}>
+ <XDSTheme theme={defaultTheme}>
<YourApp />
- </Theme>
+ </XDSTheme>
);
}
```
-### 2. Import Typography Styles (Optional)
-
-For styling native HTML elements (h1-h6, p, lists, code blocks, etc.), import the typography stylesheet:
-
-```tsx
-import '@xds/core/typography.css';
-```
+### 3. Apply Typography (Optional)
-Apply to your document body or use `XDSFontWrapper` for scoped sections:
+Typography styles activate via the `xds-typography` class or the `XDSFontWrapper` component. Choose one:
```tsx
-// Option A: Global - apply to body
+// Option A: Global — apply to body
<body className="xds-typography">
-// Option B: Scoped - wrap specific content
+// Option B: Scoped — wrap specific content
import { XDSFontWrapper } from '@xds/core';
<XDSFontWrapper>
@@ -75,7 +82,7 @@ The typography styles support two heading scales:
</XDSFontWrapper>
```
-### 3. Use Components
+### 4. Use Components
```tsx
import {XDSButton, XDSText, XDSHeading} from '@xds/core';
diff --git a/apps/sandbox/babel.config.js b/apps/sandbox/babel.config.js
index a358cce1e7..f6bab9468f 100644
--- a/apps/sandbox/babel.config.js
+++ b/apps/sandbox/babel.config.js
@@ -16,7 +16,8 @@ module.exports = {
aliases: {
'@xds/core/*': [path.join(rootDir, 'packages/core/src/*')],
'@xds/core': [path.join(rootDir, 'packages/core/src')],
- '@xds/theme/*': [path.join(rootDir, 'packages/theme/src/*')],
+ '@xds/theme-default/*': [path.join(rootDir, 'packages/themes/default/src/*')],
+ '@xds/theme-neutral/*': [path.join(rootDir, 'packages/themes/neutral/src/*')],
},
unstable_moduleResolution: {
type: 'commonJS',
diff --git a/apps/sandbox/next.config.mjs b/apps/sandbox/next.config.mjs
index a9088cc7ca..de34b7a075 100644
--- a/apps/sandbox/next.config.mjs
+++ b/apps/sandbox/next.config.mjs
@@ -8,7 +8,7 @@ const nextConfig = {
output: 'export',
trailingSlash: true,
basePath: process.env.SANDBOX_BASE_PATH || '',
- transpilePackages: ['@xds/core', '@xds/theme'],
+ transpilePackages: ['@xds/core', '@xds/theme-default'],
images: {
unoptimized: true,
},
diff --git a/apps/sandbox/postcss.config.js b/apps/sandbox/postcss.config.js
index 787fc76b54..af668d9eb3 100644
--- a/apps/sandbox/postcss.config.js
+++ b/apps/sandbox/postcss.config.js
@@ -10,7 +10,8 @@ module.exports = {
include: [
'src/**/*.{js,jsx,ts,tsx}',
path.join(rootDir, 'packages/core/src/**/*.{ts,tsx}'),
- path.join(rootDir, 'packages/theme/src/**/*.{ts,tsx}'),
+ path.join(rootDir, 'packages/themes/default/src/**/*.{ts,tsx}'),
+ path.join(rootDir, 'packages/themes/neutral/src/**/*.{ts,tsx}'),
],
babelConfig: {
babelrc: false,
diff --git a/apps/storybook/.storybook/preview.tsx b/apps/storybook/.storybook/preview.tsx
index 591511ace8..ed3a03120f 100644
--- a/apps/storybook/.storybook/preview.tsx
+++ b/apps/storybook/.storybook/preview.tsx
@@ -4,8 +4,9 @@ import {XDSTheme} from '@xds/core';
import {defaultTheme} from '@xds/theme-default';
import {neutralTheme} from '@xds/theme-neutral';
-// Import the base reset stylesheet
+// Import the base reset and typography stylesheets
import '@xds/core/reset.css';
+import '@xds/core/typography.css';
// Import the pre-built StyleX CSS from the core package
// Use relative path since @xds/core alias points to source, not dist
@@ -31,6 +32,7 @@ const withXDSTheme: Decorator = (Story, context) => {
if (themeKey === 'none') {
return (
<div
+ className="xds-typography"
style={{
colorScheme: mode,
padding: 16,
@@ -45,6 +47,7 @@ const withXDSTheme: Decorator = (Story, context) => {
return (
<XDSTheme theme={theme} mode={mode}>
<div
+ className="xds-typography"
style={{
backgroundColor: 'var(--color-surface)',
padding: 16,