Widget Settings Conventions

Never hardcode a font stack without the CSS variable — that will not match the native Homey UI.

Available Homey CSS Variables

Canonical Shared Settings

Size

5-tier size system. Default value depends on the widget.

{
  "id": "size",
  "type": "dropdown",
  "label": { "en": "Size", "nl": "Grootte" },
  "value": "medium",
  "values": [
    { "id": "xsmall", "label": { "en": "Extra Small", "nl": "Extra Klein" } },
    { "id": "small", "label": { "en": "Small", "nl": "Klein" } },
    { "id": "medium", "label": { "en": "Medium", "nl": "Gemiddeld" } },
    { "id": "large", "label": { "en": "Large", "nl": "Groot" } },
    { "id": "xlarge", "label": { "en": "Extra Large", "nl": "Extra Groot" } }
  ]
}

Font Weight

Setting ID is fontWeight (NOT weight). Label is "Font Weight" / "Letterdikte".

{
  "id": "fontWeight",
  "type": "dropdown",
  "label": { "en": "Font Weight", "nl": "Letterdikte" },
  "value": "normal",
  "values": [
    { "id": "thin", "label": { "en": "Thin", "nl": "Dun" } },
    { "id": "normal", "label": { "en": "Normal", "nl": "Normaal" } },
    { "id": "bold", "label": { "en": "Bold", "nl": "Vetgedrukt" } }
  ]
}

CSS mapping in widget HTML:

const WEIGHT_MAP = { thin: '300', normal: 'normal', bold: 'bold' };

Horizontal Alignment

Setting ID is horizontalAlignment (NOT align). Label is "Horizontal Alignment" / "Horizontale Uitlijning".

{
  "id": "horizontalAlignment",
  "type": "dropdown",
  "label": { "en": "Horizontal Alignment", "nl": "Horizontale Uitlijning" },
  "value": "center",
  "values": [
    { "id": "left", "label": { "en": "Left", "nl": "Links" } },
    { "id": "center", "label": { "en": "Center", "nl": "Midden" } },
    { "id": "right", "label": { "en": "Right", "nl": "Rechts" } }
  ]
}

Color

6-option color dropdown. Uses hex values mapped in the widget HTML.

{
  "id": "color",
  "type": "dropdown",
  "label": { "en": "Color", "nl": "Kleur" },
  "value": "default",
  "values": [
    { "id": "default", "label": { "en": "Default", "nl": "Standaard" } },
    { "id": "blue", "label": { "en": "Blue", "nl": "Blauw" } },
    { "id": "green", "label": { "en": "Green", "nl": "Groen" } },
    { "id": "orange", "label": { "en": "Orange", "nl": "Oranje" } },
    { "id": "red", "label": { "en": "Red", "nl": "Rood" } },
    { "id": "purple", "label": { "en": "Purple", "nl": "Paars" } }
  ]
}

CSS mapping in widget HTML:

const COLOR_MAP = {
  default: '',  // Uses --homey-text-color CSS variable
  blue: '#3B82F6',
  green: '#22C55E',
  orange: '#F97316',
  red: '#EF4444',
  purple: '#A855F7',
};

Files That Must Stay in Sync

When a widget uses shared settings, these 3 files must all have identical setting definitions:

1. widgets/<name>/widget.compose.json — Source of truth for the widget
2. app.json — Generated/maintained app manifest (must match compose)
3. apps/sandbox/src/registry.json — Sandbox testing registry (must match compose)

Widgets Using These Conventions