<!-- skill-index: generated by scripts/skill-index.py; make check-skill-index -->

Find it fast

sed -n '<from>,<to>p' SKILL.md one section rather than reading the file; ./mxcli syntax <topic> answers how do I write this for a fraction of either.

lines	section
31-48	When to Use This Skill
49-97	The Pipeline at a Glance
98-122	Where the Theme Lives (read this first — it avoids the main friction)
123-213	① Build the Theme — mxcli theme create --from
214-281	② Rebuild Components — Atlas block/class first, custom class only for identity
282-389	Component → Mendix widget map
390-486	The App Shell: Navigation & Layout (built once, not per page)
487-573	③ Apply Classes in Pages (MDL)
574-587	④ Build & Preview
588-595	⑤ Verify Against the Prototype
596-632	Never put a grid on a Mendix widget's own class
633-653	Gotchas (learned building this app)
654-705	MDL gotchas that block a faithful build
706-724	Checklist

<!-- /skill-index -->

Migrate a Claude Design Prototype into a Mendix App (Theme + Pages)

When to Use This Skill

Use this skill when you are given a Claude Design prototype / design handoff (an HTML/CSS prototype, a *.dc.html design-console export, a tokens file, a PRD, and/or screenshots) and need to reproduce that look in a Mendix app using mxcli + MDL.

It covers the two halves of the job:

1. Build the SCSS theme — turn the prototype's design language (colours, fonts, spacing, component styles) into a Mendix theme in theme/web/main.scss.
2. Apply it in pages — attach the theme's classes to widgets with MDL (Class: / DynamicClasses: on create page / alter page).

Related skills: atlas-design (read first — the Atlas-first taste + workflow layer), theme-styling (SCSS compilation chain, hot-reload, styling caveats), create-page (widget syntax), alter-page (in-place widget edits), bulk-widget-updates (apply a class across many widgets).

---

The Pipeline at a Glance

Claude Design handoff                         Mendix app
─────────────────────                         ──────────────────────────────
*.dc.html / prototype  ──①  theme    ──►  mxcli theme create --from <file>
tokens / CSS / PRD          create        → a theme the project owns
                                                    │
component styles       ──②  rebuild  ──►  Atlas block / utility class, and only
(cards, chips, …)           as classes      then .ss-* classes in main.scss
                                                    │
screenshots            ──③  reference ──►  widgets get Class: / DynamicClasses:
(per screen)                per screen          via create page / alter page
                                                    │
                            ──④  build   ──►  docker build → docker reload --css
                                                    │
                            ──⑤  verify  ──►  compare running screen to screenshot

Golden rule: the prototype is the source of truth. Before building or polishing any screen, open the matching screenshot/handoff for that screen and match it — colours, spacing, font, component shapes. Do not invent styling the prototype doesn't show.

Atlas-first (read atlas-design). Reproduce the prototype with what Atlas already gives you before hand-writing custom SCSS. In order of preference:

1. An Atlas building block — use building block Atlas_Web_Content.Card / Pageheader / List_Cards etc. gives you the whole component's markup + styling for free. Discover with list building blocks, inspect with describe building block.
2. Atlas utility classes and typed design properties — class:'card', class:'btn btn-primary', spacing-inner-*/spacing-outer-* for padding/margin, flex-row/flex-column + align-x-*/align-y-* for layout (no layoutgrid needed); or the typed equivalents designproperties: ('Card style': on), ['Background color': 'Brand Primary'], ['Spacing': ['margin-bottom': 'L']]. mxcli check -p validates design-property keys and values (MDL-WIDGET11/12) and lists the allowed values.
3. Brand-token retune — build the palette with mxcli theme create --from (step ①). The theme maps ~60 Atlas variables onto it, so the whole app inherits the look; hand-mapping a handful of --brand-* leaves most of Atlas on stock blue.
4. Custom .ss-* SCSS — for brand identity only. Reach for a hand-rolled component class (below) only when Atlas genuinely can't express the shape (bespoke chrome, fractional-track grids, pixel-exact rows). Hand-rolling .panel/.stat/.card SCSS that just re-implements what class:'card' already does is the single most common mistake — see atlas-design.

The rest of this skill (custom SCSS components, .ss-* classes, ListView row reshaping) is layer 4 — the identity layer you drop to when the first three don't reach the design.

---

Where the Theme Lives (read this first — it avoids the main friction)

