Support compound (nested) design properties in MDL

[ako]

Summary

MDL designproperties: can only express flat design properties — a key with a single value (option/dropdown string, or toggle boolean). It cannot express a compound design property: one whose value is itself a set of sub-properties (e.g. Atlas's Spacing, which Studio Pro stores as compound:Spacing → {option:margin-top: 'L', option:margin-bottom: 'M', …}).

A compound property written in MDL is silently not emitted.

Scope (stack-wide, not backend-specific)

This isn't an MCP or file-backend bug — both are at parity. Adding support requires changes across the stack:

1. MDL grammar/AST — syntax for nesting, e.g. designproperties: ['Spacing': ['margin-top': 'L', 'margin-bottom': 'M']] (ast.DesignPropertyEntryV3 is currently a flat key-value).
2. SDK type — sdk/pages.DesignPropertyValue{Key, ValueType, Option} is flat; needs a compound/nested variant (ValueType currently ∈ toggle/option/custom).
3. File (MPR) backend — sdk/mpr/writer_widgets.go serializeDesignProperties emits only Forms$Toggle/Option/Custom/DesignPropertyValue; needs Forms$CompoundDesignPropertyValue (confirm the exact $Type + structure with an on-disk BSON capture of a Studio-Pro-set compound property).
4. MCP backend — mdl/backend/mcp designPropertiesMap needs to emit the compound: object form (the pg_write_page shape is already known: "compound:Spacing": {"option:margin-top": "L"}, captured in mdl/backend/mcp/testdata/pg-page-contact-newedit-designprops.json).

Workaround (today)

Set compound design properties in Studio Pro directly, or use style: (raw CSS) / class: (Atlas utility classes).

Priority

Low/medium — flat properties cover most cases; compound (grouped Spacing, per-device settings) is used in richer Atlas theming. No regression: this has never worked through either backend.

Notes

• Surfaced during the MCP page-design-property fix; the pg_read_page capture revealed the compound:/nested shape.
• Known-limitation documented in the theme-styling skill.

[github-actions]

Issue Triage

Summary:
The issue requests support for compound (nested) design properties in MDL so that values like Atlas Spacing can be expressed and emitted correctly.

Checklist for feature request

Required info	Present?	Details
Use case – why the feature is needed, what problem it solves	✅	Explains that flat design properties cannot express compound values (e.g., Atlas Spacing) and that they are silently ignored.
Proposed syntax or behavior (if applicable)	✅	Suggests MDL syntax like designproperties: ['Spacing': ['margin-top': 'L', 'margin-bottom': 'M']] and outlines needed changes in AST, SDK, MPR, and MCP backends.
Mendix version relevance (if version‑specific)	❌	No mention of which Mendix versions this affects or whether it is version‑specific.

Missing information
Could you please add the Mendix version relevance? For example, indicate whether this applies to all Mendix versions (e.g., 9.x and 10.x) or only to specific releases, and if any version‑specific behavior should be considered.

Thank you for the detailed request! Once we have the version info, we can move forward.

---

Automated triage via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Completeness Assessment

The issue provides sufficient detail for implementation. It clearly describes:

• The limitation (flat vs compound design properties)
• Stack-wide changes needed (grammar, AST, SDK, MPR/MCP backends)
• Specific file references (sdk/mpr/writer_widgets.go, mdl/backend/mcp/testdata/pg-page-contact-newedit-designprops.json)
• Workaround and priority context
• Notes about MCP page-design-property fix and Atlas theming

No additional questions are needed. The reporter has provided concrete examples of the desired BSON structure and existing test data.

Overlap Check

This cannot be done with existing syntax. Current MDL designproperties: only supports flat key-value pairs (e.g., ['Spacing top': 'Large', 'full width': on]). There is no way to express nested structures like Atlas's Spacing property. The workaround requires Studio Pro manual configuration or CSS alternatives, which don't provide the same structured, theme-aware properties.

Proposed MDL Syntax

The issue's proposed syntax designproperties: ['Spacing': ['margin-top': 'L', 'margin-bottom': 'M']] aligns with MDL design guidelines:

• ✅ Reads as English: Follows property assignment pattern (key: value)
• ✅ One way to do each thing: Extends existing design properties syntax without removing flat support
• ✅ Qualified names: Not applicable (design property keys are widget-specific)
• ✅ Property format: Uses ( key: value, ... ) with colon separators (consistent with widget properties)
• ✅ LLM-friendly: One example clearly shows nesting pattern
• ✅ Diff-friendly: Adding a nested property is a one-line diff
• ✅ No keyword overloading: Reuses existing colon/bracket syntax
• ✅ Deterministic: Nested lists can be sorted for consistent output

**

---

Automated guide via OpenRouter — workflow source

[ako]

Implemented on the mcp branch (commit 9d30640f3), scoped to the modelsdk + MCP backends.

MDL syntax — compound value is a nested list, mirroring the flat form:

designproperties: [
  'Column gap': 'Medium',
  'Spacing': ['margin-top': 'Large', 'margin-bottom': 'Medium']
]

Done (full pipeline): grammar (designPropertyEntryV3 → nested designPropertyListV3) → AST (DesignPropertyEntryV3.Nested) → visitor → SDK (pages.DesignPropertyValue.Compound, ValueType compound) → executor → backends:

• modelsdk: serializes via the codec to Forms$CompoundDesignPropertyValue (nested Properties = Forms$DesignPropertyValue wrappers). Note this also fixed flat properties, which the modelsdk backend was dropping entirely.
• MCP: emits the "compound:<Name>": {nested} pg_write_page shape captured from pg_read_page.

Tests: codec emits the flat+compound structure; MCP map nests compound; mxcli check parses the syntax; example in 12-styling-examples.mdl; theme-styling skill updated.

Remaining: the legacy sdk/mpr writer (serializeDesignProperties) is still flat-only — intentionally out of scope, as it's being phased out for the modelsdk engine. Leaving this issue open until that's resolved (or closed if the legacy writer is dropped first).

[ako]

Closing — compound (nested) design properties are now fully supported across the stack.

All five layers called out in the issue are implemented, and the DESCRIBE round-trip (the last gap) is now closed.

Implementation

Layer	Status	Where
MDL grammar/AST	✅ Nested list syntax designproperties: ['Spacing': ['margin-top': 'L', …]]; DesignPropertyEntryV3.Nested	MDLPage.g4, ast_page_v3.go, visitor_page_v3.go
SDK type	✅ DesignPropertyValue.ValueType = "compound" + Compound []DesignPropertyValue	sdk/pages/pages_widgets.go
File (MPR) backend	✅ Emits Forms$CompoundDesignPropertyValue (recursive Properties of Forms$DesignPropertyValue)	mdl/backend/modelsdk/widget_write.go
MCP backend	✅ Emits the compound: nested object form	mdl/backend/mcp/page_widgets.go
DESCRIBE read-back	✅ (now fixed) Both DESCRIBE PAGE and DESCRIBE STYLING parse and re-emit compound properties	cmd_pages_describe_parse.go, cmd_pages_describe_output.go, cmd_styling.go

The describe side previously dropped compound properties silently — the value was written to BSON correctly and shown in Studio Pro, but describe rendered only the flat siblings, so a describe → re-exec lost them. The parser now recurses into Forms$CompoundDesignPropertyValue.Properties, and a single shared formatter (joinDesignPropertyEntries) emits the nested list across both describe paths.

Verification (end-to-end round-trip)

written:   designproperties: ['Column gap': 'Medium', 'Spacing': ['margin-top': 'Large', 'margin-bottom': 'Medium']]
DESCRIBE PAGE:     DesignProperties: ['Column gap': 'Medium', 'Spacing': ['margin-top': 'Large', 'margin-bottom': 'Medium']]
DESCRIBE STYLING:  DesignProperties: ['Column gap': 'Medium', 'Spacing': ['margin-top': 'Large', 'margin-bottom': 'Medium']]

The describe output re-parses cleanly (mxcli check passes), confirming write → describe → re-exec is lossless.

Tests & examples

• Write-side: mdl/backend/modelsdk/design_property_test.go (asserts the Forms$CompoundDesignPropertyValue BSON), mdl/backend/mcp/page_pgshape_test.go
• Read-side: mdl/executor/cmd_pages_describe_designprops_test.go (parse + emit)
• Working example: mdl-examples/doctype-tests/12-styling-examples.mdl §"Compound (nested) design properties (Support compound (nested) design properties in MDL #668)"

Commits

• af15629ce — feat(pages): compound (nested) design properties — Support compound (nested) design properties in MDL #668 (modelsdk + MCP)
• c71d7f120 — fix(describe): emit compound design properties in DESCRIBE PAGE/STYLING (Issue 668)

Note: the legacy sdk/mpr engine (--engine legacy) does not emit compound design properties — only the default modelsdk engine and the MCP backend do. This is a known limitation of the legacy path, which is slated for removal.

Closing as completed.