Standard Form Design Specification

A unified framework for building single-record editing screens across Master Data, Transactional, and Setup applications—ensuring consistent user experience, minimal navigation, and clear separation between reference and editable content.

Audience & Version

• Audience: Solution Architects, Application Designers, Partners
• Module: Fuuz Platform / Application Design
• Applies to versions: 2025.12+
• Template Reference: Form_Screen_-_Standard_System_Page_Design_0_0_1.json

Overview

The Standard Form Design defines a consistent screen architecture for viewing and editing individual records within Fuuz applications. It establishes patterns for layout, component organization, and interaction behaviors that apply universally across MES, WMS, QMS, Asset Management, and custom industrial applications.

Design Principles

1. Minimize Navigation: Vertical scrolling within the main content area eliminates the need for users to navigate away from the form to access related information.
2. Clear Visual Hierarchy: Distinct separation between immutable reference data (sidebar) and editable content (main area) reduces user confusion.
3. Progressive Disclosure: Content is organized in logical cards, allowing users to focus on relevant sections without being overwhelmed.
4. Contextual Actions: Actions are available where needed—header for primary save, sidebar for quick actions, inline for record-specific operations.

Screen Architecture

Layout Structure

The standard form screen follows a fixed two-column layout with a persistent header:

┌─────────────────────────────────────────────────────────────────┐
│  ScreenHeaderAndActions (40px fixed)              [Save] [Delete]│
├─────────────────────────────────────────────┬───────────────────┤
│                                             │                   │
│  MainContentForm (flexGrow, Y-scroll)       │  SidebarContainer │
│                                             │  (280px fixed)    │
│  ┌─────────────────────────────────────┐    │                   │
│  │ PrimaryContent Card                 │    │  ┌─────────────┐  │
│  └─────────────────────────────────────┘    │  │ Essential   │  │
│  ┌─────────────────────────────────────┐    │  │ Details     │  │
│  │ RelatedRecords Card                 │    │  └─────────────┘  │
│  └─────────────────────────────────────┘    │  ┌─────────────┐  │
│  ┌─────────────────────────────────────┐    │  │ Activity    │  │
│  │ CodeContent Card                    │    │  └─────────────┘  │
│  └─────────────────────────────────────┘    │  ┌─────────────┐  │
│  ┌─────────────────────────────────────┐    │  │ Quick       │  │
│  │ SettingsContent Card                │    │  │ Actions     │  │
│  └─────────────────────────────────────┘    │  └─────────────┘  │
│  ┌─────────────────────────────────────┐    │                   │
│  │ AttachmentsContent Card             │    │                   │
│  └─────────────────────────────────────┘    │                   │
│  ┌─────────────────────────────────────┐    │                   │
│  │ CustomFieldContent Card             │    │                   │
│  └─────────────────────────────────────┘    │                   │
│                                             │                   │
└─────────────────────────────────────────────┴───────────────────┘

Component Hierarchy

ROOT (Screen)
├── ScreenHeaderAndActions
│   └── SaveAction, DeleteAction, etc.
└── MainContainer
    ├── MainContentForm (scrollable)
    │   ├── PrimaryContent
    │   ├── RelatedRecords (optional)
    │   ├── CodeContent (optional)
    │   ├── SettingsContent (optional)
    │   ├── AttachmentsContent (optional)
    │   ├── NotesContent (optional)
    │   └── CustomFieldContent (optional)
    └── SidebarContainer (fixed 280px)
        ├── EssentialDetails
        ├── DataChangeActivity
        ├── QuickActionsContainer
        └── [Deployment-specific sections]

Header Specifications

ScreenHeaderAndActions

Save Action Behavior

Main Content Area

MainContentForm Container

Card Display Order

Default ordering prioritizes the most commonly accessed information:

1. Primary Content (always first)
2. Related Records (if applicable)
3. Code Content (if applicable)
4. Settings Content (if applicable)
5. Attachments Content (if applicable)
6. Notes Content (if applicable)
7. Custom Fields Content (always last when present)

Card Specifications

Standard Card Structure

All cards follow a consistent structural pattern:

Card Reference Table

Primary Content Card

Purpose: Contains all general editable fields for the current record. This is the primary workspace for user input.

• Minimum height: 500px
• Supports internal tabs for complex entities with multiple relationship types
• Place most frequently edited fields at the top
• Group related fields logically (identification, classification, configuration)

Related Records Card

Purpose: Displays and manages child/related entities.

• Simple (1-2 child types): Expandable sections within the card
• Complex (3+ child types): Tabs within Primary Content, one per child type
• Summary table with key columns, row count, and inline actions (View, Add)

Code Content Card

Purpose: Contains JSON schemas, JSONata expressions, SQL queries, or other structured code fields.

• Uses JSONInput component
• Collapsible: true, collapsedByDefault: true
• Supports syntax highlighting

Settings Content Card

Purpose: Contains boolean configuration values as switches or checkboxes.

• Layout: Grid, 1 column, 12px gap
• Each setting row: padding 6px, background: light, borderRadius: 4px
• Switch/checkbox on left (60px), label and description on right

Attachments Content Card

Purpose: Manages file attachments, documents, images, and media.

Common attachment types:

• SOPs, work instructions, procedures
• Quality certificates, inspection reports
• CAD drawings, schematics
• Photos (defects, setup verification)
• Compliance documents, certifications

Custom Fields Content Card

