frontend-definition-of-done.md

Frontend Definition of Done

Curated by Joe Maffei

This document outlines key considerations for determining when a feature can be considered "done." It's crucial to address these points as early as possible in the development process and continue to revisit them at each stage. By doing so, we can ensure higher quality, reduce rework, and streamline our development pipeline. Consider these points at the following stages:

1. When drafting requirements documents
2. During the design and wireframing phase
3. While writing user stories or bug tickets
4. Throughout the development process
5. Before opening a merge request
6. During code reviews
7. In the end-to-end testing stage

By integrating these considerations early and often, we can catch potential issues sooner, improve overall quality, and reduce the time and effort needed for revisions later in the development cycle.

The following sections detail specific areas to consider. Use these as a checklist to ensure all aspects of quality and functionality are addressed before declaring a feature complete.

User Experience

User Interface

Text Quality

• Has all text content been checked for typos, correct capitalization, and proper punctuation?
  • Is the developer using a spell-checking tool like cSpell integrated into their development environment?

Content Consistency

• Is terminology used consistently throughout the user interface?
• Are abbreviations and acronyms used consistently and explained where necessary?

Text Formatting

• Are dates and currency formatted consistently throughout the user interface?
• Are numbers formatted appropriately for the values they represent?

Typography

• Is the font choice appropriate for readability across different devices and screen sizes?
• Is text sizing consistent and appropriate throughout the application?

Layout and Responsiveness

• Does the layout adapt appropriately to different screen sizes and orientations?
• Are there any issues with element alignment or spacing across different viewports?

Branding

• Does the UI correctly and consistently represent the brand identity?
• Are logos, brand colors, and other brand elements used appropriately?

User Input

Input Sanitization

• Has whitespace trimming been implemented for all relevant input fields?
• Any concerns about cross-site scripting?
• Are special characters properly handles, escaped or encoded?

Field Length Constraints

• Are field length restrictions enforced for all appropriate inputs?
• Does the maximum length need to be communicated to the user?
• If applicable, is input truncation implemented before form submission?

Data Type Validation

• Are all input fields properly validated for their respective data types (strings, numeric, dates)?
• Is there appropriate error handling for incorrect data type inputs?
• For date fields, is a date picker implemented to minimize input errors?

General Input Considerations

• Are all required fields clearly marked?
• Is input validation thorough enough to catch potential issues before they become errors?
• Is there clear visual feedback when input validation fails?
• Are error messages specific and helpful to the user?

Application/Component States

Worth reading: The Nine States of Design

Loading States

• Are loading states implemented for incoming data?
  • For critical data, does the loading state block the entire UI?
  • For page-level data, does the loading state only block the main content while allowing navigation?
  • For component-level data, is the loading state confined to the specific component?
• Are loading states implemented for data being sent?
  • Do these states prevent multiple submissions of the same data?

Empty States

• Are empty states properly implemented for all relevant components?
• Is there a mechanism to ensure empty states don't display while data is still loading?

Error States

• Are critical ("everything is broken") error states implemented and user-friendly?
• For recoverable errors, are "try again" options provided to the user?
• Are "expected" errors (e.g., required field validation, no search results) handled gracefully?
• Do error messages provide clear guidance on how to resolve the issue?

Additional Considerations

• Are transition animations implemented between different states for a smoother user experience?
• Is there a consistent design language for different states across the application?
• For long-running processes, is there a progress indicator to keep users informed?
• Are timeout scenarios handled appropriately with user-friendly messages?
• Is there a mechanism to recover application state in case of unexpected page reloads?

Accessibility

Interaction

• Are all buttons, links, and other interactive elements clearly identifiable?
• Is there consistent and appropriate feedback for user interactions (e.g., hover states, click animations)?
• Do all input fields have associated labels?
  • Are labels used instead of relying solely on placeholders?
  • If placeholders are used, are they supplementary to labels rather than replacements?

The Problem with Placeholders

“(…) placeholders confuse many users. In particular, people with cognitive disabilities tend to have issues understanding placeholder text because they think it is pre-populated text and will try to submit the form without entering their specific information.

It is important to note that not all screen readers will announce the placeholder attribute.”

Source: https://www.deque.com/blog/accessible-forms-the-problem-with-placeholders

Tables

• Do all tables in the application have proper headers?
• If visually hidden headers would improve accessibility, have they been implemented?
• Could the content be better presented using a different HTML structure for improved accessibility?

