Figma to Frontend UI Specification Agent

Project name: NexaFlow Analytics Dashboard Product type: Responsive SaaS web application Source material: Desktop Figma frame descriptions Tablet screenshots Mobile screenshots Existing component inventory Partial design token document Target platforms: Desktop web Tablet web Mobile web Frontend stack: Next.js React TypeScript Styling approach: Tailwind CSS with semantic CSS variables Component framework: Custom components built on Radix primitives Browser support: Current and previous major versions of Chrome, Safari, Firefox, and Edge Breakpoints: Small: below 640 px Medium: 640–1023 px Large: 1024–1439 px Extra Large: 1440 px and above Design system exists: Partial Accessibility target: WCAG 2.2 AA implementation review Localization: English at launch Future multilingual support Allow approximately 30% text expansion No RTL requirement in the first release Input screens: Dashboard Overview Analytics Detail Customers Customer Detail Transactions Reports Settings Authentication Empty States Error States Critical user flows: Log in Review dashboard metrics Filter analytics by date Open customer details Search transactions Export reports Update account settings Need output: Complete developer handoff report Design token specification Responsive behavior matrix Component inventory State matrix Accessibility requirements Implementation sequence Acceptance criteria Discrepancy audit QA checklist Special constraints: Clearly separate observed facts from assumptions. Do not invent exact measurements when the source does not support them. Prioritize reusable components. Preserve mobile information hierarchy. Include reduced-motion behavior. Include loading, empty, error, disabled, and permission-restricted states.

=== 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.