Design tokens are easier to explain when people can change the example and see what breaks. A static code snippet can show the naming convention, but a working demo helps the team feel the difference between palette values and semantic decisions.
A token playground in MDX
The example below shows a card built with semantic tokens. Every color, border, and text style comes from a token — not a raw hex value. Change the theme from light to dark using the toggle in the header and watch the card keep its intent.
1 import { styled, VStack, HStack } from "@/styled-system/jsx";
2
3 export function TokenCard() {
4 return (
5 <styled.div
6 bg="bg.surface"
7 borderWidth="1px"
8 borderColor="border.subtle"
9 rounded="xl"
10 p="6"
11 maxW="sm"
12 >
13 <VStack alignItems="stretch" gap="4">
14 <styled.h3
15 color="text.primary"
16 fontSize="lg"
17 fontWeight="bold"
18 >
19 Semantic Card
20 </styled.h3>
21 <styled.p color="text.secondary" lineHeight="relaxed">
22 This card uses <CodeInline>bg.surface</CodeInline> for its
23 background and <CodeInline>text.secondary</CodeInline> for this
24 paragraph. No raw hex values anywhere.
25 </styled.p>
26 <HStack gap="2">
27 <styled.span color="accent.default" fontWeight="semibold">
28 Read more â
29 </styled.span>
30 <styled.span color="text.muted" fontSize="sm">
31 Tap to expand
32 </styled.span>
33 </HStack>
34 </VStack>
35 </styled.div>
36 );
37 }Semantic Card
This card uses bg.surface for its background, text.secondary for this paragraph, and border.subtle for the edge. No raw hex anywhere.
Recessed Variant
Same component, different token: bg.subtle instead of bg.surface. The card recedes visually but the structure stays intact.
Accent Variant
Call-to-action treatment using accent.soft background and accent.default border.
What changes when you swap tokens
Try changing the card's surface token from bg.surface to bg.subtle and watch the card recede. Then try swapping text.secondary for text.primary and notice how the hierarchy flattens. These are the same decisions your design system makes across every component.
1 // Surface variant: elevated
2 <styled.div bg="bg.surface" borderColor="border.strong" shadow="md">
3
4 // Surface variant: recessed
5 <styled.div bg="bg.subtle" borderColor="border.subtle">
6
7 // Accent treatment: call-to-action surface
8 <styled.div bg="accent.soft" borderColor="accent.default">Run it yourself
Want to see this in a live sandbox? Open a new StackBlitz project with Vite + React, paste the TokenCard component into App.tsx, and toggle between light and dark mode. Better yet, build the card in Storybook and run Chromatic snapshots to see every variant across themes in a single review.