17

Composition Rules

Design Patterns & Do's and Don'ts

Visual guidelines for composing components with correct color, typography, and iconography. Reference for designers and design system consumers.

Iconography Do & Don't

Do

  • Use fa-sharp fa-solid prefix for all icons (Sharp Solid only)
  • Add aria-hidden="true" to all decorative icons
  • Add aria-label or title to icon-only interactive elements
  • Use CSS token colors (color: var(--color-alpine)) — never inline hex
  • Size icons relative to context: 12px chips, 16px buttons, 20px nav
  • Use a fixed width on icon wrappers to maintain text alignment

Don't

  • Use fa-solid alone — this loads the rounded variant, not Sharp
  • Use fill to color FA icons — they use currentColor via CSS color
  • Mix FA Sharp with other icon systems (Material, Heroicons, etc.)
  • Use icon-only buttons without accessible labels
  • Scale icons disproportionately to their context (48px icon in a 13px label)
  • Use outline or duotone FA variants — Sharp Solid only in the platform

Color Do & Don't

Do

  • Use Salt (#f6f4ed) as the primary page background
  • Use Alpine (#23403b) for dark surfaces (nav, dark cards)
  • Use BSI Yellow (#f1f14d) on Alpine backgrounds only, or as a fill with Carbon text — never as text or icon color on Salt or white (contrast 1.09:1 and 1.20:1 respectively — both fail WCAG)
  • Use Wasatch (#5a87c3) for links and focus indicators
  • Use Uinta (#43573d) for success states
  • Use Canyonlands (#6c372e) for error/danger only

Don't

  • Use BSI Yellow as a background color (large surfaces)
  • Use Carbon (#000) as a page background
  • Use off-palette colors, generic gradients, or purples
  • Mix Arches and Canyonlands without semantic intent
  • Use white as the primary background (use Salt instead)

Typography Do & Don't

Do

  • Use sentence case for all headings (H1–H4)
  • Use DM Sans 700 for H1, H2, H4; 600 for H3
  • Use DM Sans 500 for Micro / Label / buttons / UI elements
  • Use DM Sans 300 for body copy and longer text
  • Apply negative letter-spacing on H1–H3 (−0.2 to −0.4px)
  • Minimum body: 13px digital · 8pt print
  • Labels and eyebrows (Micro, Label tokens) are the only all-caps patterns — headings are always sentence case

Don't

  • Title Case Headlines (every word capitalized)
  • ALL-CAPS for headings (labels/eyebrows only exception)
  • Italic styling on DM Sans
  • Synthetic bold or unapproved fonts (Fraunces, Inter, Roboto, etc.)
  • Fraunces or any serif in platform UI
  • Text below 12px in any digital context