• Custom styles go in theme/web/main.scss AFTER the @imports, or in your own partial. Styles placed after the imports win the cascade over Atlas defaults. Once main.scss grows, prefer splitting a partial out for readability: create theme/web/_<name>.scss and add @import "<name>"; after the Atlas imports (the same cascade-order rule then applies within the partial). New partials are creatable — keep the import order (custom after Atlas) and everything works.
• Use a project prefix for every custom class so it never collides with Atlas or widget CSS — .ss-panel, .ss-chip. Pick one and use it everywhere. Do not invent a parallel set of --ss-* colour variables: the theme's --mxt-* palette is already the app's vocabulary, and a second one silently stops following a theme or variant swap.
• theme/web/custom-variables.scss holds the palette, and mxcli theme apply writes it — it is a generated, digest-fenced block. Retune tokens there for a one-value tweak; for a real brand, own the theme (mxcli theme create, step ①) rather than editing inside the fence, which the next apply refuses.
• theme/mxcli-themes/<name>/ is where a theme the project owns lives. Committed, and not compiled — mxbuild's entry point is theme/web/main.scss and it does not glob theme/, so the sources sit inert until theme apply copies them into theme/web/.
• Do not hand-edit theme-cache/web/ — that is the compiled build artifact.

---

① Build the Theme — mxcli theme create --from

Do not hand-write a token block. A theme's palette is nothing but --mxt-* custom properties, and mxcli builds one from a design artifact directly:

mxcli theme create acme -p app.mpr --from design/canvas.dc.html
mxcli theme apply acme -p app.mpr

--from reads --mxt-* declarations out of any CSS-shaped text — a stylesheet, an SCSS partial, or the <style> blocks of an HTML export — wherever they appear:

