| name | devup-ui |
| description | Zero-runtime CSS-in-JS preprocessor for React. Transforms JSX styles to static CSS at build time.
TRIGGER WHEN:
- Writing/modifying Devup UI components (Box, Flex, Grid, Text, Button, etc.)
- Using styling APIs: css(), globalCss(), keyframes()
- Configuring devup.json theme (colors, typography, length, shadow, extends)
- Setting up build plugins (Vite, Next.js, Webpack, Rsbuild, Bun)
- Debugging "Cannot run on the runtime" errors
- Working with responsive arrays, pseudo-selectors (_hover, _dark, etc.)
- Using polymorphic `as` prop or `selectors` prop
- Working with @devup-ui/components (Button, Input, Select, Toggle, etc.)
- Using responsive length tokens ($containerX, $gutter) or shadow tokens ($card, $sm)
|
Devup UI
Build-time CSS extraction. No runtime JS for styling.
Critical: Components Are Compile-Time Only
All @devup-ui/react components throw Error('Cannot run on the runtime'). They are placeholders that build plugins transform to native HTML elements with classNames.
<Box bg="red" p={4} _hover={{ bg: "blue" }} />
<div className="a b c" />
Components
@devup-ui/react (Layout Primitives)
All are polymorphic (accept as prop). Default element is <div> unless noted.
| Component | Default Element | Purpose |
|---|
Box | div | Base layout primitive, accepts all style props |
Flex | div | Flexbox container (shorthand for display: flex) |
Grid | div | CSS Grid container |
VStack | div | Vertical stack (flex column) |
Center | div | Centered content |
Text | p | Text/typography |
Image | img | Image element |
Input | input | Input element |
Button | button | Button element |
ThemeScript | -- | SSR theme hydration (add to <head>) |
@devup-ui/components (Pre-built UI)
Higher-level components with built-in behavior. These are runtime components (not compile-time only).
| Component | Key Props |
|---|
Button | variant (primary/default), size (sm/md/lg), loading, danger, icon, colors |
Checkbox | children (label), onChange(checked), colors |
Input | error, errorMessage, allowClear, icon, typography, colors |
Textarea | error, errorMessage, typography, colors |
Radio | variant (default/button), colors |
RadioGroup | options[], direction (row/column), variant, value, onChange |
Toggle | variant (default/switch), value, onChange(boolean), colors |
Select | type (default/radio/checkbox), options[], value, onChange, colors |
Stepper | min, max, type (input/), , |
Select compound: SelectTrigger, SelectContainer, SelectOption, SelectDivider
Stepper compound: StepperContainer, StepperDecreaseButton, StepperIncreaseButton, StepperInput
Hooks: useSelect(), useStepper()
All components accept a colors prop object for runtime color customization via CSS variables.
Style Prop Syntax
Shorthand Props (ALWAYS prefer these)
Spacing (unitless number x 4 = px)
| Shorthand | CSS Property |
|---|
m, mt, mr, mb, ml, mx, my | margin-* |
p, pt, pr, pb, pl, px, py | padding-* |
Sizing
| Shorthand | CSS Property |
|---|
w | width |
h | height |
minW, maxW | min-width, max-width |
minH, maxH | min-height, max-height |
boxSize | width + height (same value) |
Background
| Shorthand | CSS Property |
|---|
bg | background |
bgColor | background-color |
bgImage, bgImg, backgroundImg | background-image |
bgSize | background-size |
bgPosition, bgPos | background-position |
bgPositionX, bgPosX | background-position-x |
bgPositionY, bgPosY | background-position-y |
bgRepeat | background-repeat |
bgAttachment | background-attachment |
bgClip | background-clip |
bgOrigin | background-origin |
bgBlendMode | background-blend-mode |
Border
| Shorthand | CSS Property |
|---|
borderTopRadius | border-top-left-radius + border-top-right-radius |
borderBottomRadius | border-bottom-left-radius + border-bottom-right-radius |
borderLeftRadius | border-top-left-radius + border-bottom-left-radius |
borderRightRadius | border-top-right-radius + border-bottom-right-radius |
Layout & Position
| Shorthand | CSS Property |
|---|
flexDir | flex-direction |
pos | position |
positioning | Helper: "top", "bottom-right", etc. (sets edges to 0) |
objectPos | object-position |
offsetPos | offset-position |
maskPos | mask-position |
maskImg | mask-image |
Typography
| Shorthand | Effect |
|---|
typography | Applies theme typography token (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) |
All standard CSS properties from csstype are also accepted directly (e.g., display, gap, opacity, transform, animation, etc.).
Spacing Scale (unitless number x 4 = px)
<Box p={1} />
<Box p={4} />
<Box p="4" />
<Box p="20px" />
Responsive Arrays (5 breakpoints)
<Box bg={["red", null, "blue", null, "yellow"]} />
<Box p={[2, null, 4, null, 6]} />
<Box w={["100%", null, "50%"]} />
Pseudo-Selectors (underscore prefix)
<Box
_hover={{ bg: "blue" }}
_focus={{ outline: "2px solid blue" }}
_focusVisible={{ outlineColor: "$primary" }}
_active={{ bg: "darkblue" }}
_disabled={{ opacity: 0.5 }}
_before={{ content: '""' }}
_after={{ content: '""' }}
_firstChild={{ mt: 0 }}
_lastChild={{ mb: 0 }}
_placeholder={{ color: "gray" }}
/>
All CSS pseudo-classes and pseudo-elements from csstype are supported with _camelCase naming.
Group Selectors
Mark a parent with the data-group attribute, then children can react to that parent's state:
<Box data-group>
<Text _groupHover={{ color: "blue" }}>Changes when parent hovered</Text>
<Box _groupFocus={{ outline: "2px solid" }} />
<Box _groupActive={{ bg: "darkblue" }} />
</Box>
Available: _groupHover, _groupFocus, _groupActive, _groupDisabled.
The legacy role="group" parent marker is still matched for backward
compatibility but will be removed in v2. Use data-group for new code so
role="group" stays reserved for genuine ARIA grouping semantics.
Theme Selectors
<Box _themeDark={{ bg: "gray.900" }} />
<Box _themeLight={{ bg: "white" }} />
At-Rules (Media, Container, Supports)
<Box _print={{ display: "none" }} />
<Box _screen={{ display: "block" }} />
<Box _media={{ "(min-width: 768px)": { w: "50%" } }} />
<Box _container={{ "(min-width: 400px)": { p: 4 } }} />
<Box _supports={{ "(display: grid)": { display: "grid" } }} />
<Box {...{ "@media": { "(min-width: 768px)": { w: "50%" } } }} />
Custom Selectors
<Box selectors={{
"&:hover": { color: "red" },
"&::before": { content: '">"' },
"&:nth-child(2n)": { bg: "gray" },
}} />
Dynamic Values = CSS Variables
<Box bg="red" />
<Box bg={props.color} />
<Box bg={isActive ? "blue" : "gray"} />
Responsive + Pseudo Combined
<Box _hover={{ bg: ['red', 'blue'] }} />
<Box _hover={[{ bg: 'red' }, { bg: 'blue' }]} />
Special Props
as (Polymorphic Element)
Changes the rendered HTML element or renders a custom component:
<Box as="section" bg="gray" />
<Box as="a" href="/about" />
<Box as={MyComponent} bg="red" />
<Box as={b ? "div" : "section"} />
props (Pass-Through to as Component)
When as is a custom component, use props to pass component-specific props:
<Box as={MotionDiv} w="100%" props={{ animate: { duration: 1 } }} />
styleVars (Manual CSS Variable Injection)
<Box styleVars={{ "--custom-color": dynamicValue }} bg="var(--custom-color)" />
styleOrder (CSS Cascade Priority)
Controls specificity when combining className with direct props. Required when mixing css() classNames with inline style props.
<Box className={cardStyle} bg="$background" styleOrder={1} />
<Box bg="red" styleOrder={isActive ? 1 : 0} />
Styling APIs
css() Returns className String (NOT object)
import { css, globalCss, keyframes } from "@devup-ui/react";
import clsx from "clsx";
const cardStyle = css({ bg: "white", p: 4, borderRadius: "8px" });
<div className={cardStyle} />
const baseStyle = css({ p: 4, borderRadius: "8px" });
const activeStyle = css({ bg: "$primary", color: "white" });
<Box className={clsx(baseStyle, isActive && activeStyle)} styleOrder={1} />
globalCss() and keyframes()
globalCss({ body: { margin: 0 }, "*": { boxSizing: "border-box" } });
const spin = keyframes({ from: { transform: "rotate(0)" }, to: { transform: "rotate(360deg)" } });
<Box animation={`${spin} 1s linear infinite`} />
Dynamic Values with Custom Components
css() only accepts static values. For dynamic values on custom components, use <Box as={Component}>:
<CustomComponent className={css({ w: width })} />
<Box as={CustomComponent} w={width} />
Theme (devup.json)
{
"extends": ["./base-theme.json"],
"theme": {
"colors": {
"default": { "primary": "#0070f3", "text": "#000", "bg": "#fff" },
"dark": { "primary": "#3291ff", "text": "#fff", "bg": "#111" }
},
"typography": {
"heading": {
"fontFamily": "Pretendard",
"fontSize": "24px"
- Colors: Use with
$ prefix in JSX props: <Box color="$primary" />
- Typography: Use with
$ prefix: <Text typography="$heading" />
- Length: Responsive length tokens:
<Box px="$containerX" />, <Flex gap="$gutter" />
- Shadow: Responsive shadow tokens:
<Box boxShadow="$card" />
- extends: Inherit from base config files (deep merge, last wins)
- Responsive typography/length/shadow: Use arrays with
null for unchanged breakpoints
Length & Shadow Token Behavior
Length and shadow tokens support responsive arrays like typography. The key distinction is how $token behaves depending on syntax:
| Syntax | Behavior | Classes |
|---|
px="$containerX" | Expands to all defined breakpoints | Multiple |
px={"$containerX"} | Expands to all defined breakpoints | Multiple |
px={["$containerX"]} | Single value at index 0 only | 1 |
px={["8px", null, "$containerX"]} | 8px at index 0, token at index 2 | 2 |
Both "$token" and {"$token"} expand the responsive token. Only {["$token"]} inside a responsive array keeps it as a single class — because the array itself defines the breakpoint levels.
Theme types are auto-generated via module augmentation of DevupTheme and DevupThemeTypography.
Theme API
import { useTheme, setTheme, getTheme, initTheme, ThemeScript } from "@devup-ui/react";
setTheme("dark");
const theme = getTheme();
const theme = useTheme();
initTheme();
<ThemeScript />
Build Plugin Setup
Vite
import DevupUI from "@devup-ui/vite-plugin";
export default defineConfig({ plugins: [react(), DevupUI()] });
Next.js
import { DevupUI } from "@devup-ui/next-plugin";
export default DevupUI({ });
Rsbuild
import DevupUI from "@devup-ui/rsbuild-plugin";
export default defineConfig({ plugins: [DevupUI()] });
Webpack
import { DevupUIWebpackPlugin } from "@devup-ui/webpack-plugin";
Bun
import { plugin } from "@devup-ui/bun-plugin";
Plugin Options
DevupUI({
singleCss: true,
include: ["@devup/hello"],
prefix: "du",
debug: true,
importAliases: {
"@emotion/styled": "styled",
"styled-components": "styled",
"@vanilla-extract/css": true,
},
})
$token Scope
$token values (colors, length, shadow) only work in JSX props. Use var(--token) in external objects.
<Box bg="$primary" />
<Box px="$containerX" />
<Box boxShadow="$card" />
<Box bg={{ active: '$primary', inactive: '$gray' }[status]} />
const colors = { active: '$primary' }
<Box bg={colors.active} />
const colors = { active: 'var(--primary)' }
<Box bg={colors.active} />
Inline Variant Pattern (Preferred)
Use inline object indexing instead of external config objects:
<Box
h={{ lg: '48px', md: '40px', sm: '32px' }[size]}
bg={{ primary: '$primary', secondary: '$gray100' }[variant]}
/>
const sizeStyles = { lg: { h: '48px' }, md: { h: '40px' } }
<Box h={sizeStyles[size].h} />
Anti-Patterns (NEVER do)
| Wrong | Right | Why |
|---|
<Box style={{ color: "red" }}> | <Box color="red"> | style prop bypasses extraction |
<Box {...css({...})} /> | <Box className={css({...})} /> | css() returns string, not object |
css({ bg: variable }) | <Box bg={variable}> or <Box as={Comp} bg={variable}> | css()/globalCss() only accept static values |
$color in external object | var(--color) in external object | $color only transformed in JSX props |
| No build plugin configured | Configure plugin first | Components throw at runtime without transformation |
as any on style props | Fix types properly | Type errors indicate real issues |
@ts-ignore / @ts-expect-error | Fix the type issue | Suppression hides real problems |
background="red" | bg="red" | Always use shorthands |
padding={4} | p={4} | Always use shorthands |
width="100%" | w="100%" | Always use shorthands |
styled("div", {...}) | <Box bg="red" /> | Use Box component with props, not styled() |
stylex.create({...}) | <Box bg="red" /> | Use Box component with props, not stylex |
