5.1 Atlas UI Architecture & Design System

5.1 Atlas UI Architecture & Design System

Exam Focus: The Mendix Certified Intermediate Developer exam rigorously tests your understanding of Atlas UI as both a design framework and an engineering system. You must master the 12-column layout grid mechanics, understand how design properties map to compiled CSS classes, navigate the precise SCSS directory hierarchy inside theme/web and themesource/, apply brand styling using custom variables, and recognize why responsive utility classes cannot replace domain-level entity security.

Modern enterprise applications demand responsive, accessible, and visually coherent interfaces that perform predictably across phones, tablets, and desktop workstations. In the Mendix ecosystem, Atlas UI fulfills this requirement. Built on open web standards—including modern React component architectures, flexbox, CSS grid, and Sass (SCSS)—Atlas UI establishes a modular design system that separates structural page composition from decorative brand styling.

---

Core Principles of the Atlas UI Framework

Atlas UI is not merely a collection of CSS stylesheets; it is a unified design language that provides low-code developers with consistent UI patterns while giving front-end engineers full programmatic control over styling. The framework operates on four foundational pillars:

1. Component-Based Architecture: Every visual element in Mendix—from basic buttons to complex data grids—is encapsulated as a reusable, composable component. Components follow atomic design principles, assembling from atoms (buttons, inputs) into molecules (search bars, input groups) and organisms (cards, navigation sidebars).
2. Clean Separation of Concerns: Application domain logic, microflows, and data security reside strictly in the domain and logic layers. The UI layer focuses exclusively on presentation, data binding, and user interaction. Visual adjustments never alter data integrity or business rules.
3. Responsive by Default: Every layout and container adapts fluidly across device viewports using a responsive 12-column grid and standard CSS media queries.
4. Extensibility & Governance: Organizations can package custom corporate design systems as reusable marketplace modules (e.g., company design tokens, typography, and color schemes) that distribute across multiple project repositories without modifying core framework code.

---

The 12-Column Responsive Layout Grid System

The foundation of page layout in Atlas UI is the Layout Grid widget, which implements a flexible 12-column grid system derived from modern CSS flexbox standards. A layout grid consists of one or more rows, with each row subdivided into columns whose total width increments sum to 12.

+-----------------------------------------------------------------------------+
|                          Total Row Width = 12 Columns                       |
+-----------------------+-----------------------------+-----------------------+
|      col-md-4         |           col-md-4          |        col-md-4       |
|   (One-Third Width)   |      (One-Third Width)      |   (One-Third Width)   |
+-----------------------+-----------------------------+-----------------------+
|              col-md-8 (Two-Thirds)                  |   col-md-4 (One-Third)|
+-----------------------------------------------------+-----------------------+
|                            col-md-12 (Full Width)                           |
+-----------------------------------------------------------------------------+

Device Widths & Column Weights

The Mendix layout grid is built on the Bootstrap grid system and exposes three device widths on every column: Desktop width, Tablet width, and Phone width. You set an independent column weight for each one in the column properties, which is what makes a single page model render sensibly on all three.

Do not memorise pixel thresholds. The Mendix layout-grid reference does not publish fixed pixel values for these device widths — it defers to the underlying Bootstrap grid tiers. What the exam actually tests is the behaviour you control: the per-device column weight, the three width modes (auto-fill, which takes the available space; auto-fit content, which sizes the column to its content; and manual, where you set the weight yourself), and what happens when weights exceed 12.

Auto-Fit and Manual Weight Allocation

• Manual Weight Distribution: The developer specifies explicit column weights per row (e.g., 8 and 4). If the sum of column weights in a row exceeds 12, the excess columns automatically wrap onto a subsequent line.
• Auto-Fit: When columns are configured with equal or automatic weights, the layout grid divides the available 12 columns equally among all child columns within that row.
• Nested Grids: A column can host a nested layout grid. The nested grid establishes its own internal 12-column coordinate space regardless of the parent column's outer span.

Design Properties: Zero-Code Visual Styling

One of Atlas UI's most powerful productivity features is Design Properties. In standard web development, altering a button's visual prominence, card shadow, or element margin requires authoring raw CSS classes. In Mendix, design properties surface predefined CSS utility classes as visual dropdown menus, button groups, and toggle switches within the Properties pane of Studio Pro.

How Design Properties Operate

Design properties are declared within JSON configuration files named settings.json, located inside the themesource/<ModuleName>/web/ directory. When Studio Pro opens a project, it parses these manifests and binds the defined options to the matching widget types.

