@webeach-io/design

v0.2.1

Published

2 days ago

Design tokens for WebEach services

Downloads

349

0High
0Medium
0Low

ruslan_mart

`@webeach-io/design`

@webeach-io/design is a unified design tokens package used across the webeach services.

It provides a standardized foundation for building visually consistent user interfaces with full support for both light and dark modes.

@webeach-io/design

📦 Installation

yarn add @webeach-io/design

🎨 Colors

Each color group includes 9 shades (100–900) adapted for both light and dark modes. Shade 600 is the brand/accent anchor.

In light mode, 100 is the lightest shade and 900 is the darkest. In dark mode, the direction is inverted: 100 is the darkest (dark background) and 900 is the lightest (light foreground). This ensures that semantic variables like --color-neutral-100 always represent the primary background colour regardless of the active mode.

Primary — main brand accent colors
Secondary — additional accent colors
Neutral — neutral grayscale palette
Danger — used for errors and critical states
Warning — used for warnings and alerts
Success — used for success messages and confirmations

Light Mode Colors

The table below shows the color values for the light mode:

Dark Mode Colors

The table below shows the color values for the dark mode:

Mode Colors

The table below shows color values that adapt to both light and dark modes:

🌈 Gradients

Currently, there is one gradient variation, available in 9 shades (100–900) for each mode. Gradients are used for decorative elements and to emphasize visual hierarchy.

Light Mode Gradients

The table below shows the gradients for the light mode:

Dark Mode Gradients

The table below shows the gradients for the dark mode:

Mode Gradients

The table below shows gradients that adapt to both light and dark modes.

📐 Sizes

The design tokens package also includes size groups, consisting of both base and semantic values.

Base Sizes — foundational size values (e.g., container width/height)
Spacing — gaps between elements
Rounding — border radius values
Border Sizes — border thickness values

Base Sizes

Below is a table of all available base sizes:

| Name | Value | JS | CSS | |:----:|:-------:|:--------------:|:------------------:| | 1x | 4px | Size['1x'] | var(--size-1x) | | 2x | 8px | Size['2x'] | var(--size-2x) | | 3x | 12px | Size['3x'] | var(--size-3x) | | 4x | 16px | Size['4x'] | var(--size-4x) | | 4.5x | 18px | Size['4.5x'] | var(--size-4-5x) | | 5x | 20px | Size['5x'] | var(--size-5x) | | 6x | 24px | Size['6x'] | var(--size-6x) | | 7x | 28px | Size['7x'] | var(--size-7x) | | 8x | 32px | Size['8x'] | var(--size-8x) | | 10x | 40px | Size['10x'] | var(--size-10x) | | 12x | 48px | Size['12x'] | var(--size-12x) | | 16x | 64px | Size['16x'] | var(--size-16x) | | 24x | 96px | Size['24x'] | var(--size-24x) | | 32x | 128px | Size['32x'] | var(--size-32x) |

Spacing Sizes

The table below shows all available spacing sizes.

| Name | Value | JS | CSS | |:----:|:------:|:-----------------:|:---------------------:| | 0.5x | 2px | Spacing['0.5x'] | var(--spacing-0-5x) | | 1x | 4px | Spacing['1x'] | var(--spacing-1x) | | 2x | 8px | Spacing['2x'] | var(--spacing-2x) | | 3x | 12px | Spacing['3x'] | var(--spacing-3x) | | 4x | 16px | Spacing['4x'] | var(--spacing-4x) | | 5x | 20px | Spacing['5x'] | var(--spacing-5x) | | 6x | 24px | Spacing['6x'] | var(--spacing-6x) | | 7x | 28px | Spacing['7x'] | var(--spacing-7x) | | 8x | 32px | Spacing['8x'] | var(--spacing-8x) | | 10x | 40px | Spacing['10x'] | var(--spacing-10x) | | 12x | 48px | Spacing['12x'] | var(--spacing-12x) |

Roundings

Ниже приведена таблица с размерами сгруглений

| Name | Value | JS | CSS | |:----:|:------:|:------------------:|:----------------------:| | 1x | 4px | Rounding['1x'] | var(--rounding-1x) | | 1.5x | 6px | Rounding['1.5x'] | var(--rounding-1-5x) | | 2x | 8px | Rounding['2x'] | var(--rounding-2x) | | 4x | 16px | Rounding['4x'] | var(--rounding-4x) |

