Application Designer - Mobile Template Guidelines v1.0

---

Design Philosophy

Mobile-First Thinking

Mobile screens in the Fuuz Application Designer must prioritize simplicity, clarity, and task completion. The design standard is built on three core principles:

1. Constrained Flexibility: Leverage responsive layouts while maintaining strict control over growth and overflow
2. Predictable Behavior: Screen elements should remain stable and not shift during user interaction
3. Task-Focused Design: Each screen should accomplish one primary task with minimal cognitive load

Target Devices

• Primary: Smartphones (320px - 428px width)
• Secondary: Tablets in portrait mode (768px - 834px width)
• Testing: Use device emulation for iPhone SE, iPhone 12/13/14, and iPad mini

Template Architecture

Container Hierarchy

The standard template uses a four-level container architecture:

ROOT (Screen)
└── ContainerOuter (Prevents uncontrolled growth)
    ├── ContainerHeader (Fixed height: 60px)
    ├── ContainerBody (Flexible, scrollable)
    │   └── Form1
    │       └── ContainerInnerBody (Content wrapper)
    └── ContainerFooter (Fixed height: 80px)

Container Specifications

ContainerOuter

Purpose: Primary layout constraint container
Properties:

• width: 100%, height: 100%
• flexDirection: column
• justifyContent: space-between
• overflow-x: hidden, overflow-y: hidden
• flexGrow: false, flexShrink: false

Why: Prevents the screen from growing uncontrollably in both X and Y axes. This is the foundation of layout stability.

ContainerHeader

Purpose: Fixed navigation and title area
Properties:

