RFC-33: Modernized macro styling while editing in Confluence Cloud

[DavidMichelson]

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Summary of Project:

We are considering modernizing the visual & interaction design of the frame surrounding Confluence Cloud macros when viewed in the new editing experience (NOT the legacy editor - learn more about the distinction here), i.e.:

• The gray border with a file icon, macro name, and macro parameters (if applicable)
• Visual behavior on hover
• Visual behavior on selection

This will have no impact on the content within macros. This will impact all kinds of macros when viewed in the editing experience:

• Macros built by vendors or customers using Connect
• Macros built by vendors or customers using Forge
• Macros built by Atlassian

No changes are being made to macros when viewed in the rendered experience.

No updates / work will be required on your end as a result of these changes.

Current state

Viewing macros in the editor: macros have a gray border, file icon and name displayed. This styling is not visible when the page is published.

Future state

GIF of future state experience. No macro name or border by default, users can see a thin gray border and the macro name in a tooltip on hover, and a thin blue border is used on selection.

• Publish: 1 Feb 2024
• Discuss: 14 Feb 2024
• Resolve: 6 Mar 2024

Problem

The current visual & interaction design of the frame surrounding Confluence macros when viewed in the editor is outdated:

• The gray border with a file icon, macro name, and macro parameters (if applicable)
• Visual behavior on hover
• Visual behavior on selection (e.g. the file icon, macro name, and gray border)

Macros typically have a gray box around them in the Editor, with a generic page icon. This hurts the Confluence creator user experience in a few ways:

• Disconnect between the edit and render experience (not What You See Is What You Get, or WYSWIYG) means users can’t predict what content will look like until they publish their page, adding extra time and effort.
• Generic, meaningless macro icon creates visual noise.
• Gray box surrounding each macro in the editor, doesn’t match the way editing looks and feels for other content people put inside Confluence pages, including editor elements and smart link embeds. It feels heavy and adds visual noise, and does not feel interactive.
• Macro name is displayed by default in the Editor - users cannot hide this. For some macros, the name is very technical and does not add to user understanding. For other macros, the user may want to add a custom title, or toggle the title display, but this is not possible today.

By solving these issues, we can make macros (built both by Atlassian & vendors) more approachable and easily adoptable by Confluence users.

Proposed Solution

We are proposing the following visual & interaction design updates to the frame surrounding Confluence macros when viewed in the editing experience to solve the above issues & modernize macros. These changes will apply to all macros when viewed in the editing experience:

• Macros built by vendors or customers using Connect
• Macros built by vendors or customers using Forge
• Macros built by Atlassian

No changes are being made to macros when viewed in the rendered experience.

No updates / work will be required on your end as a result of these changes.

Scenario 1:

• User sees macros inside their page, as they edit.
• Updated experience: Macros do not display a border, icon, name, or macro parameters until a user interacts with the macro (see later scenarios)

Scenario 2:

• User hovers on a macro
• Updated experience: The name of the macro appears in a tooltip, and a thin gray border surrounds the macro. If a macro contains parameters, these will not be shown on hover. Users must open the macro editor to see and change any parameters.
• Example: excerpt macros have the parameter of excerpt name. Using this new design, the name of the excerpt will not be displayed on the macro itself - users must open the macro editor to see and change the excerpt name.

Hover: macro name appears, but not any parameters.

Select: User can select the macro and select the edit button in the floating toolbar, to open the configuration panel and edit parameters (example: excerpt name is a parameter.)

Scenario 3:

• User clicks on a macro
• Updated experience: A thin blue border appears, along with the floating toolbar.

Scenario 4:

• If the user selects the entire body of the macro (for example, to copy it)
• Updated experience: The macro content will have a light blue background in addition to the thin blue border.

Asks

While we would appreciate any reactions you have to this RFC (even if it’s simply giving it a supportive “Agree, no serious flaws”), we’re especially interested in learning more about:

• Do you have any feedback on the proposed changes we are making to modernize the frame of Confluence macros?
• Are there other ways this may impact, that we haven’t anticipated?

[nathanwaters]

I assume this won’t affect custom macro editor UIs but it wasn’t mentioned: Macro Editor

[PhilipFeldmann]

As @nathanwaters suggested, could you please confirm that this does not affect the macro editor in any way?

