Skip to main content

Protocol-Driven UX: The Foundation of Framework UI

Vision Statement​

Framework UI is not a static set of layouts or a fixed theme. It is an API-driven grammar for composing high-density applications. It provides the "primitives of interaction" that allow developers to build anything from an ERP to a chat platform while maintaining a Zero-Cliff transition from standard configuration to advanced custom development.

Core Principles​

1. Protocol-Separation (The Dual Port)​

To avoid the trap of "JS composition in the backend," we maintain a strict separation between the Context Port and the Fidelity Port:

  • Context Port (Python): Resolves the Logical Hierarchy. It answers: "Who is the user?", "What tenant are they in?", "What apps/nodes are they entitled to see?".
  • Fidelity Port (React): Resolves the Physical Rendering. It answers: "How is this section animated?", "What component renders a 'Report' node?", "How does the glassmorphism effect look?".

[!NOTE] The Backend returns Manifests (Data); the Frontend returns Components (UI).

2. Zero-Cliff Decomposition​

Every built-in UI primitive (Sidebar, Header, Landing) must be:

  • Extensible: Augmented via Metadata Decorators.
  • Overridable: Replaced by custom Adapters.
  • Decomposable: Broken down into smaller sub-components that can be reused in entirely custom MFEs (Micro-Frontends).

3. Composition over Branding​

Framework UI focuses on the "Bones"—the spatial organization and navigation ease. Branding (colors, bling, whitelabeling) is treated as a CSS-level skin. A developer should benefit from the framework's complex navigation logic (Rail & Drawer) even if they completely change the look and feel.

The Physical Model: "Rail & Drawer"​

For high-density platforms, we move away from flat sidebars to a two-layered model:

  • Primary Rail (The Switcher): Global app icons for context switching (e.g., WMS, Studio, Finance).
  • Contextual Drawer (The Tree): Hierarchical navigation specific to the active App.

This model is a framework invariant for navigation ease, but its rendering (e.g., becoming a bottom bar on mobile) is managed by the Fidelity Port.

The SaaS Control Plane (Entitlements)​

SaaS developers control the UI via the Entitlement Layer. This sits above RBAC/ABAC:

  1. Entitlement (Tenant): Does this organization pay for the 'Finance' feature?
  2. Permission (User): Does this individual have the 'Accountant' role?

If either is False, the node is pruned from the manifest at the Context Port level.

V1 UX Mandate: "Engagement Expectation"​

We are looking for UX designers to define the UI Grammar, not just the UI Styles. The engagement should result in:

  • Composition Rules: How nodes merge when multiple apps (e.g., Core + India Compliance) are installed.
  • Navigation Patterns: How a user flows from a 'Landing' page to a specific 'DocType' without feeling a "cliff" between different app styles.
  • Protocol Mappings: Defining the data structures required in the SidebarManifest to enable rich, conditional UI states.

[!IMPORTANT] The designers shouldn't just "design a sidebar." They should design the logic of a sidebar that can handle 100+ dynamic resources.