04a - A design methodology

Info: This article is work in progress and subject to change.

The Workflow Assistant Configurator gives you a lot of expressive power. A panel can hold dozens of fields, actions, notifications, conditions, and widgets, all reacting to the asset selection in real time. That power makes it tempting to build a panel by listing every metadata field your users ever asked for and dropping them all into one tab.

That kind of panel does not work.

A panel earns its place by being focused on the job. The fastest way to design one that works is to start from the user’s job, not the metadata schema; to map the workflow before placing a single component; and to use Notifications generously to keep the user oriented. This article is a short, opinionated set of principles that, in our experience, separate a panel that works from a panel that feels designed.

Treat each principle as a habit, not a rule. The order matters: each principle prevents a problem the next one builds on.

Start with the user’s job, not the field list

The biggest single mistake in panel design is starting from the Assets metadata schema and asking “which of these fields should we expose?” That question produces a flat list of every possible field and a panel that mirrors a database, not a workflow.

Start instead with the user’s job:

• Who is the panel for?
• What is the smallest piece of work they need to complete in one sitting?
• What information do they need to make a decision?
• What action do they need to take when they are done?

Answer those four questions and the panel almost designs itself. The fields are whatever the user needs to see to make their decision; the actions are whatever they need to do; the rest of the metadata schema does not belong on the panel.

Tip: A useful heuristic — if a field is only there because an admin or auditor might need it once a quarter, it does not belong on the panel. The panel is for the people who use it daily. Audit-style fields belong in Assets’ standard metadata view, not in the workflow tool.

Map the workflow before you place a single component

Open a blank document — paper works fine — before you open the Configurator. Sketch the user’s flow: where they start, what they read, what they decide, what they do, where they finish. Three or four bullet points are enough.

For the Image details panel in the Quick Start tutorial, the workflow is:

1. The user selects an image
2. They check the title and credit
3. If credit is missing, they fill it
4. They look for related images by the same credit

The four components on the panel — two fields, one action, one notification — fall straight out of those four steps. Skipping the sketch is what produces panels with eleven fields the user does not know what to do with.

Once the workflow is sketched, ask one more question: what is the user expected to do next? A panel without a clear next step leaves the user stranded. A panel that ends with a Mark approved button or a Move to next stage action ends a session cleanly.

Group by task, not by metadata schema

Sections are how you tell users which fields belong together. Their grouping should match the task, not the Assets metadata category.

A bad section: Custom fields. Users do not think in terms of “custom fields”; that is an admin concern.

A good section: Brief details. Or Approval or Production status or Find related assets. Each name describes a job, not a schema branch.

Two questions you can ask of every section you create:

• Could a user explain in one sentence what this section is for?
• Does the section contain everything the user needs for that one thing, and nothing more?

If both answers are yes, the section is doing its job.

Use Notifications generously

By far the most common design mistake — measured by support tickets — is not using Notifications enough. A panel without notifications is a panel that asks the user to deduce state from the absence of buttons and the presence of disabled overlays. That is a guessing game, not a workflow tool.

Notifications fix this. They tell the user, in a sentence you write, what is going on. Three places they earn their keep on every panel:

A panel rarely has too many Notifications; it almost always has too few. If you are choosing between adding a Notification and writing a paragraph in your support documentation, add the Notification.

Make guard rails visible

Lucene Disable conditions are powerful and quiet. The user clicks a button, nothing happens, and they have no idea why. The fix is always to pair the disable with a visible explanation:

• Always set a Disabled message when you set a Disable condition on a button. The disabled message appears as text under the button, telling the user why the button is greyed out
• For Fields, the equivalent is the Disabled overlay message — visible when the user hovers a non-editable field, explaining why
• Required-condition errors should always have a Required message — telling the user what to fill in to clear the requirement
• Pattern validation errors should always have a Pattern message — telling the user what shape the value should take

A guard rail is only useful if the user can see it. A silent disable is a bug, not a feature.

Write hints and messages as if the reader has never seen the panel

The hints, messages, descriptions, and notifications on a panel are the only documentation the user gets. Write them well.

The pattern is the same in every case: short, specific, and oriented to the user’s next move. “Why is this happening, and what should I do?” should be answerable from the message alone.

Tip: Read every message in your panel out loud, in the voice of a user encountering it for the first time. If your reading sounds dismissive, technical, or vague, rewrite it. The user has no other source of information.

Test with a colleague before you publish

A panel feels obvious to the person who built it. It is not obvious to anyone else.

Once your panel works in your own browser, send it to a colleague who has never used it. Do not explain it. Watch them try to complete one task with it. They will:

• Click in the wrong place
• Miss a Notification you thought was prominent
• Be surprised by a disable condition you thought was self-explanatory
• Type something the regex does not allow and not know why

Every one of those moments is a fix you should make before publishing. A ten-minute test catches more issues than an hour of self-review.

Iterate after release

A panel is never finished on day one. After it is in use, watch for two signals:

• Support tickets that look like panel-design errors — visibility wrong for a kind, condition firing in the wrong direction, missing required-field message — go straight back into the Configurator as fixes
• User confusion that does not show up in tickets but does show up in workshops, demos, or one-to-ones. A user who cannot find a button has not been blocked, but the panel has cost them time. Add a Notification, reorder a section, or rewrite a hint

Treat the panel as living configuration. Small, frequent changes — paired with rollback as a safety net — keep it aligned with how the work actually happens.

Where to go from here

• 04b — Patterns and anti-patterns — concrete examples of habits worth copying and habits worth breaking
• 05c — Notifications reference — the technical reference for the Notification component, with display-condition patterns
• 06b — Disabling components and writing disable conditions — practical guidance on guard rails
• 09 — Testing, publishing, and rollback — the operational lifecycle behind “iterate after release”

Revisions

• 8 May 2026: First publication of the manual