docs: improve documentation for newcomers (#982) (#1005)

Improve README with details about how to use the product.
Improve DocC documentation for web builds to have things clearer.

Closes #982
Closes #1005

Suggested-by: Thomas Martin <thomas2.martin@orange.com>
Acked-by: Ludovic Pinel <ludovic.pinel@orange.com>
Signed-off-by: Pierre-Yves Lapersonne <pierreyves.lapersonne@orange.com>

Author: pylapp

CHANGELOG.md

@@ -14,6 +14,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Migration to Xcode 26.0 (Orange-OpenSource/ouds-ios#972)
+- Improve README for onboarding and newcomers (Orange-OpenSource/ouds-ios#1005)
+- Improve web documentation for onboarding and newcomers (Orange-OpenSource/ouds-ios#982)
 - Button component `hierarchy` property renamed to `appearance` (Orange-OpenSource/ouds-ios#969)
 
 ## [0.19.0](https://github.com/Orange-OpenSource/ouds-ios/compare/0.18.0...0.19.0) - 2025-09-24

OUDS/Core/OUDS/Sources/_OUDS.docc/GettingStarted.md

@@ -29,15 +29,15 @@ import OUDSThemesOrange // To use the default Orange theme
 import OUDSThemesOrangeInverse // To use the Orange Inverse theme
 import OUDSThemesOrangeBusinessTools // To use the Orange Business Tools theme
 import OUDSThemesSosh // To use the Sosh theme
-import OUDSThemeWireframe // To use the Wireframe theme
+import OUDSThemesWireframe // To use the Wireframe theme
 import OUDSTokensComponent // If you need to override or use directly components tokens
 import OUDSTokenSemantic // If you need to override or use directly semantic tokens
 import OUDSTokensRaw // If you need to override or use directly raw tokens
 ```
 
 ### Chose your theme
 
-The *Orange Unified Design System* framework provides several themes:
+The *Orange Unified Design System* framework provides today five themes:
 
 Theme                     | Description                          
 ------------------------- | ------------------------------------- 
@@ -90,4 +90,4 @@ Wireframe                 | For mockups, prototypes and prooves of concepts wito
     }
 }
 
-> Tip: Keep in mind only one theme can be used within the `OUDSThemeableView`.
+> Tip: Keep in mind only one theme can be used within one `OUDSThemeableView`.

OUDS/Core/OUDS/Sources/_OUDS.docc/Themes.md

@@ -66,16 +66,18 @@ OUDSThemeableView(theme: YourCustomTheme()) {
 
 Some themes like `OrangeTheme`, `OrangeInverse` and `OrangeBusinessTools` can be tuned so as to be more flexible and adapt to some countries
 or affiliates constraints.
-However other themes like `SoshTheme` and `WireframeTheme` cannot be tuned
+However other themes like `SoshTheme` and `WireframeTheme` cannot be tuned.
+
+> Note: Tuning represents the group of "flexibility points" allowed by the Orange Brand to tailor and customize themes for particular contexts.
 
 ### Tuned values
 
 There are few elements which can be tuned. Some tunings have also been defined.
 
-Tunable elements                       | Default values | Orange France | Orange Business | Max It   |                          
--------------------------------------- | -------------- | ------------- | --------------- | -------- |
-rounded corners for buttons            |     false      |    false      |      false      |   true   |
-rounded corners for text inputs        |     false      |    false      |      true       |   true   |
+Tunable elements                       | Default values    | Orange France    | Orange Business    | Max It      |                          
+-------------------------------------- | ----------------- | ---------------- | ------------------ | ----------- |
+rounded corners for buttons            |     ❌ false      |    ❌ false      |      ❌ false      |   ✅ true   |
+rounded corners for text inputs        |     ❌ false      |    ❌ false      |      ✅ true       |   ✅ true   |
 
 ### Tuning usages
 
@@ -96,21 +98,6 @@ The tuning to apply must be done at theme init.
     let maxItTheme = OrangeTheme(tuning: Tuning.MaxIt)
 ```
 
-### "Max it" case
-
-A predefined tuning configuration is also available for "Max it":
-
-```swift
-    let theme = OrangeTheme(tuning: Tuning.MaxIt)
-```
-
-It applies the following settings:
-
-Tunable elements               | Default values                          
------------------------------- | ------------------------------------- 
-rounded corners                | true  
-
-
 ## Define a custom theme if needed
 
 You will have to create a _Swift class_ which will inherit from `OrangeTheme` (if you need Orange brand assets) or `OUDSTheme`.

OUDS/Core/OUDS/Sources/_OUDS.docc/Tokens.md

@@ -5,7 +5,7 @@
     @PageImage(purpose: card, source: "ic_design_token_intro")
 }
 
-Design tokens represent the small, repeated design decisions that make up a design system's visual style. Tokens wrap hard-coded static values, such as hexadecimal codes for color, with self-explanatory names.
+Design tokens represent the small, repeated design decisions that make up a design system's visual style. Tokens wrap hard-coded static values, such as hexadecimal codes for color, with self-explanatory names. They are used to define the look and feel and the style of everything. They are exposed through the themes and can be used as they are.
 
 ## Component tokens
 

OUDS/Core/OUDS/Sources/_OUDS.docc/_OUDS.md

@@ -10,7 +10,7 @@ Do not add @PageImage(purpose: card) because not managed for landing page of onl
 See https://github.com/swiftlang/swift-docc/issues/1283
 -->
 
-The iOS library of *Orange Unified Design System*, the new design system unified and cohesive across all platforms to build Orange mobile applications for everyone everywhere.
+The Apple OS Swift Package of *Orange Unified Design System*, the new design system unified and cohesive across all platforms to build Orange mobile applications for everyone everywhere.
 
 ## Overview
 
@@ -35,6 +35,8 @@ You can get details about the this design system in [the official website unifie
 
 > Important: Orange Unified Design System framework focuses on iOS / iPadOS, other platforms like visionOS, watchOS, macOS and tvOS are not scoped yet.
 
+> Tip: Feel free to submit pull requests if you can improve the support of macOS, visionOS, tvOS and watchOS!
+
 ## Topics
 
 ### Essentials

README.md

@@ -61,6 +61,67 @@ The project is open source (except some assets) and topics like accessibility an
 
 It replaces internal frameworks and also [ODS](https://github.com/Orange-OpenSource/ods-ios) as the only one design system for Orange group and affiliates.
 
+> Important: It brings components and API for *SwiftUI*.
+
+## Quick start
+
+### Add the dependency
+
+First, you must add as _package dependency_ of your _project_ the URL of this _Swift Package_ GitHub repository:
+
+```text
+https://github.com/Orange-OpenSource/ouds-ios
+```
+
+You can choose the _dependency rule_ you want. Keep in mind OUDS iOS releases are frozen and are based on semantic versioning.
+
+### Add the librairies
+
+In your Xcode _targets_, add the librairies you need. Everything is splitted so as to let users choose the content to embed they want.
+In most of cases, the `OUDS` library at least must be imported, it brings abstraction layer.
+Components are available with `OUDSComponents`. Themes are available through their librairies too (`OUDSThemeOrange`, `OUDSThemeSosh`, `OUDSThemeWireframe`, etc.).
+
+You can have more details [in the wiki](https://github.com/Orange-OpenSource/ouds-ios/wiki/30-%E2%80%90-About-the-architecture#the-ouds-ios-swift-package).
+
+### Instanciate and inject theme
+
+In the root view of your app, add the `OUDSThemeableView` with inside the _theme_ object you want to apply.
+You can instanciate the theme object on the fly, but only once.
+
+```swift
+import OUDS
+import SwiftUI
+
+@main
+struct YourApp: App {
+
+    var body: some Scene {
+        WindowGroup {
+            OUDSThemeableView(theme: theTheme) { // theTheme can be: OrangeTheme(), SoshTheme(), WirefameTheme(), etc.
+              AppRootView() // Add your app root view here
+            }
+        }
+    }
+}
+```
+
+Feel free to read the [online documentation](https://ios.unified-design-system.orange.com/documentation/ouds/gettingstarted).
+You can find also [more details about theme instanciations online](https://ios.unified-design-system.orange.com/documentation/ouds/themes).
+
+### Get the theme
+
+If you need to get configuration details from the theme (colors, dimensions, etc.), get the theme through _environment object_:
+
+```swift
+  @Environment(\.theme) var theme
+```
+
+### Use the components
+
+Import the `OUDSComponents` library and instanciate the component you need. All of them are described [in the online documentation (and grouped by categories)](https://ios.unified-design-system.orange.com/documentation/oudscomponents).
+
+The wiki lists also [the components and their availability](https://github.com/Orange-OpenSource/ouds-ios/wiki/01-%E2%80%90-Available-API).
+
 ## Content
 
 > [!NOTE]

docs_release/generateWebDocumentation.sh

@@ -231,7 +231,7 @@ fi
 # Landing page of generated documentation is broken, real content is in /documentation
 # Override this page and force by code redirection
 # See Orange-OpenSource/ouds-ios#636
-echo '<!doctype html><html><head><meta http-equiv="refresh" content="0; URL= https://ios.unified-design-system.orange.com/documentation/"></head><body>Redirecting to https://ios.unified-design-system.orange.com/documentation/</body></html>' > "$DOCUMENTATION_HTML_LOCATION/index.html" 
+echo '<!doctype html><html><head><meta http-equiv="refresh" content="0; URL= https://ios.unified-design-system.orange.com/documentation/ouds"></head><body>Redirecting to https://ios.unified-design-system.orange.com/documentation/ouds</body></html>' > "$DOCUMENTATION_HTML_LOCATION/index.html" 
 
 # Step 5 - Checkout to service pages dedicated branch (if relevant)
 # ------------------------------------------------------------------