Frontend Guidelines

This directory contains the development guidelines for the PermaplanT frontend.

For an overview of the frontend entry points and application startup, see Contributing to Frontend.

Reading Order

Read the guidelines in the following order. The specialized guidelines near the end only need to be read when working on the corresponding area.

General Guidelines General conventions, navigation, accessibility, validation, naming, and frontend documentation.
Architecture Feature-based organization, shared components, hooks, utilities, types, and the map component hierarchy.
React Components, state management, hooks, effects, component purity, and memoization.
Common Utilities Finding, creating, locating, documenting, and testing reusable utilities.
API Calls TanStack Query, query keys, mutations, error handling, and scalable API organization.
Zustand Store selectors, derived state, subscriptions, and performance considerations.
Store Actions Organization and naming of actions in the map store.
UI and Usability Text, colors, forms, icons, buttons, tooltips, wording, errors, z-index, and touchscreen behavior.
General Responsiveness General responsive layouts, breakpoints, and usability requirements.
Component Responsiveness Responsive behavior for the map toolbar, navbar, and timeline.
CSS CSS units, Tailwind CSS, custom properties, CSS Modules, responsive styling, dark mode, and third-party styles.
Keybindings Keyboard configuration, focused elements, global shortcuts, and Konva key handling.
Locators Accessible and resilient locators for frontend and end-to-end tests.
Error Handling Handling user-actionable, developer-caused, and cleanup-related image errors.
Default Map View Map view rectangles, stored view state, resizing, and default-view behavior.
Stored Map Information Persisted map-specific frontend state and migrations.
Creating a New Layer End-to-end instructions for adding a new map layer.