Skip to content

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

TypeScript

docs: update for v0.0.2 — fix stale references, remove isFullBleed from docs, add changeset

Cindy Zhang10c8ca60ede5
diff --git a/.changeset/v002-release.md b/.changeset/v002-release.md
new file mode 100644
index 0000000000..a8b92222d5
--- /dev/null
+++ b/.changeset/v002-release.md
@@ -0,0 +1,105 @@
+---
+'@xds/core': minor
+'@xds/cli': minor
+'@xds/theme-default': minor
+'@xds/theme-neutral': minor
+---
+
+## 0.0.2 Release
+
+### New: CSS-based theming (replaces StyleX theme system)
+
+The StyleX-based theme system (`stylex.createTheme`, `ComponentStyles` context) has been replaced with a CSS-based approach using `defineTheme()`.
+
+**Migration:**
+
+```tsx
+// Before (0.0.1)
+import { defaultTheme } from '@xds/theme-default';
+<XDSTheme theme={defaultTheme}>
+
+// After (0.0.2) — same API, new internals
+import { defaultTheme } from '@xds/theme-default';
+import '@xds/theme-default/theme.css'; // NEW: import the theme CSS
+<XDSTheme theme={defaultTheme}>
+```
+
+Custom themes now use `defineTheme()`:
+
+```tsx
+import {defineTheme} from '@xds/core';
+
+const myTheme = defineTheme({
+ name: 'my-theme',
+ tokens: {
+ '--color-accent': ['#0077B6', '#48CAE4'], // [light, dark]
+ },
+ components: {
+ button: {base: {borderRadius: '999px'}},
+ },
+ icons: myIcons,
+});
+```
+
+Build theme CSS with: `npx xds build-theme`
+
+### New: `className` and `style` props on all components
+
+All components now accept `className` and `style` alongside `xstyle`. Use Tailwind, CSS modules, or plain CSS — no StyleX build requirement for consumers.
+
+```tsx
+<XDSCard className="max-w-md shadow-lg" />
+<XDSCard style={{ maxWidth: 400 }} />
+<XDSCard xstyle={myStyleXOverrides} /> // still works
+```
+
+### New: Numeric spacing scale for `padding` and `gap`
+
+Layout components accept a numeric `padding` prop. Stack and Grid `gap` migrated from string tokens to numbers.
+
+```tsx
+// Before
+<XDSStack gap="space4">
+<XDSCard isFullBleed>
+
+// After
+<XDSStack gap={4}>
+<XDSCard padding={0}>
+```
+
+Scale: 0=0px, 1=4px, 2=8px, 3=12px, 4=16px (default), 6=24px, 8=32px, 10=40px.
+
+**Codemod:** `npx xds upgrade --apply`
+
+### New: RSC-compatible icon registry
+
+Icons now use a global registry instead of React Context:
+
+```tsx
+import {registerIcons, getIcon} from '@xds/core';
+registerIcons(myIcons); // works in RSC — no 'use client' needed
+const icon = getIcon('close'); // no hooks required
+```
+
+### New: React 19 ref prop
+
+All 64 components migrated from `forwardRef` to the React 19 `ref` prop pattern. No consumer changes needed — `ref` works the same way.
+
+### Breaking changes (all have codemods)
+
+Run `npx xds upgrade --apply` to auto-migrate:
+
+- `XDSTopNavTitle` → `XDSTopNavHeading`, prop `title` → `heading`
+- `XDSSideNavHeader` → `XDSSideNavHeading`, props `title/titleHref/supertitle/subtitle` → `heading/headingHref/superheading/subheading`
+- `useXDSIcon()` → `getIcon()`, `IconRegistryContext` removed
+- `gap="space4"` → `gap={4}` (numeric scale)
+- `isFullBleed` → `padding={0}` (on Card, Section, Layout\*)
+
+### Bug fixes
+
+- Badge height fixed to 20px
+- Token medium padding reduced to 8px
+- Card border uses opaque color for consistency across backgrounds
+- DateInput autocomplete disabled
+- SideNav 8px spacing alignment
+- Breadcrumbs text centering
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index c33d686975..af9de687f0 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -36,12 +36,6 @@ export const docs = {
type: 'ReactNode',
description: 'Content to render inside the card.',
},
- {
- name: 'isFullBleed',
- type: 'boolean',
- description: 'Deprecated. Use `padding={0}` instead.',
- default: 'false',
- },
{
name: 'padding',
type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index dc366b7e1c..83097b0be5 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -109,12 +109,6 @@ export const docs = {
'Height behavior — fill the container or grow with content.',
default: "'fill'",
},
- {
- name: 'isFullBleed',
- type: 'boolean',
- description: 'Remove padding at outer edges.',
- default: 'false',
- },
],
examples: [
{
@@ -163,12 +157,6 @@ export const docs = {
type: 'number | string',
description: 'Header height.',
},
- {
- name: 'isFullBleed',
- type: 'boolean',
- description: 'Remove internal padding.',
- default: 'false',
- },
{
name: 'label',
type: 'string',
@@ -198,12 +186,6 @@ export const docs = {
type: 'ReactNode',
description: 'Content.',
},
- {
- name: 'isFullBleed',
- type: 'boolean',
- description: 'Remove internal padding.',
- default: 'false',
- },
{
name: 'isScrollable',
type: 'boolean',
@@ -250,12 +232,6 @@ export const docs = {
type: 'number | string',
description: 'Footer height.',
},
- {
- name: 'isFullBleed',
- type: 'boolean',
- description: 'Remove internal padding.',
- default: 'false',
- },
{
name: 'label',
type: 'string',
@@ -291,12 +267,6 @@ export const docs = {
description: 'Border on the appropriate edge.',
default: 'false',
},
- {
- name: 'isFullBleed',
- type: 'boolean',
- description: 'Remove internal padding.',
- default: 'false',
- },
{
name: 'isScrollable',
type: 'boolean',
diff --git a/packages/core/src/MobileNav/README.md b/packages/core/src/MobileNav/README.md
index ec6fe395a8..22c746de5a 100644
--- a/packages/core/src/MobileNav/README.md
+++ b/packages/core/src/MobileNav/README.md
@@ -99,7 +99,7 @@ const isMobile = useMediaQuery('(max-width: 768px)');
const [drawerOpen, setDrawerOpen] = useState(false);
<XDSTopNav
- title={<XDSTopNavTitle title="My App" />}
+ heading={<XDSTopNavHeading heading="My App" />}
startContent={
isMobile ? (
<XDSButton
diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjs
index ff5fee8add..8ad06f3173 100644
--- a/packages/core/src/Section/Section.doc.mjs
+++ b/packages/core/src/Section/Section.doc.mjs
@@ -84,12 +84,6 @@ export const docs = {
type: "Array<'top' | 'bottom' | 'start' | 'end'>",
description: 'Which sides of the section have divider borders.',
},
- {
- name: 'isFullBleed',
- type: 'boolean',
- description: 'Removes internal padding so content extends edge-to-edge.',
- default: 'false',
- },
],
theming: {
targets: [
diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjs
index e1194a8d30..8d2aec9a84 100644
--- a/packages/core/src/Slider/Slider.doc.mjs
+++ b/packages/core/src/Slider/Slider.doc.mjs
@@ -223,7 +223,7 @@ export const docs = {
keyboard:
'Arrow keys ±1 step, Page Up/Down ±10 steps, Home/End jump to min/max.',
notes: [
- 'The component uses `forwardRef` — the ref is merged with an internal `trackRef` used for pointer position calculations.',
+ 'The ref is merged with an internal `trackRef` used for pointer position calculations.',
'Pointer capture is used during drag for smooth interaction even when the cursor leaves the track.',
'`snapToStep` rounds to the nearest valid step value; `clamp` enforces min/max bounds.',
'In range mode, the closest thumb to the click position is selected automatically.',
diff --git a/packages/core/src/theme/README.md b/packages/core/src/theme/README.md
index a3704aa88b..a4541de80b 100644
--- a/packages/core/src/theme/README.md
+++ b/packages/core/src/theme/README.md
@@ -145,8 +145,8 @@ See `.xds-docs/tokens.md` for the full token reference.
### How the icon registry works
-1. `XDSTheme` reads `theme.icons` and wraps children in `IconRegistryContext.Provider`
-2. `XDSIcon` with a semantic name string calls `useXDSIcon(name)` which checks the context
+1. `XDSTheme` calls `registerIcons(theme.icons)` to populate the global icon registry
+2. `XDSIcon` with a semantic name string calls `getIcon(name)` which checks the global registry
3. If the theme provides that icon, it's used. Otherwise, the built-in fallback SVG renders.
### Adding a new semantic icon name