devup.json

The devup.json file is the configuration file for your Devup UI theme. Create it at the root of your project to define colors, typography, length, shadow, and other design tokens.

Custom prop shorthands are extraction behavior rather than design tokens, so they do not belong in this file. Configure them in the build plugin instead; see Custom Shorthands.

Basic Structure

1{
2  "theme": {
3    "colors": {
4      "default": {},
5      "dark": {}
6    },
7    "typography": {},
8    "length": {
9      "default": {}
10    },
11    "shadow": {
12      "default": {}
13    }
14  }
15}
1{
2  "theme": {
3    "colors": {
4      "default": {},
5      "dark": {}
6    },
7    "typography": {},
8    "length": {
9      "default": {}
10    },
11    "shadow": {
12      "default": {}
13    }
14  }
15}

Complete Example

1{
2  "theme": {
3    "colors": {
4      "default": {
5        "primary": "#0070f3",
6        "primaryHover": "#0060df",
7        "secondary": "#7928ca",
8        "success": "#0070f3",
9        "warning": "#f5a623",
10        "error": "#e00",
11        "text": "#000",
12        "textMuted": "#666",
13        "background": "#fff",
14        "backgroundMuted": "#fafafa",
15        "border": "#eaeaea"
16      },
17      "dark": {
18        "primary": "#3291ff",
19        "primaryHover": "#2080ef",
20        "secondary": "#8a63d2",
21        "success": "#3291ff",
22        "warning": "#f7b955",
23        "error": "#f33",
24        "text": "#fff",
25        "textMuted": "#888",
26        "background": "#000",
27        "backgroundMuted": "#111",
28        "border": "#333"
29      }
30    },
31    "typography": {
32      "h1": [
33        {
34          "fontFamily": "Pretendard",
35          "fontSize": "32px",
36          "fontWeight": 800,
37          "lineHeight": 1.2
38        },
39        null,
40        null,
41        null,
42        {
43          "fontFamily": "Pretendard",
44          "fontSize": "48px",
45          "fontWeight": 800,
46          "lineHeight": 1.2
47        }
48      ],
49      "body": {
50        "fontFamily": "Pretendard",
51        "fontSize": "16px",
52        "fontWeight": 400,
53        "lineHeight": 1.5
54      },
55      "caption": {
56        "fontFamily": "Pretendard",
57        "fontSize": "14px",
58        "fontWeight": 400,
59        "lineHeight": 1.4
60      }
61    }
62  }
63}
1{
2  "theme": {
3    "colors": {
4      "default": {
5        "primary": "#0070f3",
6        "primaryHover": "#0060df",
7        "secondary": "#7928ca",
8        "success": "#0070f3",
9        "warning": "#f5a623",
10        "error": "#e00",
11        "text": "#000",
12        "textMuted": "#666",
13        "background": "#fff",
14        "backgroundMuted": "#fafafa",
15        "border": "#eaeaea"
16      },
17      "dark": {
18        "primary": "#3291ff",
19        "primaryHover": "#2080ef",
20        "secondary": "#8a63d2",
21        "success": "#3291ff",
22        "warning": "#f7b955",
23        "error": "#f33",
24        "text": "#fff",
25        "textMuted": "#888",
26        "background": "#000",
27        "backgroundMuted": "#111",
28        "border": "#333"
29      }
30    },
31    "typography": {
32      "h1": [
33        {
34          "fontFamily": "Pretendard",
35          "fontSize": "32px",
36          "fontWeight": 800,
37          "lineHeight": 1.2
38        },
39        null,
40        null,
41        null,
42        {
43          "fontFamily": "Pretendard",
44          "fontSize": "48px",
45          "fontWeight": 800,
46          "lineHeight": 1.2
47        }
48      ],
49      "body": {
50        "fontFamily": "Pretendard",
51        "fontSize": "16px",
52        "fontWeight": 400,
53        "lineHeight": 1.5
54      },
55      "caption": {
56        "fontFamily": "Pretendard",
57        "fontSize": "14px",
58        "fontWeight": 400,
59        "lineHeight": 1.4
60      }
61    }
62  }
63}

Colors Configuration

Define color tokens for each theme variant:

1{
2  "theme": {
3    "colors": {
4      "default": {
5        "primary": "#0070f3",
6        "text": "#000"
7      },
8      "dark": {
9        "primary": "#3291ff",
10        "text": "#fff"
11      }
12    }
13  }
14}
1{
2  "theme": {
3    "colors": {
4      "default": {
5        "primary": "#0070f3",
6        "text": "#000"
7      },
8      "dark": {
9        "primary": "#3291ff",
10        "text": "#fff"
11      }
12    }
13  }
14}

The first key (default) is the default theme applied on initial load
Each variant must have the same color token names
Colors are accessed with the $ prefix: $primary, $text

See Colors for more details.

Typography Configuration

Define typography styles as objects or responsive arrays:

