Design System

How the EverydayOS design system works across the monorepo — for humans and AI.

One token source, shared config, consistent components — used by console, marketing, studio, and this playground. This page explains how the pieces connect. For token values, see Tokens. For component docs, see the Registry. For layout rules, see Composition.

Architecture

Tokens flow down through packages into apps. Never edit generated files directly.

Source of Truth

brand.json

semantic.json

→

pnpm tokens:generate

@everydayos/config

tailwind/preset

eslint/next

typescript/base

@everydayos/ui

components

theme.css

*.meta.ts

ds.index.json

Apps (each has own public/fonts/)

console

marketing

studio

playground

packages/design-tokens

Source JSON files. Edit brand.json for colors, typography, spacing. Edit semantic.json for light/dark mappings. Run pnpm tokens:generate after changes.

packages/config

Shared Tailwind preset (tailwind/preset, tailwind/semantic), ESLint config, TypeScript base. All apps import these — ensures consistent tooling without duplication.

packages/ui

Component library with *.meta.ts files for AI context. Generated catalog (ds.index.json). Includes theme.css with CSS variables and @font-face rules. Font files live in src/fonts/ as the source of truth.

packages/content

Sanity CMS schemas and GROQ queries for the marketing site. Shared between apps/marketing and apps/studio.

The .meta.ts System

Every component has a co-located *.meta.ts file that makes it AI-readable. This is how AI knows when to use a component, what to avoid, and how to compose it with others.

What a .meta.ts contains

purposeWhat the component is for (shown in catalog)

rolesSemantic tags: container, layout, typography, control, etc.

oftenWithComponents commonly composed together

avoidWhenWhen NOT to use it — points to the correct alternative

propPreferencesPreferred vs rare prop values for AI guidance

examplesCanonical JSX patterns (inline code strings)

patternsComposition recipes — how to combine with other components

Generated catalog (tiered)

Running pnpm --filter @everydayos/ui build generates a tiered catalog from all *.meta.ts + *.tsx files:

ds.intent-mapKeyword → component lookup. Read FIRST for fast matching.

ds.summaryAll components: name, purpose, avoidWhen (~200 lines).

ds.patternsAggregated composition patterns across all components.

components/*Per-component full spec (props, examples, patterns).

ds.indexFull monolithic index (~4K lines). Use tiered files instead.

Why this matters

The everyday-design-system skill reads the catalog before writing any JSX. If a component is missing examples or patterns in its .meta.ts, AI is more likely to fall back to raw divs and arbitrary classes. Rich meta = better AI output.

Fonts & Assets

Font files must exist in each app's public/fonts/ directory. The UI package is not bundled with apps — it only provides CSS @font-face rules that reference /fonts/... paths.

How fonts work

Source of truthpackages/ui/src/fonts/ — all font files live here

@font-face rulespackages/ui/src/theme.css — Everyday + KP Spatial (*.woff2)

Per-app copyEach app needs fonts in its own public/fonts/ directory

Why?Next.js serves static files from public/. The UI package's theme.css emits url(/fonts/...) which resolves relative to the app's public/ dir.

KP Spatial Trial

Primary — woff2

Main body + heading font. All weights (Light → Black) including italics. Available in all apps.

Everyday

Brand — woff2

Primary brand sans (first in font-sans stack). Weights Light–Black including italics. Source files in packages/ui/src/fonts/; copy Everyday-*.woff2 into each app public/fonts/.

Rhymes Display

Display — TTF

Secondary display font. Regular weight only. Available in playground + marketing.

Adding fonts to a new app

Copy needed font files into your app's public/fonts/ (same filenames as in theme.css). Then import @everydayos/ui/theme.css in your root stylesheet. Next.js serves static files from public/, so url(/fonts/...) resolves correctly per app.

Resources

Where to find what you need across the playground and monorepo.

Tokens

Color palettes, typography scale, spacing, radius — live values from brand.json and semantic.json.

Registry

Component catalog with props, examples, and usage patterns. Generated from *.meta.ts files.

Composition

new

Layout hierarchy guide — Page → Section → Container → Stack/Grid → Surface.

Playbook

Marketing block patterns and hero variations. Visual cookbook for common layouts.

Documentation in the monorepo

All prose documentation lives in /docs/ — never in the project root.

docs/development/DESIGN_SYSTEM.md, MONOREPO_STRUCTURE.md, CURSOR_GUIDE.md

docs/project/STATUS.md, VISION.md, ROADMAP.md, CONSTRAINTS.md

docs/architecture/ARCHITECTURE.md — system-level overview

docs/deployment/ENVIRONMENTS.md, VERCEL.md — deployment guides

docs/business/Market analysis, competitive landscape

docs/reference/Customer journey, hardware specs, integration docs

docs/AI_CONTEXT_INDEXWhich docs to load for each task type

CLAUDE.mdRoot project context for AI — tech stack, commands, conventions

AI Skills

Cursor skills that load specialized context. Invoke with skillkit read <name>. Skills are loaded on-demand — only load when relevant to the current task.

everyday-design-system→ building UI, selecting components, implementing Figma

Primary UI skill. Decision tree, composition patterns, spacing tokens, catalog lookup. Start here for any UI work.

everyday-catalog→ adding components, updating meta files, generate:catalog

How to register components, write *.meta.ts, and regenerate the catalog.

everyday-sanity-workflow→ sanity, CMS content, staging/production datasets

Sanity MCP workflow for marketing content. Querying, publishing, creating pages.

everyday-monorepo→ cross-package work, pnpm filter, turbo pipeline

Workspace commands, dependency management, build order.

figma→ Figma URLs, design-to-code, node IDs

Fetch design context via Figma MCP and translate to production code.

everyday-vercel-deploy→ deploy, vercel config, environment variables

Vercel deployment for monorepo apps. Preview and production deploys.

Quick Reference

Common commands and patterns. Copy-paste ready.

Token workflow

1. Edit source files

packages/design-tokens/source/brand.json
packages/design-tokens/source/semantic.json

2. Generate outputs

pnpm tokens:generate

3. Verify in playground

pnpm --filter playground dev

Component workflow

1. Create component + meta

packages/ui/src/components/ui/MyComponent.tsx
packages/ui/src/components/ui/MyComponent.meta.ts

2. Export from index

packages/ui/src/index.ts

3. Rebuild catalog

pnpm --filter @everydayos/ui build

Layout composition (summary)

Page                    # min-h-screen, once per route
  Section               # full-width band, vertical padding (py), background
    Container           # max-width, centered, horizontal gutters (px)
      Stack / Grid      # vertical/grid layout with token gaps
        Surface         # card: tone, radius, border, padding
          Inline        # wrapping horizontal flow for buttons/badges

Section = vertical rhythm. Container = horizontal constraint. Never nest Container in Container. See Composition guide for details.

App Notes

How each app uses the design system differently.

marketing

Sanity CMS

Uses BlockRenderer to map Sanity sections → layout hierarchy. Presets-only page builder — editors choose content, developers own layout. Glass effects and MediaFrame for hero imagery. Content managed via everyday-sanity-workflow skill.

studio

Sanity v5

Sanity Studio with custom theme. Schemas in @everydayos/content. Not a Next.js app — runs on port 3334. Uses Sanity MCP for content operations.

console

Internal ops

Dashboard layout with sidebar. Uses Surface for cards, Grid for data displays, Item for list rows. Supabase auth via @everydayos/auth. Currently only has KP Spatial fonts — needs Everyday + Rhymes Display added.

playground

This app

Design system documentation and testing ground. Registry generated from ds.index.json. Tokens page renders live values from source JSON. Has all fonts including Everyday and Rhymes Display.