:root { --mxt-brand: #2b5170; --mxt-ground: #eef1f4; --mxt-ink: #1a2129; }
@media (prefers-color-scheme: dark) { :root { --mxt-ground: #16161a; } }

Declarations inside a dark block (prefers-color-scheme: dark, .theme-dark, [data-theme="dark"]) seed the dark palette; everything else seeds the light one. Tokens the design does not name keep the base theme's value, so a five-colour handoff still yields a complete, working palette.

Three reasons this beats writing the tokens yourself, and each is a mistake this skill used to teach:

1. The Atlas mapping is already done, and it is ~60 variables, not eight. Hand-mapping --brand-primary, --topbar-bg and a handful of others leaves most of Atlas — form controls, tables, modals, the pluggable widgets — on stock Mendix blue.
2. Fonts are vendored, not @imported from a CDN. A @import url("https://fonts.googleapis.com/…") in main.scss is an @import-ordering trap, a third-party request on every page load, and it fails outright in an air-gapped deployment. The theme ships the .woff2 files under theme/web/mxcli-fonts/.
3. Light and dark come for free. A hand-written :root block is one palette; every mxcli theme carries both and follows the OS before first paint.

What to extract from the handoff

Ask the design step to emit a --mxt-* block if you can — then this is a parse, not a judgement call. Otherwise read the values off the prototype and write them into a small tokens.css to pass to --from. Run mxcli theme show signal for the full vocabulary; the ones that carry the look:

From the handoff	Token
brand / primary, its hover, text on a brand fill	--mxt-brand, --mxt-brand-hover, --mxt-brand-ink
app background, cards/panels, striped rows, hover, selected	--mxt-ground, --mxt-surface, --mxt-surface-alt, --mxt-surface-hover, --mxt-surface-selected
body text, muted text, faint text, hairlines	--mxt-ink, --mxt-ink-muted, --mxt-ink-faint, --mxt-line
sidebar / topbar chrome and its text	--mxt-rail, --mxt-rail-line, --mxt-rail-ink, --mxt-rail-ink-active
ok / warning / danger / info	--mxt-success, --mxt-warning, --mxt-danger, --mxt-info
status chip fills and their text	--mxt-tint-ok / --mxt-tone-ok (and -warn, -risk, -info, -neutral)
body font, headings, mono, base size, line height	--mxt-font, --mxt-font-heading, --mxt-font-mono, --mxt-font-size, --mxt-line-height
corner radius, row/control height, elevation, focus ring	--mxt-radius, --mxt-radius-lg, --mxt-row-height, --mxt-control-height, --mxt-shadow, --mxt-focus-halo

A --mxt-* name the base theme does not declare is refused, not written. Nothing reads it, so the theme would apply cleanly and render unchanged — which is indistinguishable from the design never having been applied. If a handoff value has no token, it belongs in the theme's own skin (below), not in the palette.

Two constraints worth knowing before you start

• The navigation rail stays dark in both palettes. Several Atlas topbar widgets paint their own text assuming a dark rail, at a specificity a simple override cannot beat. If the prototype has a light sidebar, expect to fight it — see theme-styling.
• Never pin an Atlas variable to a literal colour. Map it to a token so the dark variant restates ~30 values instead of ~60. A hardcoded --font-color-default is invisible the moment the ground goes dark.

Fonts the theme does not ship

The built-in themes vendor IBM Plex, Source Sans/Serif, JetBrains Mono and Space Grotesk. For a different family, drop the .woff2 files into theme/mxcli-themes/<name>/files/theme/web/mxcli-fonts/, add an @font-face loop to that theme's partial beside the existing ones, and point --mxt-font at it. Vendored, for the reasons above — not a CDN @import.

If the design needs more than the palette

Genuinely bespoke chrome goes in the theme's own skin mixin (@mixin mxcli-<name>-skin in theme/mxcli-themes/<name>/files/theme/web/_mxcli-<name>.scss), where it is scoped with the theme and survives theme apply. Reach for .ss-* classes in main.scss only for per-screen identity that is not part of the design language — and read atlas-design first, because most of what looks bespoke is an Atlas building block or utility class.

---

② Rebuild Components — Atlas block/class first, custom class only for identity

For each repeated element in the prototype (panel, stat tile, chip, card, table row, progress bar…), first check whether Atlas already provides it (Atlas-first, above): is there a building block (list building blocks) or an Atlas class / design property (card, btn-*, spacing-*, flex-*+align-*, ['Card style': on]) that gets you most of the way? If so, use it and add a thin .ss-* class only for the brand delta (colour, radius, font). Re-implementing card/panel/btn from scratch is the mistake atlas-design exists to prevent.

When Atlas can't express the shape, write one reusable class driven by the theme's tokens. Never a literal colour: a literal survives a light/dark flip and a theme swap, and is wrong under every palette but the one you wrote it against. Keep classes small and composable so a widget can stack several (Class: 'ss-panel ss-grid-lv').

Check the theme first — .pill and .stat below already ship as recipe classes (mxcli theme show <name>), so a chip and a KPI tile usually need no CSS at all.

// Surface panel — every value resolves through the palette
.ss-panel {
  background: var(--mxt-surface);
  border: 1px solid var(--mxt-line);
  border-radius: var(--mxt-radius);
  box-shadow: var(--mxt-shadow);
}

// Status chip — one base + colour modifiers. The theme's own `pill` /
// `pill-ok` / `pill-warn` / `pill-risk` do this already; write your own only
// if the design's shape genuinely differs.
.ss-chip {
  display: inline-block; border-radius: 11px; padding: 2px 10px;
  font-family: var(--mxt-font-mono); font-size: 11px; font-weight: 600;
  border: 1px solid transparent;
  white-space: nowrap;              // status chips must never wrap to 2 lines
}
.ss-chip--ok     { background: var(--mxt-tint-ok);   color: var(--mxt-tone-ok); }
.ss-chip--danger { background: var(--mxt-tint-risk); color: var(--mxt-tone-risk); }

Base + modifier convention. Give each component a base class and add --variant modifiers for state/colour (.ss-chip + .ss-chip--danger, .ss-heat--ok/--warn/--over). Widgets then combine base + modifier: Class: 'ss-chip ss-chip--danger'.

Reshaping Mendix chrome. To make Atlas widgets read like the prototype you often need to override Mendix's own DOM classes. Common targets:

• Sidebar / topbar shell: .region-topbar, .mx-header, .region-sidebar, .mx-scrollcontainer-left, and nav items under .mx-navigationtree.

• ListView rows are the workhorse for grids/tables — neutralise Atlas's default row chrome (padding/border/background) so rows read as your design's grid lines:

  .ss-grid-lv > ul > li,
  .ss-grid-lv .mx-listview-item {
    padding: 12px 16px !important;
    margin: 0 !important;
    border-bottom: 1px solid var(--mxt-line);
  }
  

• ::before / ::after on .mx-navigationtree can inject brand blocks / section labels the design shows but the Mendix nav model doesn't produce.

Use !important sparingly but expect to need it when overriding Atlas widget CSS.

---

Component → Mendix widget map

The lookup that removes the guesswork: for each component in the prototype, pick the widget here first, then style it with your --<prefix> classes. Validated across the BAE Resource Scheduling and Expense Approval designs.

Design component	Mendix widget	Notes
Page / screen canvas	container	one per page, e.g. Class: 'ea-page'
Card / panel / section	Atlas Card building block, or container class:'card' / ['Card style': on]	drop to a custom panel class only for brand delta
KPI / stat tile	container	label + value + delta as child dynamictext
Row/column layout (even columns, gaps)	container with flex-row/flex-column + align-* (or ['Flex container': …])	no layoutgrid needed for simple flex layouts
Multi-column / dashboard layout	layoutgrid + row + column	for exact fractional tracks (2.4fr 1.2fr …) use a container styled display:grid instead — see Layout techniques
Heading / title	dynamictext (RenderMode H1/H2)
Body / label / caption / table cell	dynamictext	the workhorse — text is inline, see techniques
Metric / big number	dynamictext	mono class
Chip / badge / tag / status pill	dynamictext	base class + colour modifier; leading dot via CSS ::before
Data table / grid / row list	listview (database source; row = layoutgrid or grid container)	preferred for bespoke row layouts — full control of the row markup; the datagrid pluggable widget exists but is heavier to style to a custom design
Table header row	static header band (container/layoutgrid) above the listview
Tabs / segmented / filter-chip row	tabcontainer styled as pills (one tabpage per XPath-filtered view)	for static/decorative chips use dynamictext
Master list + detail pane	listview (Selection) + dataview (DataSource: SELECTION)
Detail / read view	dataview
Create / edit form	dataview + inputs + footer	Save/Cancel in the footer
Text input / multiline	textbox / textarea
Dropdown / enum select	combobox	bound to an enum or association
Date field	datepicker
Boolean / toggle	checkbox
Button (primary/secondary)	actionbutton	ButtonStyle or a class
Link / text button	linkbutton
Search box	listview built-in search bar	hoist/restyle via CSS
Avatar / initials	dynamictext	styled as a circle
Image / logo / thumbnail	image / dynamicimage / staticimage
Icon / colour dot	CSS ::before on a class
Chart (line/bar/column/pie/area/bubble)	chart pluggable widget (Mendix Charts / ChartJS)	via PLUGGABLEWIDGET '<id>' — see Pluggable widgets below; needs a datasource + series config
Donut / gauge	ProgressCircle pluggable widget	via PLUGGABLEWIDGET '<id>'; static or attribute-driven — worked example below
Progress bar / meter	progressbar widget, or a container (track + fill)	a styled track+fill container needs no widget package
Sparkline / bespoke SVG	HTMLElement pluggable widget, or a container with a CSS SVG background	embed the design's inline SVG directly

Layout techniques

• Exact fractional columns. Atlas's layoutgrid is a 12-column system and can't express ratios like 2.4fr 1.2fr 1fr 1.4fr 0.6fr. For pixel-faithful tables/dashboards, style a plain container as display:grid; grid-template-columns: … in its class and put the cell widgets as its direct children — each widget becomes a grid item.
• dynamictext is inline by default. For stacked text (a title over a subtitle) set display:block in the class, or the lines run together.

Pluggable widgets (charts, donut, HTML/SVG)

Pluggable widgets do round-trip through MDL — but not by bare name. A bare progresscircle / CUSTOMWIDGET is rejected by the builder ("unsupported widget type"). The working form uses the widget's full package id as a quoted string:

PLUGGABLEWIDGET '<widget.package.id>' widgetName ( prop: value, … ) { childslots }

One-time registration. The widget package must be present in the project's widgets/ before you can reference its id:

mxcli widget init    -p baedemo.mpr                 # scaffold pluggable-widget support (run once)
mxcli widget extract -p baedemo.mpr --mpk widgets/ProgressCircle.mpk   # register a package
mxcli widget list    -p baedemo.mpr                 # list available widget ids + their props

mxcli widget list prints each widget's id and property names — copy the id verbatim into the PLUGGABLEWIDGET '…' string, and use the property names it reports as the widget's props.

Worked example — the status donut (Expense Dashboard). A ProgressCircle in static mode, with a text label overlaid via a sibling container (the widget draws only the ring):

container donutWrap (Class: 'ea-donut') {
  PLUGGABLEWIDGET 'com.mendix.widget.custom.progresscircle.ProgressCircle' donut (
    type: 'static', staticCurrentValue: 67, staticMinValue: 0, staticMaxValue: 100, showLabel: false
  ) { }
  container donutLabel (Class: 'ea-donut-label') {
    dynamictext donutPct (Content: '67%', Class: 'ea-donut-pct')
  }
}

This passed mx check with 0 errors, survived docker build, and renders its SVG arc at runtime (verified on the dashboard).

Real Mendix Charts (BarChart/LineChart/PieChart/HeatMap/…) are fully authorable too — each series/line binds its own OQL-view datasource + X/Y attributes; Pie/HeatMap bind at the widget level (ValueAttribute:, Pie needs SeriesName:). See Custom & Pluggable Widgets → Charts for the chart-type → id table, per-chart required-property gotchas (TimeSeries needs a datetime X, Bubble needs a size attribute), and the CE0463 → mxcli fix widgets step (it normalizes the stored widgets and preserves MPRv2 storage — never run bare mx update-widgets on a mxcli new project; it deletes mprcontents/). mdl-examples/doctype-tests/34-chart-widget-examples.mdl is the full showcase.

Pluggable-widget gotchas:

• Reach for built-ins first. listview, dynamictext, container, gallery, combobox need no registration. Drop to a pluggable widget only when the design genuinely needs one (charts, gauges, embedded SVG, maps, sliders). Many "charts" in a handoff are just static SVG — a container with a CSS background SVG (KPI sparklines, area trends here) is lighter than a real chart widget and needs no datasource.
• Reserved keywords can't be widget names — activity, legend, etc. are rejected by the parser; rename (actCard, legendCol).
• Empty slot is { }. Always close the child-slot braces, even when empty.

---

The App Shell: Navigation & Layout (built once, not per page)

Most Claude Design prototypes render a persistent sidebar + topbar on every screen — a brand block, a menu, sometimes a footer tag. It is tempting to rebuild that chrome inside each page. Don't. In Mendix the shell is not a page — it comes from two shared places:

• The layout (Atlas_Core.Atlas_Default in this project) provides the topbar + left sidebar regions. Every page sets Layout: Atlas_Core.Atlas_Default, so they all inherit the same shell; the page's own widgets render only in the content region.
• The navigation profile supplies the menu items. One Responsive profile drives the whole app — home page, login page, and the flat/nested menu. Menu items point at pages, not at widgets you place.

So the prototype's sidebar maps to navigation config + layout styling, configured once, and its menu grows by adding navigation items — never by editing pages.

Add a screen to the menu

mxcli -p baedemo.mpr -c "LIST NAVIGATION"              # profiles, home page, item count
mxcli -p baedemo.mpr -c "LIST NAVIGATION MENU Responsive"   # the menu tree

Add or reorder items with CREATE OR MODIFY NAVIGATION <Profile> { … } (the { } block replaces the whole menu, so dump the current profile first with DESCRIBE NAVIGATION <Profile>, edit, re-apply; omitted clauses such as the home page keep their stored value). See manage-navigation for the item syntax, home/login pages, and role-based homes.

Style the shell to match the design

The menu items and regions are standard Atlas DOM, so the prototype's look is reproduced with CSS in main.scss (step ②) — you do not model the sidebar's chrome as widgets:

• Recolour the regions via the mapped Atlas vars (--sidebar-bg, --topbar-bg, --navigation-bg) or by overriding .region-sidebar / .region-topbar / .mx-header directly.
• Restyle menu entries under .mx-navigationtree (idle / hover / active states, spacing, the active-item accent bar).
• Inject chrome the nav model can't express — a brand logo block, a WORKSPACE section label, an ITERATION 1 · DEMO footer tag — with ::before / ::after on .mx-navigationtree (or the sidebar region). The Mendix navigation model has no field for these, so CSS pseudo-elements are the right tool; keep their text in the SCSS with the rest of the theme.

Rule of thumb: if a design element is the same on every screen, it belongs to the shell (navigation + layout + CSS), not to a page. Only the content region is built per-page in ③.

Restructuring the shell to match the prototype (full-height sidebar, fixed topbar)

Recolouring is rarely enough — most prototypes put a full-height sidebar (brand block at the very top) with the topbar only over the content, whereas Atlas_Default renders the topbar full-width above a sidebar+content row. Reproduce the prototype layout with CSS, no custom layout document needed:

• Full-height sidebar: pin it out of the flex flow and offset the rest.

  .mx-scrollcontainer-left.region-sidebar { position: fixed; top: 0; left: 0; height: 100vh; z-index: 100; }
  .region-topbar, .mx-scrollcontainer-top,
  .region-content, .mx-scrollcontainer-center { margin-left: 256px !important; }  /* = sidebar width */
  

• Force region sizes with flex-basis, not width/height. Atlas sizes the topbar and sidebar as flex items, so plain width/height is ignored — use flex: 0 0 256px !important (sidebar) and flex: 0 0 62px !important (topbar).
• Hide the collapse toggle when the design has no collapse: .toggle-btn { display: none !important; }.
• The sidebar's inner scroll area (.mx-scrollcontainer-wrapper) should be flex: 1 1 auto so a ::after footer tag pins to the bottom.

Pixel-exact multi-part chrome via inline-SVG backgrounds

A ::before/::after pseudo-element is a single box with one text style — it cannot render a brand block (logo square + title + differently-styled subtitle) or a user chip (avatar circle + two text lines) faithfully. For those, render the whole element as an inline-SVG background image, which gives you exact sub-shapes, fonts, and colours:

.region-sidebar::before {
  content: ''; height: 80px; border-bottom: 1px solid rgba(255,255,255,.07);
  background: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='256' height='80'>\
<defs><linearGradient id='g' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='%233a6fd6'/>\
<stop offset='1' stop-color='%231d3f86'/></linearGradient></defs>\
<rect x='22' y='21' width='38' height='38' rx='10' fill='url(%23g)'/>\
<text x='41' y='45' fill='%23fff' font-family='Public Sans' font-size='15' font-weight='800' text-anchor='middle'>EA</text>\
<text x='72' y='37' fill='%23fff' font-family='Public Sans' font-size='15' font-weight='700'>Expense Approval</text>\
<text x='72' y='55' fill='%237d8ba4' font-family='IBM Plex Mono' font-size='11'>Finance workflow</text></svg>") no-repeat;
}

Encode # as %23 in the data URI. Use the same trick for the topbar's decorative search field (a ::before box with a magnifier-icon SVG background) and the user chip (::after). Simpler single-style chrome — the WORKSPACE label, the PROTOTYPE · DEMO footer, per-item nav dots (.mx-navigationtree a::before { content:''; width:9px; height:9px; border-radius:3px; background: … }, coloured per item by its .mx-name-* anchor class) — stay as plain pseudo-elements.

Decorative-only: an injected search box / avatar / "New" button is not interactive (it's CSS). The prototype's are usually mockups too; if the design needs a working search or profile menu, that's a real widget in a custom layout (Studio Pro), not CSS on the Atlas shell.

---

③ Apply Classes in Pages (MDL)

Every Mendix widget takes a Class: (static) and DynamicClasses: (expression) property. This is how the theme reaches the page. Prefer native Mendix widgets styled with your classes — container, listview, dataview, dynamictext, tabcontainer — over custom widgets, which are far harder to drive from MDL.

Static classes — the primary mechanism

Space-join base + modifiers in a single Class: string:

mdl 1;
create or modify page ResourceScheduling.ResourceHeatmap (
  Title: 'Resource Heatmap', Layout: Atlas_Core.Atlas_Default
) {
  container heatmapPage (Class: 'ss-page') {
    dynamictext heatmapTitle (Content: 'Resource Heatmap', RenderMode: H1, Class: 'ss-page-title')

    listview loadLV (
      DataSource: database from ResourceScheduling.Resource where LoadSeries != empty,
      Class: 'ss-panel ss-heat-lv'
    ) {
      container heatRow (Class: 'ss-heat-row') {
        dynamictext hc01 (Content: '{1}', ContentParams: ({1} = M01), Class: 'ss-heat-cell')
      }
    }
  }
};

State-driven styling — DynamicClasses: expression

For colour/state that depends on data (over-capacity cell, conflict card, load bucket), use a DynamicClasses: expression returning a space-separated class string. It stacks on top of Class:.

container heatCell (
  Class: 'ss-heat-cell',
  DynamicClasses: if $currentObject/M01 >= 100 then 'ss-heat--over'
                   else if $currentObject/M01 >= 80 then 'ss-heat--warn'
                   else 'ss-heat--ok'
)

(Written as-is: plain single quotes inside, no outer quotes around the expression.)

Computed dimensions — the bucket-class idiom

A widget has no computed inline style: Style: is a static string and DynamicClasses: returns class names, not CSS values. So anything with a data-driven dimension — a progress bar width, a bar-chart height, a meter fill — can't be Style: 'width: {expr}%'. The idiom is to quantise the value into a bucket and generate one class per bucket:

1. In a microflow, publish an integer bucket attribute (e.g. 0..20): $obj/PctBucket = round($obj/Done / $obj/Total * 20).
2. Generate the classes once with an SCSS @for loop:

@for $i from 0 through 20 { .ss-pb-#{$i} { width: $i * 5%; } }

3. Select the class from the bucket: DynamicClasses: 'ss-pb-' + toString($currentObject/PctBucket).

Trade-off worth noting: this adds one bucket attribute per animated dimension to the domain model. Pick a bucket count that matches the visual precision you need (20 → 5% steps is usually plenty).

Adding classes to an existing page

Use alter page to attach a class without rewriting the page (see alter-page):

mdl 1;
alter page ResourceScheduling.Approvals {
  set (Class: 'ss-appr-card ss-appr-card--conflict') on queueCard;
};

To apply the same class across many widgets/pages at once, see bulk-widget-updates (update widgets ... dry run first).

---

④ Build & Preview

SCSS is not live — you must compile before the theme shows. See theme-styling.

mxcli docker build -p baedemo.mpr      # compiles SCSS into the deployment package (~55s)
mxcli docker reload -p baedemo.mpr --css   # pushes compiled CSS to browsers (instant)

• --css only pushes already-compiled CSS — always docker build first after editing SCSS.
• For widget-property changes (a new Class: on a page), use a normal docker reload.

---

⑤ Verify Against the Prototype

Put the running screen next to the handoff screenshot and reconcile the diff — spacing, colours, font, component shapes. The project already has Playwright wired in (test-app) for screenshotting the running app. Iterate ②–④ per screen until it matches.

---

Never put a grid on a Mendix widget's own class

A layout that should be two columns comes out as one, and the CSS is right — it is on the wrong element. Mendix wraps a repeating widget's children in an intermediate element, so display: grid on the widget's own class has exactly one grid item and every card stacks:

div.mx-listview.my-cards   [689x2054] display=grid    <- the class you wrote
  ul.                      [334x2038] display=block   <- ONE child
    li.mx-name-index-0     [334x526]                  <- the things you meant to lay out

A data view does the same with .mx-dataview-content. One project hit this twice in two different widgets before naming the rule (mxcli-owid, findings #15 and #41).

Put the grid on the element that actually holds the repeated children:

/* list view */
.my-cards > ul                { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }
.my-cards > ul > li           { min-width: 0; }

/* data view */
.my-page > .mx-dataview-content { display: grid; grid-template-columns: 240px 1fr; }

min-width: 0 on the child matters: a grid item defaults to min-width: auto, so a wide table or a long unbroken string inside a card pushes the column past its track instead of scrolling within it.

How to find the right element rather than guess: run the app, inspect the widget, and walk down from the class you wrote until you reach the element with one child per row. mxcli run --local --screenshot plus the browser inspector settles it in one pass — see .claude/skills/verify-in-runtime.md.

Gotchas (learned building this app)

• Never put Style: (inline style) on a DYNAMICTEXT — it crashes MxBuild with a NullReferenceException. Class: on a DYNAMICTEXT is fine; for inline style, wrap it in a styled container instead. (Same applies to alter styling/alter page set style.)
• Prefer Class: + a real CSS class over inline Style:. It keeps the design system in one place and dodges the DYNAMICTEXT crash.
• DynamicClasses: for state, not duplicate widgets. One widget + an expression beats cloning a widget per state.
• Status chips: white-space: nowrap so labels like "Fully allocated" never wrap.
• ListView rows carry Atlas padding/border/background — neutralise them in your .ss-*-lv class or rows won't read as the design's grid.
• For bespoke tables, prefer a styled listview over the datagrid pluggable widget — you control the full row markup, which a pixel-faithful design usually needs.
• Prefer typed designproperties: / Atlas classes over custom SCSS for anything Atlas covers (spacing, alignment, card/background, flex layout) — see atlas-design. Keys and values are case-sensitive; mxcli check -p validates them (MDL-WIDGET11/12) and lists the allowed values. theme-styling has the compilation/reload mechanics.
• alter styling can't find widgets in MDL-builder-created pages — apply classes via Class:/DynamicClasses: in create page / alter page instead.

MDL gotchas that block a faithful build

Distilled from a full prototype build. Some are covered in depth by the linked skills — this is the fast index so a design migration doesn't rediscover them.

• A real docker build is the only trustworthy check. mxcli check --references passes MDL that mxbuild rejects. Build after every slice before you screenshot.
• Quote to escape keywords in bindings; the unquoted form is cleaner in expressions. Quote identifiers in create entity, attribute: bindings, and create/change targets when they collide with an MDL keyword. Inside expressions — microflow if/decisions, contentparams, visible, dynamicclasses, and inline-bracket XPath where — mxcli now strips stray identifier quotes, so a quoted attribute no longer breaks the build or makes an XPath where silently return 0 rows; still prefer the unquoted form there for readability. See write-microflows.
• Show a related (to-one) object's attributes — two ways, both persist now:
  • A nested "data from context" DataView for a full read view of the referenced object; its children bind to the related entity:

    dataview dvEmp (datasource: $currentObject/Module.Entity_Related) {
      dynamictext n (content: 'By {1}', contentparams: ({1} = Name))   -- own attr of the related entity
    }
    

  • An association path for a single inline value: contentparams: ({1} = Entity_Related/Name) in a dynamictext, or attribute: Entity_Related/Name on a DataGrid2 column — both persist as an AttributeRef over the association (use a bare association name; a module-qualified one is rejected on a column).
• Status chips = one dynamictext + a DynamicClasses: expression mapping the enum/value to a colour modifier (ea-chip--ok/--warn/--danger). Base .ea-chip + modifiers; white-space: nowrap.
• Charts: ProgressCircle / ProgressBar build and work (donut, meters). Mendix Charts (Charts.mpk: column/bar/line/area/pie) now author via MDL — each series (an object-list item inside the chart) binds a datasource plus X/Y attributes: series s1 (staticDataSource: database from Module.View, staticXAttribute: "X", staticYAttribute: "Y") (a per-series OQL view works too). mxcli fix widgets clears the widget-version-drift CE0463 (it normalizes the stored widgets and preserves MPRv2 storage — do not run bare mx update-widgets, which deletes mprcontents/). Still lighter when the design allows: a CSS-background SVG container (or HTMLElement) for sparklines/trends — no datasource — and ProgressCircle (type: expression, expressionCurrentValue: '$currentObject/Rate', min '0' / max '100', labelType: percentage) for a single-value gauge.
• Dashboard aggregates → OQL view entities (write-oql-queries). A grouped enum column in the view must be typed enumeration(Module.Enum), not string, or you get CE6770. Test with mxcli oql first.
• Seed demo data via an after-startup microflow guarded to run once (skip if data exists); it must return true. Direct-SQL seeding doesn't apply to the default HSQLDB. See demo-data.
• New entities / view entities need a runtime restart (docker up --detach --wait) to register — a hot reload won't see them. Hot reload also occasionally crashes the runtime; if the app stops responding, docker up --detach --wait recovers it with data intact.
• mxcli behaviour shifts between versions — the chart-build and a few persistence quirks are version-dependent. If a documented property silently vanishes on write, check mxcli version and confirm with describe page.

---

Checklist

• Read the handoff/screenshot for the screen before building or polishing it
• Palette built with mxcli theme create --from <design-file>, not hand-written — the Atlas mapping is ~60 variables and the theme already does it
• Every handoff value that has a --mxt-* token uses it; anything left over went into the theme's skin mixin, not the palette
• mxcli theme apply <name> -p app.mpr run, and the theme verified in a browser (light and dark)
• Fonts vendored under theme/web/mxcli-fonts/ — no @import url("https://fonts.googleapis.com/…") anywhere
• Components are base classes + --variant modifiers, all using the project prefix
• Persistent sidebar/topbar built as navigation profile + layout + CSS, not per-page widgets; new screens added via CREATE OR REPLACE NAVIGATION
• Shell restructured to the design (full-height sidebar via position:fixed + margin-left offset; region sizes forced with flex-basis; collapse toggle hidden if unused)
• Multi-part chrome (brand block, user chip) rendered as inline-SVG backgrounds; single-style chrome (labels, dots, footer) as plain ::before/::after
• Related (to-one) object attributes shown via a nested "data from context" DataView (full read view) or an association path (contentparams: ({1} = Assoc/Attr) / column attribute: Assoc/Attr) for a single inline value — both persist
• A real docker build run after each slice (not just mxcli check) before screenshotting
• Widgets styled with Class:; data-driven state via DynamicClasses:
• No inline Style: on any DYNAMICTEXT
• Grids/tables built as styled listviews, not custom Datagrid widgets
• Charts/gauges use PLUGGABLEWIDGET '<id>' … with the package registered via mxcli widget extract; static SVG (sparklines) done as CSS-background containers
• docker build then docker reload --css after SCSS edits
• Running screen verified against the prototype screenshot