Mouse Navigation

• Do all interactive elements have a visible hover state?
• Are titles or tooltips provided for icons and buttons without text labels?
• Is there a mechanism to prevent or mitigate unintended actions from double clicks or rage clicks?

Keyboard Navigation

• Can all interactive elements be accessed and operated using keyboard-only navigation?
• Is there a logical and intuitive tab order throughout the application?
• Is a visible focus state implemented for all interactive elements?
• For modals, dialogs, panels, et al.:
  • Can they be closed using the Escape key or a clearly visible close button?
  • Is focus trapped within the modal when it's open to prevent users from accidentally interacting with background content?

Screen Reader Support

• Are all non-text elements (images, icons) properly labeled with alternative text?
• If only decorative, do elements have a role="presentation" (or alt="" for <img> elements)?
• Are any fields disabled? If so, is it possible to change the implementation using a more accessible alternative ? (e.g., explaining why a field is unavailable, or displaying a message on click explaining why the action can’t be completed)
• Are ARIA attributes used appropriately to convey structure and relationships?
• Are dynamic content changes announced to screen readers? (e.g., modals, popups, toasts)

Color and Contrast

• Has the color contrast been checked to ensure it meets WCAG guidelines?
  • https://dequeuniversity.com/rules/axe/4.7/color-contrast
• Is color alone never used as the sole means of conveying information?

Additional Considerations

• Are there skip links to bypass repetitive content?
• Is the page structure semantically correct using appropriate HTML5 elements?
• Are form inputs properly labeled and associated with their descriptions?
• Is there a mechanism to resize text without breaking the layout?
• Does changing the default font size in the browser, OS or mobile device cause a font size change in the application?

Code Quality

Error Handling

Error Scope and Handling

• Are errors categorized based on their severity and impact on the application?
• For each type of error:
  • Is there a clear strategy for how it should be handled?
  • Is there a defined process for logging or reporting the error?

Exception Management

• Are try/catch blocks implemented appropriately throughout the codebase?
  • Is the scope of each try block kept as small as possible to pinpoint errors accurately?
  • Has each catch block been evaluated for potential user experience impacts?

User-Facing Error Handling

• Are user-friendly error messages implemented for different types of errors?
• Do error messages provide clear guidance on what went wrong and possible next steps?
• For recoverable errors, are users given options to retry or take alternative actions?
• Is there a consistent approach to error handling across different components and modules?
• Are error messages and their presentation standardized throughout the application?

Observability

Logging

• Was logging implemented where appropriate?
• Is the right tool being used for logging? (e.g., Google Analytics, OpenTelemetry)

Analytics

• Is there a business need for analytics in the current body of work?
• Is the right tool being used for analytics? (e.g., Google Analytics)

Error Tracking

• Are errors and exceptions being automatically tracked using a tool like Sentry?
• Are there any places that require intentional, programmatic error tracking? (e.g., a caught exception that should be tracked for better visibility)

Automated Testing

Unit Tests

• Are unit tests implemented for all critical functions and utilities?
• Do unit tests cover both positive and negative scenarios?
• Are edge cases being tested?
• Are mocks and stubs used appropriately to isolate units of code?

Component Tests

• Are component tests implemented for all key UI components?
• Do these tests verify both the rendering and behavior of components?
• Is there testing for different prop combinations and user interactions?

End-to-End (E2E) Tests

• Are E2E tests implemented to simulate real user scenarios?
• Is there coverage for integration points with backend services?
• Are error scenarios and edge cases included in E2E testing?

Continuous Maintenance

Dependency Management

• Are there any errors or warnings when running npm install?
  • If so, have they been reviewed and addressed?

Security

• Does npm audit report any vulnerabilities in the project dependencies?
  • If vulnerabilities are found, is there a plan to address them promptly?

Developer Experience

• Are there any linting errors in the codebase?
• Are variables, functions, classes and files free of typos and named according to the team's standards?

Type Safety

• Are there any type errors reported by the TypeScript compiler (or similar type checker)?
  • Is there a plan to address any any types or other type-related technical debt?

Bundle Size

• Were there any dependencies installed?
  • If so, what was the impact on bundle size?
• Is there any dead code that can be deleted as part of the current work?

Documentation

• Does any documentation need to be updated as a result of the current changes?