Border Sizes

The table below shows all available border thickness values.

✍️ Typography

The typography system includes styles for various levels of headings, body text, and code blocks.

Available groups:

Headings — 5 levels with different weight variations
Body text — multiple sizes and weights
Monospaced style — for displaying code

⚠️ Note: Font files are not included in this package. You are responsible for importing fonts manually in your project, for example via Google Fonts.

Root Font Size Requirement

Font sizes in this package use rem units scaled to a 10px base: 1rem = 10px. This means your project must set the following in its global CSS:

:root {
  font-size: 62.5%; /* 1rem = 10px (62.5% of the browser default 16px) */
}

Without this, all rem-based typography values will render at incorrect sizes. For example, 1.6rem is intended to render as 16px, but without the root override it would compute to 25.6px (1.6 × 16px).

Why 62.5%? Most browsers default to font-size: 16px. Setting 62.5% brings it down to 10px, which makes rem arithmetic straightforward: 1.6rem → 16px, 1.2rem → 12px, 3.2rem → 32px, etc.

Font Families

Font stacks are exposed as separate CSS variables, which allows consumers to override them independently of the individual typography tokens:

| Variant | CSS Variable | Font Stack | |:------------|:--------------------------------|:---------------------------------------------------------------------------------| | primary | var(--font-variant-primary) | "Roboto", -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif | | monospace | var(--font-variant-monospace) | "Roboto Mono", "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace |

Font size values use rem units. Line height values are unitless ratios.

Typography Styles

Below is a table of all available typography styles:

| Name | Font Variant | Font Size | Font Weight | Line Height | JS | CSS | |:----------------------------|:------------:|:---------:|:-----------:|:-----------:|:------------------------------------:|:--------------------------------------------:| | H1 / medium | primary | 3.2rem | 500 | 1.25 | Typography.H1.medium | var(--typography-h1-medium) | | H2 / medium | primary | 2.4rem | 500 | 1.25 | Typography.H2.medium | var(--typography-h2-medium) | | H3 / regular | primary | 2rem | 400 | 1.2 | Typography.H3.regular | var(--typography-h3-regular) | | H3 / medium | primary | 2rem | 500 | 1.2 | Typography.H3.medium | var(--typography-h3-medium) | | H4 / regular | primary | 1.8rem | 400 | 1.33333 | Typography.H4.regular | var(--typography-h4-regular) | | H4 / medium | primary | 1.8rem | 500 | 1.33333 | Typography.H4.medium | var(--typography-h4-medium) | | H5 / regular | primary | 1.6rem | 400 | 1.5 | Typography.H5.regular | var(--typography-h5-regular) | | H5 / medium | primary | 1.6rem | 500 | 1.5 | Typography.H5.medium | var(--typography-h5-medium) | | H5 / bold | primary | 1.6rem | 700 | 1.5 | Typography.H5.bold | var(--typography-h5-bold) | | Body / extraSmall / regular | primary | 1.2rem | 400 | 1.5 | Typography.Body.extraSmall.regular | var(--typography-body-extra-small-regular) | | Body / extraSmall / medium | primary | 1.2rem | 500 | 1.5 | Typography.Body.extraSmall.medium | var(--typography-body-extra-small-medium) | | Body / small / regular | primary | 1.4rem | 400 | 1.28571 | Typography.Body.small.regular | var(--typography-body-small-regular) | | Body / small / medium | primary | 1.4rem | 500 | 1.28571 | Typography.Body.small.medium | var(--typography-body-small-medium) | | Body / small / bold | primary | 1.4rem | 700 | 1.28571 | Typography.Body.small.bold | var(--typography-body-small-bold) | | Body / medium / regular | primary | 1.6rem | 400 | 1.5 | Typography.Body.medium.regular | var(--typography-body-medium-regular) | | Body / medium / medium | primary | 1.6rem | 500 | 1.5 | Typography.Body.medium.medium | var(--typography-body-medium-medium) | | Body / medium / bold | primary | 1.6rem | 700 | 1.5 | Typography.Body.medium.bold | var(--typography-body-medium-bold) | | Code / regular | monospace | 1.4rem | 400 | 1.42857 | Typography.Code.regular | var(--typography-code-regular) |

🎛️ Mode Switching

To enable automatic mode-based styling, make sure to include the generated CSS tokens file:

import '@webeach-io/design/tokens.css';

