Skip to content

Design System

This document defines the visual design system for Forge documentation. Use these patterns to maintain consistency across all documentation pages.

🎨 Color Palette

Forge Brand Colors

Forge Flame
#ff6b35
Primary brand, active states, CTAs
Flame Light
#ff8a5c
Hover states, dark mode
Flame Dark
#e55a2b
Pressed states
Forge Anvil
#434343
Header, footer, dark surfaces

SAIF Brand Colors

Pacific
#007ACC
Links, accents
Evergreen
#4F7E11
Success, stable
Lemon
#FACB47
Warning, beta
Poppy
#E01F22
Error, deprecated

Neutral Colors

Graphite
#323131
Slate
#747272
Stone
#9E9C9C
Pebble
#DFDEDE
Alabaster
#F7F5F2

When to Use Each Color

Color CSS Variable Usage
Forge Flame --forge-flame Primary CTAs, active navigation, brand emphasis
SAIF Pacific --saif-pacific Text links, accent elements, informational
SAIF Evergreen --saif-evergreen Success states, stable badges, checkmarks
SAIF Lemon --saif-lemon Warnings, beta/preview badges, caution
SAIF Poppy --saif-poppy Errors, deprecated badges, critical notices
Forge Anvil --forge-anvil Header, footer, dark backgrounds

📐 Spacing System

The spacing system uses a 16px base with 8 tokens for consistent layouts.

Token Value Pixels Usage
--spacing-xs 0.25rem 4px Tight spacing, inline elements
--spacing-sm 0.5rem 8px Small gaps, padding
--spacing-md 0.75rem 12px Medium padding, card gaps
--spacing-lg 1rem 16px Standard padding, section spacing
--spacing-xl 1.5rem 24px Card padding, major section gaps
--spacing-xxl 2rem 32px Section margins
--spacing-xxxl 3rem 48px Large section breaks
--spacing-xxxxl 4rem 64px Page-level spacing

🔤 Typography

Font Families

Purpose Font CSS Variable
Body text Verdana (SAIF digital standard)
Code Roboto Mono Monospace fallback

Font Weights

Weight Value Usage
Medium 500 Navigation items
Semi 600 Active navigation, emphasis
Bold 700 Headings, strong emphasis

🧩 Components

Version Badges

Use version badges to indicate release status inline.

Syntax:

<span class="version-badge new">LTS</span>
<span class="version-badge beta">Preview</span>
<span class="version-badge deprecated">Deprecated</span>

Result:

LTS Preview Deprecated

When to use:

  • ✅ Version tables to indicate LTS/STS/Preview status
  • ✅ Feature documentation to mark new or deprecated features
  • ✅ Package references to show stability
  • ❌ Don't use for emphasis—use bold instead

Status Indicators

Use status indicators to show feature or component maturity.

Syntax:

<span class="status stable">Stable</span>
<span class="status preview">Preview</span>
<span class="status deprecated">Deprecated</span>

Result:

Stable Preview Deprecated

When to use:

  • ✅ Tool/feature overviews showing maturity level
  • ✅ Roadmap items indicating development stage
  • ✅ Foundry experiments to show experimental status
  • ❌ Don't use within running text—use version badges instead

Use quick links for pill-styled navigation or resource links.

Syntax:

<div class="quick-links">
  <a href="../guides/">📚 Guides</a>
  <a href="../reference/">🔧 Reference</a>
  <a href="https://teams.microsoft.com/...">💬 Teams Channel</a>
</div>

Result:

📚 Guides 🔧 Reference 💬 Teams Channel

When to use:

  • ✅ Index pages for quick navigation
  • ✅ External resource collections
  • ✅ Support/contact link sections
  • ❌ Don't use for inline content links—use standard markdown links

Feature Cards

Use feature cards for homepage-style content sections.

Syntax:

<div class="feature-cards">
  <div class="feature-card">
    <h3>📚 Guides</h3>
    <p>Step-by-step tutorials for building applications.</p>
  </div>
</div>

When to use:

  • ✅ Landing pages with multiple navigation options
  • ✅ Overview sections highlighting key areas
  • ❌ Don't use for regular content—use headings and paragraphs

Custom Admonitions

Beyond Material for MkDocs defaults (tip, note, warning, info, etc.), we have custom admonitions:

Platform Admonition

For platform-specific guidance that applies across the Forge ecosystem.

!!! platform "Platform Configuration"
    This setting applies to all Forge applications deployed to Azure.

Platform Configuration

This setting applies to all Forge applications deployed to Azure.

Forge Admonition

For Forge-specific features and capabilities.

!!! forge "Forge Feature"
    This capability is unique to the Forge platform and not available in standard .NET.

Forge Feature

This capability is unique to the Forge platform and not available in standard .NET.

Security Admonition

For security-related notices and requirements.

!!! security "Security Requirement"
    All API endpoints must implement authentication. See the security guide for details.

Security Requirement

All API endpoints must implement authentication. See the security guide for details.

🌗 Dark Mode

All components automatically support dark mode through CSS custom properties. When creating custom styles:

  1. Use CSS variables instead of hardcoded colors
  2. Test in both modes before committing
  3. Ensure sufficient contrast (WCAG AA minimum)

Testing Checklist

  • Text readable on light backgrounds
  • Text readable on dark backgrounds
  • Links distinguishable from surrounding text
  • Status indicators visible in both modes
  • Code blocks have sufficient contrast

♿ Accessibility

Color Contrast

  • Text on backgrounds: Minimum 4.5:1 contrast ratio (WCAG AA)
  • Large text: Minimum 3:1 contrast ratio
  • Non-text elements: Minimum 3:1 contrast ratio

Focus States

All interactive elements must have visible focus indicators. The theme provides:

  • Orange outline for navigation items
  • Blue outline for content links

Screen Readers

  • Use semantic HTML elements (<nav>, <main>, <article>)
  • Provide alt text for informational images
  • Use ARIA labels for icon-only buttons

📁 File Locations

File Purpose
docs/overrides/main.html Theme extension with CSS custom properties
docs/assets/stylesheets/extra.css Component-specific styles
mkdocs.yml Theme configuration
docs/assets/icons/ Brand icons (SVG, PNG)

🔧 Adding New Styles

When adding new component styles:

  1. Check if existing patterns apply - Use version badges, status indicators, or admonitions first
  2. Use CSS variables - Reference --forge-*, --saif-*, and --spacing-* tokens
  3. Add to extra.css - Keep component styles separate from theme tokens
  4. Document the pattern - Update this page with usage examples
  5. Test both modes - Verify light and dark mode appearance

Example: Adding a New Component

/* In docs/assets/stylesheets/extra.css */

/* ==========================================================================
   New Component Name
   ========================================================================== */

.my-component {
  background: var(--md-default-bg-color);
  border: 1px solid var(--md-default-fg-color--lightest);
  border-radius: 8px;
  padding: var(--spacing-lg);
}

.my-component:hover {
  border-color: var(--forge-flame);
}

[data-md-color-scheme="slate"] .my-component {
  /* Dark mode overrides if needed */
}

📚 Resources