Skip to content
AtlasOSFramework API
Browse the docs

Design rules

The rules every Atlas app follows, and which Atlas.Ui control or token carries each one.

Every Atlas app follows these rules. Atlas.Ui implements them, so an app that builds its pages from Atlas.Ui's controls gets them for free. The framework's tools/lint-app.sh fails an app on the default buttons and warns on the other default controls.

1. Pages built from Atlas controls

2. Window caption buttons come from the window

AtlasOS's window decoration draws minimise, maximise and close as rounded squares: tinted at rest, accent on hover, red for close. An app never draws its own caption buttons. An app that wants one merged header row puts an AtlasHeaderBar in its AtlasWindow's header; the window then draws the caption buttons itself (AtlasWindowButtons) in the same look and in the desktop's button order.

3. One blur switch for every app

The window is AtlasWindow. With "Transparency and blur" on and a compositor that blurs, its background is AtlasStyle.base, partly see-through over the blurred desktop. With it off, the window is opaque. The switch is Transparency under [Appearance] in ~/.config/atlasrc (default on), read and written through the Appearance singleton. A change in one app, or in the file, reaches every open Atlas app at once. AtlasTransparencySwitch is a ready-made settings row for it. See Style and theming.

4. The logo plus a check mark when up to date

A screen that reports "all is well" (no updates, nothing to fix) shows the OS logo in its own colours with a check badge on its corner, not a tinted circle. Use StatusHero with iconName set to the logo (LOGO= from os-release, then distributor-logo), iconIsMask: false, showTintCircle: false and cornerBadgeIcon: "checkmark". Atlas Updater's Updates page is the model.

5. The Atlas look, on the Plasma theme

Calm and precise, Light and Dark equally.

  • Violet is the accent (AtlasStyle.accent) for buttons and selection; magenta-violet (AtlasStyle.focus) is for focus rings. When the user has chosen an accent in Plasma, that accent wins, as in other KDE apps.
  • Fonts are IBM Plex Sans and JetBrains Mono for code (AtlasStyle.fontFamily and monoFamily), falling back to the system fonts. The application font's size stays the user's.
  • Corners are small (4, 6 and 8) and motion is quick and subtle (100, 150 and 250 ms).
  • Every colour comes from AtlasStyle or Kirigami.Theme, every size from Kirigami.Units or AtlasStyle's scale. No hard-coded colours, so light, dark and the user's accent all work.
  • The Qt Quick Controls style is org.kde.desktop.

6. Never the default buttons

No QQC2.Button, QQC2.ToolButton, QQC2.Switch or buttons made from Kirigami.Action in an app's own pages: use Atlas.Ui's buttons and switch. The same goes for the controls Atlas.Ui now has: text fields, combo boxes, check boxes, sliders, spin boxes, tooltips and busy indicators. If Atlas.Ui lacks a control, it is added to Atlas.Ui rather than worked around with the default one.

7. Everyone can use it

  • Every control has an accessible role and name, so screen readers can read it.
  • Every control that acts takes keyboard focus and shows AtlasFocusRing when the focus came from the keyboard. The exceptions are small chrome buttons that are reached another way (a shortcut, a menu or the key that clears a field): ToolbarButton, StatusBarItem, AtlasWindowButtons, a tab's close button and a search field's clear button.
  • Nothing animates while hidden, and nothing animates when Plasma's animation speed is "Instant" (the AtlasStyle durations are 0 then). See Motion.
  • Text a user reads is in qsTr().

See Accessibility for the details.

Icons

Icons are Material Symbols through Symbol and the symbol: property of buttons, sidebar items and menu items, or theme icons by name where a control takes iconName. See Symbols.

Only the selected item of a navigation control (a sidebar entry, tab bar or view switcher tab) turns solid with Symbol.filled. Everything else, selected or not, uses the outline. The selection tint of those controls is one rectangle that slides to the new item.

States

Every control behaves the same way in each state, and the framework's tests check the ones that can be measured.

State What it does
Disabled (enabled: false) Dimmed, takes no focus (Tab skips it), no hover or press reaction, no cursor change, reported as disabled to screen readers. A disabled parent disables its children.
Read only The value is shown normally (not dimmed) and cannot be edited. The control keeps focus, selection and copy.
Error The error colour (AtlasStyle.error) on the border or text, and a message beside the field. The message is announced to screen readers, not only coloured.
Busy A spinner replaces the value or chevron. The control stays enabled but does not act again until the work ends, and says it is busy to screen readers.
Hover A grey tint of the text colour (never the accent), only for a control that acts, never for a disabled or busy one. Buttons keep the arrow cursor; a clickable row or card, a link and a table header show a hand cursor.
Pressed A stronger tint than hover, gone on release or when the pointer leaves.
Focus AtlasFocusRing, only for keyboard focus, never after a click. Rows (SidebarItem, StepItem, a Section header, DataTable cells) draw a 2 px outline in the focus colour instead.

A control that holds other controls (a SectionRow with trailing items) shows its own ring only while it has focus itself, not while an item inside it does.