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

# UI Designer best practices

> Best practices for creating effective user interfaces using FlowX.AI UI Designer, based on established design principles and platform capabilities.

## UI Designer best practices in FlowX.AI

When designing user interfaces with FlowX.AI UI Designer, following established best practices ensures consistent, usable, and effective user experiences.

## Design principles

Based on FlowX.AI documentation for creating user interfaces:

> [card] Consistent Styling
>
> **Use consistent styling across all screens** for a cohesive user experience.
>
> Use platform-specific overrides strategically while maintaining visual consistency.

> [card] Logical Grouping
>
> **Group related inputs within logical sections or cards**.
>
> Use Cards and Containers to organize content and create visual hierarchy.

> [card] Proper Validation
>
> **Implement proper validation** to prevent errors and guide users.
>
> Use the built-in validators (such as **Required**, **Min length**, **Pattern**, and **Email**), a **Custom expression** validator, or a **Custom** validator your app registers.

> [card] Clear Feedback
>
> **Provide clear feedback** on actions with success and error messages.
>
> Use event handlers to handle user interactions appropriately.

## Component usage guidelines

### Form elements best practices

> [accordion] Input Fields
>
> **Configuration**:
>
> * Use clear, descriptive labels
> * Implement appropriate validation (for example required, pattern, or a custom validator)
> * Configure hide/disable expressions for dynamic behavior
> * Add helper text for complex requirements
>
> **Available Properties**:
>
> * Label and placeholder text
> * Validation rules (for example required, pattern, or a custom validator)
> * Hide and disable expressions
> * Platform-specific overrides

> [accordion] Selection Components
>
> **Select Component**:
>
> * Use for dropdown menus and single selections
> * Configure options with proper labels and values
> * Add an **On change** event handler to update dependent fields
>
> **Radio Buttons**:
>
> * Best for 2-4 exclusive options
> * Use when all options need to be visible
>
> **Checkboxes**:
>
> * Use for multiple selections or single yes/no choices
> * Add an **On change** event handler for dynamic interactions

> [accordion] Action Components
>
> **Buttons**:
>
> * Use descriptive labels that indicate the action
>
> - Add an **On click** event handler with the action the button runs: **Node action** in a process, **Start workflow** or **Navigate to** in a UI Flow
> - Consider platform-specific button styles
>
> **File Upload**:
>
> * Clearly indicate accepted file types
> * Provide appropriate feedback during upload process
> * Consider platform limitations for mobile devices

### Layout best practices

> [tab] Linear Layout
>
> **When to Use**: Simple, sequential content flow
>
> **Configuration**:
>
> * **Direction**: Choose Horizontal for row layout, Vertical for column layout
> * **Justify**: Control main axis alignment (Start, Center, End, Space Between, etc.). Space Between, Space Around, and Space Evenly are offered on Web only
> * **Align**: Control cross axis alignment (Start, Center, End, Stretch). Stretch is offered on Web only
> * **Gap**: Set spacing between elements, in px on Web, pt on iOS, and dp on Android
> * **Wrap**: Enable for responsive behavior when needed (Web only)
>
> **Best For**:
>
> * Form layouts
> * Content that flows in one direction
> * Mobile-first designs

> [tab] Grid Layout
>
> **When to Use**: Complex, multi-dimensional layouts
>
> **Benefits**:
>
> * Better control over 2D layouts
> * Responsive design capabilities
> * Suitable for dashboard-style interfaces
>
> **Considerations**:
>
> * More complex to configure than linear layouts
> * Test across platforms for consistent behavior

## Platform-specific best practices

### Web Platform

**1. Navigation Design**

**Navigation Types**:

* Use **Single page form** (the default) for displaying all User Tasks on the same page
* Use **Wizard** for step-by-step processes
* Configure actions properly for smooth navigation flow

**2. Zone Configuration**

**Web-Specific Features**:

* Utilize zones with headers and footers (web-only feature)
* Implement proper navigation hierarchy
* Use cards to guide users through content on single-page forms

**3. Layout Optimization**

**Screen Real Estate**:

* Take advantage of larger screen sizes
* Use appropriate justify and align settings for content distribution
* Consider horizontal layouts for better space utilization

### Mobile Platforms (iOS & Android)

> [accordion] Screen Configuration
>
> **Mobile-Specific Properties**:
>
> * Configure **Screen title** for navigation bar display (Card or Container at the root of a user task, or a direct child of a navigation area in a UI Flow)
> * Set **Scrollable** property appropriately (iOS and Android, same root components as the screen title)
> * Use platform overrides for shorter titles and mobile-optimized content
>
> **Limitations**:
>
> * Zones with headers and footers are not supported
> * Navigation areas are limited to Stepper, Page, Modal, and Tab Bar (no Zones), and the **Navigation type** field is Web only

> [accordion] Content Adaptation
>
> **Content Strategy**:
>
> * Use shorter titles and labels for mobile displays
> * Consider touch interaction patterns
> * Ensure content fits within mobile screen constraints
> * Test with realistic content lengths

## Dynamic behavior best practices

### Hide and Disable Expressions

