Adaptive Card designs for Virtual Assistant & Skills

[ryanisgrig]

Adaptive Cards & Themes Spec

Area
Virtual Assistant

Goals

Design

• The default Fabric theme uses UI elements that match the out-of-the-box Web Chat and Adaptive Card design.
  • Additional themes can be provides with replacement image assets, card JSONs, and host config JSON (for a custom Web Chat).
• Cards will be used as supplemental UX to speech and text scenarios. They should avoid interactive UI elements as this requires additional data processing that may not have cross-channel coverage.

Development

• Developers can unpack a zipped file of image assets and an Adaptive Card host JSON.
• Image assets should maintain consistent names between design packs to enable easy asset replacement.
• When deployed with a Virtual Assistant, assets from individual skills should surface up to the root web app.
• Developers should be able to easily deploy new asset packs into an existing Virtual Assistant & Skills.
  • Card resources should be in a standard location for Skills.
• Store image assets as base64 when possible

Common Elements

Icons

Every Skill will require a unique icon to identify itself.

Header

Every card will have a header identifying itself with a Skill icon. Since the current version of Adaptive Cards only supports a single background image, those images should account for the header space to remain unchanged.
The preferred solution would be to assign background images to individual containers, this is on the Adaptive Cards 1.2 tentative feature list (microsoft/AdaptiveCards#2444).

Users

User avatars should be displayed when possible, and default to a user's initials if one is unavailable (see UI Avatars for a sample solution).

User Avatar	Initials Avatar

When displaying a list of users in a meeting or mail, if the count is:

• 5 or less: display up to 5 user icons
  
• More than 5: display 4 user icons & a text block with "+ #"
  

Order them with sender, then alphabetical order.

Text

Elements should have the appropriate color assigned based on their data status. For example, conflicting calendar appointments should use the alert or warning color.

Speak

Speak property should give a summary of the card. Keep in mind if the card may be displayed in a carousel; in this case it a Virtual Assistant should read out each card.

Footer

Show a footer container at the bottom of overview cards to attribute data sources (i.e. Powered by Microsoft Graph)

Cards

Virtual Assistant

Introduction to a new user

Introduction to a returning user

• When a user is returning to the bot, the VA should show a different card for welcoming back.
• This sample uses a column set of 4 columns that map to enabled skills. Each column has an ImBack submit action that will trigger that skill with a sample query (what's on my calendar today, show my to do list, etc.)

Calendar Skill

Schedule (single day)

• Header: Show count of all events that day and overlapping events, user avatar, date
• Show MAX 5 items
• Related meeting data is split between 2 columns: time, event name & location.
  • If meetings are tentative/unaccepted - isSubtle:true
• If there are meeting conflicts, use the attention color on the overlapping time text blocks.

Show Meetings per User,Location, and Subject

• Use variant of Schedule Overview with header related to user.
• Paginate through top 3 items and show total count.

Meeting

• Show maximum 2 lines of the subject.
• Show maximum 2 lines of location.
• Show maximum 5 lines of body.

Email Skill

Overview

• Header: show count of all unread messages & high priority messages, user avatar, date.
• Show 5 MAX most recent email items.
• Related email data is shared in the same container: from user avatar and name, subject, attachment/importance icons, timestamp.
• Timestamp formatting: For the day of, show HH:mm AM/PM. For previous days, show day MM:dd.
• Show powered by textblock

Show Messages per User & Subject

• Paginate through top 3 items and show total count.

Message

• Header: Subject, from user avatar and name, datetime with format day MM/dd HH:mm AM/PM
• Use maximum 5 lines to display message preview

Confirm Whole Email

• Show the subject, contacts, and message when confirming

Confirm Message Content

• Only show a title and the message content.

To Do Skill

Show To Do

• One task per line
• Investigate if API allows to check for user setting if they prefer to show "checked off" tasks or not.
• Max is 4 to read out.
• When removed, delete.
• When completed, mark as complete.

Point of Interest Skill

Details

Route Details

• Use status color for route info dependent on delay
  • No/light delay: good (green)
  • Medium delay: warning (yellow)
  • Heavy delay: attention (red)

[ryanisgrig]

Should backend APIs be attributed on the card somewhere? i.e. "Provided by X"?
How would this work if cards have data from multiple sources? For example, POI cards using Azure Maps for geolocation and Foursquare for location details.

[darrenj]

Should backend APIs be attributed on the card somewhere? i.e. "Provided by X"?
How would this work if cards have data from multiple sources? For example, POI cards using Azure Maps for geolocation and Foursquare for location details.

I think this would be a great thing to add into here, "Powered by Microsoft Graph", this will also help on other scenarios where we have data that does need to be attributed. This however is more around highlighting what is powering it (and customers could remove if they wanted to)

[Quirinevwm]

• For the adaptive cards, can we make sure we show 5 max (UX guideline) for the overview of your upcoming events/inbox emails.
• for tasks the list is 4 max to read out and remember a task in a list (UX test), the adaptive card should match this.
• Paginate through top 3 items and show total count - this option is a bit confusing, it can come across like the date/month format.