Yamada UI

Using Semantic Tokens in Yamada-UI

Yamada-UI provides a robust design system that encourages the use of semantic tokens for spacing, sizing, and typography. Instead of hardcoding pixel values (e.g., 20px), you should use semantic tokens such as md, lg, etc. This approach offers several benefits:

• Consistency: Semantic tokens ensure a consistent look and feel across the application, as all components use the same set of spacing and sizing values.
• Theme Adaptability: Semantic tokens are mapped to values defined in your theme. If you update the theme (for example, to support dark mode or a new design system), all components using semantic tokens will automatically adapt.
• Maintainability: Using tokens like md or lg makes your code more readable and easier to maintain. It's clear that md is a medium size, regardless of the actual pixel value, which might change in the future.
• Responsiveness: Semantic tokens can be mapped to responsive values, making it easier to build layouts that work well on all devices.

Example

❌ Avoid:

<Box padding="20px" />
<Text fontSize="18px">Hello</Text>

✅ Prefer:

<Box padding="md" />
<Text fontSize="lg">Hello</Text>

In this example, md and lg refer to the values defined in your Yamada-UI theme, which can be centrally managed and updated.

When to Use Semantic Tokens

• For all spacing (padding, margin, gap, etc.)
• For font sizes
• For border radii and other design tokens

Where to Find the Tokens

You can find the available semantic tokens in your theme configuration, under the packages/theme/src/tokens directory.

Layout Best Practices with Yamada-UI

When building layouts in Yamada-UI, prefer using layout primitives like HStack, VStack, Stack, and Flex to provide clear context and intent for your component structure. These components make your layouts more readable and maintainable.

• Use HStack and VStack:

  • HStack arranges children horizontally with consistent spacing.
  • VStack arranges children vertically with consistent spacing.
  • Stack can be used for either direction with the direction prop.

• Prefer gap over direction-specific margins:

  • Use the gap prop to define spacing between children, rather than applying marginLeft, marginTop, etc. This keeps spacing consistent and easier to manage.

Example

❌ Avoid:

<div style={{ display: 'flex', flexDirection: 'row' }}>
  <Box>Item 1</Box>
  <Box style={{ marginLeft: '16px' }}>Item 2</Box>
</div>

✅ Prefer:

<HStack gap="md">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</HStack>

This approach improves clarity and leverages the design system's spacing tokens.

For more complex layouts, use Flex or Stack with the gap prop, and avoid using direction-specific margins unless absolutely necessary.

Style Props in Yamada-UI

Yamada-UI supports a powerful system called Style Props, which allows you to style components directly via props, similar to how you would use inline styles, but with full support for theme tokens and shorthands. This makes it easy to build consistent, theme-aware UIs efficiently.

• Theme-aware: Style props accept semantic tokens and theme values, so you can use values like md, lg, or color names defined in your theme.
• Shorthands: Many CSS properties have shorthand props (e.g., p for padding, bg for background).
• Efficiency: You can quickly style components without writing separate CSS or styled-components.
• Consistency: By using theme tokens and shorthands, your UI remains consistent and easy to maintain.

Example

<Box w="full" p="md" bg="warning" color="white">
  This is Box
</Box>

In this example, w, p, bg, and color are all style props that map to theme tokens and CSS properties. This approach works seamlessly with semantic tokens and layout primitives like HStack, VStack, and Flex.

For a full list of available style props and their mappings, see the official documentation: Yamada-UI Style Props

CSS Value Functions in Yamada-UI

Yamada-UI provides CSS Value Functions that make it easy to perform calculations, comparisons, and color manipulations directly in your style props, all while referencing your theme tokens. This enables more dynamic and theme-consistent styles without leaving your component code.

• calc: Perform calculations using theme tokens or numbers, e.g. w="calc(lg / 2)".
• min/max/clamp: Use CSS's min, max, and clamp functions with theme tokens for responsive and adaptive values.
• Color functions: Easily mix, tint, shade, transparentize, or tone colors using theme tokens, e.g. bg="mix(red.500, blue.500)" or bg="tint(purple.500, 50%)".
• Gradients: Create gradients using theme tokens or custom values, e.g. bgGradient="linear(to-r, purple.500, blue.400)".

Example

<Center w="calc(lg / 2)" bg="primary" p="md" rounded="md" color="white">
  Calc
</Center>

<Box w="full" h="xs" bgGradient="linear(to-r, purple.500, blue.400)" />

For more, see the official documentation: Yamada-UI CSS Value Functions

Prefer HStack/VStack over Flex

While Yamada-UI provides a Flex component for custom layouts, in most cases you should use HStack (for horizontal layouts) or VStack (for vertical layouts). These components provide clearer intent, simpler props, and better maintainability. Only use Flex when you need advanced flexbox features that HStack or VStack cannot provide.

❌ Avoid:

<Flex direction="row" gap="md">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</Flex>

✅ Prefer:

<HStack gap="md">
  <Box>Item 1</Box>
  <Box>Item 2</Box>
</HStack>

This makes your layout code more expressive and easier to understand.