After our SUMMIT presentation on's AEM implementation, I had several people ask about how we approach dialog complexity. 

Below are a few rules we go by when building dialogs.

1. Differentiate labels, descriptions, and help paths

  • Label (fieldLabel) - Short & concise
  • Description (fieldDescription) - More context & information
  • Dialog Help (helpPath) - Dense and verbose, full documentation with screenshots and examples.

Each should have a different meaning and purpose. On, we optimize for the everyday use experience, not the first use experience. Sure, an author may need more instruction with a short label like, 'Border' during first-use, but once an author is trained on a feature, something more verbose like, 'Component Border Control' is redundant and un-necessary.


Label: Border

Description: Define the width, type, and color of the component's border.

Label: Enable Container

Description: Turn on a container to prevent the contents from expanding beyond a 1200px max width.

Personally, I also try to re-word concepts between label and description to prevent duplicating the same words. 'Enable Container' worded differently would be, 'Turn on a container'. This is to capture different ways authors may read and understand a particular field.

2. Remove complex and redundant words

The general idea is that most authors don't need overly complex labels and descriptions, this is the work they do every day. It's also important to remove redundant words. If you're in a table component, there's no sense in saying, 'Table Width'. The term, 'Table' is implied. 

Words we strictly prohibit that sound overly complex and typically do not bring value to labels:

  • Configuration - I.E. Border Configuration
  • Control - I.E. Background Control
  • Select - I.E. Select Type
  • Set - I.E. Set Type

These terms do not provide value. We're in a dialog; configuring, controlling, selecting, and setting things is the whole point we're there.

3. Add a little CSS

There's nothing saying you cannot add a clientlib to give Coral 3 a little help. There are several scenarios where having a top-to-bottom approach to all fields can have a negative impact on the authoring experience. 

Let's look at setting a custom width with OOTB Coral 3:

With a little CSS, we can clean things up and give better differentiation of the section:

Or how about a multifield:

Anyone who has worked with multifield knows it can get very complex very fast. Above, we have little differentiation of items and no easy way to identify each. With a little CSS, we can add an index and a separator:

4. Lean on mobile-first inheritance
Building mobile-first components is a no-brainer. However, providing tools inside the dialog to create an inheritance model can also reduce complexity. Below we have an example of how an author can set mobile / default colors, and inherit or override as needed.


5. Hide complexity until it's needed

On, we have two powerful components used for a lot of general purpose layout. Unfortunately, with power comes complexity. We do everything possible to remove complexity until it's needed. We have two primary ways we achieve this:
  1. Using cq-dialog-dropdown-showhide-target we can show / hide containers.
  2. Using granite:renderconditions we can completely remove fields. - See point 6.

Below we have an area to define borders:

However, there might be a scenario where a design calls for a border on an individual side.

We can expose that complexity using cq-dialog-dropdown-showhide-target :

6. Leverage Editable Templates and Render Conditions

Sometimes the best UI is no UI. Combining the power of render conditions with the power of editable templates (and content policies) can allow you to selectively render parts of a component during page creation.

Here's a quick video on how this can work:

7. Use Custom Icons

Custom icons are a great way to give a little extra polish and help show authors some love.

You can use a file (_cq_icon.svg or _cq_icon.png) in the component folder or you choose one of the many coral icons names in your component's XML definition.

I've created a sample of a _cq_icon.svg on github free to download.