Skip to content
Browse documentation
whisk/ui

Style props

Use component props for layout, color, typography, borders, and visual states.

Use props

Whisk/UI utility props compile to static CSS classes. Use them when a component exposes the visual rule you need.

Props keep layout and token choices beside the component they affect. Use semantic components for behavior, then apply utility props for layout, spacing, color, typography, and surfaces.

The packaged stylesheet covers the default component profile and common Box utilities, including spacing. Configure the build plugin when your application uses utility values outside that profile, recipes, or runtime choices declared through utilityUses.

Utility values must be static

A utility value must be a literal. For a value chosen at runtime, use a named recipe or declare its possible values in utilityUses.

Runtime values

The build must know every utility class it needs to emit before the application runs.

AccountCard.tsx — not supported
import { Box } from "@smoothie-framework/whisk-react";

export function AccountCard(props: { isActive: boolean; isCompact: boolean }) {
  return (
    <Box
      padding={props.isCompact ? 2 : 4}
      background={props.isActive ? "accent" : "surface2"}
    />
  );
}
What happens

The build stops with WhiskUtilityScanError: the computed utility prop must be a literal value or have its possible values declared in utilityUses.

styles.config.ts — supported runtime values
import type { CompileWhiskCssOptions } from "@smoothie-framework/whisk-styles";

export const styleOptions = {
  utilitySources: ["src"],
  utilityUses: [
    { name: "padding", value: 2 },
    { name: "padding", value: 4 },
    { name: "background", value: "accent" },
    { name: "background", value: "surface2" },
  ],
} satisfies CompileWhiskCssOptions;
vite.config.ts
import { defineConfig } from "vite";
import { whiskStyles } from "@smoothie-framework/whisk-styles/vite";
import { styleOptions } from "./styles.config.js";

export default defineConfig({
  plugins: [whiskStyles(styleOptions)],
});

With that configuration, the AccountCard example is supported. You choose the filename; pass its exported options to the build plugin explicitly. Keep the list finite and close to the application configuration. For an application-owned pattern with variants, use a recipe instead; see the recipe build setup.

Prop reference

This is the complete generic utility surface. A component exposes only the utility props in its own documented props.

The foundation pages explain the token scales and semantic roles used by these props: Spacing, Sizes, Colors, Borders and radii, and Typography.

Spacing

Padding: all sides

All padding props accept Responsive<SpacingStep>.

PropShorthandCSS propertyToken scale
paddingppaddingSpacing
Padding: all sides example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box padding={4} />

// Shorthand
<Box p={4} />

Padding: axis

All padding props accept Responsive<SpacingStep>.

PropShorthandCSS propertyToken scale
paddingXpxpadding-inlineSpacing
paddingYpypadding-blockSpacing
Padding: axis example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box paddingX={4} />

// Shorthand
<Box px={4} />

Padding: one side

All padding props accept Responsive<SpacingStep>.

PropShorthandCSS propertyToken scale
paddingTopptpadding-topSpacing
paddingRightprpadding-rightSpacing
paddingBottompbpadding-bottomSpacing
paddingLeftplpadding-leftSpacing
Padding: one side example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box paddingTop={4} />

// Shorthand
<Box pt={4} />

Padding: logical

All padding props accept Responsive<SpacingStep>.

PropShorthandCSS propertyToken scale
paddingStartpspadding-inline-startSpacing
paddingEndpepadding-inline-endSpacing
Padding: logical example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box paddingStart={4} />

// Shorthand
<Box ps={4} />

Margin: all sides

Margin props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
marginmmarginSpacing

margin and m also accept one responsive { x?, y? } object to set both axes.

Margin: all sides example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box margin={"auto"} />

// Shorthand
<Box m={"auto"} />

Margin: axis

Margin props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
marginXmxmargin-inlineSpacing
marginYmymargin-blockSpacing
Margin: axis example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box marginX={"auto"} />

// Shorthand
<Box mx={"auto"} />

Margin: one side

Margin props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
marginTopmtmargin-topSpacing
marginRightmrmargin-rightSpacing
marginBottommbmargin-bottomSpacing
marginLeftmlmargin-leftSpacing
Margin: one side example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box marginTop={4} />

// Shorthand
<Box mt={4} />

Margin: logical

Margin props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
marginStartmsmargin-inline-startSpacing
marginEndmemargin-inline-endSpacing
Margin: logical example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box marginStart={4} />

// Shorthand
<Box ms={4} />

Gap and sibling space

Gap and sibling-space props accept Responsive<SpacingStep>.

PropShorthandCSS propertyToken scale
gap—gapSpacing
gapX—column-gapSpacing
gapY—row-gapSpacing
spaceX—margin-inline-startSpacing
spaceY—margin-block-startSpacing
Gap and sibling space example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box gap={4} />

// Exact prop
// No shorthand is defined for this prop.

Layout and sizing

