UI Guidelines

These guidelines serve as a reference for developers of the digital blueprint app. They ensure that all components and layouts are designed consistently and provide a unified user experience. The covered topics can be found in the table of contents on the right

App Shell

The App Shell is the fundamental structure of a digital blueprint application that loads first before any content. It provides the consistent framework within which all activities are displayed, ensuring a unified user experience across the entire application.

The App Shell consists of three main components:

Header <header> - Contains the main navigation elements [Fig. 1]
Side Menu <aside> - Houses the activity navigation [Fig. 2]
Main Content Area <main> - Displays the current activity content [Fig.4] [Fig.6]

App Shell Behavior

Loading State

The App Shell loads first, providing immediate visual feedback to users while the activity content is being loaded.

Responsive Behavior

Full App Shell with maximum content width of 1400px, using standard layout by default
At the breakpoint of 768px (and below) the application automatically switches to wide layout (the layout switcher is no longer available)

Theme Support

The App Shell supports theming through CSS variables:

Light/Dark mode toggle in the main navigation affects the entire App Shell
Custom themes can be implemented by overriding the CSS variables -> See theming page.
All App Shell components use the same variables as the rest of the application for visual consistency

The main navigation [Fig. 1] <header> is centered and contains:

Light/Dark mode switch
Layout switch: Toggle between standard layout and wide layout
Language switch: EN & DE
Logged-in user

**Fig. 2: Listed activities in sidemenu**

The side menu <aside> contains various activities [Fig. 2] of an app:

Active activities are displayed in bold and highlighted with a red vertical line on the left side[Fig. 2]
In standard layout, the <aside> side menu switches to a dropdown menu[Fig. 3] at the top of the screen at breakpoint 768px
In wide layout, the <aside> menu with all activities is already at the top

Activities

An activity [Fig. 4][Fig. 5] follows the structure:

H2 title (An activity should be named using a verb, because this emphasizes it being a real activity, something the user can do.)
Subtitle with class="subheadline" - Short explanation of the activity (mandatory!)
Intro Text - Overview of the activity if needed (optional)
Activity Stuff

**Fig. 4: Basic activity GUI visualization**

**Fig. 5: Basic activity mobile GUI visualization**

UI Flow

The user interface always follows similar rules. We distinguish between Informational views and click-through flow.

Informational views

For informational views, all UI elements are weighted equally. The user decides for themselves what they want to do next. All buttons are then equivalent [Secondary Button]. The user is not guided through the activity/section. Example: Clipboardmanagement activity or see picture Fig. 14.

Click-through flow

In the click-through flow you want to guide the user through an activity/an element. The developer decides which steps are taken to "move forward". This is achieved by setting a "call-to-action" [Primary-Button] button [Fig. 15]. This button always marks the next step. How the button is set see Buttons.

Layout and Grid System

Layout Types

The dbp app supports two different layout types that users can switch between using the "layout switcher" icon Icon for switching layouts in the main navigation:

Standard Layout

Default layout for all apps [Fig.6]
The side menu <aside> is positioned on the left side of the screen
Main content area <main> occupies the remaining space – contains activities
Optimized for navigation-heavy workflows where frequent access to the menu is needed
At breakpoint 768px, the side menu <aside> moves to the top of the screen [Fig.7]

**Fig. 7: Standard layout mobile visualization**

Wide Layout

Alternative layout that provides more horizontal space for content
The side menu <aside> is positioned at the top of the screen by default
Main content area <main> spans the full width below the <aside> navigation [Fig.8]
Optimized for content-heavy workflows where maximum screen real estate is needed (E.g: Cabinet – filter options)
Maintains the same maximum content width (1400px) like the standard layout

Maximum Content Width

Maximum content width: 1400px. Regardless of standard layout or wide layout, a maximum width of 1400px must be set. This prevents texts or other elements from becoming too long to read or elements within the <main> column from being stretched too much.

Maximum width visualization for the standard layout — **Fig. 9: Wide layout desktop visualization**

Responsive Design & Breakpoint Structure

Main breakpoints

The apps should be developed so that adjustments are primarily made at the main breakpoints to ensure a consistent responsive design. Only in special exceptional cases can an additional breakpoint be used.

First main breakpoint: 768px (Tablet)

**Fig. 10: First main breakpoint at 768px**

Second main breakpoint: 490px (Smartphone and below)

**Fig. 11: Second main breakpoint at 490px**

Additional Breakpoints

If an activity design doesn't fit into the main breakpoint scheme, these additional breakpoints should be implemented as intermediate solutions. They serve exclusively as a supplement between the defined main breakpoints.

1100px for small laptops/screens
320px for the smallest smartphones [See Mobile XS]

Example for using Additional Breakpoints

The Cabinet app uses the space within the <main> column for its filter options. This leads to a reduction of space for the actual content and also to a cut on smaller screens, especially in the standard layout, as seen in the case of hit boxes. [Fig.12]

**Fig. 12: 1100px viewwith without additional breakpoint shows layout cuts**

