Figma to Frontend UI Specification Agent

=== DEVELOPER HANDOFF REPORT ===

Project
NexaFlow Analytics Dashboard

Product Type
Responsive SaaS web application

Frontend Stack
Next.js, React, TypeScript, Tailwind CSS, semantic CSS variables, and custom components built on Radix primitives.

Accessibility Target
WCAG 2.2 AA implementation review

=== EXECUTIVE SUMMARY ===

The supplied interface uses a persistent application shell, modular dashboard cards, responsive data visualizations, filter controls, search interfaces, tabular data, detail panels, and account settings forms.

The design is sufficiently complete for a detailed implementation specification, but several interaction states, mobile table behaviors, chart accessibility requirements, and component-token inconsistencies require resolution before production implementation.

Primary implementation priorities

1. Confirm semantic design tokens.
2. Confirm container and breakpoint rules.
3. Consolidate repeated button, field, card, badge, and table patterns.
4. Define responsive navigation.
5. Define data-loading, empty, error, and permission states.
6. Confirm mobile table behavior.
7. Add keyboard and screen-reader requirements.
8. Implement page layouts after primitive components are approved.
9. Complete visual, functional, responsive, and accessibility QA.

=== SOURCE READINESS ASSESSMENT ===

Overall Readiness
Usable With Assumptions

Screen Coverage
High

Component Consistency
Moderate

Token Consistency
Moderate

Responsive Coverage
Moderate

State Coverage
Low

Interaction Clarity
Moderate

Accessibility Readiness
Low

Asset Completeness
Moderate

Engineering Readiness
Moderate

High-Risk Gaps

• Mobile table behavior is not fully shown.
• Loading and retry states are incomplete.
• Chart text alternatives are not defined.
• Sidebar collapse behavior requires confirmation.
• Several card padding values appear inconsistent.
• Focus-visible states are not documented.
• Permission-restricted states are missing.
• Long translated labels have not been tested.

=== EVIDENCE CLASSIFICATION ===

Observed

• Desktop layout uses a persistent left sidebar.
• The dashboard contains four metric cards.
• Analytics filters appear above chart content.
• Customer and transaction screens use data tables.
• Mobile screenshots use a compact top navigation.
• Cards share similar visual structure.

Inferred

• The sidebar collapses below the large breakpoint.
• Metric cards use one shared component.
• Filter controls move into a compact mobile control.
• Tables require horizontal scrolling or a mobile transformation.

Recommended

• Use horizontal scrolling for medium-width tables.
• Use card-based records for the narrowest customer view.
• Use semantic color tokens.
• Add reusable loading, empty, error, and permission-state components.
• Add text summaries for chart data.

Open Questions

• Should the mobile navigation open as a full-screen sheet or side drawer?
• Should the first table column remain sticky?
• Are dashboard cards required to have equal heights?
• Should filters persist in the URL?
• Are report exports synchronous or asynchronous?
• Which user roles can access each settings section?

=== DESIGN TOKEN SPECIFICATION ===

Color Token Model

Primitive
color.blue.600
color.blue.700
color.gray.50
color.gray.100
color.gray.300
color.gray.600
color.gray.900
color.red.600
color.green.600
color.amber.600

Semantic
color.background.page
color.background.surface
color.background.elevated
color.text.primary
color.text.secondary
color.text.disabled
color.border.default
color.border.strong
color.action.primary
color.action.primary-hover
color.action.secondary
color.status.success
color.status.warning
color.status.error
color.focus.ring

Component
button.primary.background.default
button.primary.background.hover
input.border.default
input.border.focus
card.background
badge.success.background
table.row.hover

Accessibility Rule
Status must never be communicated by color alone.

Typography

Display Large

• Font size: 32 px
• Line height: 40 px
• Weight: 700
• Usage: Main dashboard title

Heading Medium

• Font size: 24 px
• Line height: 32 px
• Weight: 700
• Usage: Major page sections

Heading Small

• Font size: 20 px
• Line height: 28 px
• Weight: 600
• Usage: Card and panel titles

Body

• Font size: 16 px
• Line height: 24 px
• Weight: 400

Body Small

• Font size: 14 px
• Line height: 20 px
• Weight: 400

Label

• Font size: 14 px
• Line height: 20 px
• Weight: 600

Caption