Display and box sizing

These props accept Responsive<UtilityValue>, except inline, which accepts Responsive<boolean>.

PropShorthandCSS propertyToken scale
display—display—
inline—display—
boxSizing—box-sizing—
Display and box sizing example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box display={"flex"} />

// Exact prop
// No shorthand is defined for this prop.

Position and offsets

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
position—position—
top—top—
right—right—
bottom—bottom—
left—left—
inset—inset—
Position and offsets example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box position={"relative"} />

// Exact prop
// No shorthand is defined for this prop.

Overflow and isolation

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
overflow—overflow—
overflowX—overflow-x—
overflowY—overflow-y—
isolation—isolation—
aspectRatio—aspect-ratio—
Overflow and isolation example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box overflow={"hidden"} />

// Exact prop
// No shorthand is defined for this prop.

Dimensions

Dimension props accept Responsive<DimensionValue>.

PropShorthandCSS propertyToken scale
widthwwidthSizes
heighthheightSizes
minWidthminWmin-widthSizes
maxWidthmaxWmax-widthSizes
minHeightminHmin-heightSizes
maxHeightmaxHmax-heightSizes
Dimensions example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box width={"full"} />

// Shorthand
<Box w={"full"} />

Flex item sizing

basis and shrink accept Responsive<UtilityValue>; grow accepts Responsive<UtilityValue | boolean>.

PropShorthandCSS propertyToken scale
basis—flex-basisSizes
grow—flex-grow—
shrink—flex-shrink—
Flex item sizing example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box grow={true} />

// Exact prop
// No shorthand is defined for this prop.

Flex and grid

Flex axis

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
direction—flex-direction—
wrap—flex-wrap—
Flex axis example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box direction={"row"} />

// Exact prop
// No shorthand is defined for this prop.

Flex alignment

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
align—align-items—
alignItems—align-items—
alignContent—align-content—
alignSelf—align-self—
justify—justify-content—
justifyContent—justify-content—
justifyItems—justify-items—
justifySelf—justify-self—
Flex alignment example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box justify={"between"} />

// Exact prop
// No shorthand is defined for this prop.

Grid alignment

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
placeContent—place-content—
placeItems—place-items—
placeSelf—place-self—
Grid alignment example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box placeItems={"center"} />

// Exact prop
// No shorthand is defined for this prop.

Grid templates

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
columnscolsgrid-template-columns—
rows—grid-template-rows—
areas—grid-template-areas—
area—grid-area—
autoColumns—grid-auto-columns—
autoRows—grid-auto-rows—
flow—grid-auto-flow—
Grid templates example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box columns={3} />

// Shorthand
<Box cols={3} />

Grid placement

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
colSpan—grid-column—
colStart—grid-column-start—
colEnd—grid-column-end—
rowSpan—grid-row—
rowStart—grid-row-start—
rowEnd—grid-row-end—
Grid placement example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box colSpan={2} />

// Exact prop
// No shorthand is defined for this prop.

Color, border, radius, and elevation

Surface and text colors

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
backgroundbg, backgroundColorbackgroundColors
color—colorColors
Surface and text colors example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box background={"surface2"} />

// Shorthand
<Box bg={"surface2"} />

Border shorthand

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
border—borderBorders
borderTop—border-topBorders
borderBottom—border-bottomBorders
borderLeft—border-leftBorders
borderRight—border-rightBorders
borderStart—border-inline-startBorders
borderEnd—border-inline-endBorders
borderX—border-inlineBorders
borderY—border-blockBorders
Border shorthand example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box border={"sm"} />

// Exact prop
// No shorthand is defined for this prop.

Border and outline colors

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
borderColor—border-colorColors
outlineColor—outline-colorColors
borderTopColor—border-top-colorColors
borderBottomColor—border-bottom-colorColors
borderLeftColor—border-left-colorColors
borderRightColor—border-right-colorColors
borderStartColor—border-inline-start-colorColors
borderEndColor—border-inline-end-colorColors
borderXColor—border-inline-colorColors
borderYColor—border-block-colorColors
Border and outline colors example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box borderColor={"borderSubtle"} />

// Exact prop
// No shorthand is defined for this prop.

Border widths

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
borderWidth—border-widthBorders
borderTopWidth—border-top-widthBorders
borderBottomWidth—border-bottom-widthBorders
borderLeftWidth—border-left-widthBorders
borderRightWidth—border-right-widthBorders
borderStartWidth—border-inline-start-widthBorders
borderEndWidth—border-inline-end-widthBorders
borderXWidth—border-inline-widthBorders
borderYWidth—border-block-widthBorders
Border widths example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box borderWidth={"sm"} />

// Exact prop
// No shorthand is defined for this prop.

Border styles

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
borderStyle—border-style—
borderTopStyle—border-top-style—
borderBottomStyle—border-bottom-style—
borderLeftStyle—border-left-style—
borderRightStyle—border-right-style—
borderStartStyle—border-inline-start-style—
borderEndStyle—border-inline-end-style—
Border styles example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box borderStyle={"solid"} />

