@maltjoy/themes

This package gather all themes for Joy design system. This includes a set of tokens in the form of css variables applied to :root.

Customization

As each theme is a simple group of CSS custom properties, you can easily override a specific value if needed.

:root {
    --joy-color-neutral-60: #000;
}

Tokens

This package includes all "Tokens" defined for Joy design system. You can find all of it on our Zeroheight documentation.

Tokens types

• Colors
• Functional colors
• Elevations
• Border radius
• Spacing
• Transition (animation)
• Layers (z-index)
• Forms
• Typography (font-family, font-size, font-weight, line-height)

Source of truth

Tokens are declared in tokens/{primitive,semantic}/*.json and built with Style Dictionary.

• Primitive — raw scales (palette hex, spacing, radius, font size, motion)
• Semantic — role or component aliases that reference primitives (color.text.heading, text.size.default, form.field.height.medium). typography.json composites are build-only: they compile to $FONTS_MAP / getFontBySize() / .joy-font-*, not --joy-typography-* CSS variables.

Generated outputs:

• _tokens-vars.scss — CSS custom properties on :root
• _tokens-classes.scss — utility classes (colors, radius, elevation, font-size, …)
• _fonts-map.generated.scss — typography preset map consumed by src/_tools.scss
• dist/tokens-vars.js — ESM export for JavaScript

Run pnpm build:tokens in this package after editing JSON files. src/_tools.scss remains the stable public Sass facade for $FONTS_MAP and getFontBySize().

Semantic text sizes (text.size.*)

Font-size-only role tokens (--joy-text-size-*). Use when you need size without changing family, weight, or line-height.

| Token | CSS variable | Typical use | |---|---|---| | text.size.heading.page | --joy-text-size-heading-page | page title | | text.size.heading.overlay | --joy-text-size-heading-overlay | overlay title (Dialog, Drawer, …) | | text.size.heading.section | --joy-text-size-heading-section | section title | | text.size.default | --joy-text-size-default | body, input, label | | text.size.support | --joy-text-size-support | helper, badge, tooltip | | text.size.caption | --joy-text-size-caption | caption, small status |

Utility classes: .joy-text-size-heading-page, etc.

Typography role presets

Full stacks in $FONTS_MAP — emitted as .joy-font-* classes and getFontBySize($preset), not as --joy-* CSS variables. Source lives in tokens/semantic/typography.json (build input only). Prefer these for product titles so size and metrics stay aligned with text.size.*.

| Preset | Utility class | Replaces | Components | |---|---|---|---| | heading-page | .joy-font-heading-page | secondary-200 + manual size | Template, TitleBrand | | heading-overlay | .joy-font-heading-overlay | primary-850 + manual size | Dialog, Drawer, Walkthrough, Product Tour | | heading-section | .joy-font-heading-section | primary-650 + manual size | Panel, PanelSection | | default | .joy-font-default | primary-400 + manual size | Dialog/Drawer body, Highlight, Bottom Sheet, PanelSection content | | support | .joy-font-support | primary-300 + manual size | All subtitles/subheaders/sublabels, FormError, Tooltip body, Textarea helper | | caption | .joy-font-caption | primary-200 + manual size | Availability status, Tooltip small line |

@use '@maltjoy/themes/src/tools' as tools;

.page-title {
  @include tools.getFontBySize(heading-page);
}

.dialog-title {
  @include tools.getFontBySize(heading-overlay);
}

.body-copy {
  @include tools.getFontBySize(default);
}

.helper-text {
  @include tools.getFontBySize(support);
}

.caption-text {
  @include tools.getFontBySize(caption);
}

In Figma, matching text styles are named heading-page, heading-overlay, heading-section, default, support, and caption (lowercase), with fontSize bound to the matching text/size/* variable. See TOKENS_FIGMA_SYNC.md Part 3 for the full sync log.

Legacy presets (primary-400, secondary-200, …) remain available for marketing scale and existing components not yet migrated.

Default theme

Import the compiled default theme:

@import '@maltjoy/themes/dist/default.css';

Or from SCSS:

@use '@maltjoy/themes/dist/default.css';

Custom theme

Extend the default theme and override CSS variables. See src/themes/_example.scss:

@use './tokens-vars';
@use './tokens-classes';
@use './fonts-presets-classes';
@use './spacing-classes';

:root {
  --joy-color-neutral-60: #000;
  --joy-font-size-primary-300: 9px;
}

SCSS utilities

• @maltjoy/themes/src/tools — $FONTS_MAP, getFontBySize() mixin
• @maltjoy/themes/src/tokens/src/spacing — $SPACING_SCALE indices for generated gap/spacing classes

Utility classes (colors, spacing, typography presets, .joy-link, …) are included in dist/default.css.