# Styled System
> This section explains the structure of the styled system, detailing its components and illustrating how they integrate with design tokens.
## Introduction
All components are designed to be styled using props.
Hopper embraces a **Styled System-inspired** approach to styling components, allowing developers to define styles directly via props rather than writing CSS. This method provides a **type-safe and intuitive API**, making it easier to build consistent, on-brand interfaces without dealing with complex class names or global styles. With built-in **intellisense and static analysis**, developers can confidently apply design tokens without memorizing them, ensuring efficiency and reducing errors.
### Style Props
Style props are the most fundamental way to style your components in Hopper. They are basically css styles as props. [Learn more about style props](/styled-system/concepts/styling.md)
### Do's and Don'ts
These guidelines help ensure consistency, maintainability, and design system compliance when using the styled system.
**Rule 1**
* ✅ Do:
```tsx
import { Stack } from "@hopper-ui/components";
;
```
Use styled system props to apply design tokens directly to components
* 🚫 Don't:
```tsx
import { Stack } from "@hopper-ui/components";
;
```
Use the standard React 'style' prop
**Rule 2**
* ✅ Do:
Use styled system props to apply design tokens directly to components
* 🚫 Don't:
Use external CSS files or CSS-in-JS solutions alongside styled system components
**Rule 3**
* ✅ Do:
```tsx
import { Stack } from "@hopper-ui/components";
;
```
Use the UNSAFE\_ prefix when you use a value that is not a token
* 🚫 Don't:
```tsx
import { Stack } from "@hopper-ui/components";
;
```
Use the standard React style prop
### Key Concepts
Follow these links to learn key concepts about the Styled System:
* [Responsive Styles](/styled-system/concepts/responsive-styles.md)
* [Using Style Props on HTML Elements](/styled-system/concepts/html-elements.md)
* [Using Style Props on custom components](/styled-system/concepts/custom-components.md)
## Style Props
This page describes how styling works in Hopper, including how to customize spacing, sizing, and positioning, and how to create your own custom components using Hopper styles.
Hopper components are designed to be consistent across all Workleap applications. They include built-in styling that has been considered carefully, and extensively tested. In general, customizing Hopper is discouraged, but most components do offer control over layout and other aspects. In addition, you can use Hopper's tokens to ensure your application conforms to design requirements, and is adaptive across color schemes.
### Style props
A Hopper style property is a mapping of a CSS property to a component property. With style props, Hopper let you easily set style values for a curated set of CSS properties like font-size, margin, padding, width and many more.
All of the available style props are listed in the ["Properties List"](#properties-list) section below.
#### Usage
To use a style prop on a Hopper component, pass the prop as a camelCased string to the component. By default, only tokens are accepted as values for style props. They help promote consistency and maintainability across your application.
If you need to pass a custom value, you can use the `UNSAFE_` prefix to bypass the token system. You can refer to the ["Escape hatches"](#escape-hatches) section for more information.
```tsx
import { Div } from "@hopper-ui/components";
export default function Example() {
return (
Style properties are fun.
);
}
```
#### Shorthands
Props like border and paddingX are also provided to help you save keystrokes. An exhaustive list of all the supported props is available in the ["Properties List"](#properties-list) section.
```tsx
import { Div } from "@hopper-ui/components";
export default function Example() {
return (
Shorthands.
);
}
```
#### Responsive styles
All style props support responsive values. You can pass an object with breakpoints as keys and values as values to a style prop to set different values for different breakpoints. More information is available in the [Responsive Styles article](./responsive-styles.md).
#### Escape hatches
**CRITICAL: NOT ALL PROPS SUPPORT THE `UNSAFE_` PREFIX.** Only a specific set of props (listed in the [escape-hatches guide](/styled-system/escape-hatches.md)) have `UNSAFE_` versions available.
For these whitelisted props, you can bypass the token system by prefixing the prop name with `UNSAFE_`:
```tsx
```
Critical Rules:
1. Check the [escape-hatches guide](/styled-system/escape-hatches.md) FIRST - it contains the complete whitelist.
2. If a prop is in the whitelist → use UNSAFE\_propName for custom values
3. If a prop is not in the whitelist:
* Use propName directly (no `UNSAFE_` prefix)
* NEVER use tokens for it (`top="core_640"` or `left="core_0"` are invalid)
5. Props with "Tokens Category" of "none" (like `overflow`, `flex`, `position`) are used directly
While we encourage teams to utilize Hopper styles as it is, we do realize that sometimes product specific customizations may be needed. In these cases, we encourage you or your designers to talk to us. We may be able to suggest an alternative implementation strategy, or perhaps your design can help inform future Hopper additions.
While the traditional className and style props are always supported in Hopper components, we also provide an escape hatch for passing custom values to style props. This is done by prefixing the prop name with `UNSAFE_`.
The `UNSAFE_` prefix might look scary, but it's there to remind you that you're bypassing the token system. It's a way to ensure that you're aware that you're doing something that might not be automatically updated when tokens change. It will also help you to search for these usages when you want to update them, or help us to provide missing tokens.
```tsx
import { Div } from "@hopper-ui/components";
export default function Example() {
return (
Style properties are fun.
);
}
```
#### Pseudo-classes
Style props doesn't support every CSS pseudo-classes. [Location pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes#location_pseudo-classes), [input pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes#the_input_pseudo-classes), [tree-structural pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes#tree-structural_pseudo-classes), ::before and ::after are not supported and will most likely never be.
When a CSS pseudo-class is not supported by Hopper style props, we recommend using a CSS class.
Since the following user action pseudo-classes are often used, some style props support them. These behaves like their pseudo CSS counterparts.
| Suffix | Pseudo state |
| ------ | ------------ |
| active | :active |
| hover | :hover |
| focus | :focus |
Not all style props support user action pseudo-classes. Find out which props support user action pseudo-classes in the ["Properties List"](#properties-list) section.
### Properties List
The following tables provide a list of all available style props by category.
#### Space
```tsx
```
Border props (border, borderBottom, borderTop, borderRight, borderLeft) uses an implicit style (solid) and width(1px). These properties only accepts colors for value.
| Property Name | CSS Property | Tokens Category | UNSAFE\_ | Supports |
| ----------------------- | -------------------------- | ------------------------------------------- | -------- | -------------------------------- |
| border | border-color | [Semantic > Colors](/tokens/semantic/color.md) | ✓ | breakpoints & focus/hover/active |
| borderBottom | border-bottom-color | [Semantic > Colors](/tokens/semantic/color.md) | ✓ | breakpoints & focus/hover/active |
| borderTop | border-top-color | [Semantic > Colors](/tokens/semantic/color.md) | ✓ | breakpoints & focus/hover/active |
| borderLeft | border-left-color | [Semantic > Colors](/tokens/semantic/color.md) | ✓ | breakpoints & focus/hover/active |
| borderRight | border-right-color | [Semantic > Colors](/tokens/semantic/color.md) | ✓ | breakpoints & focus/hover/active |
| borderRadius | border-radius | [Semantic > Shape](/tokens/semantic/shape.md) | ✓ | breakpoints |
| borderTopLeftRadius | border-top-left-radius | [Semantic > Shape](/tokens/semantic/shape.md) | ✓ | breakpoints |
| borderTopRightRadius | border-top-right-radius | [Semantic > Shape](/tokens/semantic/shape.md) | ✓ | breakpoints |
| borderBottomLeftRadius | border-bottom-left-radius | [Semantic > Shape](/tokens/semantic/shape.md) | ✓ | breakpoints |
| borderBottomRightRadius | border-bottom-right-radius | [Semantic > Shape](/tokens/semantic/shape.md) | ✓ | breakpoints |
| outline | outline | [Semantic > Colors](/tokens/semantic/color.md) | ✓ | breakpoints & focus |
#### Position
```tsx
```
| Property Name | CSS Property | Tokens Category | UNSAFE\_ | Supports |
| -------------- | --------------- | --------------- | -------- | ----------- |
| position | position | none | ✗ | breakpoints |
| top | top | none | ✗ | breakpoints |
| bottom | bottom | none | ✗ | breakpoints |
| right | right | none | ✗ | breakpoints |
| left | left | none | ✗ | breakpoints |
| zIndex | z-index | none | ✗ | breakpoints |
| objectFit | object-fit | none | ✗ | breakpoints |
| objectPosition | object-position | none | ✗ | breakpoints |
#### Shadow
```tsx
```
| Property Name | CSS Property | Tokens Category | UNSAFE\_ | Supports |
| ------------- | ------------ | -------------------------------------------------- | -------- | -------------------------------- |
| boxShadow | box-shadow | [Semantic > Elevation](/tokens/semantic/elevation.md) | ✓ | breakpoints & focus/hover/active |
#### Miscellaneous
| Property Name | CSS Property | Tokens Category | UNSAFE\_ | Supports |
| ------------- | -------------- | --------------- | -------- | ------------------ |
| content | content | none | ✗ | breakpoint |
| cursor | cursor | none | ✗ | breakpoint & hover |
| pointerEvents | pointer-events | none | ✗ | breakpoint |
| resize | resize | none | ✗ | breakpoint |
| willChange | will-change | none | ✗ | breakpoint |
## Responsive Styles
Hopper style props accept a specialized syntax to support responsive breakpoints. These responsive properties help build adaptive user interfaces.
### Introduction
In addition to static values, all style props support object syntax to specify different values for the prop depending on a responsive breakpoint. Breakpoints are named following t-shirt sizing, and correspond to common device resolutions.
#### Example
A `Div` with a default background color overridden at each breakpoint. Resize your browser window to see this in action.
```tsx
import { Div, Text } from "@hopper-ui/components";
export default function Example() {
return (
Resize the window to see the background color change!
);
}
```
### Breakpoints
In addition to the base, there are five breakpoints inspired by typical device resolutions.
| Name | Media query |
| ---- | ----------------- |
| base | min-width: 0px |
| xs | min-width: 640px |
| sm | min-width: 768px |
| md | min-width: 1024px |
| lg | min-width: 1280px |
| xl | min-width: 1440px |
### Mobile-first
Hopper uses a mobile-first breakpoint system, similar to those in frameworks like Bootstrap and Tailwind.
> **error**Don't use `sm:` to target mobile devices
```tsx
import { Div, Text } from "@hopper-ui/components";
export default function Example() {
return (
Text Content
);
}
```
> **success**Use `base` to target mobile devices
```tsx
import { Div, Text } from "@hopper-ui/components";
export default function Example() {
return (
Text Content
);
}
```
It's often best to start with the mobile first layout for a design, then add styles as the screen size increases, moving from small to larger screens.
### Utility Methods
#### useResponsiveValue
To resolve a responsive value within a React component, Hopper provides a `useResponsiveValue` hook.
```tsx
import { Div, useResponsiveValue } from "@hopper-ui/components";
export default function Example() {
const isFluidValue = useResponsiveValue({ base: true, lg: false });
return (
Content
);
}
```
## HTML Elements
Using Hopper style props on HTML elements.
Hopper provides a set of HTML element components already configured with Hopper styled system. You should choose these components over native HTML elements.
``, ``, ``, `