Merge pull request MicrosoftDocs#314 from tahoon-ms/controls-a11y-reference

Add accessibility guidelines for every control in PowerApps

Author: rjagiewich

powerapps-docs/maker/canvas-apps/controls/control-add-picture.md

@@ -24,86 +24,97 @@ Takes a photo or loads images from the local device.
 ## Description
 With this control users can take photos or upload image files from their device and update the data source with this content. On a mobile device the user is presented with the device's choice dialog to choose between taking a photo or selecting one already available.
 
-This control is a composite control, made up of two controls.  Press or tap once to select the outer control that shows the image that has been loaded.  Press or tap again to select the inner label control.
+This control is a grouped control containing two controls: an **Image** and an **Add media button**. The **Image** control shows the uploaded image or a placeholder if no image has been uploaded. The **Add media button** prompts for an image to be uploaded.
 
-## Outer control properties
-These properties apply to the outer control.
+See the [Image control reference](control-image.md) for **Image** properties.
+
+## Add media button properties
+**[AccessibleLabel](properties-accessibility.md)** – Label for screen readers. Should describe the purpose of adding a picture.
+
+**[Align](properties-text.md)** – The ___location of text in relation to the horizontal center of its control.
 
 **[BorderColor](properties-color-border.md)** – The color of a control's border.
 
 **[BorderStyle](properties-color-border.md)** – Whether a control's border is **Solid**, **Dashed**, **Dotted**, or **None**.
 
 **[BorderThickness](properties-color-border.md)** – The thickness of a control's border.
 
-**[DisplayMode](properties-core.md)** – Whether the control allows user input (**Edit**), only displays data (**View**), or is disabled (**Disabled**).
+**ChangePictureText** – Text that appears on the button when an image has been uploaded.
+
+**[Color](properties-color-border.md)** – The color of text in a control.
 
 **[DisabledBorderColor](properties-color-border.md)** – The color of a control's border if the control's **[DisplayMode](properties-core.md)** property is set to **Disabled**.
 
+**[DisabledColor](properties-color-border.md)** – The color of text in a control if its **[DisplayMode](properties-core.md)** property is set to **Disabled**.
+
 **[DisabledFill](properties-color-border.md)** – The background color of a control if its **[DisplayMode](properties-core.md)** property is set to **Disabled**.
 
+**[DisplayMode](properties-core.md)** – Whether the control allows user input (**Edit**), only displays data (**View**), or is disabled (**Disabled**).
+
 **Error** - If there is a problem uploading an image, this property will contain an appropriate error string.
 
 **[Fill](properties-color-border.md)** – The background color of a control.
 
-**[Height](properties-size-___location.md)** – The distance between a control's top and bottom edges.
+**[FocusedBorderColor](properties-color-border.md)** – The color of a control's border when the control is focused.
 
-**[HoverBorderColor](properties-color-border.md)** – The color of a control's border when the user keeps the mouse pointer on that control.
+**[FocusedBorderThickness](properties-color-border.md)** – The thickness of a control's border when the control is focused.
 
-**[HoverFill](properties-color-border.md)** – The background color of a control when the user keeps the mouse pointer on it.
+**[Font](properties-text.md)** – The name of the family of fonts in which text appears.
 
-**Media** – An identifier for the clip that an audio or video control plays.
+**[FontWeight](properties-text.md)** – The weight of the text in a control: **Bold**, **Semibold**, **Normal**, or **Lighter**.
 
-**[OnSelect](properties-core.md)** – How the app responds when the user taps or clicks a control.
+**[Height](properties-size-___location.md)** – The distance between a control's top and bottom edges.
 
-**[PressedBorderColor](properties-color-border.md)** – The color of a control's border when the user taps or clicks that control.
+**[HoverBorderColor](properties-color-border.md)** – The color of a control's border when the user keeps the mouse pointer on that control.
 
-**[PressedFill](properties-color-border.md)** – The background color of a control when the user taps or clicks that control.
+**[HoverColor](properties-color-border.md)** – The color of the text in a control when the user keeps the mouse pointer on it.
 
-**[Visible](properties-core.md)** – Whether a control appears or is hidden.
+**[HoverFill](properties-color-border.md)** – The background color of a control when the user keeps the mouse pointer on it.
 
