# Custom Pages > Guide for building non-CRUD pages with consistent design. Use when creating portal pages, custom views, detail modals, sidebar widgets, notification drawers, or any page that is not a standard CRUD table. Covers fullscreen modals, minimal text patterns, calendar widgets, doorbell notifications, optimistic updates, and CrudPage read-only integration. Use when this capability is needed. - Skill: `tomevault-io/custom-pages` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/custom-pages` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/custom-pages/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/custom-pages --- # Custom Pages Pattern This skill defines how to build pages that are not standard CRUD tables. Follow these patterns for portal pages, detail views, dashboard-style layouts, and interactive features to ensure visual consistency across the application. ## Design Principles 1. **Minimal text, maximum signal** - Use icons, badges, and compact layouts instead of paragraphs. Show data, not descriptions. 2. **Fullscreen modals for detail views** - Open items in near-fullscreen `Dialog` (98vw x 96vh) with sidebar metadata + main content. Never navigate away from the list. 3. **Progressive disclosure** - Summary cards on the page, full details in a modal/sheet. Tabs for complex data. 4. **Icon-driven metadata** - Small icons (`h-3 w-3` to `h-4 w-4`) next to compact key-value pairs. Never bare text. 5. **Responsive descriptions** - Long text on desktop, short on mobile: `hidden md:inline` / `md:hidden`. 6. **Sidebar widgets** - Calendar, events, activities as right-sidebar cards. Full width on mobile, fixed `xl:w-[380px]` on desktop. 7. **Optimistic updates** - Update UI state immediately, make API call, revert on error. 8. **Permission-gated** - Wrap sections in `PermissionGate` or conditionally render based on `canPerformAction()`. ## Page Types | Type | Pattern | Example | |------|---------|---------| | **Fully custom** | Custom controller + custom React page | Opportunities (procurement for SME users) | | **CrudPage read-only** | GenericPageController with mandatory filters + CrudPage `readOnly` | My Applications | | **Role-specific dashboard** | Detect role in dashboard, render alternate component | SME Dashboard | | **Sheet/Drawer overlay** | Slide-in panel for editing without leaving page | MySmeModal, FormalisationEditSheet | | **Drawer notification** | Bottom-slide drawer for notifications | NotificationDrawer (doorbell) | ## File Structure ``` # Fully custom page app/http/controllers/{feature}/ {feature}_page_controller.go # Custom controller (NOT GenericPageController) resources/js/pages/{Feature}/ Index.tsx # Main page component # CrudPage read-only app/http/controllers/{feature}/ {feature}_page_controller.go # GenericPageController with SetMandatoryFilterProvider resources/js/pages/{Feature}/ Index.tsx # Wraps CrudPage with readOnly={true} # Widgets resources/js/components/widgets/ {Widget}Widget.tsx # Reusable widget card index.ts # Barrel exports # Overlays resources/js/components/ {Feature}Modal.tsx # Sheet or Dialog overlay ``` ## Page Layout Template Every custom page follows this layout: ```tsx

{/* 1. Header */}

Page Title

Full description for desktop Short description for mobile

{/* Optional: Context badges (SME name, score, etc.) */} {smeName && (

{smeName}

{usmeNumber} Score: {score}%

)}

{/* 2. Error state */} {error && ( Error {error} )} {/* 3. Main + Sidebar */}

{/* Stats row */} {/* Tabbed content */} {/* Cards / lists */} {/* Tip card */}

