diff --git a/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Integration/Basic/Describe/AccessibilityAttributes/AccessibilityAttributes.tutorial b/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Integration/Basic/Describe/AccessibilityAttributes/AccessibilityAttributes.tutorial index 14f3f9c..0c0e607 100644 --- a/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Integration/Basic/Describe/AccessibilityAttributes/AccessibilityAttributes.tutorial +++ b/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Integration/Basic/Describe/AccessibilityAttributes/AccessibilityAttributes.tutorial @@ -1,41 +1,50 @@ @Tutorial(time: 15) { - @Intro(title: "Describing Interface For Assistive Technology") { + @Intro(title: "Describing Interface for Accessibility API") { In this tutorial we're going to discuss unquestionably the most important thing to make an interface accessible — properly **describe its elements** for both users and assistive technology. ## What elements are considered accessible? To enable [accessibility applications]() work as intended for a particular *element* it has to have *certain properties* specified. Sometimes elements inherit such information by default — if they are of an *accessible class* (like [`UIButton`](https://developer.apple.com/documentation/uikit/uibutton)), but most of the times we have to manually set properties for the items present on the screen to make it not only *function*, but *be pleasant* to use. - Let's grab a coffee and go over *core* attributes of [`UIAccessibilityElement`](https://developer.apple.com/documentation/uikit/uiaccessibilityelement) to figure out **why** and **when** we should use them. + To know more about how Accessibility API decides whether the element is accessible, take a step back to [**Accessibility in Code**](). + + Once you know what is an accessible element, let's grab a coffee and go over their *core* attributes of to figure out **why** and **when** we should specify them. } @Section(title: "Label") { @ContentAndMedia { - We are going to deal with `Label` and `Value` at the same time as they are similar in their nature: both are *localised strings* and of *informative purpose*. Firstly, let's take a closer look at each of them. + We are going to deal with `Label` and `Value` at the same time as they are similar in their nature: both are *localised strings* and of *informative purpose*. To start with, let's take a closer look at each of them. - ### Label — Identification - [`accessibilityLabel`](https://developer.apple.com/documentation/uikit/uiaccessibilityelement/1619577-accessibilitylabel) is the *main property* of the element's description. It is said that `Label` "succinctly identifies the element", which is, translated to human-readable language, means that **users must be able to get everything they need to get about the element by only hearing its label**. Or *call* this exact element by calling its name. Depends on the technology used. + ### Label — Identification, a Name + `Label` is the *main property* of the element's description. It is said that `Label` "succinctly identifies the element", which is, translated to human-readable language, means that **users must be able to get everything they need to get about the element by only hearing its label**. Or *call* this exact element by calling its name. Depends on the technology used. @Video(source: coffee) } @Steps { @Step { - Let's start with elements that are *purely informative*, such as "Drink Name" text on a drink page. + Let's start with elements that are *purely informative*, such as "Drink Name" text on a drink page. How should we call it? @Image(source: americano-view-name, alt: "") } @Step { - Since there is nothing more than a *very specific* piece of data stored in the element we **use its `Value` as `Label`**. + Since there is nothing more than a *very specific* piece of data stored in the element we **use its "value" as `Label`**. @Image(source: americano-view-name-label, alt: "") } @Step { - There is `accessibilityValue` property, but in this particular case it is **unreasonable** to separate the fact that it's "name" and its name into two different properties. It would be an **inconvenient* experience for users. - + -- But there is `Value` property! Shouldn't we put this information there? + @Image(source: americano-view-name-verbosity, alt: "") + } + @Step { + A sharp notice. In this particular case it is **unreasonable** to separate the fact that it's "name" and its name into two different properties. It would be an **inconvenient experience** for users. + @Image(source: americano-view-name-verbosity, alt: "") + } + @Step { + Deciding between `Label` and `Value`, remember that the former one is a required attribute for any accessibility element. An accessible element may have no value, but having no label makes the element inaccessible. @Image(source: americano-view-name-verbosity, alt: "") } } @@ -45,19 +54,19 @@ @ContentAndMedia { ### Value — Details - Then there is [`accessibilityValue`](https://developer.apple.com/documentation/objectivec/nsobject/1615117-accessibilityvalue). Basically this property is used to store any *additional information* about the element that is unnecessary for `Label` to contain. + Then there is `accessibilityValue`. Basically, this property is used to store any *additional information* about the element that is unnecessary for `Label` to contain, i.e. excessive for element's identification. @Video(source: coffee) } @Steps { @Step { - Now comes a little bit of *complexity*. An element that represents a song in a music player — there is *lots* of data to be described. + This adds a little bit of *depth* to our description. An element that represents a song in a music player — there is *lots* of data to be described. @Image(source: chapter-placeholder.png, alt: "") } @Step { - To *succinctly identify* the song we will risk to use its name as `Label`. + To *succinctly identify* the song we will risk to use its name as `Label`. Nothing else is needed to recognise this song among other correctly. @Image(source: placeholder-image.png, alt: "") } @@ -69,7 +78,7 @@ } @Step { - And... this is it for "plain" elements. To continue pocking at accessible elements' properties let's move to the next one and see how its presence affects already familiar `Label` and `Value`. + And... this is it for "informative" elements. Those elements who only provide output and do not trigger any program behaviour. To continue pocking at accessible elements' properties let's move to the next one and see how its interactiity affects already familiar `Label` and `Value`. @Image(source: placeholder-image.png, alt: "") } @@ -78,11 +87,9 @@ @Section(title: "Label vs Value") { @ContentAndMedia { - ### Fine Line Between Label And Value + ### Fine line between label and value To properly adapt an interface for various [**Accessibility Features**]() one has to clearly differentiate between these two traits. For example, `Label` is heavily exploited by [`Voice Control`]() and has to be independent of unnecessary information to avoid ambiguity. In the meantime `Value` is that part of element's description that is changeable by [`AdjustableTrait`]()'s usage. - - To learn how to fluently use these traits let's work on some more exemplary elements. - + @Video(source: coffee) } @@ -105,11 +112,11 @@ @Section(title: "Traits") { @ContentAndMedia { - A value stored in [`accessibilityTraits`](https://developer.apple.com/documentation/objectivec/nsobject/1615202-accessibilitytraits) property points at the *functionality* of the element. By the default it is [`none`](https://developer.apple.com/documentation/uikit/uiaccessibilitytraits/1620179-none) and means that the element is plain and textual and there is nothing you can do about it. Same behaviour is implemented by explicitly stated [`staticText`](https://developer.apple.com/documentation/uikit/uiaccessibilitytraits/1620206-statictext) trait - it only exists for convenience so it is easier for humans to comprehend the role of the element. + A value stored in `Traits` property points at the *functionality* of an element. By the default it is `none` and means that the element is plain and textual and there is nothing you can do about it. Same behaviour is implemented by explicitly stating `staticText` trait - it only exists for convenience so it is easier for humans to comprehend the role of the element. (Use it.) - If an element has *more* than --none-- purely informative role **it has to be specified in this property** by stating one of [`UIAccessibilityTraits`](https://developer.apple.com/documentation/uikit/uiaccessibilitytraits) so users and assistive technology know how to deal with this item. + If an element has *more* than --none-- purely informative role **it has to be specified in this property** by stating one of [`UIAccessibilityTraits`](https://developer.apple.com/documentation/uikit/uiaccessibilitytraits) so both users and assistive technology know how to deal with this item. - To see the complete list of traits available visit the [**Traits**]() tutorial - it has an example of each them. + To see the complete list of traits available visit the [**Traits**]() tutorial - it has a living example of each them. @Video(source: traits-scroll) } diff --git a/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/Accessibility/Accessibility.md b/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/Accessibility/a11yTerminology.md similarity index 99% rename from Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/Accessibility/Accessibility.md rename to Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/Accessibility/a11yTerminology.md index 048398a..ef12425 100644 --- a/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/Accessibility/Accessibility.md +++ b/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/Accessibility/a11yTerminology.md @@ -1,5 +1,7 @@ # Digital Accessibility +Accessibility **terminology** crash course + @Metadata { @PageColor(blue) @TitleHeading("What Are We Even Talking About") diff --git a/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/iOS Accessibility/AccessibilityInCode.md b/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/iOS Accessibility/AccessibilityInCode.md new file mode 100644 index 0000000..630c057 --- /dev/null +++ b/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/iOS Accessibility/AccessibilityInCode.md @@ -0,0 +1,81 @@ +# Accessibility in Code + +How accessibility is **programmed** + +@Metadata { + @PageColor(blue) + @TitleHeading("Same Result, Different Means") + @PageImage( + purpose: icon, + source: "swift", + alt: "") + @PageImage( + purpose: card, + source: "placeholder-image", + alt: "") + @CallToAction( + url: "https://www.apple.com/accessibility/", + purpose: link, + label: "General Knowledge") +} + +Here we are, knowing what are things like *screen readers*, interface *controls* and *colour blindness*. If you're not sure that you are familiar with the **terminology** used visit the following pages to have a cohesive picture. + +### Featured +@Links(visualStyle: list) { + - + - + - + +} + +## Mobile applications +**Application** is a computer **program**, commonly designed to carry out a certain *task* for a user. In other words, it is a piece of **code** communicating with its users via a **user interface**. + +### User interface +A **user interface** is a part of this program: regardless of where and how the interface was designed, its implementation always results in a piece of **code**. + +### UI frameworks +Talking about iOS, there are two frameworks purposed to build user interfaces for iOS applications: **UIKit** and **SwiftUI**. + +### UIKit +**UIKit** is a classic UI framework that has been there for ages. Written on **Objective-C** (predecessor of **Swift**), imperative, clumsy, and, most importantly, widely recognised. Which means it is researched in **great detail** and has tons of **documentation** of drastically different **interfacial solutions**. + +### SwiftUI +On the other hand, **SwiftUI** is a *relatively* new product of Apple, introduced in 2019. Written on **Swift** (just like this book), declarative, human-readable and elegant. Not as well-documented as the former one, but it doesn't mean that SwiftUI doesn't solve the same problems. + +### Frameworks dichotomy +Even though Apple transfers all their **system interfaces** to SwiftUI day by day, the amount of applications written with UIKit is **prevailing**. Moreover, UIKit's life is to be stopped in the observable future, so, we have to discuss interfaces built with both SwiftUI and UIKit. + +### Interfaces monotomy +And it's not a problem at all. All concepts of accessible interfaces are shared not only between different frameworks, but platforms. Thus accessibility can be adopted by any interface as far as you know what to do. + +## What to do + +Whether an interface is accessible is decided by properties of its components on their own and properties of the interface as a whole. The accessibility has to be built with accessible components by accessible tools, following an accessible design. + +### Accessible elements +Element is an abstraction of a unit of an interface. A button, a text, a thin decorative line that separates texts, an image, an icon, a sounds -- everything singular is considered an element. Other terms used include items, patterns and components. + +In UIKit, an accessible element is an element that conforms to `UIAccessibility` protocol. Standard views inherit the conformance from `UIView` class, so using default elements like `UIControls` will enable accessibility API to recognise the element as an accessible one. + +Creation of custom interface elements might mean that the implicit inclusion of `UIAccessibilityElement` instance to the subclass, which is your custom UIView, is required. Otherwise the element won't be accessible either for assistive technology or its users. + +In SwiftUI the situation is slightly different due to its declarative syntax. Every `View` is an accessible element, but there is nothing to access by default: + +``` swift +func accessibilityElement(children: + AccessibilityChildBehavior = .ignore + ) -> some View +``` + +To enable a correct accessible representation of your element in SwiftUI you have to provide all the data needed to be exposed to the accessibility API. It is done by modifiers. + +## Accessibility tree +Regardless of the framework, the accessibility API constructs accessible element hierarchy -- Accessibility Tree -- the same way for both UIKit and SwiftUI. Whether the element is accessible is decided by its own accessibility or accessibility of its content: if a `View` is a container for other interfacial elements (`Subviews`), the accessibility API will check every child before rendering the verdict. + +## Accessibility attributes +Every element of an interface can be given attributes that affect the behaviour of assistive technology. Accessibility attributes are in essence an accessible description of an element, that provides sufficient data of the semantic structure of the element to accessibility API. + +### Tutorials start here +As accessibility professionals, we have to speak the semantic language fluently, so our next stop will be discussing accessibility attributes, its purpose and implementation. With code samples of both frameworks. diff --git a/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/iOS Accessibility/UIFrameworks.md b/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/iOS Accessibility/UIFrameworks.md deleted file mode 100644 index dbcf7c9..0000000 --- a/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/Introduction/Theory/iOS Accessibility/UIFrameworks.md +++ /dev/null @@ -1,104 +0,0 @@ -# Accessibility in Code - -How accessibility is programmed - -@Metadata { - @PageColor(blue) - @TitleHeading("Same Result, Different Means") - @PageImage( - purpose: icon, - source: "swift", - alt: "") - @PageImage( - purpose: card, - source: "placeholder-image", - alt: "") - @CallToAction( - url: "https://www.apple.com/accessibility/", - purpose: link, - label: "General Knowledge") -} - -Here we are, knowing what is a screen reader, interface controls and colour blindness. Serious talk starts here. - -Application is a computer program, commonly designed to carry out a certain for a user. In other words, it is a piece of code communicating with its users via a user interface. A user interface is a part of this program, thus also just a code. - -Therefore regardless of where the interface was designed, its implementation always results in a piece of code. - -Talking about iOS, there are two frameworks purposed to build user interfaces for applications: UIKit and SwiftUI. - -UIKit is a classic UI-framework that has been there for decades. Written on Objective-C (predecessor of Swift), imperative, clumsy, and, most importantly, widespread. Researched in great detail, recognised by all. - -SwiftUI is a relatively new product of Apple, introduced in 2019. Written on Swift (just like this book), declarative, human-readable and elegant. - -Even though Apple transfers all their interfaces to SwiftUI day by day, the amount of application written with UIKit is prevailing. Moreover, UIKit's life is not stopping in observable future, so, we will have to discuss interfaces of both SwiftUI and UIKit. - -And it's not a problem at all. All concepts of accessible interfaces shared not only between different frameworks, but platforms. Thus can be implemented on any interface as far as you know what to do. - -Whether an interface is accessible is decided by properties of its components on their own and properties of the interface as a whole. So the accessibility house has to be built with accessible bricks by an accessible blueprint. - -### Accessible elements -Element is an abstraction of a unit of an interface. A button, a text, a thin decorative line that separates texts, an image, an icon, a sounds -- everything singular is an element. - - - - - -> Note: Jepa ↑↓→ ← стрелочки - -> Tip: Jepa - -> Important: Jepa - -> Warning: Jepa - -> Experiment: Jepa - -## UI Frameworks Differences -First | Second | Third | ------ | ------ | ----- | -One || Two | -Three | Four || -Five ||| - -Leading | Center | Trailing | -------: | :----: | :------- | -One || Two | -Three | Four || -Five ||| - -First | Second | Third | Fourth ------ | ------ | ----- | ------ -One | Two | Three | Four -^ | Five | ^ | Six -Seven | ^ | ^ | Eight - -First | Second | Third ------ | ------ | ----- -One || Two -^ || Three - -| Sloth speed | Description | -| ------------ | ------------------------------------ | -| `slow` | Moves slightly faster than a snail | -| `medium` | Moves at an average speed | -| `fast` | Moves faster than a hare | -| `supersonic` | Moves faster than the speed of sound | - -@TabNavigator { - @Tab("First") { - Jepa. - @Image(source: placeholder-image, alt: "") - } - - - @Tab("Second") { - Jepa? - } - - - @Tab("Third") { - Jepa. - } -} -## Здесь нужно буквально пару параграфов про дихотомию фреймворков и как одни и те же аксесибилити решения работают в обоях (одинаково) diff --git a/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/iOSAccessibilityHandbook.md b/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/iOSAccessibilityHandbook.md index 8df70b8..af28ae3 100644 --- a/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/iOSAccessibilityHandbook.md +++ b/Sources/iOSAccessibilityHandbook/iOSAccessibilityHandbook.docc/Pages/iOSAccessibilityHandbook.md @@ -79,16 +79,9 @@ Illustrative materials created exclusively for the book can be found [**here**]( ## Topics ### Introduction -- - - -### Interface Theory -- -- - -### General Knowledge -- -- +- +- ### Assistive Technology - @@ -101,13 +94,5 @@ Illustrative materials created exclusively for the book can be found [**here**]( - - -### Accessibility in Code -- - ### Integrating Accessibility - - -### Miscellaneous -- -- -