• Font size: 12 px
• Line height: 16 px
• Weight: 500

Data Value

• Font size: 28 px
• Line height: 36 px
• Weight: 700
• Use tabular numbers where available.

Spacing Scale

• space.0 = 0 px
• space.1 = 4 px
• space.2 = 8 px
• space.3 = 12 px
• space.4 = 16 px
• space.5 = 20 px
• space.6 = 24 px
• space.8 = 32 px
• space.10 = 40 px
• space.12 = 48 px
• space.16 = 64 px

Recommended Consolidation
Replace accidental 15 px, 17 px, 23 px, and 25 px values with the nearest approved spacing token after design review.

Radius

• radius.control = 8 px
• radius.card = 12 px
• radius.panel = 16 px
• radius.pill = 999 px

Border

• border.default = 1 px solid color.border.default
• border.strong = 1 px solid color.border.strong

Focus Ring

• 2 px solid color.focus.ring
• 2 px offset
• Must remain visible on light and dark surfaces

Elevation

• elevation.1 = subtle card elevation
• elevation.2 = floating panel
• elevation.3 = modal or drawer

=== PAGE LAYOUT SPECIFICATION ===

Application Shell

Large Screens

• Persistent sidebar width: 240 px
• Main content: fluid
• Maximum content width: 1440 px
• Horizontal page padding: 32 px
• Main vertical section gap: 32 px

Medium Screens

• Sidebar collapses to icon-only mode or drawer according to final product decision.
• Horizontal page padding: 24 px
• Main section gap: 24 px

Small Screens

• Sidebar is replaced by a modal navigation drawer.
• Horizontal page padding: 16 px
• Main section gap: 20 px
• Selected media and table regions may extend to the viewport edge when required.

Dashboard Grid

Extra Large

• Four metric cards per row
• 24 px gap

Large

• Four metric cards per row
• 24 px gap

Medium

• Two metric cards per row
• 20 px gap

Small

• One metric card per row
• 16 px gap

=== COMPONENT INVENTORY ===

Foundations

• Typography
• Color
• Spacing
• Radius
• Border
• Elevation
• Motion
• Breakpoints

Layout

• AppShell
• PageContainer
• ContentGrid
• Stack
• Inline
• SplitPane

Navigation

• SidebarNavigation
• MobileNavigationDrawer
• TopBar
• Breadcrumbs
• Tabs
• Pagination

Actions

• Button
• IconButton
• MenuButton
• LinkButton

Forms

• TextField
• SearchField
• Select
• Combobox
• Checkbox
• RadioGroup
• Switch
• DateRangePicker
• FormField
• ErrorSummary

Data Display

• MetricCard
• ChartCard
• StatusBadge
• Avatar
• DataTable
• CustomerCard
• TransactionRow
• KeyValueList

Feedback

• Alert
• Toast
• Skeleton
• Spinner
• EmptyState
• ErrorState
• PermissionState

Overlays

• Modal
• Drawer
• Popover
• Tooltip
• DropdownMenu
• ConfirmationDialog

=== COMPONENT SPECIFICATION ===

Component
MetricCard

Purpose
Display one high-priority metric, supporting context, and trend information.

Anatomy

• Container
• Label
• Main value
• Trend indicator
• Supporting comparison
• Optional icon
• Optional action
• Loading placeholder
• Error message

Required Elements

• Label
• Main value

Optional Elements

• Trend
• Comparison period
• Icon
• Action

Variants

• Default
• Positive Trend
• Negative Trend
• Neutral Trend

States

• Default
• Hover when interactive
• Focus-visible when interactive
• Loading
• Empty
• Error
• Permission Restricted

Sizing

• Minimum width: 240 px
• Minimum height should be determined by content and grid consistency.
• Do not force equal height unless approved by design.

Spacing

• Card padding: 24 px large
• Card padding: 20 px medium
• Card padding: 16 px small
• Label-to-value gap: 8 px
• Value-to-trend gap: 12 px

Content Rules

• Use locale-aware number formatting.
• Use tabular numbers where supported.
• Do not rely on color alone for trend direction.
• Support values up to at least 12 visible characters before wrapping or abbreviation.

Accessibility

• Trend icon is decorative when adjacent text explains direction.
• Interactive cards require an accessible name.
• Loading updates should not repeatedly interrupt screen readers.
• Error states require readable recovery guidance.

