# 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:** ```html LTS Preview Deprecated ``` **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:** ```html Stable Preview Deprecated ``` **Result:** Stable Preview Deprecated **When to use:** - βœ… Tool/feature overviews showing maturity level - βœ… Foundry experiments to show experimental status - ❌ Don't use within running textβ€”use version badges instead --- ### Quick Links Use quick links for pill-styled navigation or resource links. **Syntax:** ```html
πŸ“š Guides πŸ”§ Reference πŸ’¬ Teams Channel
``` **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:** ```html

πŸ“š Guides

Step-by-step tutorials for building applications.

``` **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. ```markdown !!! platform "Platform Configuration" This setting applies to all Forge applications deployed to Azure. ``` !!! platform "Platform Configuration" This setting applies to all Forge applications deployed to Azure. #### Forge Admonition For Forge-specific features and capabilities. ```markdown !!! forge "Forge Feature" This capability is unique to the Forge platform and not available in standard .NET. ``` !!! forge "Forge Feature" This capability is unique to the Forge platform and not available in standard .NET. #### Security Admonition For security-related notices and requirements. ```markdown !!! security "Security Requirement" All API endpoints must implement authentication. See the security guide for details. ``` !!! security "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 (`