matlab/matlab-agentic-toolkit/matlab-build-app

MATLAB Build App

Determine the best architecture for a MATLAB application, produce an implementation plan grounded in internal references, and execute the build. For UIFigure apps, optionally serialize into an App Designer format.

When to Use This Skill

Use this skill when:

• User wants to build a MATLAB app, GUI, or interactive tool
• User asks "how should I build this app?" or "which approach should I use?"
• User describes an application — with or without specifying an implementation path
• User mentions: MATLAB app, GUI, uifigure, uihtml, interactive tool, dashboard, visualization app, App Designer, .mlapp, plain-text app
• User describes spatial layout needs: dashboard, control panel, sidebar, tabs, wizard, stepper, canvas, workspace
• User has already chosen a path (e.g., "build me a uihtml app") — handle directly

When Not to Use

• The request is purely about MATLAB computation with no UI component
• The user is asking about an existing app they want to modify → read references/editing-guide.md
• The user wants to convert between App Designer formats (e.g., .mlapp to plain-text or vice versa) → tell them to use File > Save As in App Designer. Do NOT attempt the conversion programmatically.

Critical Rules

• MUST ask discovery questions before recommending a path — unless the user already specified one
• MUST confirm the path choice with the user before producing the implementation plan
• MUST produce an implementation plan grounded in internal references before writing any code
• MUST write the plan to a file (<app-name>-plan.md) in the working directory
• NEVER recommend a path without understanding the user's constraints (unless path was pre-specified)
• NEVER apply dark mode, custom colors, or visual themes unless the user explicitly requests them
• ALWAYS present the recommendation as guidance, not a mandate — the user decides
• MUST choose archetype based on the user's primary task, not aesthetics
• NEVER treat two archetypes as equals within one app — one is always the primary container
• UIFigure app: MUST use uigridlayout for all structural layout — never Position-based sizing
• UIHTML/web app: MUST use CSS Grid or Flexbox for chrome — no absolute positioning for structural panels
• The chrome (header, sidebar, tabs, step indicator) MUST remain spatially stable
• Background execution (any operation taking more than ~1 second) requires a class-structured app and MUST be read up first in references/background-tasks.md — do NOT hand-write parfeval/backgroundPool/DataQueue plumbing from memory. For an App Designer app (.mlapp or plain text) you MUST use the addBackgroundTask verb and NEVER hand-roll the infrastructure or reuse the standalone-programmatic manual wiring. For a standalone programmatic app, use the MVVM structure per that doc. A flat nested-function app that needs background work MUST escalate to one of these.
• App Designer serialization: MUST read references/app-designer/agent-guide-shared.md (covers ownership models, editing discipline, property rules, quoting) plus the format-specific guide (agent-guide-mlapp.md or agent-guide-plaintext.md) before building. Those docs are the single source of truth; do not attempt to edit app files without reading them first.

Workflow

User request arrives
        │
        ├── Path NOT specified → Full Discovery
        │       │
        │       ▼
        │   Ask Q1-Q4 (purpose, lifespan, polish, team skills)
        │       │
        │       ▼
        │   Identify layout archetype
        │       │
        │       ▼
        │   Recommend UIFigure vs UIHTML based on Q1-Q4
        │       │
        │       ▼
        │   *** STOP: Present recommendation and WAIT for user confirmation ***
        │   (Do NOT produce a plan or read references until user says yes)
        │       │
        │       ▼
        │   Ask Q5 (FINAL): Serialization format? (UIFigure apps only)
        │       │
        │       ├── App Designer → release check, present format choice,
        │       │       continue with UIFigure references + add serialization step
        │       │
        │       └── Standalone programmatic → no extra step
        │       │
        │       ▼
        │   Produce Implementation Plan → write to <app-name>-plan.md
        │       │
        │       ▼
        │   User reviews plan → confirms or adjusts
        │       │
        │       ▼
        │   Begin building (read references per the plan)
        │
        └── Path IS specified
                │
                ├── Serialization explicit (e.g., ".mlapp app", "plain-text app")
                │       → Skip Q5, proceed with stated format
                │       → Ask only missing requirements + archetype if unclear
                │       → Produce Implementation Plan
                │
                ├── Architecture explicit but serialization not stated
                │   (e.g., "build me a uifigure app")
                │       → Still ask Q5 (serialization) before planning
                │       → Ask missing requirements + archetype if unclear
                │       → Produce Implementation Plan
                │
                └── UIHTML or standalone programmatic explicit
                        → Skip Q5 entirely (not applicable)
                        → Ask missing requirements + archetype if unclear
                        → Produce Implementation Plan

Discovery Questions

Ask these conversationally — not as a rigid checklist. Gather requirements and layout intent first; ask the serialization question last, once you understand what the app needs to do.

Core Questions

1. What does the app do and who is it for?

What will this app do? Who will use it?

