Próx OS Design Language
This file is the **single design entrypoint** for Prox OS. It states product posture, constraints by surface, and where to read next.
Role
This file is the single design entrypoint for Prox OS. It states product posture, constraints by surface, and where to read next.
- OS Shell = strong design domain (layout, chrome, density, motion, spatial order).
- Sub-apps (local modules,
packages/os-apps, future standalone deployables, iframe / micro apps) = weak design domain: reuse tokens and primitives where helpful; they do not need to imitate shell chrome.
Do not duplicate long specs here. Follow links.
Product posture
Prox OS is a browser-native personal OS (not a marketing site): personal data sovereignty, an app ecosystem that can grow with the community, and surfaces that stay legible under long sessions.
Visual bias: light-first, Geist-like neutrality, subtle glass and thin structure, infra / developer-tool calm — not generic “AI SaaS” landing aesthetics.
Read order for work
| Task | Read |
|---|---|
| Any UI or visual change | This file, then task-specific docs below |
| Shell chrome, desktop, windows, dock, top bar | os-shell-design-language.md |
| Apps, embeds, iframe apps, standalone Pages apps | app-design-language.md |
| Colors, radii, shadows, density variables, Tailwind bridge | tokens.md, package @prox-os/design-tokens |
os-ui vs app code, headless encapsulation | component-layering.md |
| AI / agent execution discipline | ai-design-workflow.md |
Implementation map (facts on disk)
- CSS variables + theme/density/background variants:
@prox-os/design-tokens→css/prox.css - Optional Tailwind v4
@themebridge:@prox-os/design-tokens/tailwind/theme.css - Shell / shared primitives (stateless):
@prox-os/os-ui— must not import shell stores, app i18n, or data layers - Contracts:
@prox-os/app-contractfor manifests, window semantics, settings shapes — not visual implementation
Anti-patterns (summary)
Full list and rationale: ai-design-workflow.md.
In short: no default blue–purple SaaS gradients, no “three feature cards” filler, no emoji-as-product-icons, no fake testimonials or logo walls, no decorative fake windows to “feel like OS,” no deep imports from apps/os-shell/src/** inside reusable apps, no unmaintainable mega-prompts instead of docs.
Related architecture docs
- App routing and registry:
docs/architecture/app-registry.md,docs/architecture/os-apps.md - Windows and layering:
docs/architecture/window-manager.md - App contract:
docs/architecture/app-contract-view.md