{
  "widgetName": "Button",
  "properties": [
    {
      "name": "Button style",
      "type": "Dropdown",
      "description": "Select the visual weight and color tone of the button.",
      "options": [
        { "name": "Default", "class": "btn-default" },
        { "name": "Primary", "class": "btn-primary" },
        { "name": "Success", "class": "btn-success" },
        { "name": "Warning", "class": "btn-warning" },
        { "name": "Danger", "class": "btn-danger" },
        { "name": "Inverse", "class": "btn-inverse" }
      ]
    },
    {
      "name": "Full width",
      "type": "Toggle",
      "description": "Render button as a full-width block element.",
      "class": "btn-block"
    }
  ]
}

When a developer selects Primary in Studio Pro, Mendix appends the btn-primary class to the rendered HTML element. If a toggle is enabled, the corresponding CSS class (e.g., btn-block) is attached to the widget's class list.

Standard Categories of Design Properties

• Color & Intent: Default, Primary, Success, Warning, Danger, Info, Inverse.
• Spacing & Layout: Margin top/bottom/left/right (none, small, medium, large); Padding (none, small, medium, large).
• Typography: Text alignment (left, center, right), text transform (uppercase, capitalize), font weights.
• Visual Elevation: Card styling, subtle shadows, bordered outlines, rounded corners.

---

CSS and SCSS Styling Hierarchy in Mendix

To achieve custom corporate branding or pixel-perfect styling, developers utilize Sass (SCSS). Understanding where to author styles—and how Mendix compiles them—is a primary topic on the Intermediate Developer exam.

The File System Directory Structure

Inside any Mendix application repository, styles are organized across two distinct directory trees:

[Project Root]
   ├── theme/
   │     └── web/
   │           ├── custom-variables.scss  <-- Global brand token overrides
   │           ├── main.scss              <-- Global custom styles & component rules
   │           └── settings.json          <-- Project-level design property definitions
   └── themesource/
         ├── atlas_core/                  <-- Core framework SCSS (Never edit directly!)
         │     └── web/
         │           ├── _variables.scss
         │           └── main.scss
         └── my_custom_module/
               └── web/
                     ├── custom-variables.scss
                     ├── main.scss
                     └── settings.json

The Sass Cascade & Priority Sequence

Mendix compiles SCSS into a single production stylesheet (deployment/web/styles/css/main.css) during application startup or deployment packaging. The compilation occurs in a strict cascading order:

1. Atlas Core Base Variables (themesource/atlas_core/web/_variables.scss): Establishes default framework values (e.g., $brand-primary: #0595db;, $font-size-base: 14px;).
2. Module Themesource Variables (themesource/<module>/web/): Marketplace or custom UI modules introduce their own variables.
3. Application Custom Variables (theme/web/custom-variables.scss): This is the authoritative override file. Any SCSS variable declared here overrides the upstream Atlas defaults because Sass variables configured with !default yield to prior declarations.
4. Atlas Core Component Styles: Compiles fundamental styling for buttons, grids, typography, and page headers.
5. Module Themesource Component Styles: Compiles module-specific component rules.
6. Application Custom Styles (theme/web/main.scss): The final stylesheet layer. Rules declared here have the highest specificity and can target custom classes or override specific widget layouts.

// ==========================================================================
// theme/web/custom-variables.scss - Corporate Brand Customization
// ==========================================================================

// 1. Brand Color Overrides
$brand-primary: #1e3a8a;       // Deep Corporate Navy
$brand-secondary: #0d9488;     // Teal Accent
$brand-success: #16a34a;
$brand-danger: #dc2626;
$brand-warning: #f59e0b;

// 2. Typography
$font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
$font-size-base: 15px;
$font-size-h1: 32px;

// 3. Layout Dimensions & Borders
$border-radius-base: 6px;
$grid-gutter-width: 24px;
$topbar-bg: $brand-primary;

---

Responsive Utility Classes vs. Data Security

Atlas UI includes utility helper classes that control component visibility based on the client viewport dimension:

The Critical Exam Trap: Visibility vs. Security

[!CAUTION] Exam Trap: Never use responsive utility classes (such as hidden-xs) or conditional visibility to hide sensitive, restricted, or privileged data!

Responsive helper classes operate purely on the client side via CSS rules (e.g., display: none !important;). While the element is visually absent from the screen, the underlying HTML DOM node, its text contents, and its bound object attributes remain fully present in the browser DOM and network responses. Any tech-savvy user can open browser developer tools (Inspect Element) and view the data.

To secure sensitive data across devices, you must enforce Entity Access Rules in the domain model. When entity access denies read permission, the Mendix runtime strips the attribute value before the payload ever departs the server.