=== RESPONSIVE SPECIFICATION ===

Sidebar Navigation

Large
Persistent full-width sidebar.

Medium
Recommended icon-only rail with expandable labels, subject to product confirmation.

Small
Modal drawer triggered from the top bar.

Mobile Drawer Behavior

• Move focus into the drawer after opening.
• Trap focus while open.
• Close on Escape.
• Restore focus to the trigger.
• Prevent background keyboard interaction.
• Provide visible close control.
• Announce current navigation item.

Filters

Large
Inline filter controls.

Medium
Inline controls may wrap.

Small
Collapse secondary filters into a filter drawer.
Keep the primary date range visible when it is essential to interpreting the page.

Tables

Large
Full table with all approved columns.

Medium
Horizontal scroll with selected priority columns visible.

Small
Use a card transformation for customer records.
Use horizontal scrolling for transaction data when dense numeric comparison is essential.

=== STATE MATRIX ===

Button

Default
Primary action background with standard text and icon colors.

Hover
Increase emphasis without shifting layout.

Focus-Visible
Show approved focus ring.

Pressed
Use pressed background token.

Loading
Preserve button width.
Display progress indicator.
Prevent duplicate activation.
Keep an accessible loading label.

Disabled
Use disabled tokens.
Do not expose hover or pressed behavior.
Use only when an action is genuinely unavailable.

Danger
Use destructive semantic tokens.
Require confirmation for irreversible operations.

Text Field

Default
Hover
Focus
Filled
Disabled
Read-Only
Error
Success
Loading where asynchronous validation applies

Data Table

Loading
Populated
Empty
Filtered Empty
Error
Offline
Permission Restricted
Partial Data
Pagination Loading

=== FORM VALIDATION SPECIFICATION ===

Validation Timing

• Validate required fields on blur and submission.
• Validate formatting after sufficient input is present.
• Avoid aggressive errors before the user has interacted with a field.

Error Behavior

• Preserve entered values.
• Display inline error text.
• Associate the message programmatically with the input.
• Move focus to the first invalid field after submission.
• Show an error summary when multiple fields fail.
• Provide a clear recovery action.

Submit Behavior

• Prevent duplicate submissions.
• Preserve form state during recoverable failures.
• Announce processing and completion.
• Confirm success.
• Protect users from losing unsaved changes when relevant.

=== MOTION SPECIFICATION ===

Navigation Drawer

• Trigger: Menu button activation
• Property: Transform and overlay opacity
• Duration: approximately 220 ms
• Easing: standard deceleration curve
• Reduced Motion: appear without spatial transition or use a short opacity change

Modal

• Duration: approximately 180 ms
• Initial Focus: first meaningful control or heading
• Return Focus: original trigger
• Reduced Motion: remove scale transition

Accordion

• Animate height or grid track carefully
• Duration: approximately 180 ms
• Preserve focus
• Reduced Motion: immediate state change

Toast

• Enter without covering critical controls
• Pause dismissal during pointer or keyboard interaction
• Support persistent errors when action is required

=== ACCESSIBILITY REQUIREMENTS ===

• Use semantic landmarks.
• Maintain logical heading hierarchy.
• Provide skip navigation.
• Give every control an accessible name.
• Keep persistent field labels.
• Support full keyboard operation.
• Use visible focus indicators.
• Preserve logical focus order.
• Provide minimum practical touch targets.
• Maintain sufficient contrast.
• Do not rely on color alone.
• Associate errors with inputs.
• Provide error recovery instructions.
• Manage modal focus.
• Use semantic table markup.
• Provide text summaries for charts.
• Add alternative text to informative images.
• Hide decorative imagery from assistive technology.
• Respect reduced-motion settings.
• Support browser zoom and responsive reflow.
• Ensure loading and asynchronous updates are announced appropriately.
• Restore focus after route changes, deletion, and overlay closure.

=== DISCREPANCY AUDIT ===

Issue 1:
Metric card padding varies between approximately 20 px and 24 px.

Impact
Inconsistent visual rhythm and duplicate component variants.

Recommendation
Standardize on 24 px for large screens, 20 px for medium screens, and 16 px for small screens.

Priority
High

Decision Owner
Design System Lead

Issue 2:
Two primary button heights appear in equivalent contexts.