The filter options are the main purpose of this app to filter and display student documents and need to be available as long as possible. Therefore, an additional breakpoint of 1100px makes sense in the Cabinet app to move the <aside> menu up earlier (bp 1100px) than the first main breakpoint (768px - where this happens anyway) and keep the filter options visible on the screen longer without cuts in the layout as one can see in [Fig.13].

**Fig. 13: 1100px viewwith as additional breakpoint shows no cuts in the layout**

Side note: In this case, making only the hit boxes responsive does not resolve the layout issue on smaller screens like 900px, 800px or even right before the first bp 768px. Therefore this additional breakpoint is nessesary.

Breakpoint overview

Desktop ≥1400px

Standard- & wide layout with maximum content width of 1400px [Fig. 9] [Fig.10]

Small Laptops and Tablet Landscape (1100px)

Only implement if additional layout adjustments are required between 1400px and 768px [Fig.13]

Tablet (768px)

First main breakpoint for switching to tablet mode [Fig. 10]
Designs should be simply shrinkable until the second main breakpoint
The <aside> column moves to the top so that the <main> column expands to its full width

Mobile (490px and smaller)

Smallest breakpoint for all mobile devices and below [Fig.11]
Consideration of the smallest device (iPhone SE with 320px viewport width)

Mobile XS (320px small viewport)

As one implement responsive design in apps, one has to check for this breakpoint as the h2 tends to be too large for this view. Maybe small adjustments are needed here.

We currently try to target "iPhone SE 1^st gen" as the lowest supported (CSS) resolution: 320 x 568

See https://www.ios-resolution.com, https://www.mydevice.io/#compare-devices and https://en.wikipedia.org/wiki/IPhone_SE_(1st_generation) for more information.

UI Elements

Buttons

One Button

If only one button is used, it is set aligned with the text in the current section. E.g.: If the text is left-aligned, the button is left-aligned too. If the text is centered, the button will be centered too. Exceptions to this are optically defined sections, such as a modal. Usually a single button is placed on the right. Further information about modals see modals.

Button Groups

Button groups can consist of buttons and text. If text elements are used in button groups, they must be treated in the same way as buttons.

If there are several buttons in the UI, they are distributed evenly over the entire width of the section. Buttons can also be combined into logical groups. (e.g. similar functions) These logical groups are then not distributed but combined in one element (div) and this element is then distributed evenly with the other buttons. [Fig. 14]

Primary Button

A primary button has the css classes button and is-primary. This button always denotes a "call-to-action" or "next-step" button, i.e. how to proceed in the UI.

If a primary button is used in a button group, it is placed on the far right. [Fig. 15]

Secondary Button

A secondary button has the css classes button and is-secondary. This button is used for all actions which are not required for the flow. [Fig. 15]

**Fig. 15: secondary and primary buttons**

Buttons in responsive webdesign

In mobile views, buttons can be combined and reduced to an additional options-menu. An additional-options menu is presented with a kebab menu[Fig. 16] (three vertical aligned dots) and a dropdown menu [Fig. 17]. We use the menu-dots icon from our icon set for the kebab menu. This is opened by clicking and the additional buttons are displayed there as entries in the dropdown list.

Buttons which contain text are expanded to the full width and have a min height of 40px. Buttons which contain icons have a width and height of 40px. For more information see Accessibility.

Fig. 16: Buttons hide behind an additional menu (kebab menu) on small devices

Fig. 17: Buttons are visible in dropdown menu on small devices

Tables

We distinguish between tables with fix content [Fig. 18] and datatables [Fig. 20].

Depending on the operation area you can decide between endless scroll or pagination. An example for endless scroll can be found in the Nextcloud file picker Webcomponents. An example for pagination can be found in Formalize.

If you have an endless scroll, you can also show up a select all button as it was done in the Nextcloud file picker Webcomponents.

If you have row action buttons you can distinguish between: selecting a row and connect these rows with a button, or you can create a call to actions column in the last column of the table. The row action buttons can be placed there. E.g.: Open the row in Detail, edit a row, delete a row...

The table footer only appears if you have pagination enabled. In this section, the pagination, the next/prev/last/first buttons and the actual page is shown. This footer appears sticky in the table on mobile devices.

We are using tabulator for building our tables.

Tables with fix content

Tables with fix contents [Fig. 18] are tables where we know the columns, where we can estimate the weight of these columns. Because we can estimate the weight, we can collapse some columns on mobile devices [Fig. 19] and the rest of the table can expand to full width. These columns can be collapsed or expanded on these devices. The collapse Icon is placed in the first column of the row.

**Fig. 18: Table with fix and selectable content**

**Fig. 19: Table with fix and selectable content on mobile devices**

Datatables

Tables with unknown Data or a high amount of data are datatables [Fig. 20] [Fig. 21]. We don't know the weight of each column, so we can't collapse any of them. We need a horizontal scroll and a short preview of a row. This is done with a "show in detail" button. This button takes place in the last column - the action column. The action column is frozen.

**Fig. 21: Datatable on mobile devices**