// Exact prop
// No shorthand is defined for this prop.

Sibling dividers

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
divideX—border-inline-start-widthBorders
divideY—border-top-widthBorders
divideColor—border-colorColors
divideStyle—border-style—
Sibling dividers example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box divideY={"sm"} />

// Exact prop
// No shorthand is defined for this prop.

Radii: all and sides

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
borderRadiusroundedborder-radiusRadii
borderTopRadiusroundedTopborder-top-left-radius; border-top-right-radiusRadii
borderBottomRadiusroundedBottomborder-bottom-left-radius; border-bottom-right-radiusRadii
borderLeftRadiusroundedLeftborder-top-left-radius; border-bottom-left-radiusRadii
borderRightRadiusroundedRightborder-top-right-radius; border-bottom-right-radiusRadii
Radii: all and sides example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box borderRadius={"lg"} />

// Shorthand
<Box rounded={"lg"} />

Radii: physical corners

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
borderTopLeftRadiusroundedTopLeftborder-top-left-radiusRadii
borderTopRightRadiusroundedTopRightborder-top-right-radiusRadii
borderBottomLeftRadiusroundedBottomLeftborder-bottom-left-radiusRadii
borderBottomRightRadiusroundedBottomRightborder-bottom-right-radiusRadii
Radii: physical corners example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box borderTopLeftRadius={"lg"} />

// Shorthand
<Box roundedTopLeft={"lg"} />

Radii: logical corners

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
borderInlineStartRadiusroundedStartborder-start-start-radius; border-end-start-radiusRadii
borderInlineEndRadiusroundedEndborder-start-end-radius; border-end-end-radiusRadii
borderStartStartRadiusroundedStartStartborder-start-start-radiusRadii
borderStartEndRadiusroundedStartEndborder-start-end-radiusRadii
borderEndStartRadiusroundedEndStartborder-end-start-radiusRadii
borderEndEndRadiusroundedEndEndborder-end-end-radiusRadii
Radii: logical corners example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box borderStartStartRadius={"lg"} />

// Shorthand
<Box roundedStartStart={"lg"} />

Elevation and layers

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
boxShadowshadowbox-shadowShadows
zIndex—z-indexZ-index
Elevation and layers example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box boxShadow={"md"} />

// Shorthand
<Box shadow={"md"} />

Typography, transforms, and visibility

Text style and alignment

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
textAlign—text-align—
textStyle—font-family; font-size; font-weight; line-height; letter-spacingTypography
Text style and alignment example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box textStyle={"body"} />

// Exact prop
// No shorthand is defined for this prop.

Text presentation

textTransform and textDecoration accept their documented Responsive token unions.

PropShorthandCSS propertyToken scale
textTransform—text-transform—
textDecorationtextDecortext-decoration—
Text presentation example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box textDecoration={"underline"} />

// Shorthand
<Box textDecor={"underline"} />

Text overflow

uppercase and truncate accept Responsive<boolean>; maxLines accepts Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
uppercase—text-transform—
truncate—overflow; text-overflow; white-space—
maxLines—display; -webkit-line-clamp; -webkit-box-orient; overflow—
Text overflow example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box truncate={true} />

// Exact prop
// No shorthand is defined for this prop.

Translation and cursor

These props accept Responsive<UtilityValue>.

PropShorthandCSS propertyToken scale
translateX—translateSpacing
translateY—translateSpacing
cursor—cursor—
Translation and cursor example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box translateX={2} />

// Exact prop
// No shorthand is defined for this prop.

Responsive visibility

hideFrom and hideBelow accept a BreakpointKey.

PropShorthandCSS propertyToken scale
hideFrom—displayBreakpoints
hideBelow—displayBreakpoints
Responsive visibility example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box hideBelow={"md"} />

// Exact prop
// No shorthand is defined for this prop.

Interaction states

Each pseudo prop accepts a static Record<string, UtilityValue>.

PropShorthandCSS propertyToken scale
_hover———
_focus———
_active———
Interaction states example
import { Box } from "@smoothie-framework/whisk-react";

// Long form
<Box _hover={{{ background: "surface3" }}} />

// Exact prop
// No shorthand is defined for this prop.

Surface example

Use a semantic surface, then make the layout and presentation choices explicit.

Account summary

Your saved details are ready to review.

import { Box, Text } from "@smoothie-framework/whisk-react";

export function AccountSummary() {
  return (
    <Box
      padding={4}
      background="surface2"
      border="sm"
      borderColor="borderSubtle"
      rounded="lg"
      shadow="sm"
    >
      <Text textStyle="label">Account summary</Text>
      <Text textStyle="body" color="subtle">
        Your saved details are ready to review.
      </Text>
    </Box>
  );
}