suplement/.agents/skills/building-admin-dashboard-customizations/references/typography.md

Typography Guidelines

Contents

• Core Typography Pattern
• Typography Rules
• Complete Examples
• Text Color Classes
• Common Patterns
• Quick Reference

Core Typography Pattern

Use the Text component from @medusajs/ui for all text elements. Follow these specific patterns:

Headings/Labels

Use this pattern for section headings, field labels, or any primary text:

<Text size="small" leading="compact" weight="plus">
  {labelText}
</Text>

Body/Descriptions

Use this pattern for descriptions, helper text, or secondary information:

<Text size="small" leading="compact" className="text-ui-fg-subtle">
  {descriptionText}
</Text>

Typography Rules

• Never use <Heading> component for small sections within widgets/containers
• Always use size="small" and leading="compact" for consistency
• Use weight="plus" for labels and headings
• Use className="text-ui-fg-subtle" for secondary/descriptive text
• For larger headings (page titles, container headers), use the <Heading> component

Complete Examples

Widget Section with Label and Description

import { Text } from "@medusajs/ui"

// In a container or widget:
<div className="flex flex-col gap-y-2">
  <Text size="small" leading="compact" weight="plus">
    Product Settings
  </Text>
  <Text size="small" leading="compact" className="text-ui-fg-subtle">
    Configure how this product appears in your store
  </Text>
</div>

List Item with Title and Subtitle

<div className="flex flex-col gap-y-1">
  <Text size="small" leading="compact" weight="plus">
    Premium T-Shirt
  </Text>
  <Text size="small" leading="compact" className="text-ui-fg-subtle">
    Size: Large • Color: Blue
  </Text>
</div>

Container Header (Use Heading)

import { Container, Heading } from "@medusajs/ui"

<Container className="divide-y p-0">
  <div className="flex items-center justify-between px-6 py-4">
    <Heading level="h2">Related Products</Heading>
  </div>
  {/* ... */}
</Container>

Empty State Message

<Text size="small" leading="compact" className="text-ui-fg-subtle">
  No related products selected
</Text>

Form Field Label

<div className="flex flex-col gap-y-2">
  <Text size="small" leading="compact" weight="plus">
    Display Name
  </Text>
  <Input {...props} />
</div>

Error Message

<Text size="small" className="text-ui-fg-error">
  This field is required
</Text>

Badge or Status Text

<div className="flex items-center gap-x-2">
  <Text size="small" leading="compact" weight="plus">
    Status:
  </Text>
  <Text size="small" leading="compact" className="text-ui-fg-subtle">
    Active
  </Text>
</div>

Text Color Classes

Medusa UI provides semantic color classes:

• text-ui-fg-base - Default text color (rarely needed, it's the default)
• text-ui-fg-subtle - Secondary/muted text
• text-ui-fg-muted - Even more muted
• text-ui-fg-disabled - Disabled state
• text-ui-fg-error - Error messages
• text-ui-fg-success - Success messages
• text-ui-fg-warning - Warning messages

Common Patterns

Two-Column Layout

<div className="grid grid-cols-2 gap-4">
  <div className="flex flex-col gap-y-1">
    <Text size="small" leading="compact" className="text-ui-fg-subtle">
      Category
    </Text>
    <Text size="small" leading="compact" weight="plus">
      Clothing
    </Text>
  </div>
  <div className="flex flex-col gap-y-1">
    <Text size="small" leading="compact" className="text-ui-fg-subtle">
      Status
    </Text>
    <Text size="small" leading="compact" weight="plus">
      Published
    </Text>
  </div>
</div>

Inline Label-Value Pair

<div className="flex items-center gap-x-2">
  <Text size="small" leading="compact" className="text-ui-fg-subtle">
    SKU:
  </Text>
  <Text size="small" leading="compact" weight="plus">
    SHIRT-001
  </Text>
</div>

Card with Title and Metadata

<div className="flex flex-col gap-y-2">
  <Text size="small" leading="compact" weight="plus">
    Premium Cotton T-Shirt
  </Text>
  <div className="flex items-center gap-x-2 text-ui-fg-subtle">
    <Text size="small" leading="compact">
      $29.99
    </Text>
    <Text size="small" leading="compact">
      •
    </Text>
    <Text size="small" leading="compact">
      In stock
    </Text>
  </div>
</div>

Quick Reference

Use Case	Pattern
Section headings	weight="plus"
Primary text	weight="plus"
Labels	weight="plus"
Descriptions	className="text-ui-fg-subtle"
Helper text	className="text-ui-fg-subtle"
Metadata	className="text-ui-fg-subtle"
Errors	className="text-ui-fg-error"
Empty states	className="text-ui-fg-subtle"
Large headers	<Heading> component