Regarding the RFC: Due to the lack of wysiwyg preview for macros with a content body, users will now not know which macro they need to update if they want to update a certain part of the page that’s within a body, until they hover of the macro to see the name in the tooltip.
I agree that this experience might look cleaner, but it’s now actually much more confusing to find the correct part of the page that needs to be updated.
I don’t believe that removing the macro name from the field of immediate visibility is a great idea in this case, unless you plan to give vendors the tools to create wysiwyg experiences here. My suggestion would be to add a add the name of the macro back to the concept but just making the border much more subtle.

[marc]

Hi @DavidMichelson ,
Thanks for explaining the RFC.

My comment is mainly about accessibility. My impression is that visually impaired users might find it much more difficult to edit and navigate in the page editing state, and that this design might not be compatible with Accessibility | Atlassian .

[dlindsay]

Glad to see this getting an update! It’s long been out of alignment with the Fabric/WYSIWYG Editor .

A few questions/things that we’ve been talking about internally are:

• What does the experience look like in dark mode (especially for rich text bodied macros)?
• The blue selected/copied state looks great on a plain text background but might clash with other backgrounds/contexts. Will it be a standard or will partners be able to customise these states?

I want to expand on a few things you mentioned above:

@DavidMichelson

Generic, meaningless macro icon creates visual noise.

While this might be true for Atlassian, for marketplace partners it’s a way of differentiating themselves from Atlassian macros and from other apps who might have the same features. So, we’d argue that it is important to partners.

@DavidMichelson

Macro name is displayed by default in the Editor - users cannot hide this. For some macros, the name is very technical and does not add to user understanding. For other macros, the user may want to add a custom title, or toggle the title display, but this is not possible today.

Also not exactly true for us. For example, we use it to differentiate user named tabs. Granted it’s not ideal today but it allows us to store the title of the tab. Here’s an example:

[LauraKolkerArtemisSo]

fwiw, I don’t think hover is a good way to communicate important information. It’s really only good for additional context. Example: If the content of a section is coming in from an includePage macro that’s important to know, because I’m not even in the right page if I want to edit that content. If you bury that info it’s just going to take me longer to get where I need to be.

[david]

This feels like the solution to a problem that does not exist.

If you don’t like the look of the current macro edit view, then change it, but without losing the visual information that’s currently there.

Hiding important information in a hover state is not the way forward.

For example:

• How does the hover state work on a tablet or mobile device?
• How does the hover state work on the mobile app version?

The usability heuristic is: Make it obvious; Provide clear navigation and orientation.

A real experience quality check is: can your user/customer know where to go to for what they need, even before interacting with it?

There are other things that are actually broken and need fixing first before getting to this, that impact the usability of Confluence way worse.

For example, exact match searching has been broken since 2009.

At a recent Atlassian Community event in London someone asked if people had problems with search in Confluence, almost everyone in the room of 100+ people raised their hands.

[remie]

@DavidMichelson thank you for this detailed RFC!

I have a question with respect to user interaction within the macro during editing. You mention here:

@DavidMichelson

Disconnect between the edit and render experience (not What You See Is What You Get, or WYSWIYG) means users can’t predict what content will look like until they publish their page, adding extra time and effort.

Right now, although the macro is being rendered there is no way to interact with the macro content. If there is a button, you cannot click it. If you want a true WYSIWYG experience while editing, shouldn’t the macro also be interactive?

That also means that you should be able to open dialogs and other interactions.

Take for instance our Figma for Confluence app. When viewing the page, it looks like this:

There is an “info” button on the top right, which will flip the card when pressed:

This button will not work in edit mode, as the iframe has an overlay that captures all user interaction:

Will the new design allow users to click on that “info” button and have the card flip? Or click on the “Fullscreen” button and have a dialog open?

[remie]

I have another question, also related to this:

@DavidMichelson

Disconnect between the edit and render experience (not What You See Is What You Get, or WYSWIYG) means users can’t predict what content will look like until they publish their page, adding extra time and effort.

Will it be possible to make AP.confluence.saveMacro available in the editor?

This would allow us to have users make changes to the macro from within the macro preview instead of having to open the macro editor dialog.

[james.dellow]

