` 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 ``) |
### @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`/`text`), `value`, `onValueChange` |
**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)
```tsx
// padding: 4px
// padding: 16px
// padding: 16px (unitless string also x 4)
// padding: 20px (with unit = exact value)
```
### Responsive Arrays (5 breakpoints)
```tsx
// [mobile, mid, tablet, mid, PC] - 5 levels
// Use indices 0, 2, 4 most frequently. Use null to skip.
// mobile=red, tablet=blue, PC=yellow
// mobile=8px, tablet=16px, PC=24px
// mobile=100%, tablet+=50%
```
### Pseudo-Selectors (underscore prefix)
```tsx
```
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:
```tsx
Changes when parent hovered
```
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
```tsx
```
### At-Rules (Media, Container, Supports)
```tsx
// Underscore prefix syntax
// @ prefix syntax (equivalent)
```
### Custom Selectors
```tsx
"' },
"&:nth-child(2n)": { bg: "gray" },
}} />
```
### Dynamic Values = CSS Variables
```tsx
// Static value -> class
// className="a" + .a{background:red}
// Dynamic value -> CSS variable
// className="a" style={{"--a":props.color}} + .a{background:var(--a)}
// Conditional -> preserved
// className={isActive ? "a" : "b"}
```
### Responsive + Pseudo Combined
```tsx
// Alternative syntax:
```
## Special Props
### `as` (Polymorphic Element)
Changes the rendered HTML element or renders a custom component:
```tsx
// renders
// renders
// renders with extracted styles
// conditional element type
```
### `props` (Pass-Through to `as` Component)
When `as` is a custom component, use `props` to pass component-specific props:
```tsx
```
### `styleVars` (Manual CSS Variable Injection)
```tsx
```
### `styleOrder` (CSS Cascade Priority)
Controls specificity when combining `className` with direct props. **Required** when mixing `css()` classNames with inline style props.
```tsx
// Conditional styleOrder
```
## Styling APIs
### css() Returns className String (NOT object)
```tsx
import { css, globalCss, keyframes } from "@devup-ui/react";
import clsx from "clsx";
// css() returns a className STRING
const cardStyle = css({ bg: "white", p: 4, borderRadius: "8px" });
// Combine with clsx
const baseStyle = css({ p: 4, borderRadius: "8px" });
const activeStyle = css({ bg: "$primary", color: "white" });
```
### globalCss() and keyframes()
```tsx
globalCss({ body: { margin: 0 }, "*": { boxSizing: "border-box" } });
const spin = keyframes({ from: { transform: "rotate(0)" }, to: { transform: "rotate(360deg)" } });
```
### Dynamic Values with Custom Components
`css()` only accepts **static values**. For dynamic values on custom components, use ``:
```tsx
// WRONG - css() cannot handle dynamic values
// CORRECT - Box with as prop handles dynamic values via CSS variables
```
## Theme (devup.json)
```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",
"fontWeight": 700,
"lineHeight": 1.3,
"letterSpacing": "-0.02em"
},
"body": [
{ "fontSize": "14px", "lineHeight": 1.5 },
null,
{ "fontSize": "16px", "lineHeight": 1.6 }
]
},
"length": {
"default": {
"containerX": ["16px", null, "32px"],
"gutter": ["8px", null, "16px"]
}
},
"shadow": {
"default": {
"card": ["0 1px 2px #0003", null, null, "0 4px 8px #0003"],
"sm": "0 1px 2px rgba(0,0,0,0.05)"
}
}
}
}
```
- **Colors**: Use with `$` prefix in JSX props: ``
- **Typography**: Use with `$` prefix: ``
- **Length**: Responsive length tokens: ``, ``
- **Shadow**: Responsive shadow tokens: ``
- **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
```tsx
import { useTheme, setTheme, getTheme, initTheme, ThemeScript } from "@devup-ui/react";
setTheme("dark"); // Switch theme (sets data-theme + localStorage)
const theme = getTheme(); // Get current theme name
const theme = useTheme(); // React hook (reactive)
initTheme(); // Initialize on startup (auto-detect system preference)
// SSR hydration script (add to , prevents FOUC)
```
## Build Plugin Setup
### Vite
```ts
import DevupUI from "@devup-ui/vite-plugin";
export default defineConfig({ plugins: [react(), DevupUI()] });
```
### Next.js
```ts
import { DevupUI } from "@devup-ui/next-plugin";
export default DevupUI({ /* Next.js config */ });
```
### Rsbuild
```ts
import DevupUI from "@devup-ui/rsbuild-plugin";
export default defineConfig({ plugins: [DevupUI()] });
```
### Webpack
```ts
import { DevupUIWebpackPlugin } from "@devup-ui/webpack-plugin";
// Add to plugins array
```
### Bun
```ts
import { plugin } from "@devup-ui/bun-plugin";
// Auto-registers, always uses singleCss: true
```
### Plugin Options
```ts
DevupUI({
singleCss: true, // Single CSS file (recommended for Turbopack)
include: ["@devup/hello"], // Process external libs using @devup-ui
prefix: "du", // Class name prefix (e.g., "du-a" instead of "a")
debug: true, // Enable debug logging
importAliases: { // Redirect imports from other CSS-in-JS libs
"@emotion/styled": "styled", // default: enabled
"styled-components": "styled", // default: enabled
"@vanilla-extract/css": true, // default: enabled
},
})
```
## $token Scope
`$token` values (colors, length, shadow) only work in **JSX props**. Use `var(--token)` in external objects.
```tsx
// CORRECT - $token in JSX prop
// WRONG - $token in external object (won't be transformed)
const colors = { active: '$primary' }
// broken!
// CORRECT - var(--token) in external object
const colors = { active: 'var(--primary)' }
```
## Inline Variant Pattern (Preferred)
Use inline object indexing instead of external config objects:
```tsx
// PREFERRED - inline object indexing (build-time extractable)
// AVOID - external config object (becomes dynamic, uses CSS variables)
const sizeStyles = { lg: { h: '48px' }, md: { h: '40px' } }
```
## Anti-Patterns (NEVER do)
| Wrong | Right | Why |
|-------|-------|-----|
| `` | `` | style prop bypasses extraction |
| `` | `` | css() returns string, not object |
| `css({ bg: variable })` | `` or `` | 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", {...})` | `` | Use Box component with props, not styled() |
| `stylex.create({...})` | `` | Use Box component with props, not stylex |