• height: 60px (fixed)
• width: 100%
• flexDirection: row
• justifyContent: space-between
• alignItems: center
• background: custom (#5b30df or brand color)
• padding: 4

Content:

• Screen title (left-aligned Text element)
• Navigation menu (right-aligned Menu element)

Developer Actions:

• Manually update screen name/title
• Configure menu navigation items

ContainerBody

Purpose: Main scrollable content area
Properties:

• height: 0px (allows flex-grow to control size)
• width: 100%
• flexGrow: true
• flexShrink: false
• overflow-y: auto
• overflow-x: hidden
• scrollbar-width: thin

Why: Setting height to 0px with flexGrow:true allows the body to fill available space between header and footer without causing overflow issues.

ContainerInnerBody

Purpose: Content padding and organization wrapper
Properties:

• height: 0px
• width: 100%
• flexGrow: true
• flexDirection: column
• padding: 6 (24px equivalent)

Content: Form inputs, data displays, action elements

ContainerFooter

Purpose: Fixed action button area
Properties:

• height: 80px (fixed)
• width: 100%
• flexDirection: row
• justifyContent: space-between
• alignItems: stretch

Content: Primary and secondary action buttons (Submit, Clear, Cancel, etc.)

Layout Principles

Responsive Layout Strategy

When building screens using responsive layouts, follow these thought processes:

1. Start with Structure, Not Content

Think: "What needs to be fixed, and what needs to be flexible?"

• Fixed Elements: Headers, footers, navigation bars
• Flexible Elements: Content areas, scrollable regions

Process:

1. Place ContainerOuter first
2. Add ContainerHeader (fixed)
3. Add ContainerBody (flexible)
4. Add ContainerFooter (fixed)
5. Only then add content elements

2. Control Growth Explicitly

Think: "Where should expansion occur, and where must it stop?"

Rules:

• Set flexGrow: false on containers that must maintain size
• Set flexGrow: true only on content areas that should fill available space
• Use height: 0px with flexGrow: true to prevent initial overflow
• Always set flexShrink: false on fixed-height elements

3. Manage Overflow Intentionally

Think: "What happens when content exceeds container size?"

Guidelines:

• ContainerOuter: overflow: hidden (prevent page scroll)
• ContainerBody: overflow-y: auto (enable content scroll)
• ContainerHeader/Footer: No overflow (fixed size)
• Input containers: Fixed height to accommodate validation messages

4. Use Flex Direction Purposefully

Think: "How should child elements flow?"

• Column: Vertical stacking (most mobile layouts)
• Row: Horizontal arrangement (headers, footers, button groups)

Pattern:

ContainerOuter → column (vertical stacking)
├── ContainerHeader → row (title left, menu right)
├── ContainerBody → column (inputs stack vertically)
└── ContainerFooter → row (buttons side-by-side)

5. Justify and Align Strategically

Think: "How should available space be distributed?"

Common Patterns:

• justifyContent: space-between - Maximum separation (headers, footers)
• justifyContent: flex-start - Top/left alignment (content areas)
• alignItems: stretch - Fill cross-axis (button groups)
• alignItems: center - Center cross-axis (headers)

Component Standards

Form Inputs

General Input Properties

All form inputs must include:

Why Fixed Height?
Setting height: 120px prevents screen flexing when validation messages appear. This maintains a stable layout and prevents disorienting visual shifts.

Input Type Selection

Developer Responsibility: Choose appropriate input types based on data requirements

TextInput Guidelines

Standard Configuration:

Label Requirements:

• Use clear, action-oriented labels
• Keep labels under 25 characters
• Avoid technical jargon
• Example: "Inventory Number" not "INV_NUM_ID"

Description Field: Use the description property to document:

• Purpose of the field
• Validation rules
• Special formatting requirements
• Integration points

SelectInput Guidelines

Standard Configuration:

Critical: Always use predicate filters to return only active/usable options

Filter Pattern:

Why: Presenting inactive or unusable records to mobile users causes confusion and support issues.

Scan Input Pattern

For inputs requiring barcode/QR scanning:

1. Use TextInput with scan button
2. Set appropriate input type (text, number)
3. Configure validation for expected format
4. Provide clear feedback on successful scan

Buttons

Footer Buttons

Buttons in ContainerFooter should fill available space:

Standard Pattern: Two-button footer

Color Coding:

• Green: Primary affirmative action (Submit, Save, Confirm)
• Amber: Secondary action (Clear, Cancel)
• Red: Destructive action (Delete) - use sparingly
• Blue: Navigation action (Back, Next)

Disabled State Logic

Use JSONata expressions to control button states:

Submit Button Pattern:

Clear/Cancel Button Pattern:

Why Different?

• Submit: Disabled when required fields are empty (formState.values)
• Clear: Disabled when all fields are already empty (data)

Navigation

Menu Configuration

Required Menu Structure:

1. Explicit "Home" page as primary navigation hub
2. Function-specific pages accessible from Home
3. Each functional page includes hamburger menu
4. Minimum menu items: Home, current page indicator

Header Menu Placement:

• Right-aligned in ContainerHeader
• Icon-only (hamburger) to save space
• Clear visual indicator of current page

Navigation Flow:

Home (hub)
├── Function Page 1 (with menu → Home)
├── Function Page 2 (with menu → Home)
└── Function Page 3 (with menu → Home)

Why: Mobile users need clear escape routes. A consistent Home hub provides orientation and reduces support calls.

Validation Messages

Standard Error Messages

Developer Responsibility: Customize validation messages for clarity

Default vs Custom:

• ❌ Default: "Field is required"
• ✅ Custom: "Scan or enter inventory number"

Message Guidelines:

1. Be specific about what's needed
2. Suggest the action to resolve
3. Keep under 50 characters
4. Use plain language, no codes

Examples:

Developer Checklist

Before Deployment

Use this checklist for every mobile screen:

Layout Structure

• [ ] ContainerOuter set with overflow: hidden, flexGrow: false
• [ ] ContainerHeader fixed at 60px height
• [ ] ContainerBody set with height: 0px, flexGrow: true, overflow-y: auto
• [ ] ContainerFooter fixed at 80px height
• [ ] All containers properly nested

Screen Elements

• [ ] Screen name manually updated in ContainerHeader
• [ ] Form elements inside ContainerBody
• [ ] Action buttons inside ContainerFooter
• [ ] No more than 4 inputs on single screen (recommended)

Form Inputs

• [ ] All inputs have fixed height (120px recommended)
• [ ] Input types appropriate for data (text, number, email, tel, etc.)
• [ ] All inputs set to variant: "outlined"
• [ ] dataFontSize: 24, labelFontSize: 15 on all inputs
• [ ] Required fields marked with validation.required: true
• [ ] SelectInputs use predicate filters for active records only

Validation

• [ ] Custom error messages written for all required fields
• [ ] Messages are clear, concise, under 50 characters
• [ ] Messages suggest corrective action
• [ ] Test validation display (ensure 120px height prevents screen flex)

Buttons & Actions

• [ ] Submit button properly disabled when required fields empty
• [ ] Clear/Cancel webflow created to reset form fields
• [ ] Submit webflow created to generate proper transaction
• [ ] Button colors follow standard (green=submit, amber=cancel)
• [ ] Button text is large and clear (customTextSize: 24)

Navigation

• [ ] Menu navigation configured in ContainerHeader
• [ ] Explicit "Home" page created as navigation hub
• [ ] All functional pages include menu with Home option
• [ ] Current page visually indicated in menu

Testing

• [ ] Tested on iPhone SE emulation (320px width)
• [ ] Tested on iPhone 12/13/14 emulation (390px width)
• [ ] Tested on iPad mini emulation (768px width)
• [ ] Verified no horizontal scrolling
• [ ] Verified ContainerBody scrolls properly
• [ ] Verified validation messages display without layout shift
• [ ] Tested all button states (enabled/disabled)
• [ ] Tested navigation flow

Webflows

• [ ] Clear/Cancel flow resets all form fields
• [ ] Submit flow includes all required data processing
• [ ] Error handling implemented for submit failures
• [ ] Success feedback provided to user
• [ ] Navigation after successful submit defined

Best Practices

Screen Complexity Management

The Four-Input Rule

Guideline: Avoid adding more than 4 inputs to a single mobile screen

Why:

• Mobile screen real estate is limited
• Excessive scrolling increases error rates
• Cognitive load increases with field count
• Validation errors become harder to track

When You Need More Than 4 Inputs:

1. Split into multiple screens with clear progression
2. Group related inputs on separate pages
3. Use wizard/stepper pattern for complex processes
4. Consider if all inputs are necessary for mobile context

Example Pattern:

Screen 1: Item Selection (2 inputs)
    ↓
Screen 2: Location Selection (2 inputs)
    ↓
Screen 3: Quantity & Notes (2 inputs)
    ↓
Review & Submit

Action Limitation

Guideline: Avoid adding more than 2 primary actions per screen

Standard Pattern:

• 1 Primary action (Submit, Save, Confirm)
• 1 Secondary action (Clear, Cancel)

Why:

• Reduces decision paralysis
• Clearer call-to-action
• Fewer tap errors
• Consistent footer layout

Exceptions:

• Navigation actions (in header menu, not footer)
• Inline actions within scrollable content
• Progressive disclosure (hidden until triggered)

Form Design Patterns

Progressive Disclosure

Use when: Related inputs depend on prior selections

Pattern:

1. Start with primary selection
2. Show/hide additional fields based on selection
3. Use hidden property with JSONata conditionals

Example:

// Hide quantity input until item selected
hidden: $isNilOrEmpty($components.Form1.formState.values.item.id)

Smart Defaults

Use when: Most users select the same option

Implementation:

• Set default values in form initialization
• Use dataPath with initial value
• Allow override with clear indication

Example: Default to current shift, current location, current user

Performance Considerations

Query Optimization for SelectInputs

Guidelines:

• Set optionLimit: 5 for initial load
• Enable searchPredicate: "contains" for filtering
• Use orderByField for predictable sorting
• Always filter by active status

Why: Mobile networks can be slow; limiting options improves responsiveness

Data Subscription Management

Guidelines:

• Disable data subscriptions on forms unless real-time updates required
• Use autoLoad: false if data isn't needed immediately
• Consider data change indicator impact on layout

Accessibility

Touch Target Sizing

Requirements:

• Minimum touch target: 44px × 44px
• Buttons should fill available space
• Adequate spacing between interactive elements (minimum 8px)

Implementation:

• Footer buttons: height: "100%" (fills 80px footer)
• Input fields: height: "120px" (plenty of touch area)
• Scan buttons: Use large icon size

Font Sizing

Standards:

• Input data: 24px (readable without zoom)
• Input labels: 15px (clear but not overwhelming)
• Button text: 24px (easy to read at glance)
• Validation messages: Auto-sized (typically 12-14px)

Why: Prevents zooming, reduces errors, accommodates various vision levels

Color Contrast

Requirements:

• Text on custom backgrounds must meet WCAG AA standards (4.5:1 minimum)
• Use high contrast for primary actions
• Disabled states should be clearly distinguishable

Testing: Test header text on brand color backgrounds

Common Patterns

Pattern 1: Simple Data Collection

Use Case: Collect 2-3 pieces of information and submit

Structure:

ContainerHeader (Screen Title + Menu)
ContainerBody
  └── Form
      ├── Input 1 (required)
      ├── Input 2 (required)
      └── Input 3 (optional)
ContainerFooter
  ├── Submit Button (50%)
  └── Clear Button (50%)

Key Points:

• All inputs clearly labeled
• Submit disabled until required fields complete
• Clear resets all fields
• Success feedback navigates to confirmation or home

Pattern 2: Scan and Verify

Use Case: Scan barcode, display related data, collect additional input

Structure:

ContainerHeader (Screen Title + Menu)
ContainerBody
  └── Form
      ├── Scan Input (with button)
      ├── Display Data (read-only text, loaded after scan)
      ├── Additional Input 1
      └── Additional Input 2
ContainerFooter
  ├── Submit Button (50%)
  └── Cancel Button (50%)

Key Points:

• Scan button prominent and clearly labeled
• Related data loads automatically after successful scan
• Additional inputs enabled only after successful scan
• Validation ensures scanned data is valid

Pattern 3: Selection and Confirmation

Use Case: Choose from list, review selection, confirm action

Structure:

Screen 1: Selection
ContainerHeader (Screen Title + Menu)
ContainerBody
  └── Form
      ├── SelectInput (main selection)
      └── Optional filter inputs
ContainerFooter
  ├── Continue Button (50%)
  └── Cancel Button (50%)

Screen 2: Confirmation
ContainerHeader (Screen Title + Menu)
ContainerBody
  └── Display selected data (read-only)
ContainerFooter
  ├── Confirm Button (50%)
  └── Back Button (50%)

Key Points:

• Two-screen pattern for high-stakes actions
• Review before commit
• Clear back navigation
• Confirmation provides finality

Pattern 4: Multi-Step Process

Use Case: Complex task requiring multiple inputs in sequence

Structure:

Each Step:
ContainerHeader (Screen Title + Step Indicator + Menu)
ContainerBody
  └── Form
      ├── Step-specific inputs (max 3)
      └── Optional help text
ContainerFooter
  ├── Next/Submit Button (50%)
  └── Back/Cancel Button (50%)

Key Points:

• Clear step indicator (e.g., "Step 2 of 4")
• Progress saved between steps
• Back button allows correction
• Final step shows review/summary

Pattern 5: Dashboard/Home Hub

Use Case: Primary navigation point with status information

Structure:

ContainerHeader (App Title + Menu)
ContainerBody
  └── Container (card-style layout)
      ├── Status Display Cards
      └── Action Buttons (navigate to functions)
ContainerFooter
  └── Optional refresh or global action

Key Points:

• No form inputs on home screen
• Clear navigation buttons to functional pages
• Status information at-a-glance
• Consistent entry point for users

Troubleshooting

Common Layout Issues

Issue: Screen scrolls horizontally

Symptoms:

• Content extends beyond screen width
• User can swipe left/right

Causes:

• ContainerOuter missing overflow-x: hidden
• Child element width exceeds 100%
• Fixed-width elements too wide for mobile

Solutions:

1. Set ContainerOuter overflow-x: hidden
2. Check all child elements for width: 100% or appropriate percentage
3. Verify no fixed-width elements exceed 320px minimum screen width
4. Check padding/margin calculations

Issue: Screen content behind footer

Symptoms:

• Last input or content hidden under footer
• Cannot scroll to see all content

Causes:

• ContainerBody not using proper flexbox configuration
• Missing flexGrow: true on ContainerBody
• Footer not properly separated from body

Solutions:

1. Set ContainerBody height: 0px and flexGrow: true
2. Verify ContainerOuter has justifyContent: space-between
3. Ensure footer has fixed height (80px)
4. Check that body has overflow-y: auto

Issue: Screen layout shifts when validation errors appear

Symptoms:

• Screen elements move when error message displays
• Inputs jump or reposition
• Footer moves up/down

Causes:

• Input height set to auto instead of fixed height
• Error messages adding to container height
• Flex calculations changing with content

Solutions:

1. Set all inputs to height: 120px (or appropriate fixed height)
2. Test validation display during development
3. Adjust height if error messages need more space
4. Never use height: auto on form inputs in mobile layouts

Issue: Cannot scroll content area

Symptoms:

• Content cut off at bottom
• Scroll doesn't work in body
• All content tries to fit in viewport

Causes:

• ContainerBody missing overflow-y: auto
• ContainerOuter has overflow-y: auto (wrong place)
• Body height not properly constrained

Solutions:

1. Set ContainerBody overflow-y: auto
2. Set ContainerOuter overflow-y: hidden
3. Verify body has height: 0px and flexGrow: true
4. Test with content exceeding viewport height

Common Functional Issues

Issue: Submit button always disabled

Symptoms:

• Button remains gray even when fields complete
• Cannot submit form

Causes:

• Disabled logic checking wrong data path
• Typo in field reference
• Logic using and instead of or

Solutions:

1. Verify disabled logic uses formState.values not just data
2. Check exact field path: $components.Form1.formState.values.dataPath
3. Use or between required field checks (disabled if ANY empty)
4. Test logic with console output if needed

Issue: Clear button doesn't work

Symptoms:

• Fields don't reset when Clear clicked
• Form remains populated

Causes:

• No webflow attached to Clear button
• Webflow not configured to reset form
• Wrong form reference

Solutions:

1. Create webflow attached to Clear button
2. Use form reset action in webflow
3. Verify form element name matches (Form1)
4. Test after webflow creation

Issue: Validation messages unclear

Symptoms:

• Users don't understand what's wrong
• Support requests increase
• Users enter incorrect data

Causes:

• Using default validation messages
• Messages too technical
• Messages don't suggest solution

Solutions:

1. Customize all validation messages
2. Use plain language
3. Include corrective action
4. Test messages with actual users

Issue: SelectInput shows inactive/deleted records

Symptoms:

• Users select options that shouldn't be available
• Errors during submit due to invalid references

Causes:

• Missing additionalFilter on SelectInput
• Filter not checking active status
• Wrong filter field name

Solutions:

1. Add additionalFilter with active status check
2. Verify field name (active, isActive, status, etc.)
3. Use _eq: true for boolean active fields
4. Test with known inactive records

Version History

v1.0 - Initial Release

• Established four-container architecture
• Defined input standards (120px height, outlined variant, font sizing)
• Created developer checklist
• Documented common patterns and troubleshooting

Support and Resources

Internal Documentation

• Fuuz Application Designer User Guide
• JSONata Expression Reference
• GraphQL Query Builder Guide

Document Control
Version: 1.0