hamedmp/matrix-os/design-system

Matrix OS Design System

When to Use

Apply this for Matrix integration and accessibility in all visual work. The shared brand is authoritative for Matrix platform surfaces. Generated products and their landing pages use the user’s mood, references and chosen visual family; read app-builder’s visual-reference guidance and record the product direction in DESIGN.md.

Brand

"Technology that understands you." Matrix OS is a personal cloud computer — warm, calm, crafted. The visual language draws from natural materials (forest, sand, ember).

Color Palette

Four brand colors + warm sand shades for gradient depth:

UI Tokens

:root {
  --app-bg: var(--matrix-bg, #FAFAF9);
  --app-fg: var(--matrix-fg, #32352E);
  --app-card: var(--matrix-card, #FCFCF8);
  --app-primary: var(--matrix-primary, #434E3F);
  --app-primary-fg: var(--matrix-primary-fg, #FAFAF5);
  --app-accent: var(--matrix-accent, #D06F25);
  --app-accent-fg: var(--matrix-accent-fg, #FAFAF5);
  --app-muted: var(--matrix-muted, #E1E1D0);
  --app-muted-fg: var(--matrix-muted-fg, #747668);
  --app-border: var(--matrix-border, #D8D6C7);
  --app-success: var(--matrix-success, #3A7D44);
  --app-warning: var(--matrix-warning, #E0A12E);
  --app-danger: var(--matrix-destructive, #D74A3A);
}

Use --matrix-* directly or define --app-* aliases from them. Generated apps may override app-local semantic tokens to implement their chosen visual family. A bright, bold, retro or playful product should not be forced into the subdued Matrix brand palette. Keep contrast, visible focus, non-color status cues and bridge integration; do not mutate the global shell theme.

Matrix Platform Brand Rules

1. One Ember per view. Multiple uses = visual noise.
2. Forest is structural. Headers, primary buttons, nav active states.
3. Cream is warmth. Secondary fills, hover states.
4. Deep is text. Never use pure black #000000.
5. Matrix platform backgrounds inherit the active theme. Quiet solid surfaces are the default for content. Use gradients only when the chosen art direction calls for depth; do not hardcode a light wash over dark mode.
6. Shadows always use Deep-tinted rgba(50,53,46,X), never pure black.

For generated products, select a palette with explicit surface/text/accent roles; choose border weight, shadows, radius and type hierarchy for the actual style. Neo-brutalist products can use ink borders and solid offset shadows; playful products can use cheerful surfaces and original SVG accents. Brand-only Forest/Ember limits do not apply to those product palettes.

Optional depth

Use token-derived shadows and surfaces to explain hierarchy. Glass, gradients, and texture are optional treatments for a specific purpose, never a required app backdrop.

Typography

Inherit var(--matrix-font-sans, system-ui, sans-serif) for UI and var(--matrix-font-mono, monospace) for code. Do not load remote fonts or force a display font on app headings. Create hierarchy through size, weight, leading, and spacing. Use tabular numerals for aligned data; constrain prose measure for comfortable reading.

Type Scale

Keep labels readable at normal text sizes; use uppercase and tracking sparingly for short section labels.

Shapes

Choose a coherent radius scale for the app. Dense tables and editors may use square regions; cards and dialogs can be softer.

Shadows

Glass-morphism

background: rgba(255, 255, 255, 0.55);
backdrop-filter: blur(12px);
border: 1px solid rgba(214, 211, 200, 0.35);

Icons

Use inline SVG or bundled local icon assets only. Do not load icon scripts, CDNs, remote fonts, or third-party JavaScript from generated apps.

Generated launcher icons use the gateway/kernel icon style. Resolve it with loadIconStyle: the exact retired shipped clay default in older system/desktop.json files resolves to the current Matrix desktop family; the owner's iconStyle takes precedence when customized. The family uses mixed silhouettes on transparent backgrounds, strong app-specific pictograms, varied rich colors, controlled depth and shadows. It takes inspiration from Ubuntu/Yaru's visual variety without copying any third-party artwork. Avoid a repeated beige square tile, generic controller, text, logos or watermarks. Preserve owner-provided assets unchanged. See ../app-builder/references/app-icons.md for the full recipe.

Usage: inline an accessible SVG with aria-hidden="true" for decorative icons, or pair the icon button with an aria-label.

Default to simple line-style SVGs for all UI. Only use specialist bundled assets when the context is obvious.

NEVER use text characters as icons. No +, ×, →, ✓. Use inline SVG or a bundled local asset; text characters have unpredictable baselines and never center properly.

Animations

Discover the installed design skills and read the one relevant to polish or gestures; see the builder’s references/app-craft.md for the shared process. Motion serves feedback, continuity, or a spatial relationship. Frequency comes first: keep typing, keyboard actions, and repeated navigation immediate. Do not stagger all content on page mount.

Use short ease-out transitions for occasional entry/exit, anchored to the trigger for popovers. Prefer transform/opacity; never transition: all. Springs are for continuous, interruptible gestures. Avoid decorative bounce and hover lift on every control.

.action { transition: transform 120ms cubic-bezier(0.23, 1, 0.32, 1); }
.action:active { transform: scale(0.97); }
@media (prefers-reduced-motion: reduce) {
  .action { transition: none; }
  .action:active { transform: none; }
}

Preserve visible focus and immediate non-motion feedback. Gate hover treatments behind (hover: hover) and (pointer: fine). Use stable placeholders for loading, announce status accessibly, and never delay ready content to finish a shimmer or entrance. Render true progress rather than animating invented progress from zero on mount.

Component Patterns

Use shadcn-style primitives for app interiors whenever the repo already exposes them: Button, Card, Input, Select, Tabs, Tooltip, Badge, Dialog, and related unstyled composition helpers. Skin those primitives with selected app-local semantic tokens, using inherited Matrix tokens as a baseline instead of inventing one-off controls.

Buttons

.btn { padding: 10px 16px; border-radius: 10px; font-family: var(--matrix-font-sans, system-ui); font-size: 0.875rem; font-weight: 500; transition: transform 120ms ease-out, background-color 150ms ease; }
.btn:focus-visible { outline: 2px solid var(--matrix-accent); outline-offset: 3px; }

Cards

.card { background: var(--matrix-card); color: var(--matrix-fg); border: 1px solid var(--matrix-border); border-radius: 12px; padding: 16px; }

Use stat cards only when the number helps a real decision. A compact label/value row is a good starting point; choose hierarchy and density for the content. Glass/gradients are optional direction choices, not default card materials.

Inputs

.input { background: var(--matrix-bg); color: var(--matrix-fg); border: 1px solid var(--matrix-border); border-radius: 8px; padding: 10px 12px; font-family: var(--matrix-font-sans, system-ui); }
.input:focus-visible { outline: 2px solid var(--matrix-accent); outline-offset: 2px; }

Common Pitfalls (non-negotiable)

Never use text characters as icons. +, ×, →, ✓ will never center. Use inline SVG or bundled local assets.

Always center icon buttons with flexbox. display:flex; align-items:center; justify-content:center.

Components must fill space intentionally. No cards with 80% empty whitespace and tiny text in one corner. Use horizontal layouts for compact cards.

Touch hit areas: minimum 44×44px on touch surfaces. The visible icon may be smaller.

Text overflow. Use overflow:hidden; text-overflow:ellipsis; white-space:nowrap on single-line text in constrained containers.

All inputs need visible focus states. Never just outline:none.

All buttons need hover + active states. No flat state-free buttons.

Don't mix border-radius values on adjacent elements.

Verification