Foundations
The core system decisions behind Siteplane UI primitives, motion and global defaults.
Siteplane UI defaults are calm, dense and dashboard-ready. Base UI owns behavior primitives; Siteplane UI owns source files, visual states, variants, density, motion and product-facing composition patterns.
Principles
- Source-distributed components stay inspectable and intentionally updateable.
- Visible controls come from Siteplane UI primitives, not raw browser controls.
- Product screens compose with documented primitives and patterns.
- Motion is subtle, centralized and reduced-motion aware.
- Surface, radius, color, shadow and spacing choices use existing system values first.
- Accessibility behavior, focus, disabled states and data-slot contracts remain native to the primitive.
Global UI provider
SiteplaneUIProvider controls global defaults for compatible primitives:
<SiteplaneUIProvider controlSize="default" density="default" radius="default">
<App />
</SiteplaneUIProvider>Local component props remain stronger than provider defaults. Use provider defaults for broad product-level decisions and local props for exceptions.
Structure
| Area | Responsibility |
|---|---|
apps/site | Public site, Fumadocs content, UI Lab, Visual Grid and generated registry artifacts |
packages/ui/src/components/ui | Primitive source files |
packages/ui/src/components/patterns | Reusable product compositions |
packages/ui/src/motion | Motion tokens, config, provider and CSS variable exports |
packages/ui/src/styles/globals.css | Complete registry-ready UI base stylesheet |
apps/site/src/app/globals.css | Fumadocs, page-system, docs, UI-Lab and Showcase extensions |
docs/ui | Source-of-truth rules, component docs, pattern docs and distribution guidance |
Motion
Motion values live in packages/ui/src/motion/* and are exposed through CSS
variables and provider configuration. Feature components should not introduce
hardcoded durations, easing, scale or distances.
Reduced motion must keep state changes functional while removing transform-heavy animation.
See Motion And Reduced Motion for provider setup, component families, Button scale opt-out and global customization.
Page-facing design system
Docs, landing pages and Visual Grid use the page-facing Siteplane system in apps/site and docs/ui. That system includes the page frame, layout grid, content typography, construction lines and intersection markers. It stays separate from primitive internals in packages/ui.
UI Lab relationship
/ui-lab remains available as the review and playground environment. It is allowed to show previews, variants and unfinished polish work. /docs should stay closer to consumer-facing, accepted guidance.
When a UI Lab example becomes accepted, public docs should promote the useful preview and source contract without exposing temporary comparison work or unfinished polish notes.