Web UI Design-to-Code Prompt Architect

=== PHASED DESIGN-TO-CODE IMPLEMENTATION PROMPT ===

ROLE

Act as a senior frontend engineer and design engineer specializing in Next.js App Router, React, TypeScript, Tailwind CSS, shadcn/ui, responsive SaaS dashboards, accessible component systems, and maintainable frontend architecture.

OBJECTIVE

Implement the OrbitFlow analytics dashboard using the supplied desktop screenshot, mobile wireframe, and existing Next.js repository.

Preserve the screenshot's structural hierarchy and the wireframe's mobile information architecture while reusing the project's current dashboard shell, tokens, components, utilities, and data services.

Do not treat the screenshot as proof of hidden interactions, exact dimensions, exact fonts, backend behavior, or complete responsive behavior.

PRODUCT CONTEXT

Primary users
Operations managers and customer-success leaders

Primary user task
Review critical metrics, identify unusual changes, inspect recent activity, and export a report.

Primary business goal
Make important account changes easy to recognize and support repeat dashboard use.

Primary page hierarchy

1. Dashboard identity and date context
2. Critical metrics
3. Revenue trend
4. Account-health issues
5. Recent activity
6. Export and secondary actions

SOURCE INTERPRETATION

Observed from the desktop screenshot

• Existing left sidebar
• Dashboard header
• Date-range control
• Four metric cards
• Large revenue chart
• Smaller account-health panel
• Recent activity table
• Report export action
• Neutral surfaces with one primary accent
• Compact B2B SaaS visual density

Observed from the mobile wireframe

• Top mobile navigation
• Two-column metric grid when width permits
• Stacked analytical panels
• Recent activity represented as compact records
• Date-range control near the page title
• Export action inside an overflow menu

Inferred

• Metric cards should be reusable.
• Dashboard panels should share a common surface component.
• Activity data requires sorting and status filtering.
• Export is asynchronous.

Requires verification

• Exact metric formulas
• Exact chart library
• Existing export service
• Existing date-range API behavior
• Exact permission model
• Exact mobile breakpoint values

TECHNOLOGY STACK

Framework
Next.js App Router

Language
TypeScript with strict mode

Styling
Existing Tailwind CSS configuration

Components
Installed shadcn/ui components and current project primitives

Icons
Existing Lucide installation

Data
Existing typed dashboard service when available

Do not install additional dependencies unless the project cannot satisfy a required behavior and the user explicitly approves the dependency.

PROJECT CONSTRAINTS

• Reuse the current dashboard shell and sidebar.
• Preserve existing routes.
• Preserve existing analytics identifiers.
• Preserve current table utilities.
• Do not rewrite unrelated features.
• Do not change the package manager.
• Do not introduce a new global state library.
• Do not convert the entire route into a client component.
• Use client components only where interaction requires them.
• Do not create new backend endpoints.
• Do not hardcode private data.
• Do not remove working tests.
• Do not modify unrelated files.
• Use existing project tokens before adding new values.
• Avoid excessive Tailwind arbitrary values.
• Avoid inline styles unless required by a verified chart API.
• Avoid page-level horizontal scrolling.

PHASE 1 — REPOSITORY INSPECTION

Before implementing

1. Inspect app/dashboard/page.tsx.
2. Identify the current dashboard shell and sidebar.
3. Inspect components/ui.
4. Inspect features/dashboard.
5. Identify existing metric-card, panel, table, date-range, chart, status, loading, empty-state, and error-state components.
6. Identify existing dashboard data services and types.
7. Identify available verification scripts from package.json.
8. Identify existing test conventions.
9. Identify existing responsive and accessibility conventions.
10. Report any conflict between this prompt and the current codebase.

Do not begin a broad rewrite before completing this inspection.

PHASE 2 — FILE PLAN

Expected route
app/dashboard/page.tsx

Potential feature files
features/dashboard/components/dashboard-header.tsx
features/dashboard/components/date-range-control.tsx
features/dashboard/components/metric-grid.tsx
features/dashboard/components/metric-card.tsx
features/dashboard/components/revenue-trend-panel.tsx
features/dashboard/components/account-health-panel.tsx
features/dashboard/components/recent-activity-table.tsx
features/dashboard/components/recent-activity-mobile-list.tsx
features/dashboard/components/dashboard-empty-state.tsx
features/dashboard/components/dashboard-error-state.tsx
features/dashboard/components/mobile-dashboard-navigation.tsx
features/dashboard/types.ts
features/dashboard/mock-data.ts

Create only the files that are necessary and consistent with the repository.

Reuse

• Existing dashboard shell
• Existing sidebar
• Existing UI primitives
• Existing table utilities
• Existing status badges
• Existing loading skeletons
• Existing error components
• Existing data service
• Existing chart library, if present

Do not modify

• Unrelated routes
• Authentication flows
• Global application architecture
• Backend services
• Package manager configuration
• Unrelated design-system primitives

PHASE 3 — PAGE STRUCTURE