Listen for archetype signals: "dashboard", "control panel", "step-by-step", "workspace".

2. Is this a quick tool or something you'll maintain over time?

Is this meant to be maintained and evolved, or is it more of a quick, proof-of-concept tool?

• Maintained → proceed to remaining questions; team skills matter
• Ephemeral → favor UIHTML app path; can skip team question

3. How polished does the UI need to look?

Are standard MATLAB buttons, sliders, tables, and plots enough? Or do you need custom visuals — branded, animated, or visually richer?

• Standard controls sufficient → UIFigure app signal
• Custom visuals needed → UIHTML app signal

4. Who will work on this app going forward?

Will this be maintained by people comfortable only with MATLAB, or by people also comfortable with web technologies?

Only ask for maintained apps.

• MATLAB-only team → UIFigure app
• Web-comfortable team → UIHTML app

5. (FINAL) How should this app be saved?

Do you want this app to open and edit inside App Designer, or do you prefer a standalone programmatic file (no App Designer dependency)?

This is a serialization question, not an architecture question. The app's structure (components, layout, callbacks) is designed using UIFigure knowledge regardless of the answer. Q5 only determines how that design is persisted to disk.

• App Designer → .mlapp or plain-text .m + .xml. Check release (plain-text needs R2026b+). If Q3 indicated custom visuals, note that App Designer constrains visual customization vs UIHTML and confirm.
• Standalone programmatic → programmatic .m code, no App Designer dependency. MVVM may warrant multiple files; that is decided at build time.

Follow-up Probes (only if path isn't clear)

• Interaction style: Real-time feedback needed? → slight UIFigure lean
• Existing work: Existing MATLAB UI code? → UIFigure. Existing web assets? → UIHTML
• Distribution: May need to work outside MATLAB? → UIHTML
• Long computations: Will any operation take more than a second? → use a background task (read references/background-tasks.md). Note this requires a class-structured app: App Designer serialization, or MVVM if standalone programmatic. Heavy, long, or one-shot work is ALWAYS a background task, never a timer; a timer fits only scheduled, cheap-per-tick work that must update the UI on the main thread (read references/timers.md).

Path Decision Logic

Two stages: first determine architecture (Q1-Q4), then determine serialization format (Q5).

Stage A — Architecture (from Q1-Q4):
 
Ephemeral app? → Strong default to UIHTML app
 
Maintained app? → Weigh signals:
 
Strong UIFigure signals:
  ✓ Maintained + MATLAB-only team
  ✓ Standard UI components sufficient
  ✓ Tight real-time interaction
  ✓ Existing MATLAB UI code
 
Strong UIHTML signals:
  ✓ Ephemeral (regardless of team)
  ✓ Maintained + web-skilled team
  ✓ Custom visuals, branded look, animations
  ✓ Existing web assets
  ✓ Future portability outside MATLAB
 
UIFigure + uihtml accent:
  Mostly standard app but needs one custom visualization panel.
 
Stage B — Serialization format (Q5, UIFigure apps only):
 
Q5 = Standalone → programmatic code (no App Designer). Done.
 
Q5 = App Designer → adds a serialization layer ON TOP of Stage A.
  UIFigure references still apply in full. Serialization is IN ADDITION TO,
  not instead of, the normal UIFigure build.
  → Check release, present format choice (plain text vs .mlapp).
  → If Stage A indicated UIHTML for custom visuals, surface the trade-off:
    App Designer constrains custom visuals — confirm before committing.

Weighting: 1. Architecture (Q1-Q4) 2. Serialization (Q5, applies only to UIFigure)

Paths at a Glance

For UIFigure apps, three serialization formats:

Layout Archetype

Pick based on the user's primary task:

If unclear, ask: "Will users mostly be watching results (Dashboard), tweaking controls (Explorer), switching sections (Tabbed), going through steps (Wizard), or working on a central figure (Canvas)?"

Implementation Plan

After confirming path and archetype, produce a plan and write it to <app-name>-plan.md in the working directory. Present a concise summary inline with the approval request.

Plan Template

**Implementation Plan: [App Name]**
 
**Architecture:** [UIFigure app / UIHTML app / UIFigure + accent]
**Serialization:** [Programmatic .m / App Designer .mlapp / App Designer plain text]
**Layout:** [Archetype] — [one sentence describing spatial structure]
 
**Structure:**
- [Major panel/area — spatial description]
- [e.g., "Left sidebar (220px) with date range picker, category filter, refresh button"]
- [e.g., "Main area with line chart showing filtered results"]
 
**Key behaviors:**
- [User-visible interaction effects]
 
**Internal references that will be used:**
 
| Reference | Role in this app |
|-----------|-----------------|
| `references/path/file.md` | [what it provides] |
| ... | ... |
 
**External skills:**
- `matlab-build-chart` — [role, if applicable]
- `matlab-apply-theme` — [role, if applicable]
 
**File organization:**
[app directory tree]