Background color support for images

[dclaux]

Implementation status

• TypeScript (available with the Outlook container in the visualizer)
• UWP ([UWP] Background color support for images #1412)
• .NET ([.NET] Background color support for images #1415)
• iOS ([iOS] Background color support for images #1414)
• Android ([Android] Background color support for images #1413)
• Documentation

Problem

Often, it is necessary to present one single image on top of a variety of different background colors. It is in general not practical to either have to dynamically generate the appropriate image server-side or to have to store all possible combinations somewhere.

Solution

Add a backgroundColor property to the Image element. With that, a card author can lay an image with a transparent background on top of any color they want. The background color respects the image's style, e.g. when set to "person", which crops the image to a circle, the background color is clipped to the circle.

Example:

{
	"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
	"type": "AdaptiveCard",
	"version": "1.0",
	"body": [
	    {
	        "type": "Image",
	        "size": "medium",
	        "url": "http://messagecardplayground.azurewebsites.net/assets/circleontransparentbackground.png",
	        "backgroundColor": "#CCCCCC"
	    },
	    {
	        "type": "Image",
	        "size": "medium",
	        "url": "http://messagecardplayground.azurewebsites.net/assets/circleontransparentbackground.png",
	        "backgroundColor": "#DDDDDD",
	        "style": "person"
	    }
	]
}

The above payload renders the same image on two different colors using the both supported image styles:

[khouzam]

@dclaux,

How is the color specified? Standard color name, if so where's the list? RGB Value?

[matthidinger]

@dclaux - this one I'm a little unsure of. It's the first time we've allowed specific colors instead of semantic ones. Do we feel comfortable about the potential implications of this?

[dclaux]

@matthidinger - we are not breaking any principle with this feature. Developers can already design images that have any background color they want and have those displayed in any Adaptive Card. This feature just makes it easier to have the same image with multiple different background colors. For instance, a team in office uses a calendar icon image and needs to display it on top of the background color the user has chosen for a particular calendar in Outlook. It is not practical for that team to craft however many versions of the same image as there are potential calendar colors, and it is not reasonable to ask them to dynamically create an image server-side as the image is loaded. A simple background color property, used in conjunction with a single image with a transparent background, does the trick super easily.

[andrewleader]

Did we think about accessibility for this?

For images, we have ideas in place for how we could append query strings to request high contrast versions of the image, allowing the author to provide a different image for high contrast... but we currently don't have a way to allow the author to provide a different background color for high contrast.

I suppose the backgroundColor property could also be an object that includes "normal" and "highContrast" colors?

I'll add this to the accessibility bucket list.

[mdtauk]

Consideration would need to be made for ensuring light and dark modes/themes will be considered - with the high-contrast options too. Should those images also provide an "inverted" version to match the theme? Is this something that makes sense semantically?

[dclaux]

Card authors can already use whichever background color they want on any image, it's just a matter of crafting the image with that background color built-in. And my experience with the partners I am working with is that they just do it. This feature doesn't enable anything that is no already possible and doesn't worsen the accessibility story in any way. However, it makes it easy to display one image on top of various background colors, which, again in my experience with partners, is something they want/need to be able to do, otherwise they would either have to create N versions of a single image or dynamically generate images server-side. The result is the same in the end.

We're talking about images here - just consider that the background color is part of the final image as rendered. Images are not manipulated by hosts in high contrast mode, they are displayed as is. I don't think there is a need for doing any better here.

[andrewleader]

Yep mdtauk, we need all of that in order to properly support images (and background colors on images).

We had a couple related issues for that, but I created a new one to track specifically this: #1648

[paulcam206]

Documentation is done and in the mahiding/site1.1 branch.