Sub-app design language

Scope

This document applies to applications hosted inside or beside the OS Shell:

• Local module apps under apps/os-shell (registered via manifests)
• Shared first-party apps in packages/os-apps
• Future standalone apps (e.g. apps/<name> deployed to Cloudflare Pages) that may be loaded in iframe or micro-app modes

Shell chrome rules do not apply verbatim to app interiors.

Posture

Apps should stay readable, theme-aware, and cheap to embed. They may express their own brand and layout language. They should not visually fight the shell’s window frame or break when data-os-theme, data-os-density, or display options change.

Reuse stack (recommended)

1. @prox-os/design-tokens — import css/prox.css (and optionally tailwind/theme.css with Tailwind v4) so surfaces and text track global theme.
2. @prox-os/os-ui — optional layout primitives (Surface, Panel, dock/frame pieces, etc.) when they fit; not mandatory for every screen.
3. @prox-os/app-contract — types and manifest fields for capabilities, navigation hints, and settings; never import shell implementation.

Boundaries (non-negotiable)

• Do not import apps/os-shell/src/** (including Zustand stores, private window manager modules, or shell-only routes).
• Integrate through manifests, app contract types, iframe embedding, or documented postMessage / host bridges — not deep coupling.
• Remote data: TanStack Query (or another documented cache layer) at the app boundary — not shell Zustand.

Embedding and performance

• Assume constrained height inside a window or iframe; avoid unbounded stacking context hacks.
• Lazy-load heavy routes; avoid loading all panes up front.
• Respect reduced-motion and contrast expectations inherited from shell globals when tokens/CSS cascade from the host document.

Standalone deploy + shell carry

Standard pattern (documented for future repos as well):

1. App lives at apps/<app-name> with its own build (Rsbuild, Vite, etc.).
2. Depends on workspace:* for @prox-os/design-tokens, @prox-os/os-ui, @prox-os/app-contract while inside the monorepo.
3. Deploys independently (e.g. Cloudflare Pages).
4. OS Shell loads the deployed URL in iframe or equivalent embed route; communication stays at contract/embed layer.

If an app later moves to another repository, replace workspace:* with npm packages, private registry, or pnpm link / file: — same design packages should stay the portability layer.

Reference app: apps/esmadrider-me (esmadrider.me) — Vite, design tokens + Surface, iframe ?mode=os-app, Cloudflare Pages notes in docs/deployment/esmadrider-me.md. public/os-app.manifest.json is informational; the platform template lives in packages/app-registry (esmadriderMeTemplate), composed into the shell in apps/os-shell/src/apps/registry.ts.

Strong vs weak constraints