Dashboard Page

1. Existing dashboard shell
2. Dashboard header
3. Date-range and export actions
4. Metric grid
5. Primary analytics region
   • Revenue trend
   • Account health
6. Recent activity
7. Loading, empty, error, and permission states

COMPONENT ARCHITECTURE

DashboardPage
├── ExistingDashboardShell
├── DashboardHeader
│ ├── PageTitle
│ ├── DateRangeControl
│ └── DashboardActions
├── MetricGrid
│ └── MetricCard
├── DashboardAnalyticsGrid
│ ├── RevenueTrendPanel
│ └── AccountHealthPanel
├── RecentActivitySection
│ ├── ActivityToolbar
│ ├── RecentActivityTable
│ └── RecentActivityMobileList
├── DashboardEmptyState
├── DashboardErrorState
└── MobileDashboardNavigation

COMPONENT RESPONSIBILITIES

DashboardHeader

• Display page title and contextual supporting text.
• Contain date-range and export actions.
• Transform actions into an accessible mobile arrangement.
• Preserve semantic heading order.

MetricCard

• Accept typed label, value, trend, trend direction, supporting context, loading state, and optional action.
• Use one shared structure for all metrics.
• Communicate trend direction using text or icons in addition to color.
• Support long translated values and labels.

RevenueTrendPanel

• Display the existing revenue visualization.
• Include a textual summary for accessibility.
• Preserve loading, empty, and error states.
• Avoid continuous animation.
• Respect reduced motion.

AccountHealthPanel

• Prioritize actionable issues over decorative metrics.
• Show severity, label, count, and verified action.
• Support an empty state when no issues exist.

RecentActivityTable

• Reuse existing table utilities.
• Support sorting.
• Support status filtering.
• Use semantic headers.
• Include accessible row actions.
• Provide populated, loading, filtered-empty, error, and permission states.

RecentActivityMobileList

• Display essential record information without page-level horizontal scrolling.
• Preserve the same data and actions as the desktop table.
• Do not make swipe the only interaction method.

VISUAL SYSTEM

Use existing project tokens.

Visual direction

• Premium B2B SaaS
• Calm neutral surfaces
• One primary accent
• Strong information hierarchy
• Limited shadow usage
• Compact but readable data presentation
• Clear priority for account-health issues

Typography roles

• Page title
• Section title
• Metric value
• Metric label
• Supporting text
• Table label
• Metadata
• Button label

Spacing

• Use the existing spacing scale.
• Keep related labels and values close.
• Use larger separation between major dashboard regions.
• Keep mobile gutters consistent.
• Avoid overpadding metric cards.

Cards and panels

• Reuse the existing surface component.
• Use one consistent border and radius treatment.
• Do not give every panel the same visual emphasis.
• Make the main trend panel stronger than secondary informational panels.
• Make critical account-health states visually clear without relying on color alone.

RESPONSIVE MATRIX

Wide Desktop

• Persistent sidebar
• Four metric cards in one row where supported
• Revenue panel wider than account-health panel
• Full activity table

Desktop

• Persistent sidebar
• Four-column or two-column metric grid based on available content width
• Two-column analytics region
• Full activity table

Tablet

• Collapsible sidebar or existing tablet navigation
• Two-column metric grid
• Single-column analytical panels when required
• Activity table may retain priority columns

Mobile

• Accessible top navigation
• One or two metric columns depending on available width
• Full-width date control
• Export action inside an accessible menu where needed
• Stacked analytical panels
• Card-based recent activity
• No page-level horizontal scrolling

Small Mobile

• Single-column metric cards
• Wrapped labels
• Full-width primary controls
• No clipped values
• No overlapping actions

Short Viewport

• Sticky controls must not cover content or focus.
• Mobile navigation must remain operable with browser chrome and the virtual keyboard.

200% Zoom:

• Content must reflow.
• Controls must remain reachable.
• Tables must provide an accessible alternative.
• Text must not overlap or become clipped.

INTERACTION STATES

Date Range

• default
• focus-visible
• open
• selected
• updating
• error
• disabled

Export

• idle
• pending
• completed
• failed
• permission restricted

Dashboard Data

• loading
• loaded
• empty
• partial
• error
• stale where supported

Activity

• loading
• populated
• no activity
• filtered empty
• sorting
• filtering
• table error
• permission restricted

ACCESSIBILITY REQUIREMENTS

• Use semantic landmarks.
• Preserve one clear H1.
• Maintain logical heading order.
• Provide accessible names for every icon-only control.
• Preserve visible focus.
• Support keyboard operation for date controls, menus, sorting, filters, and row actions.
• Associate control labels and descriptions.
• Use proper table headers.
• Communicate sorting state programmatically.
• Communicate trend direction beyond color.
• Provide a textual chart summary.
• Manage focus when the mobile navigation or action menu opens.
• Return focus to the trigger when overlays close.
• Support reduced motion.
• Ensure error states are visible and announced appropriately.
• Support zoom and responsive reflow.
• Keep touch targets usable.
• Do not claim accessibility conformance without testing.