Impact
Implementation inconsistency and visual drift.

Recommendation
Define approved small, medium, and large control heights.

Priority
High

Decision Owner
Design and Frontend

Issue 3:
Mobile table behavior is not documented.

Impact
Potential clipping, inaccessible content, and inconsistent implementation.

Recommendation
Approve a per-table responsive strategy before implementation.

Priority
Critical

Decision Owner
Product, Design, and Frontend

Issue 4:
Focus-visible states are missing.

Impact
Keyboard accessibility failure.

Recommendation
Approve and implement a semantic focus-ring token.

Priority
Critical

Decision Owner
Design System and Accessibility

=== IMPLEMENTATION SEQUENCE ===

1. Confirm semantic colors, typography, spacing, radii, and elevation.
2. Confirm breakpoints and container rules.
3. Build Button, IconButton, TextField, Select, Checkbox, Badge, Card, and Alert.
4. Build application shell and navigation.
5. Build MetricCard, ChartCard, DataTable, EmptyState, ErrorState, and PermissionState.
6. Implement dashboard layout.
7. Implement responsive behavior.
8. Implement forms and validation.
9. Implement overlays and focus management.
10. Implement motion and reduced-motion behavior.
11. Complete accessibility review.
12. Complete visual regression review.
13. Resolve discrepancy log.
14. Document approved deviations from the source design.

=== ACCEPTANCE CRITERIA ===

Navigation Drawer

Given the viewport is below 640 px,
when the user activates the menu button,
then the navigation opens as a modal drawer, focus moves into it, background content becomes unavailable to keyboard interaction, Escape closes the drawer, and focus returns to the menu button.

Metric Card Grid

Given the viewport is at least 1024 px,
when the dashboard loads,
then four metric cards appear in one row with a 24 px gap.

Given the viewport is below 640 px,
when the dashboard loads,
then metric cards appear in one column with a 16 px gap and no horizontal page overflow.

Form Validation

Given multiple required fields are invalid,
when the user submits the form,
then all invalid values remain visible, inline errors appear, an error summary is announced, and focus moves to the first invalid field.

Table Error State

Given transaction data fails to load,
when the request completes with an error,
then the table region displays an error message, preserves the page heading and filters, and provides a retry action.

Reduced Motion

Given the user prefers reduced motion,
when a drawer, modal, accordion, or route transition occurs,
then nonessential spatial animation is removed or substantially reduced without hiding state changes.

=== QA CHECKLIST ===

Visual QA

• Verify container widths.
• Verify page padding.
• Verify grid columns and gaps.
• Verify typography and line height.
• Verify semantic colors.
• Verify radii and shadows.
• Verify icon sizes.
• Verify chart and image dimensions.
• Verify responsive transitions.
• Verify loading, empty, error, and permission states.
• Verify focus-visible styling.
• Verify reduced-motion behavior.

Functional QA

• Verify route navigation.
• Verify filter behavior.
• Verify URL persistence where approved.
• Verify form submission.
• Verify validation.
• Verify keyboard access.
• Verify screen-reader labels.
• Verify focus restoration.
• Verify table sorting and filtering.
• Verify pagination.
• Verify export behavior.
• Verify retry behavior.
• Verify permission restrictions.
• Verify long content.
• Verify translated text expansion.
• Verify supported browsers and devices.

=== HANDOFF RISK ASSESSMENT ===

Responsive Table Ambiguity
Critical

Focus State Coverage
Critical

Chart Accessibility
High

Design Token Inconsistency
High

Mobile Navigation Decision
High

Asset Completeness
Moderate

Localization Expansion
Moderate

Implementation Complexity
Moderate

QA Complexity
High

=== KNOWN LIMITATIONS ===

• Exact measurements require confirmation against the original Figma file.
• Prototype behavior cannot be verified without prototype access.
• Hidden component properties and variables may not be visible in exports.
• Final component architecture may require adjustment to engineering conventions.
• Accessibility compliance requires implementation testing.
• Browser behavior requires real-device and browser testing.
• This specification does not guarantee pixel-perfect code or production readiness without review.

=== FINAL DEVELOPER NOTE ===

Treat this document as the implementation contract only after design, product, frontend, accessibility, and QA owners resolve the listed open questions and approve the documented assumptions.