@dailyautomations/ui 1.0.0 → 1.1.0

package/PAGE_STRUCTURES.md

@@ -0,0 +1,718 @@
+# Daily X Page Structure Guidelines
+
+**Version:** 1.0.0 | **Last Updated:** 2026-01-29
+
+_Standard page templates, layouts, and navigation patterns for Daily X products_
+
+---
+
+## Table of Contents
+
+- [Layout Patterns](#layout-patterns)
+- [Common Page Templates](#common-page-templates)
+- [Navigation Structures](#navigation-structures)
+- [Responsive Behavior](#responsive-behavior)
+- [Page Anatomy](#page-anatomy)
+
+---
+
+## Layout Patterns
+
+### Shell Layout (Primary)
+
+The standard layout for authenticated app pages. Sidebar navigation with main content area.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Logo          Search              User Menu  │ Topbar  │
+├────────┬────────────────────────────────────────────────┤
+│        │                                                │
+│  Nav   │           Main Content Area                    │
+│  Items │                                                │
+│        │                                                │
+│        │                                                │
+│        │                                                │
+│        │                                                │
+│        │                                                │
+│        │                                                │
+├────────┼────────────────────────────────────────────────┤
+│        │  Footer (optional)                             │
+└────────┴────────────────────────────────────────────────┘
+```
+
+**Specifications:**
+| Element | Desktop | Tablet | Mobile |
+|---------|---------|--------|--------|
+| Sidebar width | 240px | 64px (icons) | Hidden (drawer) |
+| Topbar height | 64px | 56px | 56px |
+| Content max-width | 1280px | 100% | 100% |
+| Content padding | 32px | 24px | 16px |
+
+**CSS Structure:**
+```css
+.shell {
+  display: grid;
+  grid-template-columns: var(--sidebar-width) 1fr;
+  grid-template-rows: var(--topbar-height) 1fr;
+  min-height: 100vh;
+}
+
+.sidebar {
+  grid-row: 1 / -1;
+  background: var(--surface);
+  border-right: 1px solid var(--border);
+}
+
+.topbar {
+  background: var(--surface);
+  border-bottom: 1px solid var(--border);
+}
+
+.main {
+  overflow-y: auto;
+  padding: var(--spacing-lg);
+}
+```
+
+---
+
+### Topbar Layout (Secondary)
+
+Horizontal navigation at top. Use for simpler apps or marketing pages.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Logo    Nav Items           Search    User Menu        │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│                   Main Content Area                     │
+│                                                         │
+│                                                         │
+│                                                         │
+│                                                         │
+├─────────────────────────────────────────────────────────┤
+│                        Footer                           │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Use when:**
+- 5 or fewer top-level navigation items
+- Marketing/landing pages
+- Simple single-purpose tools
+
+---
+
+### Centered Layout (Auth/Onboarding)
+
+Focused layout for authentication and onboarding flows.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│                                                         │
+│                    ┌───────────────┐                    │
+│                    │     Logo      │                    │
+│                    │               │                    │
+│                    │  Form/Content │                    │
+│                    │               │                    │
+│                    │               │                    │
+│                    └───────────────┘                    │
+│                                                         │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Specifications:**
+| Element | Value |
+|---------|-------|
+| Card max-width | 400px (login), 480px (signup), 560px (onboarding) |
+| Card padding | 32px |
+| Background | Gradient or subtle pattern on `--background` |
+| Vertical position | Centered or 40% from top |
+
+---
+
+### Split Layout (Auth Alternative)
+
+Half illustration, half content. Use for marketing-focused auth pages.
+
+```
+┌──────────────────────┬──────────────────────────────────┐
+│                      │                                  │
+│                      │           Logo                   │
+│    Illustration      │                                  │
+│    / Branding        │        Form/Content              │
+│    / Testimonial     │                                  │
+│                      │                                  │
+│                      │                                  │
+└──────────────────────┴──────────────────────────────────┘
+```
+
+**Specifications:**
+- Left panel: 40-50% width, hide on mobile
+- Right panel: Centered content, max-width 400px
+- Left panel background: Gradient `purple-500` to `orange-500`
+
+---
+
+## Common Page Templates
+
+### Dashboard Page
+
+Primary landing page after login. Shows key metrics and recent activity.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Page Header                                             │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ Welcome, {Name}                    [Action Button]  │ │
+│ │ {Contextual subtitle}                               │ │
+│ └─────────────────────────────────────────────────────┘ │
+├─────────────────────────────────────────────────────────┤
+│ Metrics Row                                             │
+│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    │
+│ │ Metric 1 │ │ Metric 2 │ │ Metric 3 │ │ Metric 4 │    │
+│ │   123    │ │   456    │ │   78%    │ │   $1.2k  │    │
+│ │ +12%     │ │ -3%      │ │ +5%      │ │ +8%      │    │
+│ └──────────┘ └──────────┘ └──────────┘ └──────────┘    │
+├─────────────────────────────────────────────────────────┤
+│ Primary Content                                         │
+│ ┌─────────────────────────────┐ ┌─────────────────────┐ │
+│ │                             │ │                     │ │
+│ │      Main Chart/Table       │ │   Quick Actions     │ │
+│ │                             │ │   or Activity Feed  │ │
+│ │                             │ │                     │ │
+│ └─────────────────────────────┘ └─────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Components:**
+- Page header with greeting and primary action
+- 3-5 metric cards in responsive grid
+- Main content area (chart, table, or activity)
+- Secondary panel (quick actions, recent items)
+
+**Grid:**
+- Metrics: 4 columns desktop, 2 tablet, 1 mobile
+- Content: 2:1 ratio desktop, stacked on tablet/mobile
+
+---
+
+### List Page (Index)
+
+Display collections of items with filtering and actions.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Page Header                                             │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ {Resource} (count)                 [+ Create New]   │ │
+│ └─────────────────────────────────────────────────────┘ │
+├─────────────────────────────────────────────────────────┤
+│ Toolbar                                                 │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ [Search...] [Filter ▾] [Sort ▾]      [View: ☰ ⊞]   │ │
+│ └─────────────────────────────────────────────────────┘ │
+├─────────────────────────────────────────────────────────┤
+│ Content                                                 │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ ☐  Item 1                              [Actions ▾]  │ │
+│ ├─────────────────────────────────────────────────────┤ │
+│ │ ☐  Item 2                              [Actions ▾]  │ │
+│ ├─────────────────────────────────────────────────────┤ │
+│ │ ☐  Item 3                              [Actions ▾]  │ │
+│ └─────────────────────────────────────────────────────┘ │
+├─────────────────────────────────────────────────────────┤
+│ Pagination                                              │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ Showing 1-10 of 156        [← Prev] 1 2 3 [Next →]  │ │
+│ └─────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Components:**
+- Page header with count and create action
+- Toolbar: search, filters, sort, view toggle
+- Table or card grid view
+- Bulk selection with batch actions
+- Pagination or infinite scroll
+
+**Empty State:**
+```
+┌─────────────────────────────────────────────────────────┐
+│                         📦                              │
+│                  No {resources} yet                     │
+│           Create your first {resource} to              │
+│              get started with {benefit}                 │
+│                                                         │
+│                   [+ Create {Resource}]                 │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Detail Page (Show)
+
+View and edit a single resource.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Breadcrumb                                              │
+│ {Resources} / {Item Name}                               │
+├─────────────────────────────────────────────────────────┤
+│ Page Header                                             │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ {Item Name}                   [Edit] [Delete] [⋮]   │ │
+│ │ Created {date} • Updated {date}                     │ │
+│ └─────────────────────────────────────────────────────┘ │
+├─────────────────────────────────────────────────────────┤
+│ Tabs (optional)                                         │
+│ [ Overview ] [ Activity ] [ Settings ]                  │
+├─────────────────────────────────────────────────────────┤
+│ Content                                                 │
+│ ┌─────────────────────────────┐ ┌─────────────────────┐ │
+│ │                             │ │                     │ │
+│ │      Primary Content        │ │     Sidebar         │ │
+│ │      (details, form)        │ │   (metadata, links) │ │
+│ │                             │ │                     │ │
+│ └─────────────────────────────┘ └─────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Components:**
+- Breadcrumb navigation
+- Header with title, metadata, actions
+- Optional tabs for sub-views
+- 2:1 or 3:1 content/sidebar ratio
+- Sidebar: status, metadata, related items, quick actions
+
+---
+
+### Settings Page
+
+User or workspace configuration.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Page Header                                             │
+│ ┌─────────────────────────────────────────────────────┐ │
+│ │ Settings                                            │ │
+│ └─────────────────────────────────────────────────────┘ │
+├────────────┬────────────────────────────────────────────┤
+│            │                                            │
+│  Profile   │  Section Title                             │
+│  Account   │  ─────────────────────────────────         │
+│  Team      │                                            │
+│  Billing   │  Form fields here                          │
+│  Security  │                                            │
+│  API       │                                            │
+│            │                                            │
+│            │  ─────────────────────────────────         │
+│            │                                            │
+│            │  Another section                           │
+│            │                                            │
+│            │                           [Save Changes]   │
+└────────────┴────────────────────────────────────────────┘
+```
+
+**Components:**
+- Vertical sub-navigation (left)
+- Sections with clear headings
+- Forms with inline validation
+- Save button sticky at bottom or per-section
+
+**Settings Categories:**
+| Category | Content |
+|----------|---------|
+| Profile | Name, avatar, bio, timezone |
+| Account | Email, password, 2FA |
+| Team | Members, roles, invitations |
+| Billing | Plan, payment method, invoices |
+| Security | Sessions, API keys, audit log |
+| Integrations | Connected apps, webhooks |
+| Notifications | Email, push, in-app preferences |
+
+---
+
+### Auth: Login Page
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│                        Logo                             │
+│                                                         │
+│              ┌─────────────────────────┐                │
+│              │     Welcome back        │                │
+│              │                         │                │
+│              │  Email                  │                │
+│              │  [________________]     │                │
+│              │                         │                │
+│              │  Password               │                │
+│              │  [________________]     │                │
+│              │                         │                │
+│              │  [x] Remember me        │                │
+│              │                         │                │
+│              │  [    Sign in     ]     │  ← Orange      │
+│              │                         │                │
+│              │  Forgot password?       │                │
+│              │                         │                │
+│              │  ─── or continue with ───│               │
+│              │                         │                │
+│              │  [Google] [GitHub]      │                │
+│              │                         │                │
+│              │  Don't have an account? │                │
+│              │  Sign up →              │                │
+│              └─────────────────────────┘                │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Requirements:**
+- Email + password fields
+- Remember me checkbox
+- Forgot password link
+- Social login options (if applicable)
+- Link to signup
+- Error states inline
+
+---
+
+### Auth: Signup Page
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│                        Logo                             │
+│                                                         │
+│              ┌─────────────────────────┐                │
+│              │   Create your account   │                │
+│              │                         │                │
+│              │  Full name              │                │
+│              │  [________________]     │                │
+│              │                         │                │
+│              │  Work email             │                │
+│              │  [________________]     │                │
+│              │                         │                │
+│              │  Password               │                │
+│              │  [________________]     │                │
+│              │  • 8+ characters        │  ← Requirements│
+│              │                         │                │
+│              │  [x] I agree to Terms   │                │
+│              │      and Privacy Policy │                │
+│              │                         │                │
+│              │  [  Create account  ]   │  ← Orange      │
+│              │                         │                │
+│              │  Already have account?  │                │
+│              │  Sign in →              │                │
+│              └─────────────────────────┘                │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Requirements:**
+- Name, email, password fields
+- Password requirements visible
+- Terms/privacy checkbox (required)
+- Link to login
+
+---
+
+### Onboarding Flow
+
+Multi-step wizard for new user setup.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│                        Logo                             │
+│                                                         │
+│         Step 1 ───●─────────●─────────○ Step 3          │
+│               Welcome    Setup      Ready               │
+│                                                         │
+│              ┌─────────────────────────┐                │
+│              │   Let's set up your     │                │
+│              │      workspace          │                │
+│              │                         │                │
+│              │  Workspace name         │                │
+│              │  [________________]     │                │
+│              │                         │                │
+│              │  What will you use      │                │
+│              │  Daily for?             │                │
+│              │                         │                │
+│              │  ○ Personal projects    │                │
+│              │  ○ Team collaboration   │                │
+│              │  ○ Client work          │                │
+│              │                         │                │
+│              │          [Continue →]   │                │
+│              │                         │                │
+│              │  Skip for now           │                │
+│              └─────────────────────────┘                │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Components:**
+- Progress indicator (steps or progress bar)
+- Clear step title and description
+- Form content per step
+- Continue button (primary)
+- Skip option (when applicable)
+- Back button (from step 2+)
+
+**Onboarding Steps (typical):**
+1. Welcome/purpose selection
+2. Workspace/team setup
+3. Invite team members (optional)
+4. Connect integrations (optional)
+5. Quick tour or first action
+
+---
+
+### Error Pages
+
+**404 - Not Found**
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│                         404                             │
+│                                                         │
+│                  Page not found                         │
+│                                                         │
+│         The page you're looking for doesn't             │
+│         exist or has been moved.                        │
+│                                                         │
+│                 [Go to Dashboard]                       │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**500 - Server Error**
+```
+┌─────────────────────────────────────────────────────────┐
+│                                                         │
+│                         500                             │
+│                                                         │
+│                Something went wrong                     │
+│                                                         │
+│         We're working on fixing this.                   │
+│         Try refreshing or come back later.              │
+│                                                         │
+│            [Refresh]  [Go to Dashboard]                 │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Navigation Structures
+
+### Primary Navigation (Sidebar)
+
+Hierarchical navigation with icons.
+
+```
+┌────────────────────┐
+│   Logo             │
+├────────────────────┤
+│ ◇ Dashboard        │  ← Current page
+│ ○ Projects         │
+│ ○ Documents        │
+│ ○ Team             │
+│ ○ Analytics        │
+├────────────────────┤  ← Separator
+│ ○ Settings         │
+│ ○ Help             │
+├────────────────────┤
+│ ┌────────────────┐ │
+│ │ 👤 User Name   │ │  ← User menu
+│ │ user@email.com │ │
+│ └────────────────┘ │
+└────────────────────┘
+```
+
+**Specifications:**
+| Element | Specification |
+|---------|---------------|
+| Nav item height | 40px |
+| Icon size | 20px |
+| Icon-text gap | 12px |
+| Indent (nested) | 24px |
+| Active indicator | 3px left border, purple |
+| Hover state | `purple-500/10` background |
+
+**Collapsed State (Tablet):**
+- Show icons only
+- Tooltip on hover
+- Expand on click or hover
+
+---
+
+### Secondary Navigation (Tabs)
+
+Horizontal tabs for sub-sections within a page.
+
+```
+[ Overview ]  [ Activity ]  [ Settings ]  [ Integrations ]
+     ◇             ○             ○              ○
+```
+
+**Specifications:**
+- Active: Bold text, underline indicator (purple)
+- Hover: Text color change
+- Spacing: 24px between tabs
+- Mobile: Horizontal scroll if needed
+
+---
+
+### Breadcrumbs
+
+Show location in hierarchy.
+
+```
+Home / Projects / Project Name / Settings
+```
+
+**Rules:**
+- Max 4 levels visible
+- Truncate middle items on mobile: `Home / ... / Settings`
+- Current page not clickable
+- Separator: `/` or `>`
+
+---
+
+### User Menu
+
+Dropdown from avatar/name in topbar.
+
+```
+┌─────────────────────┐
+│ 👤 User Name        │
+│ user@email.com      │
+├─────────────────────┤
+│ Profile             │
+│ Settings            │
+│ Keyboard shortcuts  │
+├─────────────────────┤
+│ Help & Support      │
+│ What's new          │
+├─────────────────────┤
+│ Sign out            │
+└─────────────────────┘
+```
+
+---
+
+### Mobile Navigation
+
+Bottom navigation or hamburger menu.
+
+**Bottom Nav (5 or fewer items):**
+```
+┌─────┬─────┬─────┬─────┬─────┐
+│  ◇  │  ○  │  ○  │  ○  │  ○  │
+│Home │Proj │Docs │Team │More │
+└─────┴─────┴─────┴─────┴─────┘
+```
+
+**Drawer (6+ items):**
+- Hamburger icon in topbar
+- Full-height drawer from left
+- Same structure as desktop sidebar
+- Overlay background (tap to close)
+
+---
+
+## Responsive Behavior
+
+### Breakpoints
+
+| Name | Width | Target |
+|------|-------|--------|
+| `sm` | 640px | Large phones |
+| `md` | 768px | Tablets |
+| `lg` | 1024px | Small laptops |
+| `xl` | 1280px | Desktops |
+| `2xl` | 1536px | Large screens |
+
+### Layout Changes
+
+| Element | Desktop (lg+) | Tablet (md) | Mobile (sm) |
+|---------|---------------|-------------|-------------|
+| Sidebar | Full (240px) | Collapsed (64px) | Hidden (drawer) |
+| Content padding | 32px | 24px | 16px |
+| Grid columns | 12 | 8 | 4 |
+| Cards per row | 4 | 2 | 1 |
+| Tables | Full | Scroll horizontal | Card view |
+
+### Mobile-First Patterns
+
+- Stack layouts vertically
+- Hide secondary actions behind menus
+- Use bottom sheets instead of modals
+- Prefer swipe gestures for common actions
+
+---
+
+## Page Anatomy
+
+### Page Header
+
+Every page needs a header with:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ {Page Title}                           [Secondary] [+]  │
+│ {Optional description or breadcrumb}                    │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Elements:**
+| Element | Required | Notes |
+|---------|----------|-------|
+| Title | Yes | H1, descriptive |
+| Description | Optional | Explains page purpose |
+| Primary action | If applicable | Orange button, right-aligned |
+| Secondary actions | If applicable | Ghost/outline buttons |
+
+### Content Sections
+
+Group related content with clear sections:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Section Title                             [View all →]  │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│ Section content here                                    │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Spacing:**
+- Between sections: 32px
+- Section title to content: 16px
+- Within section: 16px
+
+### Page Footer (App)
+
+Optional for most app pages. Include when needed:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ © 2026 Daily X  •  Terms  •  Privacy  •  Status         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-29 | Initial page structure guidelines |
+
+---
+
+## Questions?
+
+Contact the design team at design@daily.com for page structure guidance.