Themeable icons/glyphs

Summary

Today, it’s impossible to author a card that has icon images within it that works on both a dark and light background.

Light theme
Dark theme

Neither is the card theme aware. If it were, we could allow users to provide multiple images for light mode or dark mode.

Requirements

• P0: Author can provide different images for light and dark themes

  • We could solve this with requires (say requires dark theme, then fallback to different image). But we’ll wait for more requests.

• P0: Author can provide a tintable image that automatically themes

• P1: Author can specify semantic tint colors (accent, attention, good, etc)

• P1: Author can provide a set of icons so that each icon isn’t a separate http request

Spec/schema

https://github.com/microsoft/AdaptiveCards/pull/3092/files

Proposal options

• Option 1: PNGs with tint property

  • Author provides a PNG that’s tintable, all non-transparent pixels get tinted the color.

• Option 2: SVGs with tint property

  • Author provides a SVG that’s tintable, all non-transparent vectors get tinted the color.

• Option 3: Icon fonts

  • Author provides icon font and uses font characters from that font.

PNGs
SVGs
Icon fonts
Authoring story
Developer creates and provides a PNG
Developer creates and provides a SVG
Developer creates and provides the icon font files (multiple files) at their top-level card and then references that font
Authoring simplicity
Simple until you worry about scaling
Somewhat complex, need to be able to produce SVGs
Complex, need to produce your icons as SVGs and then use tooling to produce a font out of that
Scalability
Doesn’t scale
Scales
Scales
Download size
< 0.5 KB per icon
< 0.5 KB per icon
200 KB for ALL of Material Icons

of requests

1 per icon
1 per icon
1 per icon set
Allows custom fonts
No
No
Yes, there’s no way for us to tell if they’re using it as intended for icons, or using it for text
Web
Complex, have to manipulate pixels
Moderately complex, would have to modify SVG XML and replace the fill colors
Simple
Android
Simple (tint property)
Simple (tint property)
Simple
UWP
Complex, manipulate pixels
Complex, modify SVG XML
Simple

What do people say on SVG vs Icon Fonts?

• https://www.keycdn.com/blog/icon-fonts-vs-svgs

  • SVG is typically winner

• https://bulldogjob.com/articles/626-svgs-vs-icon-fonts-the-battle-without-resolution

  • No clear winner, both have benefits

• https://css-tricks.com/icon-fonts-vs-svg/

  • Likes SVG a lot more

• https://www.creativebloq.com/web-design/icon-fonts-vs-svg-101413211

  • Icon fonts when using a large set, SVG provides more flexibility

• https://www.lambdatest.com/blog/its-2019-lets-end-the-debate-on-icon-fonts-vs-svg-icons/

  • Thinks SVGs (and SVG spritesheets) are the future

Option 1: PNGs with tint property

Very straightforward for anyone to use, even those who don’t have access to Adobe software. However, images aren’t scalable. This also requires lots of work on renderers.

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "Image",
            "url": "https://user-images.githubusercontent.com/13246069/59642306-4a673b00-9119-11e9-8408-b0b96fd64dd6.png",
            "size": "Small",
            "tint": "accent"
        }
    ],
    "version": "1.0"
}

Option 2: SVGs with tint property

Mostly straightforward for anyone to use, but does require SVG software like Adobe software. Results in scalable images. However, requires work on renderers.

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "Svg",
            "url": "https://user-images.githubusercontent.com/13246069/59642306-4a673b00-9119-11e9-8408-b0b96fd64dd6.svg",
            "size": "Small",
            "tint": "accent"
        }
    ],
    "version": "1.0"
}

Option 3: Icon fonts

Not the most straightforward, requires SVG software like Adobe software and also software to generate an icon font from the SVG. Results in scalable images. Minimal work on renderers.

UWP uses the TTF file

{
  "type": "AdaptiveCard",
  "customFontFamilies": {
    "myIcons": {
      "eot": "https://example.com/fonts/font.eot",
      "woff": "https://example.com/fonts/font.woff",
      "woff2": "https://example.com/fonts/font.woff2",
      "truetype": "https://example.com/fonts/font.ttf",
      "svg": "https://example.com/fonts/font.svg"
    }
  },
  "body": [
      {
          "type": "FontIcon",
          "text": "󥎉",
          "fontFamily": "myIcons",
          "size": "Small",
          "tint": "accent"
      }
  ],
  "version": "1.0"
}

Proposed changes (based on png option)

Add a tint property to Image, which takes any of our foreground semantic colors (like good, default, etc)

Add an icon property to Action (and deprecate iconUrl), which has two properties…

• url

• tintable boolean (in actions, authors don’t get to pick semantic colors since it’s controlled by the host)

Example

In body matching accent color

Sometimes you need icon images to match the accent color… (Look at the plane icons)

Cortana
Teams

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "ColumnSet",
            "columns": [
                {
                    "type": "Column",
                    "items": [
                        {
                            "type": "Image",
                            "url": "https://user-images.githubusercontent.com/13246069/59642306-4a673b00-9119-11e9-8408-b0b96fd64dd6.png",
                            "size": "Small",
                            "tint": "accent"
                        }
                    ],
                    "width": "auto"
                }
            ]
        }
    ],
    "version": "1.0"
}

On actions

Notice that it’s not even just white vs black… it’s actually white and Teams purple… every host can have their own tints

Light theme
Dark theme

{
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "FactSet",
            "facts": [
                {
                    "title": "Board:",
                    "value": "Adaptive Card"
                }
            ]
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Set due date",
            "icon": {
                "url": "https://cdn3.iconfinder.com/data/icons/computers-programming/512/datepicker-512.png",
                "tintable": true
            },
            "data": "submitData"
        },
        {
            "type": "Action.OpenUrl",
            "title": "View",
            "icon": {
                "url": "https://cdn2.iconfinder.com/data/icons/picol-vector/32/view-512.png",
                "tintable": true
            },
            "url": "http://adaptivecards.io"
        }
    ],
    "version": "1.0"
}

Host Config

New property, actions.iconTint, which takes a hex color string. This is so that a separate tint can be specified on actions (like the purple Teams tint). Other images will get the default color tint.

    "actions": {
        "maxActions": 6,
        "spacing": "Default",
        "buttonSpacing": 8,
        "iconTint": "#FFFFFF",
        "showCard": {
            "actionMode": "Inline",
            "inlineTopMargin": 16,
            "style": "emphasis"
        },
        "preExpandSingleShowCardAction": false,
        "actionsOrientation": "Horizontal",
        "actionAlignment": "Left"
    },

Down-level impact

Medium. For Image elements, no worse than today 😃 But for actions, since the property changed, they have to be aware of adding the old property if they want their icon to appear in old versions.

Host burden

Small. Simply provide the action tint color.

[bandtank]

Did this happen? I can’t find documentation, but it says completed in the issue’s history.

[msftbot[bot]]

This issue has been automatically marked as stale because it has not had any activity for 5 days.