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

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# 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>