# UI & UX Guidelines

* Design for clarity first.
* Prefer simple, modern and predictable interfaces.
* Optimize for fast understanding and low cognitive load.
* Every screen should have a clear primary purpose.
* Every important action should be easy to discover.
* Prefer familiar interaction patterns over novel ones.
* Do not require users to learn unnecessary custom behavior.
* Keep layouts visually calm and structured.
* Use consistent spacing, typography, colors and interaction patterns.
* Avoid visual noise.
* Avoid decorative elements that do not improve usability.
* Avoid unnecessary complexity in navigation and workflows.
* Minimize the number of steps required to complete common tasks.
* Keep related information and actions close together.
* Group content logically.
* Use clear visual hierarchy.
* Make primary actions visually distinct from secondary actions.
* Avoid giving multiple actions equal visual priority when one is clearly more important.
* Use whitespace intentionally.
* Prefer readable line lengths and sufficient spacing.
* Avoid dense walls of content.
* Avoid oversized empty areas that reduce information efficiency.
* Keep important information visible without unnecessary scrolling where practical.

## Navigation

* Navigation must be predictable and consistent.
* Users should always understand where they are.
* Users should always understand how to go back.
* Avoid hidden navigation when visible navigation is practical.
* Keep navigation depth shallow where possible.
* Use clear and descriptive navigation labels.
* Do not use ambiguous icons without labels when meaning is not obvious.
* Preserve navigation state when users return to a previous view where practical.
* Avoid resetting filters, search state or scroll position unnecessarily.
* Avoid unexpected redirects.
* Do not change navigation behavior between similar screens without a clear reason.

## Actions

* Use clear action labels.
* Prefer verbs that describe the actual outcome.
* Avoid vague labels such as `OK`, `Submit`, `Proceed` or `Execute` when a more specific label is possible.
* Make destructive actions clearly distinguishable.
* Keep dangerous actions away from common actions.
* Require confirmation for destructive or difficult-to-reverse actions.
* Do not require unnecessary confirmation for safe, reversible actions.
* Disable unavailable actions when the reason is obvious.
* Explain why an action is unavailable when it is not obvious.
* Avoid actions that appear clickable but are not.
* Provide immediate visual feedback after user actions.
* Prevent accidental duplicate submissions.
* Make loading, success and failure states visible.

## Forms

* Keep forms as short as practical.
* Ask only for information that is actually required.
* Group related fields together.
* Use clear field labels.
* Do not rely on placeholders as the only label.
* Use appropriate input controls for the expected value.
* Provide useful defaults where safe and predictable.
* Preserve user input when validation or network errors occur.
* Validate fields at useful moments without interrupting normal input.
* Show validation errors close to the affected field.
* Explain how to fix invalid input.
* Avoid technical validation messages.
* Clearly mark optional fields where useful.
* Avoid asking the same information multiple times.
* Use autocomplete and autofill where appropriate.
* Make keyboard navigation logical.
* Use sensible tab order.
* Support Enter and Escape behavior where users expect it.

## Content and Language

* Use plain, concise language.
* Prefer user terminology over internal technical terminology.
* Avoid jargon unless the target users are expected to understand it.
* Use consistent naming for the same concepts.
* Do not rename concepts between screens.
* Keep button labels, headings and descriptions concise.
* Put the most important information first.
* Avoid unnecessary explanatory text.
* Add explanation only where users may reasonably be confused.
* Error messages should explain what happened and what the user can do next.
* Avoid blaming the user.
* Avoid exposing stack traces, exception names or internal implementation details.

## Feedback and System State

* Always communicate important system state.
* Show loading states for operations that are not immediate.
* Avoid indefinite loading indicators without context.
* Use progress indicators for longer operations where progress can be measured.
* Clearly distinguish loading, empty, error and success states.
* Do not leave blank screens where an empty state is expected.
* Empty states should explain what the user can do next.
* Show success feedback when the result is not otherwise obvious.
* Keep transient notifications concise.
* Do not hide important errors in temporary notifications.
* Preserve actionable errors until the user has had a chance to understand them.
* Do not silently fail.
* Do not silently discard user input.

## Responsiveness

* The interface should feel responsive at all times.
* Provide immediate feedback after interaction.
* Avoid blocking the entire interface when only one section is loading.
* Prefer localized loading states.
* Use optimistic UI only when failures can be handled safely.
* Avoid layout jumps during loading.
* Reserve space for content where practical.
* Keep animations short and functional.
* Do not use animations that delay task completion.
* Respect reduced-motion preferences.
* Avoid unnecessary transitions and visual effects.

## Visual Design

* Prefer modern, clean and restrained visual design.
* Use a consistent design system.
* Keep typography hierarchy clear.
* Maintain sufficient contrast.
* Use color intentionally.
* Do not rely on color alone to communicate state.
* Keep the number of accent colors limited.
* Avoid excessive gradients, shadows and decorative effects.
* Use rounded corners, borders and elevation consistently.
* Keep icons stylistically consistent.
* Use familiar icons for familiar actions.
* Pair unclear icons with text labels.
* Avoid tiny click targets.
* Keep interactive targets large enough for comfortable use.
* Maintain consistent alignment.
* Avoid arbitrary spacing values.
* Prefer reusable spacing and sizing tokens.

## Accessibility