> [tab] Hide Expressions
>
> **Purpose**: Control element visibility based on conditions
>
> **Implementation**:
>
> * Use JavaScript expressions that evaluate to true/false
> * Reference process data store keys for dynamic evaluations
> * Configure in **Settings** → **Expressions**; to hide an element on one platform only, add a **Hide** expression under that platform's overrides (**Settings** → **Overrides (+)** → **Expressions**)
>
> **Common Use Cases**:
>
> * Show/hide fields based on user selections
> * Display different content for different user roles
> * Adapt interface based on process state

> [tab] Disable Expressions
>
> **Purpose**: Make elements non-interactive while keeping them visible
>
> **Best Practice**: A disable condition doesn't need a matching hide condition: each one works on its own, and hidden and disabled fields are both left out of validation.
>
> **Usage**: Disable form fields based on validation state or user permissions

### Conditional Styling

**Available For**: Text, Link, Image, Container, Card, Form, Collection and Collection prototype elements

**1. Configuration**

1. Select one of the elements listed under **Available For**
2. Navigate to the **Styles** tab
3. Locate the **Conditional Styling** section
4. Click the **➕** icon to add expressions and effects
5. Use the **JS Editor** to configure expressions

**2. Structure**

**Condition**: String expression evaluated similarly to hide/disable expressions
**Overrides**: Key-value map defining property-value pairs to apply

**3. Best Practices**

* Use real-time data evaluation for responsive UI updates
* Handle conflict resolution (latest condition takes precedence)
* Combine with data-driven expressions for adaptable designs

## Validation best practices

### Available Validators

> [accordion] Required Validator
>
> **Usage**: Ensure essential fields are completed before form submission
>
> **Application**: Apply to critical form elements like name, email, or selection fields

> [accordion] Custom Expression Validator
>
> **Usage**: Write the validation rule as an expression in the Designer. The **Custom expression** validator passes only when the expression returns `true`.
>
> **Benefits**: Business rules specific to your form, with no code in the host app

> [accordion] Custom Validator
>
> **Usage**: Call a validator that your app registers in the SDK under the name you enter in the Designer. Set its **Execution type** to `sync` or `async`.
>
> **Benefits**: Validation logic that needs code or a backend call

> [accordion] Validation on hidden or disabled fields
>
> **Usage**: Hidden and disabled fields are left out of validation. To apply a validator only in some situations, combine it with a **Hide** or **Disable** expression on the field.

## Event handlers best practices

### Event Configuration

**Triggers**: On click, On change, On load, On display, On scroll, On document end, On process end. Use **On change** to update dependent fields, run calculations, or show and hide related content.

**Action types**: Node action, Upload, Dismiss, Start process, Start workflow, Start project, External, Navigate to, Run local script, Conversation reply trigger, Download, Save local variable.

Which triggers and action types a component offers depends on the component and on whether it sits in a process or a UI Flow. For the full matrix, see [Event handlers](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/event-handlers.md).

> [!TIP]
>
> Configure event handlers to provide immediate feedback and create responsive user experiences.

## Testing and quality assurance

### Platform Testing

**1. Multi-Platform Preview**

Use the platform selector in the UI Designer toolbar (**Desktop**, **Mobile iOS**, **Mobile Android**) to preview designs across Web, iOS, and Android.

**2. Responsive Testing**

Test layouts with different content lengths and screen orientations.

**3. Expression Validation**

Test hide/disable expressions and conditional styling with various data scenarios.

**4. Navigation Flow**

Verify wizard navigation and single-page form behaviors work as expected.

### Content Considerations

> [card] [Accessibility](https://docs.flowx.ai/6.x/docs/platform-deep-dive/accessibility.md)
>
> **Design Considerations**:
>
> * Use proper labels for form elements
> * Ensure sufficient color contrast
> * Test with assistive technologies
> * Provide alternative text for images
>
> For details on WCAG 2.1 compliance, keyboard navigation, and screen reader support, see the [Accessibility guide](https://docs.flowx.ai/6.x/docs/platform-deep-dive/accessibility.md).

> [card] Responsive Design
>
> **Test Strategy**:
>
> * Verify layouts work on different screen sizes
> * Test navigation on both mobile and web
> * Ensure content remains readable across platforms
> * Check platform-specific overrides function correctly

## Common patterns and solutions

### Navigation areas management

**Copy Navigation Areas**: Use the copy/paste feature to replicate navigation hierarchies between platforms (within the same process definition and environment).

**Area Deletion**: When deleting navigation areas, remember that child areas are also removed, and user tasks are relocated to the User Tasks section.

### Theme and styling management

**Theme Overrides**:

* Customize component appearance to differ from theme settings
* Copy theme overrides between platforms (**Copy from \<platform>**, **Copy to \<platform>**) for consistency
* Use contextual menu options for efficient style management

**Style Copying**: Use copy/paste functionality for styles between compatible components and across platforms.

> [!NOTE]
>
> These best practices are based on actual FlowX.AI capabilities and documentation. Always refer to the latest documentation for the most current features and recommendations.


## Related topics

- [UI Designer](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-designer.md)
- [Navigation best practices](https://docs.flowx.ai/6.x/docs/building-blocks/process/navigation-best-practices.md)
- [Platform-specific considerations](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/platform-considerations.md)
- [Collection](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/collection/collection.md)
- [Layout configuration](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/layout-configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.