I don’t understand how removing the current grey box around macros would allow users to even understand there are macros in the page?

It would be different if pages and blog posts were only made up only of widgets / macros, but Confluence let’s you mix and match.

But yeah the icon could be better - it would be nice to set our own icons. Maybe make the box a little thinner. The macro name could be tab that’s only as wide as the label. But don’t hide this detail.

Or why not let uses choose how they want macros to appear when editing?

[dlindsay]

@DavidMichelson

Discuss: 14 Feb 2024

Hey @DavidMichelson ,

Please can we have some feedback on app vendor comments. If you’re still working through the comments please let us know. Long pauses in updates on the RFC breaks trust in the process for us.

Further expansion on how this will work with live edit will also be welcome now that RFC-36 has been published.

Cheers,
Dylan

[DavidMichelson]

@dlindsay Thanks for your detailed feedback & for following up. We have been reviewing all the feedback as it comes in, and have been making some design iterations internally based off of it. Stay tuned for a more detailed response!

Re: how this will work with Live Edit – while the changes scoped in this RFC (RFC-33) are much smaller in scope (slight visual / interaction design), we do expect them to benefit how Macros appear within Live-Edit (closer to WYSIWYG/more seamlessly integrated with the rest of the content when editing).

[Chris_at_DigitalRose]

As another marketplace vendor that uses dynamic macros in Confluence, want to echo what we have heard above:

• While the page/macro is in Edit mode, the functionality is significantly different. (as @remie said, the macro is not clickable). Seeing an almost identical rendering of the macro (with only a thin gray line) will confuse users. At least today there is some indication that the macro is in preview and may not be fully functional.
• If Atlassian is introducing a new third mode “Live-Edit”, (beyond Edit and View), is now the right time to further confuse users by blurring the line on what the legacy Edit mode looks like.
• Another vote to keep the macro name visible.

Thank you
Chris C
Digital Rose

[DavidMichelson]

@nathanwaters

I assume this won’t affect custom macro editor UIs but it wasn’t mentioned: Macro Editor

Correct. These changes will not affect custom macro editor UIs.

[DavidMichelson]

Thank you all so much for your feedback. After reading your feedback, we have made a few iterations internally and would like to share where we have landed. Check out the GIF:

User hovers, then selects an Excerpt macro while editing a page.

First and foremost, we want to make clear that we will roll out these changes gradually to customers while closely monitoring macro usage metrics & qualitative user feedback to ensure our changes impact macro adoption positively, not negatively (in which case we would iterate on our approach). Our current estimated timeframe to begin rolling these changes out to users is near the end of March 2024.

The core piece of feedback we heard was - due to a current lack of WYSIWYG ability for vendor macros (i.e. they can’t be interacted with in the editor, bodied macros which account for ~6% of all macros look very different in the editor than the renderer), it may be difficult for users to understand what they are seeing if we make it so macro names and parameters are only visible on hover.

While we agree that having the name show can be useful for orienting oneself on the page, our ultimate goal is to make macros feel more modern and familiar, which we believe will increase their adoption in the long-run. So, we are following conventions of other content in Confluence pages (i.e. smart links, media, tables, etc), where users can hover and select elements to see more details about, interact with and configure them–and will not display macro names until users hover over the macro. Similarly, macro parameters will no longer be visible in the macro frame as they were already very limited as they displayed parameter keys in camel case (confusing to less technical users) and usually had most of their information truncated.

Icons will also no longer be visible in the macro frame, to maintain a consistent experience across macros as not all macros have custom icons. The larger 40px by 40px icon illustration that users can see in the browsing menu will continue to be available to help users recognize and distinguish macros.

Lastly, as it is a large theme in RFC-36: Live-Edit Pages in Confluence Cloud, we definitely plan to add more WYSIWYG functionality (e.g. interactivity in the editor) to vendor macros in the future that can help close the gap, and will share more details as they become available.

Some other questions asked with answers:

• Is accessibility an issue? As we’ve gone through internal design iterations, we’ve made sure to closely follow our accessibility guidelines to make sure that these updates are accessible.
• Does this affect the Macro Editor? Nope!
• What does it look like in dark mode? We plan to fully support dark mode, and can share imagery when it becomes available.
• Are the selected borders/states customizable? Not at this time.