17 KiB
17 KiB
Building pages and layouts
Role
You are structuring pages for a customer-facing application. Consistent layouts across apps are essential. Every page must use an approved pattern.
The Aura system uses Tailwind CSS for layout. All layouts use Tailwind flex/grid utilities with Aura spacing tokens. The sidebar component uses Aura's sidebar tokens (bg-sidebar, text-sidebar-foreground, etc.).
For all Storybook URLs, see ./storybook-links.md.
Cross-reference these Storybook stories when implementing any layout pattern (full URLs):
Base: https://cognitedata.github.io/aura/storybook/
Standard layout primitives used across all patterns:CONTENT MAX-WIDTHS:
- max-w-7xl — dashboards, full-width layouts
- max-w-4xl — detail pages
- max-w-2xl — forms, wizard step content
- max-w-sm — search inputs, narrow controls
SECTION SPACING:
- space-y-8 — between major page sections (e.g. form groups)
- space-y-6 — between sections within a page
- space-y-4 — between items within a section
- space-y-2 — between label and field, tight groupings
GRID GAPS:
- gap-6 — dashboard grids, chart grids, panel gaps
- gap-4 — card grids, metric grids
- gap-3 — toolbar items, button groups
PAGE PADDING:
- px-6 py-8 — standard content area (desktop)
- px-4 py-6 — mobile content area
- p-4 — card/panel internal padding
- p-6 — larger card internal padding
| Token | Purpose | Light value | Dark value |
|---|---|---|---|
| bg-sidebar | Sidebar background | mountain-900 | mountain-900 |
| text-sidebar-foreground | Sidebar text | mountain-100 | mountain-100 |
| text-sidebar-primary | Sidebar primary | mountain-600 | mountain-600 |
| text-sidebar-primary-foreground | Active item text | white | white |
| bg-sidebar-accent | Active/hover bg | mountain-700 | mountain-700 |
| text-sidebar-accent-foreground | Active text | white | white |
| border-sidebar-border | Sidebar borders | mountain-800 | mountain-800 |
Note: The sidebar is ALWAYS dark-themed, even in light mode.
3+ top-level sections. Persistent navigation needed. Most common for multi-page apps. ┌──────────┬─────────────────────────────┐ │ │ Page Header / Breadcrumb │ │ Sidebar │─────────────────────────────│ │ Nav │ │ │ (dark) │ Main Content Area │ │ │ (bg-background) │ │ │ │ └──────────┴─────────────────────────────┘ Desktop (1440px+): Sidebar 240px, content fills rest. Tablet (768px-1439px): Sidebar collapsible via hamburger. Mobile (below 768px): Sidebar hidden. Hamburger menu. Consider bottom nav for 3-5 primary sections. Implement using Storybook **Example: Sidebar Left**: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--sidebar-left-layout Data visualizations, metrics, monitoring. Maximum horizontal space needed. ┌─────────────────────────────────────────┐ │ Top Navigation Bar │ ├─────────────────────────────────────────┤ │ Page Header + Filters │ ├─────────────────────────────────────────┤ │ ┌───────┐ ┌───────┐ ┌───────┐ │ │ │Metric │ │Metric │ │Metric │ │ │ └───────┘ └───────┘ └───────┘ │ ├─────────────────────────────────────────┤ │ Charts / Visualizations │ ├─────────────────────────────────────────┤ │ Data Table │ └─────────────────────────────────────────┘ Desktop: Multi-column grid (grid-cols-3 or grid-cols-4). Tablet: 2-column grid. Charts stack. Mobile: Single column. Metrics as horizontal scroll. Implement using Storybook **Example: Dashboard** and **Example: Comprehensive Dashboard**: - https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--dashboard-layout - https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--comprehensive-dashboard Data entry, creation flows, configuration, settings with form fields. ┌─────────────────────────────────────────┐ │ Page Header + Back navigation │ ├─────────────────────────────────────────┤ │ ┌───────────────────────────────┐ │ │ │ Form Section 1 (heading) │ │ │ │ [fields] │ │ │ ├───────────────────────────────┤ │ │ │ Form Section 2 (heading) │ │ │ │ [fields] │ │ │ └───────────────────────────────┘ │ ├─────────────────────────────────────────┤ │ Sticky footer: [Cancel] [Save action] │ └─────────────────────────────────────────┘ Desktop: Form centered, max-w-2xl (672px) or max-w-3xl. Tablet: Form fills width with px-6 padding. Mobile: Full width. Sticky footer stays. Fields stack. Use centered content (max-w-2xl) and Tailwind patterns from Storybook **Code Examples**: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--code-examples Viewing a single record: report details, user profile, item information with related data. ┌─────────────────────────────────────────┐ │ Breadcrumb: Reports > Q2 Summary │ ├─────────────────────────────────────────┤ │ Record Header [Title, status, actions] │ ├─────────────────────────────────────────┤ │ ┌─────────────────┬───────────────┐ │ │ │ Main Content │ Sidebar │ │ │ │ (2/3 width) │ (1/3 width) │ │ │ └─────────────────┴───────────────┘ │ └─────────────────────────────────────────┘ Desktop: Two-column (grid-cols-3, main span-2, sidebar span-1). Tablet: Sidebar below main content. Mobile: Single column. Sidebar collapses. Use asymmetric columns from Storybook **Pattern: Column Spans** and composition patterns from **Code Examples**: - https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--column-spans - https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--code-examples App preferences, account settings, notification config. ┌─────────────────────────────────────────┐ │ Page Header: Settings │ ├───────────┬─────────────────────────────┤ │ Settings │ Section Content │ │ Nav │ [Form fields / toggles] │ └───────────┴─────────────────────────────┘ Desktop: Left nav + content area. Tablet: Top tabs replacing left nav. Mobile: Category list → tap opens section full-screen. Implement using Storybook **Pattern: Layout Compositions**: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--compositions Comparison views, editor + preview, master-detail with equal emphasis on both sides. ┌─────────────────────┬─────────────────────┐ │ │ │ │ Panel Left │ Panel Right │ │ (1/2 width) │ (1/2 width) │ │ │ │ └─────────────────────┴─────────────────────┘ Desktop: grid-cols-2, equal columns. Tablet: grid-cols-2 with narrower gap. Mobile: Stack vertically (grid-cols-1), or use Segmented Control to switch between panels. Implement using Storybook **Pattern: Column Spans**: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--column-spans Navigation + content + properties panel. IDE-style layouts. Complex editing workflows with context panels. ┌──────────┬───────────────────┬──────────┐ │ │ │ │ │ Nav/ │ Main Content │ Props/ │ │ Tree │ (flexible) │ Detail │ │ (fixed) │ │ (fixed) │ │ │ │ │ └──────────┴───────────────────┴──────────┘ Desktop (1440px+): All 3 panels visible. Tablet (768-1439px): Hide right panel, toggle via button. Mobile (below 768px): Single panel with navigation as Drawer, right panel as bottom sheet or separate route. Implement using Storybook **Pattern: Layout Compositions**: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--compositions Browsing collections — reports, users, assets, items. The most common page type in data-heavy applications. ┌──────────────────────────────────────────┐ │ Page Header [Title] [Create button] │ ├──────────────────────────────────────────┤ │ Filters toolbar [Search] [Filters] │ ├──────────────────────────────────────────┤ │ Table / List │ │ (with empty state when no data) │ ├──────────────────────────────────────────┤ │ Pagination │ └──────────────────────────────────────────┘ Desktop: Full table with all columns visible. Tablet: Hide non-essential columns, allow horizontal scroll. Mobile: Switch to card/list view with stackable filters. Use Storybook **Example: Card Grid** for card-style list variants and **Grid Patterns** for table/grid configuration: - https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--card-grid-layout - https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--grid-patterns-reference Multi-step creation flows, onboarding, configuration wizards, setup processes. ┌──────────────────────────────────────────┐ │ Step indicator (1 — 2 — 3 — 4) │ ├──────────────────────────────────────────┤ │ │ │ Step Content Area │ │ (centered, max-w-2xl) │ │ │ ├──────────────────────────────────────────┤ │ [Back] [Next/Submit] │ └──────────────────────────────────────────┘ Desktop: Centered content, horizontal numbered step indicator. Tablet: Same layout with px-6 padding. Mobile: Step indicator becomes compact ("Step 2 of 4"), content fills width. Center step content with max-w-2xl; use Storybook **Code Examples** for step and footer patterns: https://cognitedata.github.io/aura/storybook/?path=/story/foundations-layout--code-examples 1. Only 1-2 pages? — Sidebar still works, or use top nav. 2. Layout not listed? — Compose from these patterns. Add a short code comment if the composition is genuinely new. 3. Both data display and entry? — Choose by primary purpose. 4. Need resizable panels? — Start with split-screen or three-panel, add resize handles as needed. 5. Very wide content (data tables)? — Use full-width-dashboard without max-w constraint, or list-page with horizontal scroll.