-**[Width](properties-size-___location.md)** – The distance between a control's left and right edges.
+**[Italic](properties-text.md)** – Whether the text in a control is italic.
 
-**[X](properties-size-___location.md)** – The distance between the left edge of a control and the left edge of its parent container (screen if no parent container).
+**Media** – An identifier for the clip that an audio or video control plays.
 
-**[Y](properties-size-___location.md)** – The distance between the top edge of a control and the top edge of the parent container (screen if no parent container).
+**[OnChange](properties-core.md)** – How the app responds when the user changes the value of a control (for example, by adjusting a slider).
+
+**[OnSelect](properties-core.md)** – How the app responds when the user taps or clicks a control.
 
-## Inner text properties
-These properties apply to the inner label control that by default says "Tap or click to add a picture".  To select this inner control, press or tap the **Add picture** control once, and then again.
+**[Padding](properties-size-___location.md)** – The distance between the text on an import or export button and the edges of that button.
 
-**[Align](properties-text.md)** – The ___location of text in relation to the horizontal center of its control.
+**[PressedBorderColor](properties-color-border.md)** – The color of a control's border when the user taps or clicks that control.
 
-**[Color](properties-color-border.md)** – The color of text in a control.
+**[PressedColor](properties-color-border.md)** – The color of text in a control when the user taps or clicks that control.
 
-**[DisabledColor](properties-color-border.md)** – The color of text in a control if its **[DisplayMode](properties-core.md)** property is set to **Disabled**.
+**[PressedFill](properties-color-border.md)** – The background color of a control when the user taps or clicks that control.
 
-**[Font](properties-text.md)** – The name of the family of fonts in which text appears.
+**[Reset](properties-core.md)** – Whether a control reverts to its default value.
 
-**[FontWeight](properties-text.md)** – The weight of the text in a control: **Bold**, **Semibold**, **Normal**, or **Lighter**.
+**[Size](properties-text.md)** – The font size of the text that appears on a control.
 
-**[HoverColor](properties-color-border.md)** – The color of the text in a control when the user keeps the mouse pointer on it.
+**[Strikethrough](properties-text.md)** – Whether a line appears through the text that appears on a control.
 
-**[Italic](properties-text.md)** – Whether the text in a control is italic.
+**[TabIndex](properties-accessibility.md)** – Keyboard navigation order in relation to other controls.
 
-**[OnChange](properties-core.md)** – How the app responds when the user changes the value of a control (for example, by adjusting a slider).
+**[Text](properties-core.md)** – Text that appears on the button when an image has not been uploaded.
 
-**[Padding](properties-size-___location.md)** – The distance between the text on an import or export button and the edges of that button.
+**[Tooltip](properties-core.md)** – Explanatory text that appears when the user hovers over a control.
 
-**[PressedColor](properties-color-border.md)** – The color of text in a control when the user taps or clicks that control.
+**[Underline](properties-text.md)** – Whether a line appears under the text that appears on a control.
 
-**[Size](properties-text.md)** – The font size of the text that appears on a control.
+**[VerticalAlign](properties-text.md)** – The ___location of text on a control in relation to the vertical center of that control.
 
-**[Strikethrough](properties-text.md)** – Whether a line appears through the text that appears on a control.
+**[Visible](properties-core.md)** – Whether a control appears or is hidden.
 
-**[Text](properties-core.md)** – Text that appears on a control or that the user types into a control.
+**[Width](properties-size-___location.md)** – The distance between a control's left and right edges.
 
-**[Underline](properties-text.md)** – Whether a line appears under the text that appears on a control.
+**[X](properties-size-___location.md)** – The distance between the left edge of a control and the left edge of its parent container (screen if no parent container).
 
-**[VerticalAlign](properties-text.md)** – The ___location of text on a control in relation to the vertical center of that control.
+**[Y](properties-size-___location.md)** – The distance between the top edge of a control and the top edge of the parent container (screen if no parent container).
 
 ## Related functions
 [**Patch**( *DataSource*, *BaseRecord*, *ChangeRecord* )](../functions/function-patch.md)
 
