Build a Responsive Text Component with Design Tokens

Building a component seems straightforward until you realize how much coordination it requires between design and code. Designers define font sizes, weights, colors, and responsive behavior in Figma. Developers then rebuild that logic manually in components. The structure that exists in design tokens doesn’t always make it to code.

This article walks you through building a Text component that actually uses the token structure created in design. We'll set up a pipeline that converts Figma variables into CSS, then build a component that references those tokens. By the end, you'll have a reusable primitive that stays in sync with your design system.

Would you prefer video format? Watch it here!

For this workflow, you’ll need:

• Style Dictionary
• Storybook
• A code editor (I'm using VSCode)
• Some HTML/JSX, CSS, and TypeScript knowledge
• Some React knowledge

Optional (needed if you want to explore the Figma workflow):

• Figma
• Tokens Studio

Want the full code? Clone the GitHub repo.

Designing the text component

Before we jump into code, I want to walk you through the structure of the design tokens. Understanding this will make the implementation much clearer.

The tokens follow a three-layer architecture that flows from options to components:

Options layer

This is the foundation; all the raw values available in the design system. It includes:

• Scale values: 0, 1px, 2px, 4px, 8px, and so on.
• Color palette: All color values and shades that could be used.

These are just reference values with no semantic meaning yet. They establish what's available to choose from.

Semantics layer

The semantics layer assigns meaning to those raw options. It's divided into two:

1. Semantic base (s-base)

Holds tokens that only need one mode. These are values that don't change based on context, like font weights and colors. Each font weight variable - light, regular, medium, semi-bold, bold - only has one mode. Same with colors, since we're not doing themes in this example.

2. Semantic responsive (s-responsive)

Contains tokens that need multiple modes for responsiveness, specifically font sizes and line heights. Since we're building responsiveness into the design tokens, this layer contains mobile and desktop modes for each token. So we have xs, sm, md, lg, xl, 2xl, and 3xl. Each one has a value for mobile and a value for desktop.

Component tokens

This is where our Text component lives. The component tokens reference the semantic values. For font size and line height, we're only referencing the s-responsive tokens, which already contain both mobile and desktop values. The responsiveness is baked into the token itself, so we don't need to write media queries in our component code.

This layered approach keeps everything organized and makes changes easier. If you need to adjust a font size, you update it once in the semantic layer, and it flows through to every component that uses it.

Tokens pipeline

My tokens start as Figma Variables, organized into the collections I described above. I installed the Tokens Studio plugin and imported those variables into it. From there, I can export them as JSON.

You can copy my tokens as JSON from this GitHub link.

Code implementation

Create project

• If you’re starting with a new project, create a folder in your directory. I’m naming mine text-component-with-design-tokens.
• Open the folder in your code editor, and then open the terminal. Run npm create vite@latest . -- --template react-ts
• Accept the default configs by clicking ‘Enter’ on each one, until your project is created successfully.
• Once the dev server starts, go to the local URL to confirm that everything works as expected. This is usually http://localhost:5173/, unless you already have something else running there.

Convert tokens

• We need to convert our tokens into CSS variables. To achieve this, we’ll create a script that uses style dictionary and Tokens Studio’s SD transforms.
• In your terminal, run npm install style-dictionary @tokens-studio/sd-transforms.
• At the root of your project, create a tokens.json file and paste in the content of the JSON file link shared above.
• Create another file called buildTokens.ts and paste in the functions below.

1import StyleDictionary from "style-dictionary";
2import type { Dictionary, TransformedToken } from "style-dictionary";
3import { register, getTransforms } from "@tokens-studio/sd-transforms";
4import fs from "fs";
5import { fileURLToPath } from "url";
6
7type TokenValue = {
8  value: string;
9  type: string;
10  [key: string]: unknown;
11};
12
13type TokenObject = {
14  [key: string]: TokenValue | TokenObject;
15};
16
17type TokensFile = TokenObject & {
18  $metadata?: {
19    tokenSetOrder?: string[];
20  };
21  $themes?: unknown;
22};
23
24type TextTokenMap = Map<string, TransformedToken>;
25
26const MOBILE_SET_NAME = "s-responsive/Mobile";
27const DESKTOP_SET_NAME = "s-responsive/Desktop";
28const OUTPUT_PATH = fileURLToPath(new URL("src/tokens.css", import.meta.url));
29const tokensPath = fileURLToPath(new URL("tokens.json", import.meta.url));
30const tokens: TokensFile = JSON.parse(fs.readFileSync(tokensPath, "utf8"));
31
32// fixes fontWeight tokens that were exported with the type of "text" due to Figma's setup
33function fixFontWeightTypes(
34  obj: TokenObject | TokenValue,
35  isInFontWeight = false
36): void {
37  if (typeof obj !== "object" || obj === null) {
38    return;
39  }
40
41  if (isInFontWeight && "type" in obj && obj.type === "text") {
42    obj.type = "fontWeight";
43  }
44
45  for (const key in obj) {
46    if (typeof obj[key] === "object" && obj[key] !== null) {
47      const newIsInFontWeight = key === "fontWeight" || isInFontWeight;
48      fixFontWeightTypes(
49        obj[key] as TokenObject | TokenValue,
50        newIsInFontWeight
51      );
52    }
53  }
54}
55
56// checks if a value is a leaf token entry
57function isTokenValue(
58  value: TokenValue | TokenObject | undefined
59): value is TokenValue {
60  return Boolean(value && typeof value === "object" && "value" in value);
61}
62
63// recursively merges two token objects without losing leaf nodes
64function deepMerge(
65  target: TokenObject,
66  source: TokenObject | undefined
67): TokenObject {
68  if (!source) {
69    return target;
70  }
71
72  const result: TokenObject = { ...target };
73
74  for (const key of Object.keys(source)) {
75    const sourceValue = source[key];
76    const targetValue = result[key];
77
78    if (
79      typeof sourceValue === "object" &&
80      sourceValue !== null &&
81      typeof targetValue === "object" &&
82      targetValue !== null &&
83      !isTokenValue(sourceValue) &&
84      !isTokenValue(targetValue)
85    ) {
86      result[key] = deepMerge(
87        targetValue as TokenObject,
88        sourceValue as TokenObject
89      );
90    } else {
91      result[key] = sourceValue;
92    }
93  }
94
95  return result;
96}
97
98// reads the token set order from metadata
99function getTokenSetOrder(): string[] {
100  const order = tokens.$metadata?.tokenSetOrder;
101  if (!Array.isArray(order) || order.length === 0) {
102    throw new Error("Token set order metadata is missing.");
103  }
104  return order;
105}
106
107// returns each set name up to and including the target set
108function getSetNamesUpTo(targetSet: string, order: string[]): string[] {
109  const targetIndex = order.indexOf(targetSet);
110  if (targetIndex === -1) {
111    throw new Error(`Missing token set "${targetSet}" in tokenSetOrder.`);
112  }
113  return order.slice(0, targetIndex + 1);
114}
115
116// merges multiple token sets into a single object
117function mergeTokenSets(setNames: string[]): TokenObject {
118  return setNames.reduce<TokenObject>((acc, setName) => {
119    const currentSet = tokens[setName];
120    if (!currentSet || typeof currentSet !== "object") {
121      throw new Error(`Token set "${setName}" is not defined.`);
122    }
123    return deepMerge(acc, currentSet as TokenObject);
124  }, {});
125}
126
127// builds a Style Dictionary dictionary from a list of set names
128async function createDictionaryForSets(
129  setNames: string[],
130  transforms: string[]
131): Promise<Dictionary> {
132  const mergedTokens = mergeTokenSets(setNames);
133  const sd = new StyleDictionary({
134    tokens: mergedTokens,
135    platforms: {
136      base: {
137        transforms,
138      },
139    },
140  });
141
142  await sd.init();
143  return sd.getPlatformTokens("base");
144}
145
146// converts camel or spaced strings into kebab-case
147function toKebabCase(value: string): string {
148  return value
149    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
150    .replace(/s+/g, "-")
151    .toLowerCase();
152}
153
154// converts a token to its css custom property name
155function getCssVarName(token: TransformedToken): string {
156  const segments = token.path.slice(1).map(toKebabCase);
157  return `--text-${segments.join("-")}`;
158}
159
160// builds a map of text token keys to their values
161function extractTextTokenMap(tokens: TransformedToken[]): TextTokenMap {
162  return tokens.reduce<TextTokenMap>((map, token) => {
163    if (!Array.isArray(token.path) || token.path[0] !== "text") {
164      return map;
165    }
166    const key = token.path.slice(1).join(".");
167    map.set(key, token);
168    return map;
169  }, new Map());
170}
171
172// generates css variable output with mobile defaults and desktop overrides
173function buildCssOutput(
174  mobileTokens: TransformedToken[],
175  desktopTokens: TransformedToken[]
176): string {
177  const mobileMap = extractTextTokenMap(mobileTokens);
178  const desktopMap = extractTextTokenMap(desktopTokens);
179  const sortedKeys = Array.from(mobileMap.keys()).sort();
180
181  const rootLines = sortedKeys.map((key) => {
182    const token = mobileMap.get(key);
183    if (!token) {
184      return null;
185    }
186    return `  ${getCssVarName(token)}: ${token.value};`;
187  });
188
189  const desktopOverrideKeys = sortedKeys.filter(
190    (key) => key.startsWith("fontSize.") || key.startsWith("lineHeight.")
191  );
192
193  const desktopLines = desktopOverrideKeys
194    .map((key) => {
195      const token = desktopMap.get(key);
196      if (!token) {
197        return null;
198      }
199      return `    ${getCssVarName(token)}: ${token.value};`;
200    })
201    .filter((line): line is string => Boolean(line));
202
203  const lines = [
204    "/**",
205    " * Do not edit directly, this file was auto-generated.",
206    " */",
207    "",
208    ":root {",
209    ...rootLines.filter((line): line is string => Boolean(line)),
210    "}",
211  ];
212
213  if (desktopLines.length > 0) {
214    lines.push(
215      "",
216      "@media only screen and (min-width: 1025px) {",
217      "  :root {",
218      ...desktopLines,
219      "  }",
220      "}"
221    );
222  }
223
224  lines.push("");
225  return lines.join("
226");
227}
228
229fixFontWeightTypes(tokens);
230
231// orchestrates generation of css variables from the responsive token sets
232async function buildTokens(): Promise<void> {
233  await register(StyleDictionary);
234  const tokensStudioTransforms = getTransforms();
235  const transforms = ["name/kebab", ...tokensStudioTransforms];
236  const tokenSetOrder = getTokenSetOrder();
237  const mobileSets = getSetNamesUpTo(MOBILE_SET_NAME, tokenSetOrder);
238  const desktopSets = getSetNamesUpTo(DESKTOP_SET_NAME, tokenSetOrder);
239  const [mobileDictionary, desktopDictionary] = await Promise.all([
240    createDictionaryForSets(mobileSets, transforms),
241    createDictionaryForSets(desktopSets, transforms),
242  ]);
243
244  const cssOutput = buildCssOutput(
245    mobileDictionary.allTokens,
246    desktopDictionary.allTokens
247  );
248
249  fs.writeFileSync(OUTPUT_PATH, cssOutput);
250}
251
252buildTokens().catch((error) => {
253  console.error(error);
254  process.exit(1);
255});

• Run npx tsx buildTokens.ts and you should have a tokens.css file in src/ containing all the tokens as CSS variables. Responsiveness has been handled automatically, with the mobile variables defined first, then the desktop variables defined in a media query override.
• Note: both your development and design teams must agree on these breakpoints to keep your UIs matched. Breakpoints can also be defined as design tokens.
• If you want these variables in a different folder, change the buildPath in the buildTokens function.
• If you skipped the tokens transformation, you can copy the variables below.

1/**
2 * Do not edit directly, this file was auto-generated.
3 */
4
5:root {
6  --text-color-brand: #2828df;
7  --text-color-default: #2d2d2d;
8  --text-color-error: #df5b5b;
9  --text-color-subtle: #5c5c5c;
10  --text-color-success: #5bd79e;
11  --text-font-family-inter: Inter;
12  --text-font-size-2xl: 32px;
13  --text-font-size-3xl: 36px;
14  --text-font-size-lg: 24px;
15  --text-font-size-md: 20px;
16  --text-font-size-sm: 16px;
17  --text-font-size-xl: 28px;
18  --text-font-size-xs: 12px;
19  --text-font-weight-bold: 700;
20  --text-font-weight-light: 300;
21  --text-font-weight-medium: 500;
22  --text-font-weight-regular: 400;
23  --text-font-weight-semi-bold: 600;
24  --text-line-height-2xl: 40px;
25  --text-line-height-3xl: 44px;
26  --text-line-height-lg: 20px;
27  --text-line-height-md: 20px;
28  --text-line-height-sm: 16px;
29  --text-line-height-xl: 24px;
30  --text-line-height-xs: 16px;
31}
32
33@media only screen and (min-width: 1025px) {
34  :root {
35    --text-font-size-2xl: 44px;
36    --text-font-size-3xl: 48px;
37    --text-font-size-lg: 32px;
38    --text-font-size-md: 24px;
39    --text-font-size-sm: 20px;
40    --text-font-size-xl: 40px;
41    --text-font-size-xs: 16px;
42    --text-line-height-2xl: 40px;
43    --text-line-height-3xl: 48px;
44    --text-line-height-lg: 24px;
45    --text-line-height-md: 20px;
46    --text-line-height-sm: 16px;
47    --text-line-height-xl: 32px;
48    --text-line-height-xs: 16px;
49  }
50}

• To ensure these tokens are available to all the components in my app, I’ll import them in my main.tsx file.

1// main.tsx
2
3import './tokens.css'

Setup Storybook

• We need to install Storybook to document and preview our Text component. To do so, open a new terminal window and run npm create storybook@latest
• Accept the ‘Yes: Help me with onboarding’ option so Storybook scaffolds examples to give you a quick introduction to how it works. Once Storybook is installed, explore its UI to understand how it works. You can also read the documentation for more. If you need to restart Storybook, you can do that by running npm run storybook in your terminal.
• Import the tokens.css file in Storybook’s preview file so it can properly reference any variable used in our component.

1// .storybook/preview.ts
2
3import "../src/tokens.css";

Create <Text /> component

• In your project’s src, create a components folder, and then a Text folder under it.
• In the Text folder, create an index.tsx file and paste in the following code.

1// src/components/Text/index.tsx
2import React from "react";
3
4export interface TextProps {
5  as?: React.ElementType;
6  children?: React.ReactNode;
7}
8
9const Text = ({ as: Component = "p", children }: TextProps) => {
10  return <Component>{children}</Component>;
11};
12
13export default Text;

• Create a text.stories.ts file in the Text folder and paste in the following:

1import type { Meta, StoryObj } from "@storybook/react-vite";
2
3import Text from ".";
4
5const meta = {
6  title: "Components/Text",
7  component: Text,
8  parameters: {
9    layout: "centered",
10  },
11  tags: ["autodocs"],
12} satisfies Meta<typeof Text>;
13
14export default meta;
15type Story = StoryObj<typeof meta>;
16
17export const Default: Story = {
18  args: {
19    children: "Hello, World!",
20  },
21};

• You should now have a folder in Storybook called ‘Components’, with a component called ‘Default’, and one Default use.

Semantics

In my experience building products, tightly coupling the styling and semantics of HTML text elements is rarely a good idea. Many design systems are set up with the h1 larger than the h2, which is larger than the h3, and so on. But in real-world use cases, we find that a section heading may be smaller than its sub-headings.

The only use cases where size must align with semantic order are those where we need to represent the order visually, e.g., markdown to webpage tools. Else, you might build a rigid system that will eventually be broken with manual overrides.

as/Component

The as prop is a polymorphic prop that lets you choose which HTML element or React component to render. It’s renamed to Component via destructuring. We specify what elements can be rendered to protect the scope of this component.

1// src/components/Text/index.tsx
2import React from "react";
3
4type TextElement =
5  | "p"
6  | "span"
7  | "strong"
8  | "em"
9  | "label"
10  | "h1"
11  | "h2"
12  | "h3"
13  | "h4"
14  | "h5"
15  | "h6";
16
17interface TextProps {
18  as?: TextElement;
19  children?: React.ReactNode;
20}
21
22const Text = ({ as: Component = "p", children }: TextProps) => {
23  return <Component>{children}</Component>;
24};
25
26export default Text;
27```tsx
28// example uses
29<Text>Regular paragraph</Text>                    // renders as <p>
30<Text as="h1">Heading</Text>                      // renders as <h1>
31<Text as="span">Inline text</Text>                // renders as <span>

children

The children prop is the content rendered inside the component as seen in the examples above.

Styling

First, you need to reset all default CSS styling. I’ve been using the meyerweb reset by Eric Meyer for years now.

• Simply copy the content of the CSS code block, and paste it into your App.css.
• Clear out all other styles in App.css and index.css.
• Import your App.css into .storybook/preview.ts just like we did with tokens.css so that Storybook also has access to these resets.

Font family

This project only uses one font family, so we’re going to set that in the CSS file.

• Add the needed font family and weights to the index.html file. Also create a .storybook/preview-head.html file and paste in the same links. This loads the font for both the app and Storybook.

1<link rel="preconnect" href="https://fonts.googleapis.com">
2<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
3<link href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap" rel="stylesheet">

• In src/components/Text, create a text.module.css file, and import it in the tsx file.

1// src/components/Text/index.tsx
2...
3const Text = ({ as: Component = "p", children }: TextProps) => {
4  const classes = [s.text].filter(Boolean).join(" ");
5
6  return <Component className={classes}>{children}</Component>;
7};
8...

• Paste the CSS variables into the style file. Then assign the font family variable to the text component, along with a fallback.

1/* src/components/Text/text.module.css */
2.text {
3  font-family: var(--text-font-family-inter), sans-serif;
4}

Font weight

• We’re handling font weight using a prop called weight.

1// src/components/Text/index.tsx
2...
3type TextWeight = "light" | "regular" | "medium" | "semi-bold" | "bold";
4
5export interface TextProps {
6  ...
7  weight?: TextWeight;
8}
9
10const Text = ({
11  as: Component = "p",
12  children,
13  weight = "regular",
14}: TextProps) => {
15  const classes = [s.text, s[`text--weight-${weight}`]]
16    .filter(Boolean)
17    .join(" ");
18
19  return <Component className={classes}>{children}</Component>;
20};
21...

1/* src/components/Text/text.module.css */
2/* weight modifiers */
3.text--weight-light {
4  font-weight: var(--text-font-weight-light);
5}
6
7.text--weight-regular {
8  font-weight: var(--text-font-weight-regular);
9}
10
11.text--weight-medium {
12  font-weight: var(--text-font-weight-medium);
13}
14
15.text--weight-semi-bold {
16  font-weight: var(--text-font-weight-semi-bold);
17}
18
19.text--weight-bold {
20  font-weight: var(--text-font-weight-bold);
21}

• We have five different font weights available. Since the default element is p, we’ll set the default font weight to regular. We’ll also accept a prop of weight.
• The component receives a weight prop, e.g., bold, builds the class name, -text--weight-regular, and styles it in CSS.

Font size and line height

• Our tokens transformation already does the responsiveness work for us. All we need to do is reference the right variables.
• We’re handling font size and line height using a single prop called size. Each font size and light height variable on the same size, (xs, sm, md, e.t.c), were created to work together.
• Then in your component, accept the size prop and use it to create the size class name.

1// src/components/Text/index.tsx
2...
3type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
4
5export interface TextProps {
6  ...
7  size?: TextSize;
8}
9
10const Text = ({
11  ...
12  size = "sm",
13}: TextProps) => {
14  const classes = [s.text, s[`text--weight-${weight}`], s[`text--size-${size}`]]
15    .filter(Boolean)
16    .join(" ");
17
18  return <Component className={classes}>{children}</Component>;
19};
20...

• Define your size modifiers in CSS.

1/* src/components/Text/text.module.css */
2/* size modifiers */
3.text--size-xs {
4  font-size: var(--text-font-size-xs);
5  line-height: var(--text-line-height-xs);
6}
7
8.text--size-sm {
9  font-size: var(--text-font-size-sm);
10  line-height: var(--text-line-height-sm);
11}
12
13.text--size-md {
14  font-size: var(--text-font-size-md);
15  line-height: var(--text-line-height-md);
16}
17
18.text--size-lg {
19  font-size: var(--text-font-size-lg);
20  line-height: var(--text-line-height-lg);
21}
22
23.text--size-xl {
24  font-size: var(--text-font-size-xl);
25  line-height: var(--text-line-height-xl);
26}
27
28.text--size-2xl {
29  font-size: var(--text-font-size-2xl);
30  line-height: var(--text-line-height-2xl);
31}
32
33.text--size-3xl {
34  font-size: var(--text-font-size-3xl);
35  line-height: var(--text-line-height-3xl);
36}

Color

We take the same approach with colors.

1// src/components/Text/index.tsx
2...
3type TextColor = "default" | "subtle" | "brand" | "error" | "success";
4
5export interface TextProps {
6  ...
7  color?: TextColor;
8}
9
10const Text = ({
11  ...
12  color = "default",
13}: TextProps) => {
14  const classes = [
15    ...
16    s[`text--color-${color}`],
17  ]
18    .filter(Boolean)
19    .join(" ");
20
21  return <Component className={classes}>{children}</Component>;
22};
23
24export default Text;

1/* src/components/Text/text.module.css */
2/* color modifiers*/
3.text--color-default {
4  color: var(--text-color-default);
5}
6
7.text--color-subtle {
8  color: var(--text-color-subtle);
9}
10
11.text--color-brand {
12  color: var(--text-color-brand);
13}
14
15.text--color-success {
16  color: var(--text-color-success);
17}
18
19.text--color-error {
20  color: var(--text-color-error);
21}

Additional props

There’s more that goes into creating a typography element. I’ve skipped others on purpose because this article is to provide a foundational guide. You can build on it based on your team’s unique needs.

The Text component accepts any standard HTML attributes through the ...rest spread operator, which is passed directly to the underlying element. This means you can add event handlers like onClick, accessibility attributes like aria-label, or any other valid HTML properties without explicitly defining them in the component's interface.

1// src/components/Text/index.tsx
2...
3const Text = ({
4  as: Component = "p",
5  children,
6  weight = "regular",
7  size = "sm",
8  color = "default",
9  ...rest
10}: TextProps) => {
11  const classes = [
12    s.text,
13    s[`text--weight-${weight}`],
14    s[`text--size-${size}`],
15    s[`text--color-${color}`],
16  ]
17    .filter(Boolean)
18    .join(" ");
19
20  return (
21    <Component className={classes} {...rest}>
22      {children}
23    </Component>
24  );
25};
26...

One property I often see added by default is margin. Working with default margins is not a great experience, and I find myself overriding them more often than using them. Common reasons why I override default margins:

• I’m using the text in a layout container with defined gaps.
• I need a margin, but it’s different from the default.
• I need the default margin, but I’m mapping over a list and the final element should not have a margin.

Issues like these are based on what you’re building, so if default margins make sense for you, then include them.

Conclusion

You now have a Text component that handles responsiveness via design tokens rather than component-level media queries. This approach scales well because responsiveness is defined once at the token level and inherited everywhere. The same pattern works for spacing, sizing, and other responsive properties across your design system. Start with tokens, reference them in components, and let the system handle the rest.