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;

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 */
}

Layout System

The Avionics layout system uses a sophisticated CSS Grid approach for responsive, content-focused layouts. Every page shares the same .grid-layout applied to <main> in BaseLayout.astro.

Prose Contexts

We distinguish between generic prose and article content:

• .prose: Generic typography styles for any text block. Uses display: contents so children participate directly in the parent grid.
• .content-prose: Enhanced styles for long-form articles, including specific spacing for headings and lists.

Spacing Tokens

--s-grid-unit: 0.5em;          /* Fundamental grid unit */
--s-gutter-min: var(--s-grid-unit); /* Minimum gutter width */
--s-gutter-max: 9.7ch;         /* Maximum gutter width */
--s-content-max: 67ch;         /* Optimal reading width */
--s-grid: 24px;                /* Base grid unit (components) */
--s-gap: 1.5rem;               /* Standard gap between elements */

Content Grid

The .grid-layout class defines a 6-column symmetric grid with three named content zones. This is the backbone of every page.

.grid-layout {
  display: grid;
  grid-template-columns:
    [full-start]     minmax(var(--s-gutter-min), 1fr)
    [breakout-start] minmax(var(--s-gutter-min), var(--s-gutter-max))
    [content-start]  min(100% - 4 * var(--s-grid-unit), var(--s-content-max))
    [content-end]
                     minmax(var(--s-gutter-min), var(--s-gutter-max)) [breakout-end]
                     minmax(var(--s-gutter-min), 1fr)                 [full-end];
}

Column Map

Zone Widths

Default Placement

All direct children of .grid-layout default to the content column. Opt in to wider zones with utility classes:

.grid-layout > *          { grid-column: content;  }  /* default */
.grid-layout > .breakout  { grid-column: breakout; }
.grid-layout > .full      { grid-column: full; width: 100%; }

Live Demo

The bars below are placed inside the page's .grid-layout to show real column boundaries:

Automatic Breakout

Some elements break out automatically via CSS rules in prose.css and grid.css — no class needed:

• table inside .prose → breakout
• figure inside .prose → breakout

Prose & Grid Integration

The .prose class uses display: contents, which makes its children direct grid participants. This is what allows markdown-rendered content (headings, paragraphs, tables) to align to named grid columns without extra wrapper markup:

.grid-layout > .prose { display: contents; }
.prose > *             { grid-column: content; }
.prose > table          { grid-column: breakout !important; }

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);
}

Components

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

<StatusBadge status="Live" />

<SpecCard 
  title="Context Engineering" 
  description="A set of practices designed to optimize what an AI agent 'sees'..."
  url="/concepts/context-engineering"
  meta="Oct 12, 2026"
  status="Live"
  tags={["context", "agentic-sdlc"]}
/>

<ul class="spec-list">
  <li>
    <SpecListItem
      title="Living Specs"
      url="/practices/living-specs"
      description="A practice for maintaining specifications..."
    />
  </li>
</ul>

<SpecHeader
  data={articleSchema.parse({
    title: "Example Specification",
    description: "A standardized header component...",
    status: "Live",
    lastUpdated: new Date(),
    tags: ["example"]
  })}
/>

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

<ArticleReferences references={[
  {
    type: "website",
    title: "OpenAI Best Practices for Prompt Engineering",
    url: "https://platform.openai.com/docs/guides/prompt-engineering",
    author: "OpenAI",
    published: new Date("2024-01-15"),
    accessed: new Date("2026-01-08"),
    annotation: "Foundational guidance on structuring prompts..."
  },
  // ... more references
]} />

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

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't's

• ❌ 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

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).

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