Modals

We distinguish between detail Modals [Fig. 22] and Modals with tabs [Fig. 23].

We are using a tiny lib for building these modals: micromodal.

A detail modal is used to view records as a whole or to get more details. The modal has a title in the left upper corner and a close sign in the right upper corner [Fig. 22]. The buttons are placed at the bottom of the modal dialogue.

An example for a detailed modal can be found in our application Formalize, where we used the detail modal to show a whole data entry row in a compact way.

If we have an additional Menu e.g. different locations for file-saving, then we can have tabs in the modal dialogue [Fig. 23]. These tabs are placed on the left side of the modal dialogue. On mobile devices these tabs are placed at the top of the screen.

We also have a modal title which indicates the context of this dialogue and a closing sign on the right upper corner.

An example for a modal with tabs can be found in the file handling webcomponents.

X and cancel buttons

Each modal has a closing button marked with an "X" in the upper right corner. This button closes the modal.

If the modal requires user interaction (e.g. overwrite file, save filter, ...) then there must be an additional "Cancel" button and a "Save"/"Apply"/"OK" button. The "Cancel" button interacts like the "X" button. It stops the active process and closes the modal. No changes are made. The "Save"/"Apply"/"OK" button saves the active changes and closes the modal.

If the modal is used for purely informative purposes (e.g.: preview, directory select, ...) the modal does not need a "Cancel" button. However, an informal "OK" button may be provided to ensure once again that the user has read the information.

States and Interaction Design

Hover state

A hover state is not specified for either links or buttons. The interaction itself is displayed as an interaction (buttons look like buttons, links are underlined...), and another state like hover is not required yet.

Within the cabinet app when users interact with the "clear filters" option a spinning icon rotates and the link itself becomes underlined. This provides visual feedback that the filter reset action is being processed and confirms the interactive nature of the element.

Active state

Active activities in the side menu are highlighted with bold text and marked with a vertical, CD-colored line --dbp-accent on the left side. See [Fig. 2]

Toggle switches are turned off by default with the --dbp-muted color. When activated, the color changes to --dbp-info.

Focus

Currently, no focus is defined. At the moment, it is the browser default focus, whose attention is not so strong due to the blue corporate design of the dbp. A more emphasized focus is recommended thought.

Disabled state

Elements in a disabled state are grayed out (color: dbp-secondary-surface; opacity: 0.4;) so they remain visually recognizable but are not interactive. This can apply to buttons or links that are temporarily inaccessible. For example, in Formalize, when not all fields have been filled out, the submission button remains in a disabled state. Only when all required information has been provided is the disabled state removed.

Loading state

The loading state is indicated by a spinning icon that shows a loading process is occurring, without indicating the loading time.

Feedback

Since there is no hover state, the only feedback state is that links function as expected and the interaction is completed - a new window opens or a modal is closed. The successful execution of the action itself serves as feedback to the user.

For toggle buttons, feedback is provided through color changes [See toggle switcher]: when toggled off, the button appears in color: --dbp-muted; when toggled on, it changes to --dbp-info green. Additionally, toggle buttons include a small animation of a slider moving from the "On" to "Off" position and vice versa, providing clear visual feedback about the state change.

Error Handling

All errors appear in the --dbp-danger color. An error is always displayed with a meaningful error message and it must be clear where the error occurs. The following example shows the app esign [Fig.24]

**Fig. 24: An highlighted error occurs in the App esign**

Animations

Toggle Switch Animation

When changing between On/Off states, the toggle button slides smoothly to indicate the state transition.

Modals open instantaneously as popup overlays without any transition.

In responsive design, side menus (such as the Cabinet filter-modal) slide from left to right into the window as an extra panel/submenu, particularly for filter options in the Cabinet app. After selecting filters there, users can close the model with the X icon, it slides back outside the viewport.

Loading Animation

The spinning icon that appears during loading processes is also considered an animation element, providing visual feedback during wait times.

Filter Interaction Animation

When users interact with the "Reset Filter Option" in Cabinet app by selecting "clear filters," a spinning icon rotates and the link itself becomes underlined.

Colors

DBP Apps have declared different CSS variables. You should avoid using hard coded colors or borders. Instead, use these CSS variables. You can find a brief description of the color system and the variables at the theming page.

CSS variables are accessed using the var() function. You can use all of these CSS variables without the 'override' in the code. E.g.: if you want to use --dbp-override-accent as a font color, you can use it in your code like

.any-selector {
  color: var(--dbp-accent);
}

The css variables with the override prefix are for integrators and explicit for the index.html. The css variables in the index.html overrides the internal variables without the prefix override. So multiple themes can be mapped to one variable and the css variables can internal used without the override prefix.

Further information about CSS variables in general can be found at developer.mozilla.org.

Accessibility Guidelines

Regarding design and structure, you must ensure WCAG 2.1 AA compliance for all DBP applications. The following accessibility requirements are mandatory for all UI implementations. For detailed guidelines, refer to the Accessibility guide:

Table of Content: