Foundations

Spacing and units

Kirigami has a handful of named distances. Use them instead of pixel numbers and your layout stays consistent with every other KDE app.

  • Kirigami.Units

Spacing is what tells people which things belong together. Kirigami provides named distances in Kirigami.Units, and the KDE guidelines say which one to use where. The values follow the user’s font and scaling settings, which is why you should use the names and not the numbers.

The spacing units

The bars are enlarged six times. Pixel values are those of a stock Plasma desktop with the default font.

Which unit goes where

Between… Use
A title and its subtitle 0
A title (with subtitle) and the content under it Kirigami.Units.smallSpacing
Controls in the same logical group Kirigami.Units.smallSpacing
Buttons and fields in a toolbar Kirigami.Units.mediumSpacing
One group of controls and the next Kirigami.Units.largeSpacing
The page edge and its content Kirigami.Units.largeSpacing
The page edge and a frameless list or grid that fills the page 0

The rule behind the table is simple: less space inside a group, more space between groups.

Two groups of checkboxes, each under a small heading. The checkboxes in a group sit close together and the gap between the two groups is clearly wider.Two groups of checkboxes, each under a small heading. The checkboxes in a group sit close together and the gap between the two groups is clearly wider.
Within each group items are smallSpacing apart; the groups are largeSpacing apart. No lines or boxes are needed to see two groups.
Show the QML for this example
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as QQC2
import org.kde.kirigami as Kirigami

// Related controls sit smallSpacing apart; groups sit largeSpacing apart.
ColumnLayout {
    spacing: Kirigami.Units.largeSpacing

    ColumnLayout {
        spacing: Kirigami.Units.smallSpacing

        Kirigami.Heading {
            text: "Notifications"
            level: 4
        }
        QQC2.CheckBox {
            text: "Show a popup"
            checked: true
        }
        QQC2.CheckBox {
            text: "Play a sound"
        }
    }

    ColumnLayout {
        spacing: Kirigami.Units.smallSpacing

        Kirigami.Heading {
            text: "Do Not Disturb"
            level: 4
        }
        QQC2.CheckBox {
            text: "While sharing the screen"
            checked: true
        }
        QQC2.CheckBox {
            text: "While an app is in full screen"
        }
    }
}

Sizes: gridUnit

For the size of things, use multiples of Kirigami.Units.gridUnit. One grid unit is about the height of a line of text, so sizes expressed in it grow when the user picks a larger font.

Kirigami.Card {
    // About 20 lines of text wide, whatever the font size is.
    Layout.maximumWidth: Kirigami.Units.gridUnit * 20
}

Use it for fixed widths and heights, and for default and minimum window sizes. Do not use it for gaps between things; that is what the spacing units are for.

Icon sizes

Icons also come in fixed steps, under Kirigami.Units.iconSizes. They are covered on the Icons page.

Durations

Animations use named durations too, so the whole desktop moves at one pace and respects the user’s animation speed setting. All values are in milliseconds.

Unit Stock value Typical use
Kirigami.Units.veryShortDuration 50 Tiny, instant-feeling changes.
Kirigami.Units.shortDuration 100 Hover and press feedback.
Kirigami.Units.longDuration 200 Things that move or appear: sheets, drawers, expanding sections.
Kirigami.Units.veryLongDuration 400 Large movements across the window.
Kirigami.Units.toolTipDelay 700 How long the pointer rests before a tooltip shows.
Kirigami.Units.humanMoment 2000 How long before a person notices they are waiting.
Behavior on opacity {
    NumberAnimation { duration: Kirigami.Units.longDuration }
}

Where this comes from

This page restates the upstream KDE documentation in plainer words and adds pictures. When the two disagree, upstream wins.