01. // Color Palette

The Avionics palette is built around International Safety colors—high-contrast, immediately recognizable, and functional.

Background Colors

--c-bg-page: #f4f4f0;    /* Warm, off-white concrete/paper */
--c-bg-surface: #ebebe6; /* Slightly darker, for cards or headers */
--c-border: #d1d1c7;     /* Visible, structural grey */

Usage: --c-bg-page for main page background, --c-bg-surface for cards and headers, --c-border for borders and dividers.

Text Colors

--c-text-primary: #111111;   /* Soft black, like high-quality toner */
--c-text-secondary: #585855; /* Muted grey for secondary information */

Brand Colors

--c-brand: #f04e30;       /* Safety Orange */
--c-brand-hover: #d13a1e; /* Darker orange for hover states */

Status Indicators

/* Success (DIN Standard Green) */
--c-success: #00703c;

/* Warning (Signal Yellow) */
--c-warning: #ffb400;

/* Error (Switch Red) */
--c-error: #cc0000;

---

02. // Typography

The Avionics typography system uses two carefully selected typefaces to create a technical, authoritative feel.

Font Families

--f-sans: "Archivo", sans-serif;  /* Variable font with industrial character */
--f-mono: "B612 Mono", monospace; /* Aviation-grade monospace */

Archivo is a variable font designed for industrial and technical applications. B612 Mono was designed by Airbus for cockpit displays.

Heading Styles

All headings use uppercase transformation and expanded width for maximum impact:

h1, h2, h3 {
  font-weight: 700;
  text-transform: uppercase;
  letter-spacing: 0.02em;
  font-variation-settings: "wdth" 110; /* Expanded width */
}

Element	Size	Usage
h1	2.5rem (40px)	Page titles, main headings (one per page)
h2	1.5rem (24px)	Major sections, chapter headings
h3	1.125rem (18px)	Subsections, technical labels (uses monospace)

---

---

03. // Layout System

The Avionics layout system uses a sophisticated CSS Grid approach for responsive, content-focused layouts.

Prose Contexts

We distinguish between generic prose and article content:

• .prose: Generic typography styles for any text block.
• .content-prose: Enhanced styles for long-form articles, including specific spacing for headings and lists.

Spacing Tokens

--s-grid: 24px;       /* Base grid unit */
--s-gap: 1.5rem;      /* Standard gap between elements */
--s-container: 800px; /* Maximum content width (legacy) */

Grid Layout System

The grid layout creates three named columns for flexible content placement:

--s-content-max: 67ch; /* Optimal reading width */

This creates three content zones:

1. content (67ch max): Default for body text, optimal reading width
2. breakout: Wider zone for tables, code blocks, images
3. full: Full-width zone for backgrounds, hero sections

Spec Grid

A responsive grid for card collections (Concepts, Patterns, Practices):

.spec-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: var(--s-gap);
}

---

04. // Components

Border Box

A utility class for bordered containers:

.border-box {
  border: 1px solid var(--c-border);
  padding: var(--s-gap);
}

Status Badge

Monospace badges for status indicators:

<StatusBadge status="Live" />

Spec Header

Standardized header for specification pages (Concepts, Patterns, Practices). Supports data-driven metadata rendering.

<SpecHeader
  data=[object Object]
/>

Warning Banner

Used for critical system-wide alerts (e.g., Alpha Release warning).

<div class="banner-warning">
  SYSTEM ALERT: EXAMPLE WARNING BANNER
</div>

Article References

Structured reference component for citing external sources in APA-inspired format. Supports 7 reference types: website, paper, book, podcast, video, repository, and standard.

<ArticleReferences references=[object Object] />

Features:

• APA-inspired citation format: Author (Year). Title. Metadata.
• Semantic HTML with <cite>, <ol>, and proper accessibility
• Automatic handling of missing optional fields
• External links with rel="external noopener"
• Required accessed date for website references (validated in schema)

---

05. // Accessibility

The Avionics design system is built with accessibility as a core principle:

Color Contrast

All text colors meet WCAG AA standards:

• Primary text on page background: 14.5:1 (AAA)
• Secondary text on page background: 6.8:1 (AA)
• Brand color on page background: 4.7:1 (AA for large text)

Semantic HTML

• Proper heading hierarchy (H1 → H2 → H3)
• Semantic elements (<article>, <nav>, <main>)
• ARIA labels where appropriate

---

06. // Best Practices

Do's

• ✅ Use CSS custom properties for all colors and spacing
• ✅ Follow the grid layout system for consistent spacing
• ✅ Use semantic HTML elements
• ✅ Maintain heading hierarchy (one H1 per page)
• ✅ Use monospace font for technical/metadata content

Don'ts

• ❌ Don't use arbitrary color values—use design tokens
• ❌ Don't skip heading levels (H1 → H3)
• ❌ Don't use multiple H1s on a single page
• ❌ Don't override font families without good reason
• ❌ Don't create layouts outside the grid system

---

07. // Diagrams

Mermaid diagrams use the Avionics palette for visual consistency. Diagrams are authored in markdown and generated to SVG.

Theme Variables

Key mermaid theme variables mapped to design tokens:

primaryColor: #f04e30    /* --c-brand (nodes) */
clusterBkg: #ebebe6      /* --c-bg-surface (subgraphs) */
clusterBorder: #d1d1c7   /* --c-border */
textColor: #111111       /* --c-text-primary */
fontFamily: "B612 Mono"  /* --f-mono */

Generation Workflow

1. Write ```mermaid block in markdown article
2. Run pnpm diagrams to generate SVG
3. Script outputs to public/mermaid/{slug}-fig-{n}.svg
4. Script adds <figure> reference after mermaid block

Example Flowchart

```mermaid
flowchart LR
    subgraph "Input Layer"
        A["Source"]
    end
    
    subgraph "Processing"
        B["Transform"]
        C["Validate"]
        B --> C
    end
    
    A --> B
    C --> D["Output"]
```

Result: Nodes use Safety Orange (#f04e30), subgraphs use warm grey (#ebebe6), text uses primary black (#111111).

---

08. // File References

The design system is implemented across these files:

• ds/index.css - Design System entrypoint
• ds/tokens.css - Design tokens
• ds/base.css - Base styles
• ds/pre-flight.css - Modern reset
• ds/typography.css - Typography rules
• ds/prose.css - Generic prose styles
• ds/content-prose.css - Article-specific prose styles
• ds/layouts/grid.css - Main grid layout
• ds/layouts/spec-grid.css - Card grid layout
• ds/components/*.css - Component styles
• mermaid.json - Mermaid diagram theme configuration