Noctalia Plugin Development

Core Design Rules (MUST follow)

1. Always import qs.Commons and use Style.* / Color.m* — never hardcode pixel values, colours, or font sizes. Using literals instead of tokens will break theme switching and per-monitor scaling.

2. Reuse qs.Widgets components — NIcon, NText, NButton, NIconButton, NScrollView, NTextInput, NComboBox, NPopupContextMenu. Only create custom components when no built-in widget fits.

3. Scale all explicit dimensions by Style.uiScaleRatio (panels) or use the per-screen helpers for bar widgets (see BarWidget section).

4. Use Color.m* tokens (Color.mPrimary, Color.mOnSurface, Color.mSurfaceVariant, Color.mHover, …) so the widget reacts to dark-mode and colour-scheme changes automatically.

5. Hover effects via binding, not imperative handlers:

   color: mouseArea.containsMouse ? Color.mHover : Style.capsuleColor
   

Reference Files — MUST read before writing code

This skill ships with detailed reference files alongside this SKILL.md. Before writing any QML or JSON for a plugin component, you MUST read the corresponding reference file in full. The cheat-sheets below are summaries only; the reference files contain complete property lists, required patterns, checklists, and edge-case guidance that are essential for correct output.

These files are located next to this SKILL.md in the references/ subdirectory. Read them with your file-reading tool before generating code — do not rely on the cheat-sheets below alone.

Style Tokens Cheat-Sheet (most commonly used)

// Spacing
Style.marginXS   Style.marginS    Style.marginM    Style.marginL    Style.marginXL

// Corner radius
Style.radiusS    Style.radiusM    Style.radiusL

// Bar capsule (use per-screen variants in BarWidget!)
Style.capsuleColor          // bar widget background
Style.capsuleBorderColor    // bar widget border
Style.capsuleBorderWidth    // typically 1

// Font sizes
Style.fontSizeXS  Style.fontSizeS  Style.fontSizeM  Style.fontSizeL
Style.fontSizeXL  Style.fontSizeXXL

// UI scale (multiply explicit panel dimensions by this)
Style.uiScaleRatio

// Helpers (per-monitor)
Style.getCapsuleHeightForScreen(screenName)
Style.getBarFontSizeForScreen(screenName)
Style.pixelAlignCenter(parentSize, childSize)

Color Tokens Cheat-Sheet

Color.mPrimary              // accent/brand colour
Color.mOnPrimary            // text on primary backgrounds
Color.mSurface              // main card/panel background
Color.mSurfaceVariant       // secondary container background
Color.mOnSurface            // primary text colour
Color.mOnSurfaceVariant     // secondary/dim text colour
Color.mHover                // hover overlay for interactive elements

Minimal BarWidget Template

import QtQuick
import QtQuick.Layouts
import Quickshell
import qs.Commons
import qs.Widgets

Item {
    id: root
    property var pluginApi: null
    property ShellScreen screen
    property string widgetId: ""
    property string section: ""

    readonly property string screenName:   screen?.name ?? ""
    readonly property real   capsuleHeight: Style.getCapsuleHeightForScreen(screenName)
    readonly property real   barFontSize:   Style.getBarFontSizeForScreen(screenName)
    readonly property real   contentWidth:  row.implicitWidth + Style.marginM * 2
    readonly property real   contentHeight: capsuleHeight

    implicitWidth:  contentWidth
    implicitHeight: contentHeight

    Rectangle {
        id: visualCapsule
        x: Style.pixelAlignCenter(parent.width,  width)
        y: Style.pixelAlignCenter(parent.height, height)
        width:  root.contentWidth
        height: root.contentHeight
        color:        mouseArea.containsMouse ? Color.mHover : Style.capsuleColor
        radius:       Style.radiusL
        border.color: Style.capsuleBorderColor
        border.width: Style.capsuleBorderWidth

        RowLayout {
            id: row
            anchors.centerIn: parent
            spacing: Style.marginS

            NIcon { icon: "plug"; color: Color.mPrimary }
            NText { text: "My Plugin"; color: Color.mOnSurface; pointSize: barFontSize }
        }
    }

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        hoverEnabled: true
        cursorShape:  Qt.PointingHandCursor
        onClicked: pluginApi?.openPanel(root.screen, root)
    }
}

Minimal Panel Template

import QtQuick
import QtQuick.Layouts
import qs.Commons
import qs.Widgets

Item {
    id: root
    property var pluginApi: null

    readonly property var  geometryPlaceholder: panelContainer
    readonly property bool allowAttach: true

    property real contentPreferredWidth:  500 * Style.uiScaleRatio
    property real contentPreferredHeight: 400 * Style.uiScaleRatio

    anchors.fill: parent

    Rectangle {
        id: panelContainer
        anchors.fill: parent
        color: "transparent"

        ColumnLayout {
            anchors { fill: parent; margins: Style.marginL }
            spacing: Style.marginL

            NText {
                text:       "My Plugin"
                pointSize:  Style.fontSizeL
                font.weight: Font.Bold
                color:      Color.mOnSurface
            }

            Rectangle {
                Layout.fillWidth:  true
                Layout.fillHeight: true
                color:  Color.mSurfaceVariant
                radius: Style.radiusL
                // panel body content here
            }
        }
    }
}

Common Services

// Toasts
import qs.Services.UI
ToastService.showNotice("Done!")
ToastService.showError("Something went wrong")

// Tooltips  (in MouseArea handlers)
onEntered: TooltipService.show(root, "Tooltip text", BarService.getTooltipDirection())
onExited:  TooltipService.hide()

// Context menus — always use PanelService, not plain popups
PanelService.showContextMenu(contextMenu, root, screen)
// in NPopupContextMenu.onTriggered:
contextMenu.close()
PanelService.closeContextMenu(screen)

// Logging
Logger.i("PluginId", "message", optionalValue)
Logger.d("PluginId", "debug",   optionalValue)
Logger.w("PluginId", "warn",    optionalValue)
Logger.e("PluginId", "error",   optionalValue)

Settings Access Pattern

// Read with fallback chain
readonly property string myValue:
    pluginApi?.pluginSettings?.myKey ||
    pluginApi?.manifest?.metadata?.defaultSettings?.myKey ||
    "fallback"

// Write and persist
pluginApi.pluginSettings.myKey = newValue
pluginApi.saveSettings()