Skip to content
yarcl

Typography

typography: {
  fontFaces: [{ family: 'Fraunces', src: '/fonts/fraunces.woff2', weight: '100 900' }],
  families: {
    serif: 'Fraunces, Georgia, serif',
    sans: 'system-ui, sans-serif',
    mono: 'ui-monospace, Menlo, monospace',
  },
  fonts: { body: 'sans', heading: 'serif', mono: 'mono' },
  styles: {
    display: { family: 'serif', size: '2.75rem', weight: 500, lineHeight: 1.05, letterSpacing: '-0.02em' },
    body:    { family: 'sans',  size: '1rem',    weight: 400, lineHeight: 1.5 },
    label:   { family: 'sans',  size: '0.875rem', weight: 500, lineHeight: 1.4 },
  },
  headings: { h1: 'display', h2: 'title', h3: 'title', h4: 'label', h5: 'label', h6: 'label' },
},

Font files

Section titled “Font files”

fontFaces becomes @font-face rules in the generated CSS. Put the files in your app’s public/ folder and reference them by URL.

Field Example Notes
family 'Fraunces' the name to use in families
src '/fonts/fraunces.woff2' a URL, a list of URLs, or 'local(Fraunces)'; the format is inferred from the extension
weight 400 or '100 900' a range for variable fonts
style 'normal' or 'italic'
display 'swap' the default

Families

Section titled “Families”

Font stacks, referenced by name from text styles and font roles. Each is also available as a key-specific CSS variable such as --yarcl-font-family-sans.

Font roles

Section titled “Font roles”

fonts maps the stable body, heading and mono roles to keys in families. The generated --yarcl-font-body, --yarcl-font-heading and --yarcl-font-mono variables keep application CSS independent of family key names:

body {
  font-family: var(--yarcl-font-body);
}


h1 {
  font-family: var(--yarcl-font-heading);
}

fonts is optional. When omitted, body and heading use sans if present, and mono uses mono if present. Each role otherwise uses the first family in families. Set fonts explicitly to choose other mappings.

Use a --yarcl-font-family-{key} variable only when the application intentionally depends on that specific family key. The existing --yarcl-font-{key} variables remain available, but role names take precedence when a family key is also named body, heading or mono.

Text styles

Section titled “Text styles”

styles is an open group: its keys become the valid values of textStyle on Text and Heading. A style’s family must be a key of families.

displayThe quick brown fox
headingThe quick brown fox
subheadingThe quick brown fox
bodyThe quick brown fox
captionThe quick brown fox
codeThe quick brown fox
labelThe quick brown fox

Each style is also a class, yarcl-type-{key}, for use outside yarcl components.

Each style also emits --yarcl-text-{key}-family, -size, -weight, -line-height and -letter-spacing variables. Letter spacing is normal when the style omits it. Use these variables when styling individual elements outside yarcl components:

.article h2 {
  font-family: var(--yarcl-text-heading-family);
  font-size: var(--yarcl-text-heading-size);
  font-weight: var(--yarcl-text-heading-weight);
  line-height: var(--yarcl-text-heading-line-height);
}

Heading levels

Section titled “Heading levels”

headings maps each level to a text style. <Heading level={2}> renders an <h2> with the h2 style, so the document structure and the visual scale are defined once. textStyle overrides the look for a single heading without changing its level.

Each level also emits --yarcl-h1-* through --yarcl-h6-* variables for family, size, weight, line height and letter spacing. They follow the configured heading map when a theme changes.

Rich text without element classes

Section titled “Rich text without element classes”

Put .yarcl-prose on the container around sanitized HTML or an editor surface. It styles headings from typography.headings, body text from defaults.textStyle, and code from the code text style when present. It also handles paragraphs, lists, quotes, links, tables, images and rules.

<div class="yarcl-prose">
  <h2>Lesson title</h2>
  <p>Lesson text</p>
  <ul><li>First point</li></ul>
</div>

Use typography.prose to choose body and code styles or spacing keys for block gaps, heading gaps and list indentation:

typography: {
  ...defaults.typography,
  prose: { body: 'body', code: 'code', blockGap: 'md', headingGap: 'lg', listIndent: 'lg' },
}

Without typography.prose, block spacing uses defaults.gap, and heading spacing and list indentation use defaults.padding. The generated --yarcl-prose-* variables can be overridden on a particular container.

All six levels are required, and each must be a key of styles.

Labels and helper text

Section titled “Labels and helper text”
  • defaults.labelStyle: Label (and so Field labels) and RadioGroup legends.
  • defaults.helperStyle: helper and error text below form controls.
  • defaults.textStyle: Text when textStyle is omitted.