-## Example
+## Examples
 ### Add images to an Image gallery control
 1. Add an **Add picture** control, and then triple-click it.
 
@@ -124,3 +135,17 @@ These properties apply to the inner label control that by default says "Tap or c
 
 Use the **[SaveData](../functions/function-savedata-loaddata.md)** function to save the images locally or the **[Patch](../functions/function-patch.md)** function to update a data source.
 
+
+## Accessibility guidelines
+The same guidelines for **[Button](control-button.md)** and **[Image](control-image.md)** apply. In addition, consider the following:
+
+### Color contrast
+* **Add media button** must have adequate contrast between its text and background. Since the uploaded image may have varying colors, use an opaque **[Fill](properties-color-border.md)** on the **Add media button** to ensure consistent contrast.
+
+### Screen reader support
+* **Add media button** must have **Text** and **ChangePictureText** that prompts the user to add or change a picture.
+
+### Keyboard support
+* **Add media button** must have **[TabIndex](properties-accessibility.md)** of zero or greater so that keyboard users can navigate to it.
+* **Add media button** must have clearly visible focus indicators. Use **[FocusedBorderColor](properties-color-border.md)** and **[FocusedBorderThickness](properties-color-border.md)** to achieve this.
+ 

powerapps-docs/maker/canvas-apps/controls/control-attachments.md

@@ -48,7 +48,7 @@ An **Attachments** control lets you open files stored on a data source as well a
 **[OnSelect](properties-core.md)** – How the app responds when the user clicks on an attachment.
 
 ## Additional properties
-**AccessibleLabel** – The label announced by screen readers.
+**[AccessibleLabel](properties-accessibility.md)** – Label for screen readers. Should describe the purpose of the attachments.
 
 **AddAttachmentText** – The label text for the link used to add a new attachment.
 
@@ -60,12 +60,18 @@ An **Attachments** control lets you open files stored on a data source as well a
 
 **[DisplayMode](properties-core.md)** – Whether the control allows adding and deleting files (**Edit**), only displays data (**View**), or is disabled (**Disabled**).
 
+**[FocusedBorderColor](properties-color-border.md)** – The color of a control's border when the control is focused.
+
+**[FocusedBorderThickness](properties-color-border.md)** – The thickness of a control's border when the control is focused.
+
 **[Height](properties-size-___location.md)** – The distance between a control's top and bottom edges.
 
 **MaxAttachmentsText** – The text that replaces the "Attach file" link when the control contains the maximum number of files allowed.
 
 **NoAttachmentsText** – Informational text shown to the user when there are no files attached.
 
+**[TabIndex](properties-accessibility.md)** – Keyboard navigation order in relation to other controls.
+
 **[Visible](properties-core.md)** – Whether a control is visible or hidden.
 
 **[Width](properties-size-___location.md)** – The distance between a control's left and right edges.
@@ -86,4 +92,31 @@ An **Attachments** control lets you open files stored on a data source as well a
 
     The Attachments field associated with the SharePoint list will appear in the form.
 
-Don't know how to [add and configure a control](../add-configure-controls.md)?
+[Learn how to add and configure a control.](../add-configure-controls.md)
+
+
+## Accessibility guidelines
+### Color contrast
+There must be adequate color contrast between:
+* **ItemColor** and **ItemFill**
+* **ItemHoverColor** and **ItemHoverFill**
+* **ItemPressedColor** and **ItemPressedFill**
+* **AddedItemColor** and **AddedItemFill**
+* **RemovedItemColor** and **RemovedItemFill**
+* **ItemErrorColor** and **ItemErrorFill**
+* **AddAttachmentColor** and **Fill**
+* **MaxAttachmentsColor** and **Fill**
+* **NoAttachmentsColor** and **Fill**
+
+This is in addition to the standard color contrast requirements.
+
+### Screen reader support
+The following properties must be present:
+* **[AccessibleLabel](properties-accessibility.md)**
+* **AddAttachmentsText**
+* **MaxAttachmentsText**
+* **NoAttachmentsText**
+
+### Keyboard support
+* **[TabIndex](properties-accessibility.md)** must be zero or greater so that keyboard users can navigate to it.
+* Focus indicators must be clearly visible. Use **[FocusedBorderColor](properties-color-border.md)** and **[FocusedBorderThickness](properties-color-border.md)** to achieve this.

