Typography Usage and Boundaries

This page covers the applied side of the website typography system.

Use it when you need examples, implementation patterns, or boundary rules for deciding whether typography belongs in a shared utility or in component-local CSS.

Representative Definitions

Representative implementations from website/themes/sambee/assets/css/shared.css:

@utility type-copy {
  font-family: var(--font-primary);
  font-size: var(--text-copy);
  font-weight: 400;
  font-style: normal;
  letter-spacing: normal;
  line-height: var(--leading-copy);
}

@utility type-label-sm {
  font-family: var(--font-tertiary);
  font-size: var(--text-label-sm);
  font-weight: 400;
  font-style: normal;
  text-transform: uppercase;
  letter-spacing: var(--tracking-label);
}

@utility type-docs-nav {
  font-family: var(--font-primary);
  font-size: var(--text-docs-nav);
  font-weight: 400;
  font-style: normal;
  letter-spacing: normal;
  line-height: var(--leading-docs-nav);
}

@utility type-title-md {
  font-family: var(--font-secondary);
  font-size: var(--text-title-md);
  font-weight: 700;
  font-style: normal;
  letter-spacing: normal;
  line-height: var(--leading-title-md);
}

Template Usage Rules

Templates should apply one semantic typography utility per text role and then combine it with separate classes for color, layout, and interaction state.

Examples from the live theme:

<span class="type-label-eyebrow type-color-accent eyebrow-stack">Documentation</span>
<h2 class="type-section-title type-color-ink">Fast local-first preview</h2>
<span class="docs-sidebar-link docs-sidebar-link-current type-docs-nav type-color-ink ui-current-primary-inset">Current page</span>
<a class="docs-sidebar-link type-docs-nav type-color-muted ui-transition-color type-hover-ink ui-hover-surface-mid" href="/docs/">Documentation</a>

Current usage rules:

apply exactly one semantic type-* utility to a text element
combine it with color helpers, layout helpers, and component-specific state classes as needed
do not stack two type-* utilities that both set size, weight, letter-spacing, line-height, or transform
do not reintroduce a partial base class such as type-label

Patterns intentionally absent from the current theme include:

<span class="type-label type-label-strong">...</span>
<span class="type-label type-label-xs">...</span>
<li class="type-label type-list-item-label">...</li>

Local Typography Boundaries

Not every text treatment is shared.

Docs UI

website/themes/sambee/assets/css/docs.css uses the shared type-docs-nav role for repeated documentation navigation text, including:

table of contents links
version switcher labels and options
nav tree links and current items
sequential navigation labels and titles

Local docs classes still own padding, indentation, and current-item state. For example, .docs-sidebar-link-current adds the stronger weight for the active item instead of relying on a separate semantic utility.

website/themes/sambee/assets/css/navigation.css keeps .nav-link as a component-local role. It consumes shared tracking values so the navigation remains aligned with the site-wide label scale.

Buttons

website/themes/sambee/assets/css/buttons.css keeps .btn and .btn-sm as local button primitives. They consume shared typography tokens where it makes sense, but buttons are not modeled as shared text-role utilities.

Footer layout classes remain local in website/themes/sambee/assets/css/footer.css. Shared typography utilities still supply the text role where that role is reused across templates.

Content-Specific Typography

Article-content semantics such as table headers, figcaption, dt, and admonition titles remain local to content.css. They belong to the content domain, not to shared site-wide text roles.