Purpose: Displays user-defined custom fields that extend the base data model.

• Component: CustomFieldsInput with dataPath: _customFields
• Always positioned as the last card in MainContentForm
• Supports field grouping via expandGroups property

Sidebar Specifications

SidebarContainer

Essential Details Section

Purpose: Displays immutable reference information that identifies the record.

Standard Components:

1. Primary Image: Product photo, equipment image, location map, or record avatar
2. Record Identifiers: Type, ID, Code, Label (read-only DisplayText fields)
3. Parent Hierarchy: Linked chain showing record lineage (clickable)
4. Status Indicator: Visual badge showing current status

Parent Hierarchy Display Pattern:

HIERARCHY
Sales Order: SO-2024-0847 →
  └─ Production Order: PO-2024-1923 →
      └─ Work Order: WO-2024-4521 (current)

Data Change Activity Section

Purpose: Displays audit trail information showing who created and last modified the record.

• Required fields: createdAt, createdByUser.email, updatedAt, updatedByUser.email
• Display format: Icon + "[Entity] [action] by [email] at [timestamp]"

Quick Actions Section

Purpose: Provides contextual actions relevant to the current record.

Standard Actions:

• View History
• Clone Record
• Export
• Print
• Delete (with confirmation)

Deployment-Specific Actions (examples):

• Start Production
• Release to Floor
• Request Inspection
• Generate Label
• Submit for Approval

Deployment-Specific Sections

The sidebar supports additional custom sections as required by specific deployments:

• Inventory Summary (for WMS records)
• Quality Metrics (for MES records)
• Maintenance Schedule (for Asset records)
• Cost Summary (for Work Order records)

Related Records Strategy

Relationship Direction Patterns

Upward (Parent Chain)

Display in Essential Details sidebar as read-only reference links. For relationships 3-4 levels deep, show the full lineage with clickable links at each level.

Downward (Child Records) - Level 1

Deep Drilling (Levels 2-4)

Use a slide-out drawer pattern:

1. Click child record row to open right-side drawer (400-600px width)
2. Drawer shows child form in condensed view
3. Drawer can stack (clicking grandchild opens another layer)
4. Breadcrumb at top shows depth: Work Order > Operation 10 > Material Issue
5. Maximum 3 drawer layers before forcing full navigation
6. "Open in New Tab" action available at any level

Relationship Explorer (Complex Entities)

For highly relational entities (BOMs, Routings, Process Flows), use a dedicated Relationship Explorer:

┌─────────────────────────────────────────────┐
│ 🔗 Relationships                        [↗] │
├─────────────────────────────────────────────┤
│  [Tree View] [List View]                    │
│                                             │
│  ▼ Operations (4)                           │
│     ├─ OP10: Cut ─┬─ Materials (3)          │
│     │             └─ Tools (1)              │
│     ├─ OP20: Weld                           │
│     └─ ...                                  │
│  ▶ Quality Checks (2)                       │
│  ▶ Documents (5)                            │
└─────────────────────────────────────────────┘

Data Model Considerations

Form Profiles by Data Model Type

Master Data (Equipment, Materials, Locations, Products)

• Primary Content: Classification, specifications, attributes
• Related Records: BOM components, alternate locations, substitutes
• Attachments: Drawings, specifications, certificates
• Custom Fields: Deployment-specific attributes
• Essential Details: Primary image prominently displayed

Transactional Data (Work Orders, Inventory Movements, Quality Records)

• Primary Content: Header info, quantities, dates, assignments
• Related Records: Operations, material issues, labor entries
• Notes: Shift notes, issue documentation
• Attachments: Photos, inspection results
• Essential Details: Full parent hierarchy chain

Setup/Configuration Data (Topics, Flows, Rules, Integrations)

• Primary Content: Configuration parameters
• Code Content: Schemas, expressions, queries
• Settings: Feature toggles, behavioral flags
• Essential Details: Application/namespace context

Card Visibility Rules

Design Tokens

Colors

Spacing

Typography

Naming Conventions

Element Names

Form Element Binding

Each card containing editable fields should have its own Form element:

• api: "Application"
• model: [DataModel name]
• dataPath: "edges[0]"
• autoLoad: true (for display), false (for save-only)
• blockNavigationWhenDirty: true

Verification

To confirm correct implementation of the Standard Form Design:

• Layout: Sidebar remains fixed at 280px; main content scrolls vertically only
• Save Button: Disabled when form is clean; enabled only when dirty + valid
• Card Visibility: Cards appear/hide based on data model capabilities
• Essential Details: Primary image displays; parent hierarchy links are clickable
• Related Records: Drill-down opens drawer; maximum 3 layers stack correctly
• Element Names: All custom.elementName values follow naming conventions

Troubleshooting

• Horizontal scroll appears on MainContentForm → Resolution: Check that overflow-x: hidden is set on the MainContentForm container
• Save button always disabled → Resolution: Verify form is bound correctly with blockNavigationWhenDirty: true and form dirty state is being tracked
• Cards not appearing → Resolution: Check visibility conditions match data model capabilities; ensure card container is not set to hidden: true
• Sidebar overflows → Resolution: Verify SidebarContainer has overflow: hidden and fixed width of 280px
• Related records drawer exceeds 3 layers → Resolution: Implement layer count check; force full navigation after layer 3
• Brand separator not showing gradient → Resolution: Check background-image: linear-gradient(90deg, #39005a, #5b30df, #03caaf) is applied