DATA BOUNDARIES

Use the existing typed dashboard service when available.

Do not create new endpoints.

When a required service is missing

• use typed mock data
• isolate mock data from presentation components
• document the replacement boundary
• do not present mocked values as live production data

Required models may include

• DashboardMetric
• MetricTrend
• RevenueDataPoint
• AccountHealthIssue
• ActivityRecord
• ActivityStatus
• DateRange
• ExportState

PERFORMANCE REQUIREMENTS

• Preserve server rendering where practical.
• Keep interactive controls in focused client components.
• Avoid making the entire page a client component.
• Reuse the installed chart library.
• Do not add a new charting dependency.
• Reserve chart dimensions to reduce layout shift.
• Lazy-load secondary analytical content only when it improves performance without harming usability.
• Avoid continuous animation.
• Respect reduced motion.
• Prevent unnecessary rerenders.
• Avoid duplicated data transformation.
• Keep component boundaries focused.

IMPLEMENTATION SEQUENCE

1. Inspect repository conventions.
2. Confirm the route and reusable components.
3. Confirm existing data services and types.
4. Create or refine the dashboard data model.
5. Implement the structural page layout.
6. Build or reuse metric cards and panels.
7. Implement desktop activity table.
8. Implement mobile activity presentation.
9. Add loading, empty, error, partial, and permission states.
10. Add responsive behavior.
11. Add accessibility behavior.
12. Add or update tests where supported.
13. Run available verification.
14. Summarize implementation and remaining assumptions.

ACCEPTANCE CRITERIA

Dashboard Structure

Given the dashboard loads on desktop,
when the page is displayed,
then the page title, date context, critical metrics, revenue trend, account health, and recent activity appear in a clear priority order.

Component Reuse

Given shared dashboard components already exist,
when implementation begins,
then the solution reuses or extends those components rather than duplicating equivalent structures.

Mobile Layout

Given the page is displayed at 390 pixels wide,
when the dashboard is loaded,
then all primary metrics, actions, analytical panels, and activity records remain accessible without page-level horizontal scrolling.

Date Update

Given the user changes the date range,
when new data is loading,
then the control and affected dashboard regions communicate the updating state without removing the current context prematurely.

Export

Given the user starts an export,
when processing begins,
then the export action communicates the pending state, prevents unsafe duplicate submission, and reports completion or failure.

Activity Empty State

Given no records match the active status filter,
when filtering completes,
then the interface displays a filtered-empty state with a clear method to remove or change the filter.

Keyboard Navigation

Given a keyboard user opens the mobile navigation,
when the menu appears,
then focus enters the menu, remains managed while open, and returns to the trigger when closed.

Zoom

Given the page is viewed at 200% zoom,
when content reflows,
then text, controls, metrics, panels, and activity records remain readable and operable without overlap.

VERIFICATION

Run only scripts supported by the project.

Verify where available

• TypeScript checking
• Linting
• Production build
• Relevant component tests
• Relevant end-to-end tests
• Responsive inspection
• Keyboard navigation
• Visible focus
• Mobile menu focus behavior
• Loading states
• Empty states
• Error states
• Export states
• 320-pixel mobile
• 390-pixel mobile
• Tablet
• Desktop
• 200% zoom
• Reduced motion

REQUIRED FINAL RESPONSE

Return

1. Implementation summary
2. Files created
3. Files modified
4. Existing components reused
5. Component architecture decisions
6. Responsive behavior implemented
7. Accessibility behavior implemented
8. Data assumptions
9. Verification completed
10. Verification not completed
11. Remaining risks
12. Open questions

PROHIBITED BEHAVIOR

• Do not rewrite the dashboard shell.
• Do not modify unrelated routes.
• Do not install unnecessary dependencies.
• Do not create new backend endpoints.
• Do not invent analytics values.
• Do not remove working tests.
• Do not replace existing table utilities.
• Do not convert the complete route into a client component.
• Do not use one monolithic dashboard component.
• Do not use inaccessible icon-only controls.
• Do not rely on color alone.
• Do not introduce page-level horizontal scrolling.
• Do not hardcode secrets.
• Do not expose private data.
• Do not claim verification that was not completed.

UNCERTAINTY HANDLING

When a detail is missing

• inspect the existing project first
• choose the smallest implementation consistent with project conventions
• label the assumption
• avoid inventing backend behavior
• preserve a replaceable data boundary
• document the remaining verification requirement

FINAL INTEGRITY NOTE

All backend behavior, authentication, authorization, data persistence, analytics, privacy, security, payment, and production assumptions must be verified before implementation.

Generated code must be reviewed, tested, and adapted to the actual project architecture before production use.

The prompt architecture is designed to improve code-generation consistency, visual fidelity, maintainability, accessibility readiness, and implementation clarity. It does not guarantee defect-free, secure, compliant, production-ready, or pixel-identical output.