{/* 4. Detail modal (rendered outside flow) */} ``` ## Fullscreen Detail Modal Use for viewing item details. Two-column layout: metadata sidebar + main content area. ```tsx const DetailModal: React.FC<{ item: Item | null; isOpen: boolean; onClose: () => void; }> = ({ item, isOpen, onClose }) => { if (!item) return null; return ( ); }; ``` ## MetadataItem Component Reusable sidebar metadata display: ```tsx const MetadataItem: React.FC<{ icon: React.ReactNode; label: string; value: React.ReactNode; }> = ({ icon, label, value }) => (

{icon}

{label}

{value}

); ``` ## Sheet (Side Panel) for Editing Use `Sheet` for editing forms that should overlay without navigating away: ```tsx Edit Details Business Owner {/* Form fields */} ``` ## Notification Drawer (Doorbell) Bottom-slide `Drawer` for notifications. Triggered from the site header bell icon. ```tsx Notifications {unreadCount > 0 ? `${unreadCount} unread` : "All caught up!"} {/* Optional: Action-required alert */} {pendingCount > 0 && (

router.visit('/admin/applications')}>

{pendingCount} Pending

Click to review

Action Required

)} {/* Tabbed notification list */} All Unread Messages System {/* Notification items with priority color coding */} ``` **Notification item pattern:** - Left border color by priority: red (high), yellow (medium), blue (low) - Icon by type: MessageCircle, Shield, AlertTriangle, CheckCircle, Info - Unread indicator: blue dot `h-2 w-2 rounded-full bg-blue-500` - Relative timestamp: "Just now", "5m ago", "3h ago", "2d ago" - Click to navigate: `router.visit(route)` based on `related_type` ## Calendar Widget Smart sidebar widget combining calendar picker with event list and RSVP: ```tsx Events {district ? `${district} & nationwide` : "Nationwide"} {/* Calendar with event date highlighting */} {/* Event list: selected date or upcoming */} {displayEvents.map(event => (

{event.title}

{urgency.label}

{formatTime(event.date)} {event.venue}

{/* RSVP button with optimistic toggle */}

))} ``` ## Optimistic Updates For any toggle/action that hits an API: ```typescript const handleToggle = async (itemId: number) => { const wasActive = activeItems.has(itemId); // 1. Update UI immediately setActiveItems(prev => { const next = new Set(prev); wasActive ? next.delete(itemId) : next.add(itemId); return next; }); try { // 2. API call if (wasActive) { await axios.delete(`/api/resource/${itemId}/action`); } else { await axios.post(`/api/resource/${itemId}/action`); } } catch (error) { // 3. Revert on failure setActiveItems(prev => { const next = new Set(prev); wasActive ? next.add(itemId) : next.delete(itemId); return next; }); } }; ``` ## CrudPage Read-Only Integration Wrap `CrudPage` with a custom header for user-scoped views: ```tsx export default function MyItemsIndex({ data, filters, permissions, smeName, error }) { const isMobile = useIsMobile(); return (

{/* Custom header with context */}

My Items

Full description Short

{smeName && (

{smeName}

{usmeNumber}

)}

{/* CrudPage in read-only mode */}

data={data} filters={filters} title="Items" resourceName="my-items" columns={isMobile ? mobileColumns : desktopColumns} detailView={ItemDetailView} onRefresh={() => router.reload({ only: ['data'] })} canView={true} readOnly={true} />

); } ``` **Backend**: Use `SetMandatoryFilterProvider` to scope data: ```go controller.SetMandatoryFilterProvider(func(ctx http.Context) map[string]interface{} { user := auth.GetPermissionHelper().GetAuthenticatedUser(ctx) sme, _ := smeService.GetSmeByUserEmail(user.Email) return map[string]interface{}{"sme_id": sme.ID} }) ``` ## Custom Page Controller (Go) For fully custom pages that don't use GenericPageController: ```go type FeaturePageController struct { smeService *services.SmeService dashboardService *services.DashboardService } func (c *FeaturePageController) Index(ctx http.Context) http.Response { // 1. Authenticate user := auth.GetPermissionHelper().GetAuthenticatedUser(ctx) if user == nil { return ctx.Response().Redirect(http.StatusFound, "/login") } // 2. Get user context (linked SME) sme, err := c.smeService.GetSmeByUserEmail(user.Email) if err != nil { return inertiaHelper.Render(ctx, "Feature/Index", map[string]interface{}{ "items": []ItemDTO{}, "error": "No MSME linked to your account", }) } // 3. Fetch and transform data based on user context items := fetchItemsForSme(sme) // 4. Include sidebar widget data calendarEvents := c.dashboardService.GetEventsForDistrictWithAttendance(sme.District, sme.ID) // 5. Render with all props return inertiaHelper.Render(ctx, "Feature/Index", map[string]interface{}{ "items": items, "userName": user.Name, "smeName": sme.Name, "usmeNumber": sme.UsmeNumber, "classification": sme.Classification, "district": sme.District, "calendarEvents": calendarEvents, "smeId": sme.ID, }) } ``` ## Stats Summary Row Compact KPI cards for custom pages: ```tsx

{score}%

Your Score

{/* More stat cards... */}

``` ## Empty State ```tsx const EmptyState: React.FC<{ type: string }> = ({ type }) => (

No {type}

Helpful guidance text here.

); ``` ## Tip / CTA Card Gradient card for tips or calls to action: ```tsx

Improve Your Score

Helpful guidance about what the user can do next.

``` ## Checklist When building a new custom page: - [ ] Use `Admin` layout wrapper with `` - [ ] Header: icon + title + responsive descriptions (`hidden md:inline` / `md:hidden`) - [ ] Context badges in header (SME name, USME number, score, classification) - [ ] Error state with `Alert variant="destructive"` - [ ] Main + sidebar layout: `flex flex-col xl:flex-row gap-6` - [ ] Sidebar: `w-full xl:w-[380px] 2xl:w-[420px] shrink-0` - [ ] Detail view: fullscreen `Dialog` (98vw x 96vh) with sidebar metadata + main content - [ ] MetadataItem: icon + `text-[10px] uppercase` label + `text-sm font-medium` value - [ ] Cards as click targets with `cursor-pointer hover:shadow-md transition-all` - [ ] Tabs for content categories (e.g., Upcoming / Past) - [ ] Empty states: centered icon + title + help text - [ ] Loading states: `animate-pulse` skeletons - [ ] Optimistic updates for toggles/actions - [ ] Local state synced with Inertia props via `useEffect` - [ ] Mobile columns via `useIsMobile()` hook - [ ] Badge color coding for status/urgency/classification - [ ] `toast()` from sonner for save feedback (not validation errors) - [ ] Calendar widget in sidebar if events are relevant - [ ] Permission gating for sections and actions For detailed code examples, see [examples/opportunities-page.md](examples/opportunities-page.md) and [examples/widgets-and-overlays.md](examples/widgets-and-overlays.md). --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/liwoo) — claim your Tome and manage your conversions.