Add articles

Sources/AccessibilityDocumentation/Documentation.docc/Articles/ControlHierarchy.md

@@ -0,0 +1,14 @@
+# ControlHierarchy
+
+- ``Book/isAccessibilityElement``
+- ``Book/accessibilityElementsHidden``
+- ``Book/accessibilityViewIsModal``
+- ``Book/shouldGroupAccessibilityChildren``
+
+## Overview
+
+<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
+
+### Section header
+
+<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->

Sources/AccessibilityDocumentation/Documentation.docc/Articles/DescribeElements.md

@@ -0,0 +1,81 @@
+# Describe elements
+
+Core properties that describes element for VoiceOver
+
+To describe element we can use label, value and trait (like a type)
+
+## Label
+
+- ``Book/accessibilityLabel``
+
+The main property is `accessibilityLabel` – defines element's name. It should be name in one or two words for buttons or represents full text from `UILabel` 
+
+**Examples:**
+- *1.4 billions views* – just the fact under the video
+- *Never Gonna Give You Up* song title that describes screen's content
+- *Next* for button that skip a song in audio player
+- *Pizza Pepperoni* for cell in the menu
+- *Size* for segmented control on product card
+- *Brightness* for slider in Control Center
+
+> Tip: Voice Control can have synonims for label. Check ``Book/accessibilityUserInputLabels`` for more details.
+
+## Value
+
+- ``Book/accessibilityValue``
+
+`AccessibilityValue` is optional second part of the element's description. It can contain additional details or represents current value of the element
+- *1.4 billions views* – no value for regular text is ofter situation
+- *Never Gonna Give You Up, **Rick Astley*** 
+- *Next, **Childish Gambino – Redbone*** can add detalization about next track. Visually you can see a cover of the song, but for VoiceOver it is better to provide text alternative. Different approaches, but same experience.
+- *Pizza Pepperoni, **Pepperoni, Mozzarella***
+- *Size, **Medium***
+
+> Note: Label and Value separates by comma automatically, it produced short pause between them
+
+> Tip: You can add additional commas in label or value, pronunciation will use them for short pauses
+
+### Label vs Value
+
+Important to understand differences between label and value. Label should be as short as possible: Voice Control will use it as HUD over UI to name things for feature voice commantds, but not show value part, because we expect that it's already presented for user on screen. <doc:VoiceControl>
+
+Otherwise, adjustable elements allow to change only value part and after change only value part will be pronounced to user. <doc:AdjustableElements>
+
+## Trait
+- ``Book/accessibilityTraits``
+
+The last part of element's description is trait. Some traits may add additional text to element's description, other just changes behaviour. 
+
+An element can have no trait - regular text, for e.g.
+
+The most common trait is ``UIAccessibilityTraits_/button`` – it helps user to understand that he can interact with an element.
+
+**Samples:**
+- *1.4 billions views* – regular text can have no traits. Sometimes ``UIAccessibilityTraits_/staticText`` can be used, but it adds no special descriptions to the end. 
+- *Never Gonna Give You Up, Rick Astley. **Header*** – Header describes that the element is main on the page and other controls are connected to it
+- *Play, Childish Gambino – Redbone. **Button*** – the Button works like button, can be activated by double tap for VoiceOver, should be focused by Switch Control or Voice Control can present tooltip over the interactive element.
+- *Pizza Pepperoni, Pepperoni, Mozzarella. **Button*** – tappable cell should contain button semantic, that's how user will understand that the cell is interactive and can be tapped. 
+- *Size, Medium. **Adjustable*** – VoiceOver can change inner value by vertical swipe.
+
+> Note: Label and Value are separated by comma, but trait represents another sentence and separated by dot automatically.
+
+> Important: Label and Value are `String` properties, but Trait can be selected only from limited amount of variants. Not duplicate trait's textual description inside Label or Value, because different technologies uses trait in different manear, not only for textual description.  
+
+// TODO: Draw full scheme
+
+## Topics
+
+Traits that add additional text:
+
+- ``UIAccessibilityTraits_/button``
+- ``UIAccessibilityTraits_/link``
+- ``UIAccessibilityTraits_/header``
+- ``UIAccessibilityTraits_/adjustable``
+- ``UIAccessibilityTraits_/tabBar``
+- ``UIAccessibilityTraits_/toggleButton``
+- ``UIAccessibilityTraits_/searchField``
+- ``UIAccessibilityTraits_/image``
+
+Other traits can add text to diferent place in description
+- ``UIAccessibilityTraits_/selected``
+- ``UIAccessibilityTraits_/notEnabled``

Sources/AccessibilityDocumentation/Documentation.docc/Documentation.md → Sources/AccessibilityDocumentation/Documentation.docc/Articles/Documentation.md

