From 8eab00ccf83e60bcae27ecd85a4ea7092743a852 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=9C=8C=EF=B8=8F=28=C2=B4=E3=83=AE=60=29?= Date: Thu, 25 Jan 2024 10:16:45 +0300 Subject: [PATCH 1/4] Update README.md --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 985d780..2e205fc 100644 --- a/README.md +++ b/README.md @@ -23,14 +23,16 @@ To focus on the implementation of assistive technologies. ### Articles To study the concepts. -- Accessibility Properties in Code: How to Use Them. A brief overwiev for implenting accessibility in the apps +- Accessibility Properties in Code: How to Use Them. A brief overview of implenting accessibility in apps - Accessibility Features Explained: How People Use Assistive Technology. A thorough description of the concepts and its technological implementations in order to provide a better understanding of how it all works. ## Can I contribute to the project? Yes, **everyone is welcome to influence the project**. It can be done by **comitting *ideas* and *fixes* to this repository**: - **describe a problem** or **discuss on the topic** in [Issues](https://github.com/VODGroup/AccessibilityDocumentation/issues); - **propose a change** by creating a *pull request* to this repository; + Screenshot 2024-01-25 at 09 58 20 - **write an article** from tasks listed in [Projects](https://github.com/orgs/VODGroup/projects/5/views/1). + Screenshot 2024-01-25 at 10 11 13 ## Sponsored by VoiceOver Designer From 823bd5584e46bc46c073de45546577d6d06b161e Mon Sep 17 00:00:00 2001 From: "C." Date: Thu, 25 Jan 2024 11:44:14 +0300 Subject: [PATCH 2/4] first adoptingCell edit --- .../SwitchControl.md | 0 .../VoiceControl.md | 0 .../VoiceOver.md | 0 .../{1.Basic => 1. Basic}/ControlHierarchy.md | 0 .../{1.Basic => 1. Basic}/DescribeElements.md | 0 .../{1.Basic => 1. Basic}/Navigation.md | 0 .../SpecificProperties.md | 0 .../{1.Basic => 1. Basic}/VisualProperties.md | 0 .../AdjustableElements.md | 0 .../{2.Advanced => 2. Advanced}/Rotor.md | 0 .../VerticalSwipe.md | 0 .../Tutorials/1,Basic/AdoptingCell.tutorial | 272 ----------------- .../Tutorials/1. Basic/AdoptingCell.tutorial | 284 ++++++++++++++++++ .../AdjustableTutorial.tutorial | 0 14 files changed, 284 insertions(+), 272 deletions(-) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{0.AssistiveTechnologies => 0. AssistiveTechnologies}/SwitchControl.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{0.AssistiveTechnologies => 0. AssistiveTechnologies}/VoiceControl.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{0.AssistiveTechnologies => 0. AssistiveTechnologies}/VoiceOver.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{1.Basic => 1. Basic}/ControlHierarchy.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{1.Basic => 1. Basic}/DescribeElements.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{1.Basic => 1. Basic}/Navigation.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{1.Basic => 1. Basic}/SpecificProperties.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{1.Basic => 1. Basic}/VisualProperties.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{2.Advanced => 2. Advanced}/AdjustableElements.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{2.Advanced => 2. Advanced}/Rotor.md (100%) rename Sources/AccessibilityDocumentation/Documentation.docc/Articles/{2.Advanced => 2. Advanced}/VerticalSwipe.md (100%) delete mode 100644 Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1,Basic/AdoptingCell.tutorial create mode 100644 Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1. Basic/AdoptingCell.tutorial rename Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/{2.Advanced => 2. Advanced}/AdjustableTutorial.tutorial (100%) diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/0.AssistiveTechnologies/SwitchControl.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/0. AssistiveTechnologies/SwitchControl.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/0.AssistiveTechnologies/SwitchControl.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/0. AssistiveTechnologies/SwitchControl.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/0.AssistiveTechnologies/VoiceControl.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/0. AssistiveTechnologies/VoiceControl.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/0.AssistiveTechnologies/VoiceControl.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/0. AssistiveTechnologies/VoiceControl.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/0.AssistiveTechnologies/VoiceOver.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/0. AssistiveTechnologies/VoiceOver.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/0.AssistiveTechnologies/VoiceOver.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/0. AssistiveTechnologies/VoiceOver.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/ControlHierarchy.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/ControlHierarchy.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/ControlHierarchy.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/ControlHierarchy.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/DescribeElements.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/DescribeElements.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/DescribeElements.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/DescribeElements.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/Navigation.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/Navigation.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/Navigation.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/Navigation.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/SpecificProperties.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/SpecificProperties.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/SpecificProperties.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/SpecificProperties.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/VisualProperties.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/VisualProperties.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/1.Basic/VisualProperties.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/1. Basic/VisualProperties.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/2.Advanced/AdjustableElements.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/2. Advanced/AdjustableElements.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/2.Advanced/AdjustableElements.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/2. Advanced/AdjustableElements.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/2.Advanced/Rotor.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/2. Advanced/Rotor.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/2.Advanced/Rotor.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/2. Advanced/Rotor.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/2.Advanced/VerticalSwipe.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/2. Advanced/VerticalSwipe.md similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Articles/2.Advanced/VerticalSwipe.md rename to Sources/AccessibilityDocumentation/Documentation.docc/Articles/2. Advanced/VerticalSwipe.md diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1,Basic/AdoptingCell.tutorial b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1,Basic/AdoptingCell.tutorial deleted file mode 100644 index 2804579..0000000 --- a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1,Basic/AdoptingCell.tutorial +++ /dev/null @@ -1,272 +0,0 @@ -@Tutorial(time: 10) { - @Intro(title: "Adopting cell") { - - Common case when a cell become an accessible element and combine all data in its description. For example we have a cell with pizza's description: image, title, ingredients and price. We can dramatically simplify cell for VoiceOver - - - } - - @Section(title: "The point") { - @ContentAndMedia { - Cell looks simple, but straitforward layout leads to several accessibility issues - @Comment { } - - @Image(source: "Chicken BBQ", alt: "Cell of Chicken BBQ with image, title, ingredients and price") - } - - @Steps { - @Step { - Let's start from VoiceOver problems. - - First of all focus outlines ever separate element in cell. - Image is hidden from VoiceOver by default (and it's fine), and first focused element is cell. - - @Image(source: "DescribeCell_1", alt: "Focus outlines title") - } - - @Step { - After swipe to the right focus moves to ingredients - - @Image(source: "DescribeCell_2", alt: "Focus outlines ingredients") - } - - @Step { - Next swipe move focus to the button with price. - - > None: Only here user can understand, that it is interactive element by hearing `.button` trait - - @Image(source: "DescribeCell_3", alt: "Focus outlines button with price") - } - - @Step { - In the end user had to do three swipes to passthrough just one cell. - - @Code(name: "Several cells and wrong rhyme", file: "DescribeCell_3_0.swift") - } - - @Step { - Moreover, when he swipes through several steps he can lose his understanding which element connects to which pizza, ingredients will be repetitive and etc - - @Code(name: "Several cells and wrong rhyme", file: "DescribeCell_3_1.swift") { - @Image(source: "DescribeCell_3_3", alt: "Focus outlines button with price") - } - } - - @Step { - For e.g. price button may looks connected to next title. - - @Code(name: "Several cells and wrong rhyme", file: "DescribeCell_3_2.swift") { - @Image(source: "DescribeCell_3_3", alt: "Focus outlines button with price") - } - } - - @Step { - Voice Control and Switch Control have problems too. They works with interactive buttons, as a result label will be shown only for price button and user had to pronounce `Tap From AED thirty` to press the cell. - - > Tip: It would be much better, if we use title as cell's label. - - @Image(source: "DescribeCell_4", alt: "Voice Control show badge over button with price") - } - } - } - - @Section(title: "Describe cell") { - @ContentAndMedia { - To properly describe the cell for VoiceOver we had to transfer text from labels to accessibility description of the cell in correct order and with correct type. - - @Image(source: "DescribeCell_9_preview", alt: "Reading order is controlled by designer") - } - - @Steps { - @Step { - Start from simple cell with explicit ViewModel. - - @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_6.swift") - } - - @Step { - First of all we should set that the cell will be focusable element. As a result we reduce number of elements on screen. - - No need to explicitly hide other elements, specifying the cell as accessibleElements it enough, read for details. - - @Comment { - // TODO: why the cell's button is visible at pizza? - } - - @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_7.swift") - } - - @Step { - The cell has no info about its label, use `title` as `accessibilityLabel` and `ingredients` as `accessibilityValue` - - @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_8.swift") - - @Comment { - // TODO: Add Voice Control screenshot - } - } - - @Step { - Price is important part of the cell, but we had to choose how to describe it. We can notice, that visual perception of order is controlled by designer: image attracts attention first; eyesight moves to title: it's on top and bold; bright colored button interrupts attention order and point to itself after title; ingredients is last point of attention: it's grey, long and boring - - As a result we can place price after title. But, we had keep `label` simple and place price at the beginning of `accessibilityValue` - - @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_9.swift") { - @Image(source: "DescribeCell_9_preview", alt: "Reading order is controlled by designer") - } - } - - @Step { - In the end we should describe that element is interactive. Specify `.button` trait for that. - - @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_10.swift") - } - } - } - - @Section(title: "Simplify scroll") { - @ContentAndMedia { - How default scroll works for VoiceOver: user scrolls by **three-finger swipe**, VoiceOver reads number of visible pages: `4 from 20.` - - If we work with table of cells VoiceOver specify number of visible rows: `From 25 to 40 from 120` - - We can improve even this by providing description for visible area, just read all titles of products: `Chicken BBQ, Meat King Supreme, Hawaii` - - @Image(source: "DescribeCell_11", alt: "Describe screen after scroll") - } - - @Steps { - @Step { - Let's start from MenuViewController's extension - - @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_11_0.swift") - } - - @Step { - To add description we use special `UIScrollViewAccessibilityDelegate` that can be implement at any `firstResponder`. - - @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_11.swift") - } - - @Step { - Our goal is providing text description for visible cells. We can start from visible path - - @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_12.swift") - } - - @Step { - Convert them to models - - @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_13.swift") - } - - @Step { - And extract titles - - @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_14.swift") - } - - @Step { - Join in single row in the end, separating by comma. - - @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_15.swift") - } - - @Step { - After three-finger swipe titles of visible elements will be spoken aloud. - - Also you can add quantity expectation after - - @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_16.swift") - - @Comment { - // TODO: Add preview - } - } - } - } - - @Assessments { - @MultipleChoice { - How do you place price in the element - - @Image(source: "Chicken BBQ", alt: "Cell of Chicken BBQ with image, title, ingredients and price") - - @Choice(isCorrect: false) { - ``` - Label: Chicken BBQ, from 30 AED - Value: pizza sauce, mushrooms... - ``` - - @Justification(reaction: "Try again!") { - There in no difference for VoiceOver, but Voice Control presents price as part of the name that should be pronounced. To hard for Voice Control. - } - } - - - @Choice(isCorrect: true) { - ``` - Label: Chicken BBQ, - Value: from 30 AED, pizza sauce, mushrooms... - ``` - - - @Justification(reaction: "That's right!") { - Voice Control will have simple label, VoiceOver will read price in front of ingredients because it's more important - } - } - - - @Choice(isCorrect: false) { - - ``` - Label: Chicken BBQ, - Value: pizza sauce, mushrooms..., from 30 AED - ``` - - @Justification(reaction: "That's right!") { - It's too long to wait for the price when you listen VoiceOver - } - } - } - - @MultipleChoice { - How to scroll down a table when VoiceOver enabled? - - @Choice(isCorrect: false) { - Just regular swipe up - - @Justification(reaction: "Try again!") { - No, vertical swipe is used for adjustable elements and other operations. Swipe from the bottom will close an application, from the top will open Notifications Screen or Control Center - } - } - - - @Choice(isCorrect: false) { - Two finger swiper - - @Justification(reaction: "That's right!") { - Two-finger swipe up will speak the entire screen *from the top* - Two-finger swipe down will speak the entire screen *from the selected item* - } - } - - - @Choice(isCorrect: true) { - Three finger swipe - - @Justification(reaction: "That's right!") { - It's too long to wait for the price when you listen VoiceOver - } - } - - @Choice(isCorrect: false) { - For finger swipe - - @Justification(reaction: "That's right!") { - Horizontal four finger swipe will change applications - } - } - } - } -} diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1. Basic/AdoptingCell.tutorial b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1. Basic/AdoptingCell.tutorial new file mode 100644 index 0000000..0ccabf3 --- /dev/null +++ b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1. Basic/AdoptingCell.tutorial @@ -0,0 +1,284 @@ +@Tutorial(time: 10) { + @Intro(title: "Adopting Cell") { + + To have assistive technology work as intented sometimes it is needed to **simplify complex cells** to such degree so there is no difference for accessibility features between *differentiated abstractions* that are stored in the cell. In other words, if there is a cell with pizza's description it is understandable to distinguish data by its nature: have an image as an illustration, a title, a list of ingridients and a price - but it complicates the work for VoiceOver, VoiceControl and SwitchControl. Such layout makes it adapt the cell's contents **wrong**. Let's take a look of what can be done to help our digital assistants navigate through the cognitive models we come up with,. + + } + + @Section(title: "The point") { + @ContentAndMedia { + Even though the cell looks simple such layout would lead to several *accessibility issues*. + @Comment { } + + @Image(source: "Chicken BBQ", alt: "Cell of Chicken BBQ with image, title, ingredients and price") + } + + @Steps { + @Step { + Why it is problematic for VoiceOver to adapt such interface? + + The thing is that **the focus works such way so it outlines *every* single element of a cell**. + + Pay attention that **images are hidden from VoiceOver *by default***, therefore are *inaccessible* to be focused on. + + The first thing put into the focus is **the title**. + + @Image(source: "DescribeCell_1", alt: "Focus outlines title") + } + + @Step { + After a swipe to the right the focus moves to **the list of the ingredients**. + + @Image(source: "DescribeCell_2", alt: "Focus outlines ingredients") + } + + @Step { + Same way the next swipe will move the focus to **the price button**. + + > Note: The *only* possibility **for a user to understand that this element is interactive by hearing VoiceOver say that's it's a *button***. It can be made possible by specifying its `.button` trait. + + @Image(source: "DescribeCell_3", alt: "Focus outlines button with price") + } + + @Step { + In such case the number of the swipes needed to go through a single cell is three. This is *too* many. + + @Code(name: "Several cells and wrong rhyme", file: "DescribeCell_3_0.swift") + } + + @Step { + Moreover such discretion leads to a decrease in *comrehensibility*: users can easily **lose track of what pizza in particular they are going through at the moment**. + + @Code(name: "Several cells and wrong rhyme", file: "DescribeCell_3_1.swift") { + @Image(source: "DescribeCell_3_3", alt: "Focus outlines button with price") + } + } + + @Step { + For example, *the price button* may be percieved connected to the next title. + + @Code(name: "Several cells and wrong rhyme", file: "DescribeCell_3_2.swift") { + @Image(source: "DescribeCell_3_3", alt: "Focus outlines button with price") + } + } + + @Step { + + Voice Control and Switch Control experience same problems too. They prioritise *interactive buttons* and as a result **the only label shown will be the price button's *label***. To press the whole cell users would have to, for example, pronounce *«Tap From AED thirty»*. + + > Tip: The solution here is to **use *the title* as the cell's *label***. + + @Image(source: "DescribeCell_4", alt: "Voice Control show badge over button with price") + } + } + } + + @Section(title: "Describe cell") { + @ContentAndMedia { + In order to **properly describe the cell for VoiceOver** we have to transfer the text from *labels* to the *accessibility description* of the cell in a correct order and with a correct type. Let's take a closer look. + + @Image(source: "DescribeCell_9_preview", alt: "Reading order is controlled by designer") + } + + @Steps { + @Step { + We will start with a simple cell with an explicit ViewModel. + + @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_6.swift") + } + + @Step { + First of all we *specify that the cell will be a *focusable element***. By doing that we *reduce* the number of elements available on the screen. + + There is no need to *explicitly* hide other elements - setting the cell with `accessibleElements` property is enough. How exactly it works is described in in great detail. + + @Comment { + // TODO: why the cell's button is visible at pizza? + } + + @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_7.swift") + } + + @Step { + As mentioned previously **the title** will take place in `accessibilityLabel`. **Ingredients** go to the `accessibilityValue` property. + + @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_8.swift") + + @Comment { + // TODO: Add Voice Control screenshot + } + } + + @Step { + + Also there is *the price* which is an essential part of such cells. + + To adapt it correctly we need follow the strategy controlled by the cell's design. Its **image is what *attracts the attention***, then **title is read and understood *loud and clear*** - it's on top and visually distinguished by a bolder font used. Furtherly the attention may be *interrupted* by a **bright coloured button**. **Ingredients are least prior** to the attention and this is in their nature: this elements is of an *informative matter*. + + Logically **we place the price *after* the title**. Pay attention that **to keep label simple the price has to be put in the beginning of `accesibilityValue`**. + + @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_9.swift") { + @Image(source: "DescribeCell_9_preview", alt: "Reading order is controlled by designer") + } + } + + @Step { + To conclude description **the interactive element has to have its `.button` trait specified*. + + @Code(name: "Cell and VoiceOver.swift", file: "DescribeCell_10.swift") + } + } + } + + @Section(title: "Simplify scroll") { + @ContentAndMedia { + In VoiceOver the default **scrolling is implemented by a three-finger swipe** that leads to reading the number of the visible page, for example, *«4 out of 20*». + + **Going through tables of cells functions *exactly* the same way**. For example, *«from 25 to 40 out of 120»* will be said during going through the rows. + + Seemingly there is not much we can do to **simplify the scrolling**, but in reality there is a trick. **Providing description for visible area allows to use commands that increase the *precision* of actions desired to be done**. Like, for example, asking to read all titles of the products which will results in hearing *«Chicken BBQ, Meat King Supreme, Hawaii»*. + + @Image(source: "DescribeCell_11", alt: "Describe screen after scroll") + } + + @Steps { + @Step { + To implement such possibility let's start with `MenuViewController` extension. + + @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_11_0.swift") + } + + @Step { + To add *description* we use `UIScrollViewAccessibilityDelegate` that can be used by any `firstResponder`. + + @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_11.swift") + } + + @Step { + In simpler words our goal is **to provide description for *all* visible cells**. It can be done by starting with the obvious path. + + @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_12.swift") + } + + @Step { + Firstly we **convert *cells* to *models***. + + @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_13.swift") + } + + @Step { + Secondly **the *titles* are extracted**. + + @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_14.swift") + } + + @Step { + The titles are joined in *a single row*, separated by *commas*. + + @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_15.swift") + } + + @Step { + And, as a result, **three-finger swipe will cause the *titles* to be listed outloud**. + + Additionally you can add some quantity expectation after everything described above is done. + @Comment { + // TODO: михаил рубанов что ты делаешь. + } + + @Code(name: "Describe screen after scroll.swift", file: "DescribeCell_16.swift") + + @Comment { + // TODO: Add preview + } + } + } + } + + @Assessments { + @MultipleChoice { + How should be prices located among other elements? + + @Image(source: "Chicken BBQ", alt: "Cell of Chicken BBQ with image, title, ingredients and price") + + @Choice(isCorrect: false) { + ``` + Label: Chicken BBQ, from 30 AED + Value: pizza sauce, mushrooms... + ``` + + @Justification(reaction: "Try again!") { + **VoiceOver *doesn't* distinguish such pieces of data**, but **VoiceControl *has to have* price as a part of the element's label** in order to use it correctly. + } + } + + + @Choice(isCorrect: true) { + ``` + Label: Chicken BBQ, + Value: from 30 AED, pizza sauce, mushrooms... + ``` + + + @Justification(reaction: "That's right!") { + VoiceControl will have a simple label, VoiceOver reads the price before the ingredients (because it's more important). Good job! + } + } + + + @Choice(isCorrect: false) { + + ``` + Label: Chicken BBQ, + Value: pizza sauce, mushrooms..., from 30 AED + ``` + + @Justification(reaction: "That's right!") { + Such case would be a wrong ordered showcase strategy. One has to know the price *before* the ingredients. + } + } + } + + @MultipleChoice { + How to scroll down a table using VoiceOver? + + @Choice(isCorrect: false) { + A regular swipe + + @Justification(reaction: "Try again!") { + Nope, vertical swipes are used for *adjustable elements* and other operations. Swipe from the bottom will close the current application, the one from the top will open Notifications Screen or Control Center. + } + } + + + @Choice(isCorrect: false) { + Two-finger swipe + + @Justification(reaction: "That's right!") { + Two-finger swipe up describes the entire screen *from the top*. + Two-finger swipe down describes the entire screen *from the selected item*. + } + } + + + @Choice(isCorrect: true) { + Three-finger swipe + + @Justification(reaction: "That's right!") { + @Comment { + // миш че за хуйня + } + It's too long to wait for the price when you listen VoiceOver + } + } + + @Choice(isCorrect: false) { + Four finger swipe + + @Justification(reaction: "That's right!") { + Horizontal four-finger swipe switches beetwen applications. + } + } + } + } +} diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2.Advanced/AdjustableTutorial.tutorial b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial similarity index 100% rename from Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2.Advanced/AdjustableTutorial.tutorial rename to Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial From 03a0c4290564dc066b1a8003e995aa2ce6953b11 Mon Sep 17 00:00:00 2001 From: "C." Date: Thu, 25 Jan 2024 12:07:41 +0300 Subject: [PATCH 3/4] minor shit --- .../Tutorials/1. Basic/AdoptingCell.tutorial | 2 +- .../2. Advanced/AdjustableTutorial.tutorial | 32 +++++++++---------- .../Tutorial Table of Contents.tutorial | 27 +++++++++------- 3 files changed, 32 insertions(+), 29 deletions(-) diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1. Basic/AdoptingCell.tutorial b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1. Basic/AdoptingCell.tutorial index 0ccabf3..9d627be 100644 --- a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1. Basic/AdoptingCell.tutorial +++ b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/1. Basic/AdoptingCell.tutorial @@ -266,7 +266,7 @@ @Justification(reaction: "That's right!") { @Comment { - // миш че за хуйня + / / миш че за хуйня } It's too long to wait for the price when you listen VoiceOver } diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial index 68bc689..7b26f6b 100644 --- a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial +++ b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial @@ -1,11 +1,11 @@ @Tutorial(time: 10) { - @Intro(title: "Setup adjustable elements") { + @Intro(title: "Setting Up Adjustable Elements") { Simplifies interactions with complex elements for VoiceOver. } - @Section(title: "Basic setup") { + @Section(title: "Basic Setup") { @ContentAndMedia { - By default any element can contains ``Book/accessibilityValue`` to expose additional data for user. Some elements come complicated and can contain dynamic value, controlled by vertical swipe. Examples: + By default any element can contain ``Book/accessibilityValue`` to expose *additional data* to user. Some elements come complicated and may contain a *dynamic value* controlled by a vertical swipe. Here some examples: } @Steps { @@ -22,9 +22,9 @@ } @Step {` - As a result the element will react on vertical swipe by calling ``Book/accessibilityIncrement()`` and ``Book/accessibilityDecrement()``. + As a result the element will react on a vertical swipe by calling ``Book/accessibilityIncrement()`` and ``Book/accessibilityDecrement()``. - After each swipe the ``Book/accessibilityValue`` getter will be reread and the new value will be spoken out. + After each swipe the ``Book/accessibilityValue`` getter will be read again and the next value will be vocalised. > Note: `AccessibilityLabel wouldn't be read again after swipe` @@ -33,24 +33,24 @@ } } - @Section(title: "Backward compatibility") { + @Section(title: "Backward Compatibility") { @ContentAndMedia { - Voice Control and Switch Control don't fit to adjustable elements and works best like separate buttons. + VoiceControl and SwitchControl work with separate *buttons* instead of *adjustable elements*. } @Steps { @Step { - > Important: Adjustable elements is useful only for VoiceOver and will brake behaviour for Voice Control and Switch Control. + > Important: Adjustable elements are only used for VoiceOver and will break the behaviour of VoiceControl and SwitchControl. - Distinguish behaviour in code by dynamic getter: + Distinguish their behaviour in code by a dynamic getter: @Code(name: "", file: "AdjustableTutorialStep_4.swift") } @Step { - Switch Control requires grouping: first time focus will be placed on group, after selection will move between elements in group. As a result it simulates navigation by reducing number of elements on each level. + SwitchControl requires grouping: firstly focus will be placed on the group itself, afterwards the selection will be moved between elements of this group. It simulates navigation by reducing the number of elements on each level. - > Note: Watch video [how grouping simplify navigation](https://youtube.com/shorts/1l8H615EkV0?si=tKyhIGjBbR9XG9HP) + > Note: Watch video [How Grouping Simplifies Navigation](https://youtube.com/shorts/1l8H615EkV0?si=tKyhIGjBbR9XG9HP) @Code(name: "", file: "AdjustableTutorialStep_5.swift") } @@ -59,14 +59,14 @@ @Assessments { @MultipleChoice { - What assistive technologies uses adjustable trait + What assistive technologies use adjustable trait? @Choice(isCorrect: false) { - Switch Control + SwitchControl @Justification(reaction: "Try again!") { - Switch Controls requires grouping, to simplify navigation, but uses ``Book/accessibilityNavigationStyle`` for that. + SwitchControl indeed requires grouping to simplify navigation, but uses ``Book/accessibilityNavigationStyle`` for that. } } @@ -75,7 +75,7 @@ @Justification(reaction: "That's right!") { - Blind person would like to reduce number of elements on screen and simplify interactions by vertical swipe to adjust the value of the element + Blind people would like to have a reduced number of elements on the screen and simplified interactions by vertical swipes to adjust the value of the element. } } @@ -84,7 +84,7 @@ @Justification(reaction: "Try again!") { - Voice Control uses person who can see and they prefer to see elements as separate buttons + VoiceControl is mostly used by people who are able to see. In such case percieving elements as separate buttons is preferred. } } } diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial index 1e61e7f..df5fa8d 100644 --- a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial +++ b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial @@ -1,26 +1,29 @@ -@Tutorials(name: "How to adopt your application") { - @Intro(title: "Few steps") { +@Tutorials(name: "How To Adapt Your application") { + @Intro(title: "Just A 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 + To make an application accessible for the assistive technology and therefore allow people with Accessibility Features enabled comfortably use it one doesn't have to do much. The adaptation plan is as simple as: + + 1. Simplify and group elements in UI's hierarchy + 2. Add labels to elements + 3. Add additional properties + + Yep, that's it. In other words the adaption process is consisted of an optional reconstructing of already-existing elements' order and their description with some flags explicitly specified. } @Volume(name: "Getting Started") { - @Chapter(name: "Adopting cell") { - Simplifies navigation and control over a complex element for VoiceOver + @Chapter(name: "Adopting Cell") { + Simplifies navigation and control over a complex element for VoiceOver. @Image(source: "Chicken BBQ", alt: "Cell of Chicken BBQ with image, title, ingredients and price") @TutorialReference(tutorial: "doc:AdoptingCell") } - @Chapter(name: "Control hierarchy") { - Simplifies navigation and control over a complex element for VoiceOver + @Chapter(name: "Control Hierarchy") { + Also simplifies navigation and control over a complex element for VoiceOver. @@ -29,7 +32,7 @@ } @Volume(name: "Climbing higher") { - @Chapter(name: "Adjustable elements") { + @Chapter(name: "Adjustable Elements") { Simplifies navigation and control over a complex element for VoiceOver @@ -37,7 +40,7 @@ @TutorialReference(tutorial: "doc:AdjustableTutorial") } - @Chapter(name: "Tweak visual properties") { + @Chapter(name: "Tweak Visual Properties") { Simplifies navigation and control over a complex element for VoiceOver From 2bc3024ecad8b24b51e6abb9d7ddcbe58f980f89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=9C=8C=EF=B8=8F=28=C2=B4=E3=83=AE=60=29?= Date: Fri, 26 Jan 2024 05:50:27 +0000 Subject: [PATCH 4/4] Update AdjustableTutorial.tutorial Co-authored-by: Mikhail Rubanov --- .../Tutorials/2. Advanced/AdjustableTutorial.tutorial | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial index 7b26f6b..49b8abd 100644 --- a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial +++ b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/2. Advanced/AdjustableTutorial.tutorial @@ -66,7 +66,7 @@ @Justification(reaction: "Try again!") { - SwitchControl indeed requires grouping to simplify navigation, but uses ``Book/accessibilityNavigationStyle`` for that. + Switch Control indeed requires grouping to simplify navigation, but uses ``Book/accessibilityNavigationStyle`` for that. } }