1{
2  "theme": {
3    "typography": {
4      "heading": {
5        "fontFamily": "Pretendard",
6        "fontSize": "24px",
7        "fontWeight": 700,
8        "lineHeight": 1.3
9      },
10      "responsiveHeading": [
11        { "fontSize": "20px", "fontWeight": 700 },
12        null,
13        null,
14        null,
15        { "fontSize": "32px", "fontWeight": 700 }
16      ]
17    }
18  }
19}
1{
2  "theme": {
3    "typography": {
4      "heading": {
5        "fontFamily": "Pretendard",
6        "fontSize": "24px",
7        "fontWeight": 700,
8        "lineHeight": 1.3
9      },
10      "responsiveHeading": [
11        { "fontSize": "20px", "fontWeight": 700 },
12        null,
13        null,
14        null,
15        { "fontSize": "32px", "fontWeight": 700 }
16      ]
17    }
18  }
19}

Typography properties:

fontFamily - Font family name
fontSize - Font size (e.g., "16px")
fontWeight - Weight (number like 700 or string like "bold")
fontStyle - Style (e.g., "italic")
lineHeight - Line height (number like 1.5 or string like "150%")
letterSpacing - Letter spacing (e.g., "-0.02em")

See Typography for more details.

Length Configuration

Define responsive length tokens for spacing, sizing, and other CSS length properties:

1{
2  "theme": {
3    "length": {
4      "default": {
5        "containerX": ["16px", null, "32px", null, "64px"],
6        "gutter": ["8px", null, "16px"]
7      }
8    }
9  }
10}
1{
2  "theme": {
3    "length": {
4      "default": {
5        "containerX": ["16px", null, "32px", null, "64px"],
6        "gutter": ["8px", null, "16px"]
7      }
8    }
9  }
10}

Length tokens use responsive arrays just like typography. Use null to skip breakpoints and inherit from the previous value.

See Length for more details.

Shadow Configuration

Define responsive shadow tokens for box-shadow values:

1{
2  "theme": {
3    "shadow": {
4      "default": {
5        "card": [
6          "0 1px 2px rgba(0,0,0,0.1)",
7          null,
8          null,
9          "0 4px 8px rgba(0,0,0,0.1)"
10        ],
11        "sm": "0 1px 2px rgba(0,0,0,0.05)"
12      }
13    }
14  }
15}
1{
2  "theme": {
3    "shadow": {
4      "default": {
5        "card": [
6          "0 1px 2px rgba(0,0,0,0.1)",
7          null,
8          null,
9          "0 4px 8px rgba(0,0,0,0.1)"
10        ],
11        "sm": "0 1px 2px rgba(0,0,0,0.05)"
12      }
13    }
14  }
15}

Shadow tokens also support responsive arrays. Non-array values define a single shadow for all breakpoints.

See Shadow for more details.

Usage in Components

Colors

1<Box bg="$primary" borderColor="$border" color="$text" />
1<Box bg="$primary" borderColor="$border" color="$text" />

Typography

1const headingExample = <Text typography="$h1">Heading</Text>
2const bodyExample = <Text typography="$body">Body text</Text>
1const headingExample = <Text typography="$h1">Heading</Text>
2const bodyExample = <Text typography="$body">Body text</Text>

Length

1<Box gap="$gutter" px="$containerX" />
1<Box gap="$gutter" px="$containerX" />

Shadow

1<Box boxShadow="$card" />
1<Box boxShadow="$card" />

File Location

The devup.json file should be placed at the root of your project:

your-project/
├── devup.json      <-- here
├── package.json
├── src/
│   └── ...
└── ...

Plugin Configuration

By default, plugins look for devup.json in the project root. You can customize this:

Vite

1import { DevupUI } from '@devup-ui/vite-plugin'
2
3export default defineConfig({
4  plugins: [
5    DevupUI({
6      devupFile: 'config/devup.json', // custom path
7    }),
8  ],
9})
1import { DevupUI } from '@devup-ui/vite-plugin'
2
3export default defineConfig({
4  plugins: [
5    DevupUI({
6      devupFile: 'config/devup.json', // custom path
7    }),
8  ],
9})

Next.js

1const withDevupUI = require('@devup-ui/next-plugin')
2
3module.exports = withDevupUI({
4  devupFile: 'config/devup.json', // custom path
5})
1const withDevupUI = require('@devup-ui/next-plugin')
2
3module.exports = withDevupUI({
4  devupFile: 'config/devup.json', // custom path
5})

Type Generation

When your project builds, Devup UI automatically generates TypeScript types from your devup.json. This enables:

Autocomplete for color, typography, length, and shadow tokens
Type errors for invalid tokens
Consistent usage across your codebase

The types are generated at df/theme.d.ts.

Hot Reload

Changes to devup.json trigger hot reload during development. You can:

Add new color tokens
Modify existing values
Add typography, length, or shadow styles

And see changes immediately without restarting the dev server.