* Accessibility is part of the default design, not an optional enhancement.
* Use semantic controls and elements.
* Ensure full keyboard usability.
* Maintain visible focus indicators.
* Use sufficient color contrast.
* Do not rely solely on hover interactions.
* Do not rely solely on color to indicate status.
* Provide accessible names for controls.
* Keep focus order logical.
* Move focus intentionally after dialogs, navigation or major state changes.
* Support screen readers where applicable.
* Use ARIA only when native semantics are insufficient.
* Respect reduced-motion and system accessibility preferences.
* Avoid flashing or distracting content.

## Responsive Design

* Design for the available viewport instead of fixed screen sizes.
* Prioritize important content on smaller screens.
* Avoid horizontal scrolling unless the content genuinely requires it.
* Keep controls usable on touch devices.
* Do not simply shrink desktop layouts.
* Adapt navigation and layout intentionally for smaller screens.
* Preserve core functionality across supported screen sizes.
* Avoid hiding important actions solely because space is limited.
* Test common breakpoints and extreme content lengths.

## Tables and Data-Dense Views

* Use tables only for genuinely tabular data.
* Keep column names concise.
* Align numeric data consistently.
* Make sorting and filtering discoverable.
* Preserve filter and sort state where useful.
* Do not overload tables with too many actions.
* Prefer a clear primary row action and secondary contextual actions.
* Keep important columns visible.
* Allow horizontal scrolling only when necessary.
* Use pagination, virtualization or incremental loading for large data sets.
* Provide clear empty states.
* Avoid showing unnecessary columns by default.
* Use sensible formatting for dates, numbers and units.

## Search and Filtering

* Search should behave predictably.
* Make active filters visible.
* Make filters easy to remove.
* Provide a clear way to reset filters.
* Preserve search and filter state when navigating back where practical.
* Avoid requiring users to configure many filters before seeing results.
* Use sensible defaults.
* Clearly distinguish no results from loading or errors.
* Suggest recovery options when no results are found.

## Dialogs and Modals

* Use dialogs only when interruption is justified.
* Avoid stacking dialogs.
* Keep dialogs focused on one decision or task.
* Use clear titles.
* Keep primary and secondary actions obvious.
* Make cancellation easy.
* Support Escape where appropriate.
* Do not use dialogs for information that belongs inline.
* Avoid large workflows inside modal dialogs.
* Do not close dialogs unexpectedly while users are entering data.

## Destructive Actions

* Clearly label destructive actions.
* Use confirmations for irreversible or high-impact operations.
* Explain the consequence before confirmation.
* Prefer reversible actions when possible.
* Offer undo where practical.
* Do not use generic confirmation text for destructive operations.
* Make the safe action visually distinct.
* Do not preselect destructive choices.

## Error Prevention

* Prevent invalid actions before they occur where practical.
* Use constraints and suitable controls instead of relying only on validation errors.
* Provide sensible defaults.
* Confirm only high-impact decisions.
* Warn users before losing unsaved changes.
* Do not clear entered data unexpectedly.
* Avoid ambiguous state transitions.
* Make dependencies between fields or actions visible.

## Consistency

* Similar problems should have similar UI solutions.
* Similar actions should use the same wording and placement.
* Do not introduce custom patterns when an existing pattern already solves the problem.
* Reuse components and design tokens.
* Keep interaction behavior consistent across the application.
* Preserve platform conventions unless there is a strong reason not to.

## User Control

* Keep users in control of important actions.
* Do not perform surprising destructive actions automatically.
* Do not change user data without a clear action or established behavior.
* Make automatic behavior visible when it materially affects the user.
* Allow users to cancel long-running operations where practical.
* Allow recovery from mistakes where possible.
* Avoid dark patterns.
* Never manipulate users into actions they did not intend.

## Progressive Disclosure

* Show the most important options first.
* Hide advanced complexity until it is needed.
* Do not overwhelm users with every possible setting at once.
* Keep advanced options discoverable.
* Avoid forcing expert workflows on normal users.
* Avoid hiding frequently used functionality behind excessive menus.

## Performance Perception

* Optimize perceived performance as well as actual performance.
* Show useful content as early as possible.
* Avoid blocking initial rendering on non-critical data.
* Use skeletons only when they improve comprehension.
* Avoid fake progress.
* Do not use loading animations to mask avoidable slowness.
* Keep interactions responsive even while background work continues.

## Defaults

* Choose safe and sensible defaults.
* Defaults should match the most common expected user intent.
* Avoid defaults with destructive consequences.
* Preserve user preferences when appropriate.
* Do not force repeated configuration for common workflows.

## Design Decision Rule

* Every UI element should have a clear purpose.
* Every additional interaction adds cognitive cost.
* Prefer removing complexity over explaining unnecessary complexity.
* Prefer familiar patterns over clever ones.
* Prefer fewer clear choices over many ambiguous choices.
* Prefer predictable behavior over surprising automation.
* If a design decision introduces ambiguity, unnecessary complexity, or multiple equally valid UX directions, ask the user instead of deciding autonomously.

## Priority Order

Prioritize UI/UX decisions in this order:

* Correctness
* Clarity
* Safety
* Accessibility
* User control
* Task efficiency
* Consistency
* Responsiveness
* Visual polish

Visual polish must never reduce usability.