powerapps-docs/maker/canvas-apps/controls/control-audio-video.md

@@ -32,6 +32,8 @@ An **Audio** control plays a sound clip from a file, a recording from a **[Micro
 **ShowControls** – Whether an audio or video player shows, for example, a play button and a volume slider, and a pen control shows, for example, icons for drawing, erasing, and clearing.
 
 ## Additional properties
+**[AccessibleLabel](properties-accessibility.md)** – Label for screen readers. Should be the title of the video or audio clip.
+
 **AutoPause** – Whether an audio or video clip automatically pauses if the user navigates to a different screen.
 
 **AutoStart** – Whether an audio or video control automatically starts to play a clip when the user navigates to the screen that contains that control.
@@ -48,6 +50,10 @@ An **Audio** control plays a sound clip from a file, a recording from a **[Micro
 
 **[Fill](properties-color-border.md)** – The background color of a control.
 
+**[FocusedBorderColor](properties-color-border.md)** – The color of a control's border when the control is focused.
+
+**[FocusedBorderThickness](properties-color-border.md)** – The thickness of a control's border when the control is focused.
+
 **[Height](properties-size-___location.md)** – The distance between a control's top and bottom edges.
 
 **[Image](properties-visual.md)** – The name of the image that appears in an image, audio, or microphone control.
@@ -70,6 +76,8 @@ An **Audio** control plays a sound clip from a file, a recording from a **[Micro
 
 **Time** – A media control's current position.
 
+**[TabIndex](properties-accessibility.md)** – Keyboard navigation order in relation to other controls.
+
 **[Tooltip](properties-core.md)** – Explanatory text that appears when the user hovers over a control.
 
 **[Visible](properties-core.md)** – Whether a control appears or is hidden.
@@ -100,3 +108,31 @@ An **Audio** control plays a sound clip from a file, a recording from a **[Micro
 1. Add a **Video** control, and set its **Media** property to the URL, enclosed in double quotation marks, of a YouTube video.
 2. Press F5, and then play the clip by clicking or tapping the play button of the **Video** control.
 3. Press Esc to return to the default workspace.
+
+
+## Accessibility guidelines
+### Audio and video alternatives
+* **ShowControls** must be true so that users can listen or watch multimedia at their own pace. This also allows users to toggle closed captions and full-screen mode on video players.
+* Closed captions must be provided for videos.
+  *  For YouTube videos, use authoring tools provided by YouTube to add captions.
+  *  For other videos, create captions in WebVTT format, upload them, and set **ClosedCaptionsUrl** to the url ___location. There are several limitations. Server(s) hosting video and captions needs to be CORS-enabled and serve them using HTTPS protocol. Captioning does not work on Internet Explorer.
+* Consider providing an audio or video transcript using one of these methods:
+  1. Put the text in a **[Label](control-text-box.md)** and position it adjacent to the multimedia player. Optionally, create a **[Button](control-button.md)** to toggle the display of the text.
+  2. Put the text in a different screen. Create a **[Button](control-button.md)** that navigates to the screen and position the button adjacent to the multimedia player.
+  3. If the description is short, it can be put it in the **[AccessibleLabel](properties-accessibility.md)**.
+
+### Color contrast
+There must be adequate color contrast between:
+* **[FocusedBorderColor](properties-color-border.md)** and the outside color
+* **[Image](properties-visual.md)** and the multimedia player controls (if applicable)
+* **[Fill](properties-color-border.md)** and the multimedia player controls (if the fill is visible)
+
+Provide closed captions and/or transcript if the video content has color contrast issues.
+
+### Screen reader support
+* **[AccessibleLabel](properties-accessibility.md)** must be present.
+
+### Keyboard support
+* **[TabIndex](properties-accessibility.md)** must be zero or greater so that keyboard users can navigate to it.
+* Focus indicators must be clearly visible. Use **[FocusedBorderColor](properties-color-border.md)** and **[FocusedBorderThickness](properties-color-border.md)** to achieve this.
+* **AutoStart** should be false because it can be difficult for keyboard users to stop playback quickly.