[#602] Update documentation with illustrations (#618)

* Add Illustration for buttons * Add illustration for progress indicators * Add illustration for sliders * Add illustration for bars tool * Rename files * Add illustration for nab bar * Add illustration for tab bars * Add illustration for list items * Add missing files * Update changelog Reviewed-by: Pierre-Yves Lapersonne <[email protected]>
Orange-OpenSource · Jan 23, 2024 · 047b249 · 047b249
1 parent b6a99bd
commit 047b249
Show file tree

Hide file tree

Showing 51 changed files with 113 additions and 32 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+- [Docs] Update documentation with illustration ([#602](https://github.com/Orange-OpenSource/ods-ios/issues/602))
 - [DemoApp/Tooling] Update sources header, license file content, build phase and template ([#582](https://github.com/Orange-OpenSource/ods-ios/issues/582))
 - [DemoApp/Tooling] Demo app crashes if no URL defined, CI/CD fails because of unversioned xcconfig file (Bug [#612](https://github.com/Orange-OpenSource/ods-ios/issues/612))
 - [Tooling] Add Fastlane lane to copy Apps Plus credentials in CI/CD chain for nightly and release builds ([#610](https://github.com/Orange-OpenSource/ods-ios/issues/610))

diff --git a/OrangeDesignSystem/Sources/OrangeDesignSystem/Components/Banner/ODSBanner.swift b/OrangeDesignSystem/Sources/OrangeDesignSystem/Components/Banner/ODSBanner.swift
@@ -32,15 +32,14 @@ public struct ODSBanner: View {
     // ==================
 
     /// Initialize the banner with two buttons added under the text.
+    /// Remarks: The default lowest emphasis is automatically applied on buttons.
     ///
     /// - Parameters:
     ///   - text: Text displayed in the banner.
     ///   - imageSource: Image displayed before the text in a circle area. If `nil`, no image will be displayed.
     ///   - firstButton: First (leading) button (text only) added under the text.
     ///   - secondButton: Second (trailing) button (text only) added under the text.
     ///
-    /// - Remarks: The default lowest emphasis is automatically applied on buttons.
-
     public init(_ text: Text,
                 imageSource: ODSImage.Source? = nil,
                 @ViewBuilder firstButton: @escaping () -> Button<Text>,
@@ -53,14 +52,13 @@ public struct ODSBanner: View {
     }
 
     /// Initialize the banner with one button.
+    /// Remarks: The default lowest emphasis is automatically applied on buttons.
     ///
     /// - Parameters:
     ///   - text: Text displayed in the banner.
     ///   - imageSource: Image displayed before the text in a circle area. If `nil`, no image will be displayed.
     ///   - button: Button with text (only) added under the text.
     ///
-    /// - Remarks: The default lowest emphasis is automatically applied on buttons.
-
     public init(_ text: Text,
                 imageSource: ODSImage.Source? = nil,
                 @ViewBuilder button: @escaping () -> Button<Text>)
@@ -76,7 +74,6 @@ public struct ODSBanner: View {
     /// - Parameters:
     ///   - text: Text displayed in the banner.
     ///   - imageSource: Image displayed before the text in a circle area. If `nil`, no image will be displayed.
-    ///
     public init(_ text: Text, imageSource: ODSImage.Source? = nil) {
         self.text = text
         self.imageSource = imageSource

diff --git a/docs/_data/data_menus.yml b/docs/_data/data_menus.yml
@@ -19,11 +19,11 @@ toc2:
       - page: Banners
         url: components/banners_docs
       - page: Bars - navigation
-        url: components/navigationBar_docs
+        url: components/barsNavigation_docs
       - page: Bars - tab
-        url: components/tabBar_docs
+        url: components/barsTab_docs
       - page: Bars - tool
-        url: components/toolBar_docs
+        url: components/barsTool_docs
       - page: Buttons
         url: components/buttons_docs
       - page: Cards

diff --git a/docs/components/navigationBar.md → docs/components/barsNavigation.md b/docs/components/navigationBar.md → docs/components/barsNavigation.md
@@ -28,6 +28,9 @@ Please follow [accessibility criteria for development](https://a11y-guidelines.o
 
 ## Standard navigation bar
 
+![Navigation bar standard light](images/bars_navigation_standard_light.png)
+![Navigation bar standard dark](images/bars_navigation_standard_dark.png)
+
 When using a navigation view, basic navigation is using 'inline' display mode by default. 
 
 ```swift
@@ -42,6 +45,9 @@ NavigationView {
 
 ## Navigation bar with large title
 
+![Navigation bar large light](images/bars_navigation_large_light.png)
+![Navigation bar large dark](images/bars_navigation_large_dark.png)
+
 Use 'large' display mode to enable large titles when scrolling up.
 
 ```swift
@@ -56,6 +62,10 @@ NavigationView {
 
 ## Navigation bar with search bar
 
+![Navigation bar search light](images/bars_navigation_search_light.png)
+![Navigation bar search dark](images/bars_navigation_search_dark.png)
+
+
 Use .searchable modifier to add a search bar in the navigation view.
 
 ```swift
@@ -73,6 +83,9 @@ NavigationView {
 
 ## Navigation bar with action item
 
+![Navigation bar items light](images/bars_navigation_items_light.png)
+![Navigation bar items dark](images/bars_navigation_items_dark.png)
+
 You can add one or several buttons (trailing or leading) in the navigation view by using .toolbar modifier
 
 ```swift

diff --git a/docs/components/barsNavigation_docs.md b/docs/components/barsNavigation_docs.md
@@ -0,0 +1,4 @@
+---
+layout: main
+content_page: barsNavigation.md
+---
diff --git a/docs/components/tabBar.md → docs/components/barsTab.md b/docs/components/tabBar.md → docs/components/barsTab.md
@@ -25,6 +25,9 @@ Please follow [accessibility criteria for development](https://a11y-guidelines.o
 
 ## Standard tab bar
 
+![Tab bar light](images/bars_tab_light.png)
+![Tab bar dark](images/bars_tab_dark.png)
+
 Tab bar is a standard iOS component. It uses bar items to navigate between views.
 Bar Item contains an icon and a title.
 An additonal badge can be also added with a count value or a text.

diff --git a/docs/components/barsTab_docs.md b/docs/components/barsTab_docs.md
@@ -0,0 +1,4 @@
+---
+layout: main
+content_page: barsTab.md
+---
diff --git a/docs/components/toolBar.md → docs/components/barsTool.md b/docs/components/toolBar.md → docs/components/barsTool.md
@@ -33,6 +33,8 @@ A tool bar allows users to do specific actions regarding the entire page. It is
 
 ### With label items
 
+![tool bar labels light](images/bars_tool_labels_light.png) ![tool bar labels dark](images/bars_tool_labels_dark.png)
+
 A tool bar can display 2 to 3 label entries.
 
 Example with 3 label entries in toolBar :
@@ -60,6 +62,8 @@ NavigationView {
 
 ### With icon items
 
+![tool bar icons light](images/bars_tool_icons_light.png) ![tool bar icons dark](images/bars_tool_icons_dark.png)
+
 A tool bar can display 2 to 5 icon controls
 ```swift
 

diff --git a/docs/components/barsTool_docs.md b/docs/components/barsTool_docs.md
@@ -0,0 +1,4 @@
+---
+layout: main
+content_page: barsTool.md
+---
diff --git a/docs/components/buttons.md b/docs/components/buttons.md
@@ -32,14 +32,53 @@ Please follow [accessibility criteria for development](https://a11y-guidelines.o
 
 Button variants range in style to denote emphasis. Use different styles and not size to show the preferred choice. 
 
+- **Layout**
+
+**Large**
+
+![Buttons high emphasis disabled](images/buttons_layout_large_with_icon.png)
+
+![Buttons high emphasis](images/buttons_layout_large_without_icon.png)
+
+**Small**
+
+![Buttons high emphasis disabled](images/buttons_layout_small_with_icon.png)
+
+![Buttons high emphasis](images/buttons_layout_small_without_icon.png)
+
+
+- **Emphasis**
+
+**High emphasis**
+
+![Buttons high emphasis disabled](images/buttons_functionnal_disabled.png)
+![Buttons high emphasis](images/buttons_emphasis_high.png)
+
+**Medium**
+
+![Buttons medium emphasis disabled](images/buttons_functionnal_disabled.png)
+![Buttons medium emphasis](images/buttons_emphasis_medium.png)
+
+**Low emphasis**
+
+![Buttons low emphasis disabled](images/buttons_functionnal_disabled.png)
+![Buttons low emphasis](images/buttons_emphasis_low.png)
+
+**Lowest emphasis**
+
+![Buttons lowest emphasis disabled](images/buttons_emphasis_lowest_disabled.png)
+![Buttons lowest emphasis](images/buttons_emphasis_lowest.png)
+
+- **Implementation**
+
 ```swift
 // High emphasis
-ODSButton(text: "Some text",
+ODSButton(text: Text("Some text"),
           image: Image("Add"),
           emphasis: .high) {}
 
 // Lowest emphasis
-ODSButton(text: "Some text",
+ODSButton(text: Text("Some text"),
           image: Image("Add"),
           emphasis: .lowest) {}
 ``` 
@@ -48,30 +87,42 @@ ODSButton(text: "Some text",
 
 If required, colour versions can also be used to inform users of positive or negative destructive actions.
 
+**Positive**
+
+![Buttons functional positive disabled](images/buttons_functionnal_disabled.png) 
+![Buttons functional positive](images/buttons_functional_positive.png)
+
+**Negative**
+
+![Buttons functional negative disabled](images/buttons_functionnal_disabled.png)
+![Buttons functional negative](images/buttons_functional_negative.png)
+
 ```swift
     // Negative button
-    ODSFunctionalButton(text: "Some text", style: .negative) 
+    ODSFunctionalButton(text: Text("Some text"), style: .negative) 
     { /* action: Do something */ }
 
-    ODSFunctionalButton(text: "Some text", image: Image("Add"), style: .negative)
+    ODSFunctionalButton(text: Text("Some text"), image: Image("Add"), style: .negative)
     { /* action: Do something */ }
 
     // Positive button
-    ODSFunctionalButton(text: "Some text", style: .positive)
+    ODSFunctionalButton(text: Text("Some text") style: .positive)
     { /* action: Do something */ }
 
-    ODSFunctionalButton(text: "Some text", image: Image("Add"), style: .positive)
+    ODSFunctionalButton(text: Text("Some text"), image: Image("Add"), style: .positive)
     { /* action: Do something */ }
 
     // To disable the button
-    ODSFunctionalButton(text: "Some text", style: .positive) { /* action: Do something */ }
+    ODSFunctionalButton(text: Text("Some text"), style: .positive) { /* action: Do something */ }
     .disabled(true)
 ```
 
 ### Icon button
 
 Plain buttons are the most ubiquitous component found throughout applications. Consisting an icon, they are the most simple button style.
 
+![Buttons icon](images/buttons_icon.png)
+
 ```swift
 // icon with system asset
 ODSIconButton(image: Image(systemName: "info.circle")) {}

diff --git a/docs/components/cards.md b/docs/components/cards.md
@@ -140,7 +140,7 @@ ODSCardHorizontal(
 The small card if prefered for two-column portrait mobile screen display.
 As it is smaller than full-width cards, it contains only title and subtitle (optional) in one line (Truncated tail).
 
-![CardSmall](images/card_small_light.png) ![CardSmall dark](images/card_small_dark.png)
+![Small card light](images/card_small_light.png) ![Small card dark](images/card_small_dark.png)
 
 > **Implementation**
 

diff --git a/docs/components/images/activity_indicator.png b/docs/components/images/activity_indicator.png
diff --git a/docs/components/images/bars_navigation_items_dark.png b/docs/components/images/bars_navigation_items_dark.png
diff --git a/docs/components/images/bars_navigation_items_light.png b/docs/components/images/bars_navigation_items_light.png
diff --git a/docs/components/images/bars_navigation_large_dark.png b/docs/components/images/bars_navigation_large_dark.png
diff --git a/docs/components/images/bars_navigation_large_light.png b/docs/components/images/bars_navigation_large_light.png
diff --git a/docs/components/images/bars_navigation_search_dark.png b/docs/components/images/bars_navigation_search_dark.png
diff --git a/docs/components/images/bars_navigation_search_light.png b/docs/components/images/bars_navigation_search_light.png
diff --git a/docs/components/images/bars_navigation_standard_dark.png b/docs/components/images/bars_navigation_standard_dark.png
diff --git a/docs/components/images/bars_navigation_standard_light.png b/docs/components/images/bars_navigation_standard_light.png
diff --git a/docs/components/images/bars_tab_dark.png b/docs/components/images/bars_tab_dark.png
diff --git a/docs/components/images/bars_tab_light.png b/docs/components/images/bars_tab_light.png
diff --git a/docs/components/images/bars_tool_icons_dark.png b/docs/components/images/bars_tool_icons_dark.png
diff --git a/docs/components/images/bars_tool_icons_light.png b/docs/components/images/bars_tool_icons_light.png
diff --git a/docs/components/images/bars_tool_labels_dark.png b/docs/components/images/bars_tool_labels_dark.png
diff --git a/docs/components/images/bars_tool_labels_light.png b/docs/components/images/bars_tool_labels_light.png
diff --git a/docs/components/images/buttons_emphasis_high.png b/docs/components/images/buttons_emphasis_high.png
diff --git a/docs/components/images/buttons_emphasis_low.png b/docs/components/images/buttons_emphasis_low.png
diff --git a/docs/components/images/buttons_emphasis_lowest.png b/docs/components/images/buttons_emphasis_lowest.png
diff --git a/docs/components/images/buttons_emphasis_lowest_disabled.png b/docs/components/images/buttons_emphasis_lowest_disabled.png
diff --git a/docs/components/images/buttons_emphasis_medium.png b/docs/components/images/buttons_emphasis_medium.png
diff --git a/docs/components/images/buttons_functional_negative.png b/docs/components/images/buttons_functional_negative.png
diff --git a/docs/components/images/buttons_functional_positive.png b/docs/components/images/buttons_functional_positive.png
diff --git a/docs/components/images/buttons_functionnal_disabled.png b/docs/components/images/buttons_functionnal_disabled.png
diff --git a/docs/components/images/buttons_icon.png b/docs/components/images/buttons_icon.png
diff --git a/docs/components/images/buttons_layout_large_with_icon.png b/docs/components/images/buttons_layout_large_with_icon.png
diff --git a/docs/components/images/buttons_layout_large_without_icon.png b/docs/components/images/buttons_layout_large_without_icon.png
diff --git a/docs/components/images/buttons_layout_small_with_icon.png b/docs/components/images/buttons_layout_small_with_icon.png
diff --git a/docs/components/images/buttons_layout_small_without_icon.png b/docs/components/images/buttons_layout_small_without_icon.png
diff --git a/docs/components/images/list_items_selection_circle_dark.png b/docs/components/images/list_items_selection_circle_dark.png
diff --git a/docs/components/images/list_items_selection_circle_light.png b/docs/components/images/list_items_selection_circle_light.png
diff --git a/docs/components/images/list_items_standard_square_dark.png b/docs/components/images/list_items_standard_square_dark.png
diff --git a/docs/components/images/list_items_standard_square_light.png b/docs/components/images/list_items_standard_square_light.png
diff --git a/docs/components/images/progress_bar.png b/docs/components/images/progress_bar.png
diff --git a/docs/components/images/sliders.png b/docs/components/images/sliders.png
diff --git a/docs/components/listItem.md b/docs/components/listItem.md
@@ -43,9 +43,12 @@ The leading icon is :
 
 ### Standard list item 
 
- For standard items, trailing icons can be added. Two types of icons are proposed:
-    - with text 
-    - with text and info button to make an action
+For standard items, trailing icons can be added. Two types of icons are proposed:
+- with text 
+- with text and info button to make an action
+
+![List item standard square light](images/list_items_standard_square_light.png)
+![List item standard square dark](images/list_items_standard_square_dark.png)
 
 The standard item can be used in a `NavigationLink` (for example, display more details)
 
@@ -87,6 +90,9 @@ List {
 
 ### Selection list item
 
+![List item slection circle light](images/list_items_selection_circle_light.png)
+![List item slection circle dark](images/list_items_selection_circle_dark.png)
+
 The selection list items can be used to enumerate data as list in order to select elements.
 
 ```swift

diff --git a/docs/components/navigationBar_docs.md b/docs/components/navigationBar_docs.md
diff --git a/docs/components/progressIndicator.md b/docs/components/progressIndicator.md
@@ -29,12 +29,14 @@ Please follow [accessibility criteria for development](https://a11y-guidelines.o
 
 Progress indicators show users that elements or pages are loading.
 
-### Progress bars
+### Progress bar
 
 Progres bar is used to display **determinate** operations. It display the indicator increasing in width from 0 to 100% of the track, in sync with the process’s progress. 
 
 To display the indicator as progress bar with a specific color use the `tint`.
 
+![Progress bar](images/progress_bar.png)
+
 We recommend to use the theme for that using the accent color as shown in following exemple.  
 
 ```swift
@@ -58,6 +60,8 @@ ProgressView(value: value, total: 100) {
 
 Activity indicator is used to display **Indeterminate** operations. It spins while a task is performed. 
 
+![Activity indicator](images/activity_indicator.png)
+
 ```swift
 ProgressView()
 ``` 

diff --git a/docs/components/slider.md b/docs/components/slider.md
@@ -36,6 +36,8 @@ We recommand to not set information on `minimumValueLabel` and `maximumValueLabe
 
 Slider is a system Slider component with accent color set to coreOrange.
 
+![Sliders](images/sliders.png)
+
 ### Unlabeled slider
 
 Unlabelled sliders allow users to make easy selections that do not require any details or context.

diff --git a/docs/components/tabBar_docs.md b/docs/components/tabBar_docs.md
diff --git a/docs/components/toolBar_docs.md b/docs/components/toolBar_docs.md