Design System

Matrix OS has a warm, organic visual language built on CSS custom properties. Every app -- whether a single HTML file or a full React project -- uses the same design tokens to stay cohesive with the desktop shell.

Philosophy

Matrix OS is not a cold developer tool. The palette draws from natural materials: terracotta accents, lavender backgrounds, warm blacks. Glass-morphism and subtle blur create depth without heaviness. The aesthetic is warm, approachable, and refined.

CSS Variables

The shell injects --matrix-* variables into app iframes via the OS bridge. Apps that reference these variables automatically adapt when the user changes their theme.

Core Colors

Semantic Colors

Typography and Radius

Color Palette

The palette is warm and organic:

• Background: Lavender #ece5f0 -- the canvas everything floats on
• Primary: Terracotta #c2703a -- the signature accent, used for buttons, links, and focus rings
• Foreground: Warm black #1c1917 -- softer than pure black, matching the organic feel
• Cards: White #ffffff -- clean surfaces with subtle shadow for depth
• Border: Lavender tint #d8d0de -- barely visible structure

Surface Hierarchy

Three levels of elevation:

1. Background (--matrix-bg): The lowest surface. Lavender canvas.
2. Card (--matrix-card): Content panels with subtle shadow.
3. Elevated (--matrix-popover): Floating elements with backdrop blur and pronounced shadow.

Typography

Scale

Font Choices

The shell uses Inter for UI text and JetBrains Mono for code. Apps should inherit via var(--matrix-font-sans) rather than redeclaring fonts.

For display headings in standalone apps, distinctive alternatives are encouraged: DM Serif Display, Space Grotesk, Sora, Fraunces, or Outfit.

Spacing

All spacing follows a 4px grid:

Component Patterns

Buttons

/* Primary */
background: var(--matrix-primary);
color: var(--matrix-primary-fg);
border-radius: var(--matrix-radius-md);
padding: 8px 20px;
font-weight: 600;

/* Secondary */
background: transparent;
border: 1px solid var(--matrix-border);
color: var(--matrix-fg);

/* Ghost */
background: transparent;
color: var(--matrix-fg);
/* hover: background: var(--matrix-accent) */

/* Destructive */
background: var(--matrix-destructive);
color: #ffffff;

Cards

.card {
  background: var(--matrix-card);
  border: 1px solid var(--matrix-border);
  border-radius: var(--matrix-radius-lg);
  padding: 16px;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
}

Glass-morphism

For floating elements:

background: rgba(255, 255, 255, 0.8);
backdrop-filter: blur(8px);
border: 1px solid var(--matrix-border);
border-radius: var(--matrix-radius-xl);

Empty States

Every view must handle zero items:

<div style="text-align: center; padding: 48px 24px;">
  <svg><!-- icon --></svg>
  <h3>No items yet</h3>
  <p>Get started by creating your first item.</p>
  <button>Create Item</button>
</div>

Animation

Only animate transform and opacity. Always respect prefers-reduced-motion.

Orchestrated Page Load

Stagger child element entrances:

.card { animation: fadeUp 0.3s ease-out backwards; }
.card:nth-child(1) { animation-delay: 0ms; }
.card:nth-child(2) { animation-delay: 60ms; }
.card:nth-child(3) { animation-delay: 120ms; }

@keyframes fadeUp {
  from { opacity: 0; transform: translateY(12px); }
  to { opacity: 1; transform: translateY(0); }
}

@matrix-os/ui Package

The @matrix-os/ui package provides themed React components for Vite apps:

import { Button, Card, CardContent, Input, Badge, Dialog } from '@matrix-os/ui';
import '@matrix-os/ui/styles.css';

Components use --matrix-* CSS variables and accept className and style props for customization. They are lightweight (no Radix dependency) and React 19 compatible.

Available Components

AI Design Resources

The AI uses two files when building UI:

• Knowledge file: ~/agents/knowledge/matrix-design-system.md -- full CSS variable reference, patterns, and anti-patterns
• Skill: ~/agents/skills/design-matrix-frontend.md -- design thinking process, aesthetic direction, quality checklist

Both are loaded automatically when the AI builds apps, ensuring consistent visual output.