The current mode is controlled via the data-ui-mode attribute on the any HTML element. You should define a default value:

<html data-ui-mode="light">
  <head>
    ...
  </head>
  <body>
    ...
  </body>
</html>

<div data-ui-mode="dark">...</div>

You can also manually retrieve mode color and gradient maps in JavaScript:

import { getModeColor, getModeGradient } from '@wrs/design';

const Color = getModeColor('light');
const Gradient = getModeGradient('light');

console.log(Color.primary600); // "hsl(301 53% 55%)"
console.log(Gradient.primary600); // ["hsl(201 84% 55%)", "hsl(301 53% 55%)"]

💡 Examples

Colors

.button {
  background-color: var(--color-primary-500);
  color: var(--color-neutral-100);
}

Gradients

.button {
  background-image: var(--gradient-primary-600);
}

Sizes

.box {
  block-size: var(--size-10x);
  inline-size: var(--size-12x);

  padding-block: var(--size-2x);
  padding-inline: var(--size-3x);
}

.box {
  display: flex;
  gap: var(--spacing-1x);
}

.button {
  background-color: var(--color-neutral-100);
  border-color: var(--color-secondary-600);
  color: var(--color-neutral-900);

  border-style: solid;
  border-width: var(--border-size-regular);
  border-radius: var(--rounding-2x);
}

Typography

.heading-1 {
  font: var(--typography-h1-medium);
}

.paragraph {
  font: var(--typography-body-medium-regular);
}

.small-text {
  font: var(--typography-body-small-regular);
}

.code {
  font: var(--typography-code-regular);
}

🧩 TypeScript Types

This package also provides full TypeScript typings for all design token objects.

import type {
  BorderSizeKey,
  BorderSizeType,
  BorderSizeValue,
  ColorKey,
  GradientKey,
  ModeKey,
  RoundingKey,
  RoundingType,
  RoundingValue,
  SizeKey,
  SizeType,
  SizeValue,
  SpacingKey,
  SpacingType,
  SpacingValue,
  TypographyType,
} from '@webeach-io/design';

You can also access the font family map at runtime (for example, to override font stacks):

import { TypographyFontFamilyMap } from '@webeach-io/design';

console.log(TypographyFontFamilyMap.primary);
// '"Roboto", -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif'

These types help you maintain type safety when working with token keys or token maps in your own components, utilities, or design tooling.

⚙️ Development

Build the library

Compiles the codebase and generates the production-ready output in the dist directory.

yarn run build

Watch mode

Watches for file changes and rebuilds automatically.

yarn run build:watch

Generate assets

Generates color and gradient preview images for use in the README.md.

yarn run generate:assets

⚠️ Note: you need to run this manually whenever you update the color or gradient token sets.

✅ Design Token Requirements

All tokens are validated during the build process. Below are the basic format requirements:

Key names (key) must be in camelCase format
- Example: primary100, secondary900, extraRelaxed
Colors must use the HSL format
- Example: hsl(301 53% 55%)
- hex, rgb, rgba, and other formats are not allowed
Sizes (e.g., Size, Spacing, Rounding, BorderSize) must be in px units
- Example: 16px, 24px
- em, rem, %, auto, inherit, and other units are not allowed
Font sizes (FontSize) must be in rem units
- Example: 1.2rem, 1.6rem
- px, em, %, and other units are not allowed
Line heights (LineHeight) must be unitless numeric ratios
- Example: 1.2, 1.5
- String values with units are not allowed
Font family (fontFamily in Typography) must be a variant key ("primary" or "monospace") — not a raw font stack string
All values must be explicitly defined — empty strings are not allowed

If any token does not meet these requirements, the build will fail with a console error.

🔖 Releasing a New Version

Releases are handled automatically using semantic-release.

Before publishing a new version, make sure to:

Commit and push all changes to the main branch.
Use commit messages that follow the Conventional Commits format:
- feat: ... — for new features
- fix: ... — for bug fixes
- chore: ..., refactor: ..., etc.
Versioning is determined automatically based on the type of commits (patch, minor, major).
Update the README.md:

All tables should be updated if any tokens related to colors, sizes, or typography were changed.
If color or gradient tokens were changed, also run yarn run generate:assets to regenerate the color preview images.

👨‍💻 Author

Developed and maintained by Ruslan Martynov

If you have any suggestions or find a bug, feel free to open an issue or pull request.

📄 License

This package is licensed under the MIT License.