@@ -23,28 +23,8 @@ To prototype interaction on early stage of development you can use [VoiceOver De
 
 ## Topics
 
-### Describe elements
-
-Core properties that describes element for VoiceOver
-
-- ``Book/accessibilityLabel``
-- ``Book/accessibilityValue``
-- ``Book/accessibilityTraits``
-
-### Control hierarchy
-- ``Book/isAccessibilityElement``
-- ``Book/accessibilityElementsHidden``
-- ``Book/accessibilityViewIsModal``
-- ``Book/shouldGroupAccessibilityChildren``
-
-### Visual properties
-- ``Book/accessibilityFrame``
-- ``Book/accessibilityActivationPoint``
-- ``Book/accessibilityPath``
-- ``Book/accessibilityRespondsToUserInteraction``
-
-### Switch Control specific
-- ``Book/accessibilityNavigationStyle``
-
-### Voice Control specific
-- ``Book/accessibilityUserInputLabels``
+- <doc:DescribeElements>
+- <doc:ControlHierarchy>
+- <doc:VisualProperties>
+- <doc:Navigation>
+- <doc:SpecificProperties>

Sources/AccessibilityDocumentation/Documentation.docc/Articles/Navigation.md

@@ -0,0 +1,11 @@
+# Navigation
+
+<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
+
+## Overview
+
+<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
+
+### Section header
+
+<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->

Sources/AccessibilityDocumentation/Documentation.docc/Articles/SpecificProperties.md

@@ -0,0 +1,18 @@
+# Specific Properties
+
+Different disabilities requires different way of perceptions and control. As a result some technologies provides additional properties for finergaind control. 
+
+
+## VoiceOver
+
+<doc:AdjustableElements> allows to control the element by vertical swipe, but in useful only for blind persons.
+
+## Switch Control
+
+- ``Book/accessibilityNavigationStyle``
+
+## Voice Control
+
+In regular vocabulary we use a lot of synonyms. To simplify interaction Voice Control can use ``Book/accessibilityLabel`` alongside alternatives from `UserInputLabel` 
+
+- ``Book/accessibilityUserInputLabels``

Sources/AccessibilityDocumentation/Documentation.docc/Articles/VisualProperties.md

@@ -0,0 +1,20 @@
+# Visual Properties
+
+Every technologies requires understanding of graphical properties for different apporoach. 
+
+
+
+## Overview
+
+<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
+
+### Section header
+
+## Topics
+- ``Book/accessibilityFrame``
+
+- ``Book/accessibilityActivationPoint``
+
+- ``Book/accessibilityPath``
+
+- ``Book/accessibilityRespondsToUserInteraction``

Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial

@@ -0,0 +1,43 @@
+@Tutorials(name: "How to adopt your application") {
+    @Intro(title: "Few steps") {
+
+        To adopt your application for assistive technologies you should forward few steps:
+        Simplify and group elements in UI's hierarchy
+        Add labels to elements
+        Add additional properties
+
+<!--        @Image(source: <#file#>, alt: "<#accessible description#>")-->
+    }
+
+    @Chapter(name: "Desribe elements") {
+        Simplifies navigation and control over a complex element for VoiceOver
+
+<!--        @Image(source: <#file#>, alt: "<#accessible description#>")-->
+
+        @TutorialReference(tutorial: "doc:AdjustableTutorial")
+    }
+
+    @Chapter(name: "Control hierarchy") {
+        Simplifies navigation and control over a complex element for VoiceOver
+
+        <!--        @Image(source: <#file#>, alt: "<#accessible description#>")-->
+
+        @TutorialReference(tutorial: "doc:AdjustableTutorial")
+    }
+
+    @Chapter(name: "Adjustable elements") {
+        Simplifies navigation and control over a complex element for VoiceOver
+
+        <!--        @Image(source: <#file#>, alt: "<#accessible description#>")-->
+
+        @TutorialReference(tutorial: "doc:AdjustableTutorial")
+    }
+
+    @Chapter(name: "Tweak visual propeties") {
+        Simplifies navigation and control over a complex element for VoiceOver
+
+        <!--        @Image(source: <#file#>, alt: "<#accessible description#>")-->
+
+        @TutorialReference(tutorial: "doc:AdjustableTutorial")
+    }
+}

Sources/AccessibilityDocumentation/UIAccessibility_.swift

@@ -42,6 +42,8 @@ public class Book {
      default == nil
      default on UIKit controls == derived from the title
      Setting the property will change the label that is returned to the accessibility client.
+
+     See <doc:DescribeElements> for more detail
      */
     open var accessibilityLabel: String? = nil
 
@@ -106,22 +108,21 @@ public class Book {
      default on UIKit controls == traits that best characterize individual controls.
      Setting the property will change the traits that are returned to the accessibility client.
      */
-    open var accessibilityTraits: UIAccessibilityTraits = .none
+    open var accessibilityTraits: UIAccessibilityTraits_ = .none
 
 
     /**
-     Returns the frame of the element in screen coordinates.
-     default == CGRectZero
-     default on UIViews == the frame of the view
-     Setting the property will change the frame that is returned to the accessibility client.
+     Returns the frame of the element *in screen coordinates.*
+
+     VoiceOver and Switch Control uses it to draw focus. In opposite way by this property we can recognise what the element under user's finger.
+
+     Voice Control draw badges over screen that is linked to element by this property.
+
+     Use ``convertToScreenCoordinates(_:in:)-4i9mu`` to calculate onscreen values
+
      */
     open var accessibilityFrame: CGRect = .zero
 
-
-    // The accessibilityFrame is expected to be in screen coordinates.
-    // To help convert the frame to screen coordinates, use the following method.
-    // The rect should exist in the view space of the UIView argument.
-
     /**
      Returns the path of the element in screen coordinates.
      default == nil
@@ -735,7 +736,7 @@ public class Book {
 //public typealias AXObjectReturnBlock = () -> Any?
 //public typealias AXArrayReturnBlock = () -> [Any]?
 //public typealias AXVoidReturnBlock = () -> Void
-//public typealias AXTraitsReturnBlock = () -> UIAccessibilityTraits
+//public typealias AXTraitsReturnBlock = () -> UIAccessibilityTraits_
 //public typealias AXNavigationStyleReturnBlock = () -> UIAccessibilityNavigationStyle
 //public typealias AXContainerTypeReturnBlock = () -> UIAccessibilityContainerType
 //public typealias AXTextualContextReturnBlock = () -> UIAccessibilityTextualContext?