> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Heuristic guidelines

> Practical usability principles for evaluating and improving UI design quality.

## Feedback and system status

Users should always know what's happening. The right message or indicator at the right time keeps them oriented and in control.

<AccordionGroup>
  <Accordion title="Visibility of system status">
    Provide timely feedback so users are never left guessing. Examples include loading indicators and validation messages.
  </Accordion>

  <Accordion title="Acknowledge user actions">
    Confirm that actions have been received. Examples include Sonner notifications after saving, or a contextual tooltip confirming something has been copied to clipboard.
  </Accordion>

  <Accordion title="Skeleton screens and loaders">
    Use the appropriate loading state for the context:

    * Full-page loaders for page transitions
    * Skeleton placeholders instead of blank screens
    * Spinners and progress bars for smaller transitions
    * Lazy loading for optimal performance
  </Accordion>
</AccordionGroup>

## Affordance and discoverability

Affordance refers to the visual and interactive cues that signal how an element can be used — so users instinctively know what actions are available.

<AccordionGroup>
  <Accordion title="Micro-interactions and signifiers">
    Small animations and visual cues that indicate an interaction is possible. Example: button hover effects.
  </Accordion>

  <Accordion title="Cursor changes">
    Cursors should change to reflect what's possible — a pointer for clickable elements, an i-beam for editable text.
  </Accordion>

  <Accordion title="Clear labels and common patterns">
    Use recognizable patterns to surface interactions. Examples: a magnifying glass inside a search input, or a chevron on a button that reveals a dropdown.
  </Accordion>

  <Accordion title="Contextual help">
    Provide tooltips or inline hints where user intent is ambiguous or the action has meaningful consequences.
  </Accordion>
</AccordionGroup>

## Progressive disclosure

Progressive disclosure hides less important information until it's needed, reducing cognitive load and preventing overwhelm. Apply affordance principles when using it so users know hidden content exists.

<AccordionGroup>
  <Accordion title="Collapsible states">
    Hide secondary content but keep it accessible and logically placed. Examples: accordions, dropdown menus for file management.
  </Accordion>

  <Accordion title="Wizards and steppers">
    Break complex tasks into focused steps so users aren't overwhelmed by the full scope of a task upfront.
  </Accordion>

  <Accordion title="Delay or hide advanced features">
    Less-used settings or inputs can be hidden until relevant. Example: show additional configuration only after a user selects an option that requires it.
  </Accordion>

  <Accordion title="Contextual menus">
    Menus that appear adjacent to the element they affect — like right-clicking in a graph or canvas. Surface relevant actions and hide less common ones.
  </Accordion>
</AccordionGroup>

## Error handling and prevention

Design for error prevention first, recovery second. When users can identify and fix problems on their own, it keeps them moving.

<AccordionGroup>
  <Accordion title="Prevention">
    Warn users before irreversible actions. Example: "Are you sure you want to delete this?"
  </Accordion>

  <Accordion title="Auto-save">
    Prevent accidental data loss by autosaving user inputs wherever possible.
  </Accordion>

  <Accordion title="Validation and error messages">
    Explain what went wrong and how to fix it before the user tries to proceed. Follow established error state patterns.
  </Accordion>

  <Accordion title="Undo and confirmation modals">
    Let users confirm or cancel an action before it's finalized, or provide an undo option in the toast notification after completion.
  </Accordion>
</AccordionGroup>

## Enable super users

Experienced users benefit from shortcuts, bulk actions, and customizable workflows that reduce friction and speed up repetitive tasks — without overwhelming beginners.

<AccordionGroup>
  <Accordion title="Shortcuts">
    Support keyboard shortcuts for common actions. Align them with platform standards or patterns used across other CDF applications.
  </Accordion>

  <Accordion title="Bulk actions">
    Support multi-select and bulk operations when users may need to perform the same action across many items.
  </Accordion>

  <Accordion title="Onboarding">
    The interface should support both novice and experienced users, making it easy to learn without getting in the way of efficiency.
  </Accordion>
</AccordionGroup>

## Layout and hierarchy

Layout and hierarchy directly impact usability, readability, and how efficiently users can navigate a product.

<AccordionGroup>
  <Accordion title="Group related elements">
    Apply the law of proximity — visually associate related content. Example: form fields within the same container, contextual menus near the elements they affect.
  </Accordion>

  <Accordion title="Persistent common actions and CTAs">
    Place frequent actions in consistent, accessible locations across the product. Example: topbar local actions.
  </Accordion>

  <Accordion title="Visual hierarchy for scannability">
    Use size, color, contrast, and whitespace to emphasize what matters most.
  </Accordion>

  <Accordion title="Logical flow and F/Z pattern layouts">
    Structure content based on how users naturally scan — left to right, top to bottom, with the most important content first.
  </Accordion>

  <Accordion title="Alignment for structure and readability">
    Keep text and elements aligned for a clean, structured layout. Example: left-aligned labels in forms.
  </Accordion>

  <Accordion title="Responsiveness">
    Components and page layouts should be optimized for desktop, tablet, and mobile.
  </Accordion>
</AccordionGroup>

## Accessibility and inclusive design

Accessible design improves usability for everyone, not just users with disabilities.

<AccordionGroup>
  <Accordion title="Keyboard accessibility">
    All interactions must be performable via keyboard. If an action is only available on hover or drag, provide a keyboard-accessible alternative.
  </Accordion>

  <Accordion title="Color contrast and readability">
    Text must meet WCAG AA contrast ratios at a minimum.
  </Accordion>

  <Accordion title="ARIA roles and labels">
    Use semantic HTML and proper ARIA attributes to support screen readers.
  </Accordion>

  <Accordion title="Focus indicators">
    Clearly show which element is focused during keyboard navigation. Most focus states are handled by Aura components.
  </Accordion>

  <Accordion title="Alternative input methods">
    Support voice commands, screen readers, and other assistive navigation tools.
  </Accordion>

  <Accordion title="Clickable and touchable areas">
    Minimum 44px for touch targets, 20px for click targets.
  </Accordion>
</AccordionGroup>