Define the text style once. Let the system adapt it.

Typography is a configured text style with responsive behavior. A component chooses a style such as h1; the theme defines its size, weight, line height and other properties across breakpoints. Like Density, it keeps shared responsive decisions in the system.

Spacing defines values. Density defines responsive spacing. Typography defines responsive text styles. Typography can use Spacing tokens without forcing the same progression as Density. Native CSS remains available for intentional exceptions.

The source is the theme JSON

This illustrative theme defines the complete progression. Omitted built-in breakpoint names retain the library defaults; custom names can also be configured.

{
  "breakpoints": { "xs": 0, "md": 768, "xl": 1280 },
  "spacing": { "7": "1.75rem", "8": "2rem", "10": "2.5rem" },
  "fonts": { "families": { "ui": "Inter, sans-serif" } },
  "typography_details": {
    "default": {
      "fontFamily": "var(--uxdsl__font__ui)",
      "fontWeight": "400",
      "lineHeight": "1.5"
    },
    "h1": {
      "fontSize": "xs(space(7)) md(space(8)) xl(space(10))",
      "fontWeight": "700",
      "lineHeight": "xs(1.2) md(1.3)"
    }
  }
}

typography_details.default supplies missing fields to each configured style. A style’s own field replaces that default field as a whole; it does not merge individual breakpoint expressions. A responsive field needs a base value. The most recent applicable rule remains active until another breakpoint overrides it.

Choose a style in the component

.page-title {
  @ds-typo(h1);
}

/* Equivalent size behavior, shown in isolation */
.page-title { font-size: 1.75rem; }
@media (min-width: 768px) {
  .page-title { font-size: 2rem; }
}
@media (min-width: 1280px) {
  .page-title { font-size: 2.5rem; }
}

The mixin consumes CSS variables such as --uxdsl__typography__h1-size and --uxdsl__typography__h1-line. The compiler generates their responsive definitions from the JSON. Pure CSS can centralize the same behavior with variables and media queries; UXDSL provides the reusable configuration and compilation layer.

Keep HTML semantics independent of visual styling: use the appropriate heading level for the document, even when its visual style comes from another Typography role. Custom configured names, such as label, can also be consumed with @ds-typo(label).

Change the system, update its consumers

• Change a Typography progression to update every component consuming that style.
• Change a Spacing token to update its direct consumers and the Typography or Density definitions referencing it.
• Change a breakpoint threshold to move transitions using that name.
• Choose another configured style or use a deliberate local CSS override when only one component should change.

One generator for build time and runtime

PostCSS accepts the JSON as its theme option. SSR and browser applications use generateThemeCss(theme) from postcss-uxdsl/ds-runtime. Both call the same Typography generator. For live changes, regenerate and replace the managed theme stylesheet rather than appending overrides:

import { generateThemeCss } from 'postcss-uxdsl/ds-runtime'

// themeStyle is the application's existing managed <style> element.
// Generate first so an invalid update cannot clear the active stylesheet.
const css = generateThemeCss(nextTheme)
themeStyle.textContent = css

The playground edits the JSON and applies this same generator. Its breakpoint buttons inspect a simulated viewport width using the shared resolver; they do not resize the browser. Default mode follows the actual viewport.

Supported fields and validation

Configured fields are fontFamily, fontSize, lineHeight, fontWeight, letterSpacing, textTransform, textDecoration, fontStyle, marginBlockStart and marginBlockEnd. Each accepts a nonempty string containing a CSS value or a configured responsive progression.

The shared compiler checks role names, fields, base values and breakpoint widths. It preserves nested CSS expressions and Spacing references. It does not yet validate every CSS value, token dependency or accessibility requirement. Legacy flat typography variables remain supported; use typography_details for structured responsive styles.