Skip to content
Browse documentation
whisk/ui

Component recipes

Create reusable product patterns on top of whisk/ui without losing theme and variant consistency.

When to use recipes

A recipe defines finite, application-owned CSS that ordinary utility props do not express.

Keep one-off layout in component props. Reach for a recipe when a named pattern, variant vocabulary, custom declaration, or finite condition is shared by more than one surface.

A recipe is not runtime styling

Calling the function returned by defineStyleRecipe selects static class names. It does not inject CSS or observe browser state.

Variants

Use stable recipe names and a small set of variants that make sense in your component API.

notice.styles.ts
import { defineStyleRecipe, whiskThemeContract } from "@smoothie-framework/whisk-styles";

export const noticeStyles = defineStyleRecipe({
  name: "product-notice",
  base: {
    borderStyle: whiskThemeContract.tokens.borderStyles.solid,
    borderWidth: whiskThemeContract.tokens.borderWidths.sm,
    borderRadius: whiskThemeContract.tokens.radii.md,
    padding: `calc(${whiskThemeContract.tokens.spacingUnit} * 4)`,
  },
  variants: {
    tone: {
      neutral: { borderColor: whiskThemeContract.tokens.colors.border },
      accent: { borderColor: whiskThemeContract.tokens.colors.accent },
    },
  },
  defaultVariants: { tone: "neutral" },
});

const className = noticeStyles({ tone: "accent" });

Recipe declarations are CSS declarations, so a literal is allowed when the application owns that value. Prefer a theme-contract reference when one exists; this example uses the shared border, radius, and spacing tokens.

A recipe named product-notice emits the deterministic base class .smth-product-notice. Variant selections add deterministic classes for their selected values.

Conditions

Recipes can define explicit selector, media, and container conditions in a fixed cascade order.

card.styles.ts
import { defineStyleConditions, defineStyleRecipe } from "@smoothie-framework/whisk-styles";

const conditions = defineStyleConditions({
  hover: { kind: "selector", selector: "&:hover" },
  reducedMotion: { kind: "media", query: "(prefers-reduced-motion: reduce)" },
});

export const cardStyles = defineStyleRecipe({
  name: "product-card",
  base: { transition: "transform 160ms ease" },
  variants: {},
  conditions,
  conditionalStyles: [
    { conditions: ["hover"], style: { transform: "translateY(-1px)" } },
    { conditions: ["reducedMotion"], style: { transition: "none" } },
  ],
});

Build setup

Configure the Whisk bundler plugin once; imported style modules emit their CSS before the browser renders the component.

Add the plugin to your application configuration. It discovers imported *.styles.ts modules automatically, so recipes are not listed separately in the configuration. Pass the same options object that declares your utility sources and runtime values; its filename is not discovered automatically.

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)],
});
rspack.config.ts
import { WhiskStylesPlugin } from "@smoothie-framework/whisk-styles/rspack";
import type { Configuration } from "@rspack/core";
import { styleOptions } from "./styles.config.js";

export default {
  plugins: [new WhiskStylesPlugin(styleOptions)],
} satisfies Configuration;
Notice.tsx
import { Box, Text } from "@smoothie-framework/whisk-react";
import { noticeStyles } from "./notice.styles.js";

export function Notice() {
  return (
    <Box className={noticeStyles({ tone: "accent" })}>
      <Text>New activity is ready to review.</Text>
    </Box>
  );
}

Import the recipe into the component that uses it and pass its returned selector to className. An unimported style module is outside the application module graph, so its recipe CSS is not emitted.

Use Custom CSS when a rule belongs to third-party host markup or browser behavior rather than a reusable Whisk/UI pattern.

Use the component's documented host props

Box accepts both className and style because it forwards native host props. Do not assume every Whisk/UI component or compound subcomponent accepts both; use the props documented for that component.