The Washington Post Design System utilizes the css-in-js library, Stitches, to optimize app performance and dev experience. For more context about why we use Stitches, check out this post by the WPDS team.

Stitches functions make creating and styling components easy. Below, we’ll dive into the functions most useful to a user of our UI Kit, but check out Stitches’ other functions if you’re curious.

The styled function is used to simply create React components with styles. The arguments to the function are:

1. either an HTML element or a react component
2. styles

Component variants may also be specified. For example:

import { styled, css } from '@washingtonpost/wpds-ui-kit'

// create a new component, 'FancyButton', which modifies a 'button' element
const FancyButton = styled('button', {
	// base styles

	variants: {
		variant: {
			fancier: {
				// fancier styles
			},
			fanciest : {
				// fanciest styles
			},
		},
	},
});

// Use it
<FancyButton>I'm fancy!</FancyButton>
<FancyButton variant="fancier">I am fancier!</FancyButton>
To enter the code editing mode, press Enter. To exit the edit mode, press Escape
You are editing the code. To exit the edit mode, press Escape

The css function can be used to create reusable styles through the application of a class name or used inline to style individual elements. Here’s an example of inline use, utilizing the already defined FancyButton from before:

<FancyButton css={{ //base styles, optional variants }}>I'm fancy!</FancyButton>
To enter the code editing mode, press Enter. To exit the edit mode, press Escape
You are editing the code. To exit the edit mode, press Escape

And below demonstrates the application of css through the classname property:

const newButton = css({
  // base styles
});

// Use it
<div className={newButton()}>I'm new!</div>;
To enter the code editing mode, press Enter. To exit the edit mode, press Escape
You are editing the code. To exit the edit mode, press Escape

**note: style property names use camel case in these functions (example: z-index becomes zIndex)

Another function available in Stitches is the keyframes function. Using the keyframe animation technique, Stitches allows the creation of global CSS keyframe rules, which lets transitions be easily reused across code. Below is an example of a simple fading-out animation:

import { keyframes } from '@washingtonpost/wpds-ui-kit'

const fadeOut = keyframes({
	from: { opacity: 1 },
	to: { opacity: 0 },
});

// Use it
const fadingInButton = styled("button", {
	'&hover': {
		animation: `${fadeOut} 200ms ease-out`,
	}
)};
To enter the code editing mode, press Enter. To exit the edit mode, press Escape
You are editing the code. To exit the edit mode, press Escape

The theme object contains useful token data that can be applied when styling an element. WPDS specifies its own tokens for many attributes, which can be explored throughout the foundations section of our documentation. Tokens can be accessed in code by using the theme object, which is is preferred over using the $ reference symbol because it provides additional checks. For more information about using our theme tokens, check out this tutorial.

const WPDS = stitches.createStitches({
  prefix,
  theme: {
    colors: {
      ...tokens.light,
      ...tokens.staticColors,
      ...tokens.defaultTheme,
    },
    sizes: tokens.sizes,
    ...
  },
  media: { ... },
  utils: { ... },
});

// Use it
const BestButton = styled('button', {
	// use the size token $200, which is equivalent to 2rem or 32px
	marginTop: theme.space["200"],
	// use the color token $primary, which is equivalent to rgba(17, 17, 17, 1)
	// color tokens change automatically when a color theme is applied
	color: theme.colors.primary,
});
To enter the code editing mode, press Enter. To exit the edit mode, press Escape
You are editing the code. To exit the edit mode, press Escape

Stitches is also capable of defining breakpoints, which are reusable media queries useful for responsive styling. The WPDS UI Kit supports a variety of size breakpoints and custom themes, which can be explored in the kit's stitches.config.ts file. The button in the example below would be uniquely styled when the viewport is smaller than 768px, or sm.

const WPDS = stitches.createStitches({
  prefix,
  theme: { ... },
  media: {
    sm: "(max-width: 767px)",
    md: "(min-width: 768px) and (max-width: 899px)",
    lg: "(min-width: 900px) and (max-width: 1023px)",
		...
  },
  utils: { ... },
});

// Use it
const VariableButton = styled('button', {
	// Base styles
	"@sm" {
		// small-screen styles
	},
});
To enter the code editing mode, press Enter. To exit the edit mode, press Escape
You are editing the code. To exit the edit mode, press Escape

Note: the "@dark" and "@light" media queries are responsive only to OS preferences, so styles specified with these will not affect elements based on the theme toggled in the application. To style an element based on local theme, consider stying based on the parent html element using the syntax: [".<className> &"]. For example:

// Adding opacity to an image when local dark mode is enabled.
const StyledImage = styled(Image, {
  paddingRight: "$075",
  [".wpds-dark &"]: { opacity: "0.9" },
});
To enter the code editing mode, press Enter. To exit the edit mode, press Escape
You are editing the code. To exit the edit mode, press Escape

Utils allow the creation of custom shortcuts to write certain styling properties. For example, the WPDS ui kit has defined utils px and py, which affect horizontal and vertical padding, respectively. px could then be used in place of padding-left and padding-right when styling elements. Check out the other utils WPDS supports defined in the config file.

const WPDS = stitches.createStitches({
  prefix,
  theme: { ... },
  media: { ... },
  utils: {
    px: (value: Stitches.PropertyValue<"padding">) => ({
      paddingLeft: value,
      paddingRight: value,
    }),
    py: (value: Stitches.PropertyValue<"padding">) => ({
      paddingTop: value,
      paddingBottom: value,
    }),
		...
  },
});

// Use it
<p css={{ px: "$075", py: "$100" }}>Paragraph with padding</p>
To enter the code editing mode, press Enter. To exit the edit mode, press Escape
You are editing the code. To exit the edit mode, press Escape

Another feature of the UI Kit that provides greater consistency is globalStyles. In the globalStyles definition, default styles for certain properties are specified by using Stitches’ globalCSS function. A darkModeGlobalStyles modification is also specified, which alters default color styles in dark mode.

The WPDS UI Kit currently supports a light and a dark theme. Using the Stitches function createTheme, tokens specified in the theme object can be overwritten to create custom themes. In the case of our UI Kit, the dark theme is employed when the breakpoint dark is toggled.

If your team would benefit from an additional util, breakpoint, or something else, please reach out to the WPDS team!