Build for Three Audiences

One page, three audiences

The DS platform serves five roles: superadmin, admin, manager, operator, viewer. These roles do not just control what data a user can access — they reflect how a user thinks about data.

A director wants to know: “How many vehicles are assigned? Any overdue maintenance? What is the fleet utilization rate?” They want three numbers and a chart. Not a table with 500 rows.

An operations manager wants to know: “Which vehicles need action today? Who is assigned to what? What changed since yesterday?” They want a sortable table with filters and action buttons.

A technical admin wants to know: “What are the raw field values? When was the last sync? Which records have data quality issues?” They want the JSON, the audit columns, and the system metadata.

Same data. Three presentations. The DensityGate component makes this one page, not three separate pages.

How DensityGate works

DensityGate is a controlled component that renders one of three children based on the selected density tier:

<DensityGate defaultDensity={roleDensity} onDensityChange={setDensity}>
  <DensityGate.Executive>
    {/* KPI cards, summary charts, trend lines */}
  </DensityGate.Executive>

  <DensityGate.Operational>
    {/* DataGrid with actions, filters, dialogs */}
  </DensityGate.Operational>

  <DensityGate.Technical>
    {/* Raw data, audit columns, JSON viewer, config */}
  </DensityGate.Technical>
</DensityGate>

The component renders a small toggle in the top-right corner: three icons representing summary, table, and detail. Users can switch between tiers at any time. But the default is set by role:

The default is a starting point, not a restriction. Any role can switch to any tier. Progressive disclosure means the executive tier is not a dumbed-down view — it is a curated view. The data behind it is the same data powering the operational table.

What goes in each tier

Executive: the 10-second view

The director walks into a meeting and pulls up the vehicle fleet page on their laptop. In 10 seconds, they need to know the fleet health. The executive tier shows:

• KPI cards — Total vehicles, active count, vehicles in maintenance, utilization percentage
• Trend chart — Active vehicles over the last 12 months (MUI LineChart or a simple recharts line)
• Breakdown — Pie or donut chart of vehicles by status (active, inactive, maintenance)
• Alert banner — If any metric crosses a threshold (e.g., utilization below 70%), a colored banner calls it out

No tables. No action buttons. No forms. If the director wants to drill down, they toggle to operational.

Operational: the working view

The fleet manager opens the page to do their job. The operational tier shows:

• MUI DataGrid — All vehicles with sortable columns, inline status toggle, row-level edit/delete
• Filter bar — Filter by status, make, year, assigned department
• Add button — Opens the create dialog
• Bulk actions — Select multiple rows, change status in batch
• Snackbar feedback — Every mutation confirms or explains the error

This is the view from Lesson 9. It is the same DataGrid, the same hooks, the same mutation handlers. DensityGate just puts a wrapper around it.

Technical: the diagnostic view

The platform admin suspects a data quality issue. The technical tier shows:

• Extended DataGrid — All columns including data_source, created_by, created_at, updated_by, updated_at
• Raw JSON panel — Click a row to see the full JSON representation
• Provenance stats — Breakdown of records by data_source value (how many manual, how many synced, how many sample)
• Sync status — If the module integrates with an external system, when was the last sync and what was the result
• System config — Module status, permissions, provenance map entry

The prompt

This prompt generates all three density tiers for the vehicle-fleet page:

Update the vehicle-fleet page component at
src/app/(protected)/vehicle-fleet/page.tsx to use DensityGate with
three view tiers.

The page already has a working MUI DataGrid with SWR data fetching from
useVehicleFleet(). Wrap the existing content in DensityGate and add
executive and technical tiers.

DENSITY GATE SETUP:
- Import DensityGate from '@/components/DensityGate'
- Import { useSession } from 'next-auth/react' to get current user role
- Map role to default density:
  viewer/manager → 'executive'
  operator → 'operational'
  admin/superadmin → 'technical'

EXECUTIVE TIER (DensityGate.Executive):
- 4 KPI cards in a responsive grid (2x2 on mobile, 4x1 on desktop):
  1. Total Vehicles (count of all records)
  2. Active (count where status='active', green accent)
  3. In Maintenance (count where status='maintenance', amber accent)
  4. Utilization Rate (active / total * 100, formatted as percentage)
- Status breakdown: MUI horizontal bar or simple div-based bar chart
  showing proportion of active/inactive/maintenance
- If utilization rate < 70%, show an amber alert banner:
  "Fleet utilization is below 70% — review inactive assignments"
- Use MUI Card, Typography, and Box components for layout
- All data derived from the same useVehicleFleet() hook data — no extra API calls

OPERATIONAL TIER (DensityGate.Operational):
- Move the existing DataGrid and mutation handlers here
- This is the current page content — no changes needed to the DataGrid itself
- Keep the Add button, edit/delete actions, status toggle, snackbar

TECHNICAL TIER (DensityGate.Technical):
- Extended DataGrid with additional columns:
  data_source, created_by, created_at, updated_by, updated_at
- Click a row to expand a panel showing the full JSON of that record
- Provenance summary: small table showing count of records by data_source value
  (e.g., manual: 45, sync: 12, sample: 0)
- Module info panel: hardcoded display of module name, status, and provenance
  map entry

IMPORTANT:
- All three tiers use the same data from useVehicleFleet() — one SWR call
- The density toggle should appear in the top-right of the page header
- Use MUI components for all UI elements
- Maintain all existing mutation handlers and snackbar feedback

Watch it work

Design principles for density tiers

Executive tier: answer the question before it is asked

Executives do not browse. They arrive with a question: “Are we on track?” “Is there a problem?” “What changed?” Design the executive tier to answer the top 3 questions for the module without any interaction. If the director has to click anything to get their answer, the executive tier is not done.

Operational tier: minimize clicks to action

Operators live in this view. Every extra click is friction they endure 50 times a day. Inline editing is better than dialog-based editing for single-field changes. Status toggles should be one click, not open-dialog-change-dropdown-save-close. The DataGrid should default-sort by the most actionable column (usually status or date).

Technical tier: hide nothing

The technical tier is the escape hatch. When something is wrong and nobody knows why, the technical view should expose every piece of metadata the system has. If a record’s updated_at timestamp does not match when the user says they edited it, the technical tier reveals that. If data_source is 'sync' but the operations team insists it was entered manually, the technical tier settles the question.

What to verify

After the AI generates the three-tier page, check these details:

What’s next

You have built a complete module: scaffolded, registered, API routes, database connection, SWR data flows, provenance, and density-gated views. In Lane 3, you will test all of it — Vitest for server logic, Playwright for end-to-end flows, and accessibility audits to make sure every density tier meets WCAG 2.1 AA.