[#818] Update typography and colors documentation (#833)

changelog.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - \[App\] Update checkboxes and switches components demo by showing only one element ([#666](https://github.com/Orange-OpenSource/ods-android/issues/666))
 - \[App\] Replace `OdsListItem` lines counter customization by choice chips allowing secondary text lines count customization ([#799](https://github.com/Orange-OpenSource/ods-android/issues/799))
 - \[Doc\] Update About module integration instructions ([#815](https://github.com/Orange-OpenSource/ods-android/issues/815))
+- \[Doc\] Update colors and typography documentations ([#818](https://github.com/Orange-OpenSource/ods-android/issues/818))
 - \[Lib\] Update i18n keys ([#752](https://github.com/Orange-OpenSource/ods-android/issues/752))
 - \[Lib\] Update `OdsChoiceChipsFlowRow` to have less vertical space between elements ([#758](https://github.com/Orange-OpenSource/ods-android/issues/758))
 - \[Lib\] Change `OdsListItem` API by replacing `singleLineSecondaryText` boolean parameter by an enum called `secondaryTextLineCount` ([#777](https://github.com/Orange-OpenSource/ods-android/issues/777))

docs/guidelines/Colors.md

@@ -5,48 +5,40 @@ title: Colors
 
 ---
 
-**Page Summary**
+<br>**On this page**
 
 * Table of contents
 {:toc}
 
 ---
 
-
 ## Specifications references
 
 - [Design System Manager - Colour](https://system.design.orange.com/0c1af118d/p/623630-colour/b/041102)
 - [Material Design - The color system](https://material.io/design/color/the-color-system.html#color-usage-and-palettes)
 
 ## Implementation in Jetpack Compose
 
-### Theme colors
+As ODS library supports multi-theme, the available colors are managed by a class (`OdsColors`) which is instantiated by the theme itself. In other words, the theme provides colors for the application which uses the ODS library. ODS library components relies on the `OdsColors` defined by the used theme.
+
+The `OdsColors` class contains Material colors, functional colors and some specific components colors which allow the override of default Material behavior. For example, in Material a top app bar has a primary color background. With ODS library you can choose another color for your top app bar background and this will be defined in your theme components colors.
 
-ODS library provides MaterialTheme colors. You can use these colors by using `MaterialTheme.colors`:
+ODS library colors can be used by calling `OdsTheme.colors`:
 
 ```kotlin
-Text(
-    text = "Hello world",
-    color = MaterialTheme.colors.primary
+Icon(
+    painter = painterResource(id = R.drawable.ic_chevron_down),
+    contentDescription = null,
+    tint = OdsTheme.colors.onSurface
 )
 ```
 
-### Functional colors
-
-Functional colors have been added and can also be used as above:
-- `MaterialTheme.colors.functionalPositive`
-- `MaterialTheme.colors.functionalInfo`
-- `MaterialTheme.colors.functionalAlert`
-
-Note: These colors will be different depending on whether they are displayed in light or in dark mode.
+You can use the following **functional colors** in your application:
 
-### Other colors from Orange Design System
+- `OdsTheme.colors.functional.positive` and `OdsTheme.colors.functional.onPositive`
+- `OdsTheme.colors.functional.negative` and `OdsTheme.colors.functional.onNegative`
+- `OdsTheme.colors.functional.info`
+- `OdsTheme.colors.functional.alert`
 
-All the other colors defined in the library can be used directly through their names:
-
-```kotlin
-Text(
-    text = "Hello world",
-    color = Pink100
-)
-```
+Note that all colors will be different depending on whether they are displayed in light or in dark mode.
+Keep in mind that each theme provides colors for light and dark mode so avoid to use "static" colors directly like `Orange100` in your code cause the orange will be probably not the same in light and dark to keep an high contrast in the two modes.

docs/guidelines/Typography.md

@@ -5,7 +5,7 @@ title: Typography
 
 ---
 
-**Page Summary**
+<br>**On this page**
 
 * Table of contents
 {:toc}
@@ -19,29 +19,43 @@ title: Typography
 
 ## Implementation in Jetpack Compose
 
-### TextStyles
+As ODS library supports multi-theme, the available typography is managed by a class (`OdsTypography`) which is instantiated by the theme itself. It has a default constructor with the values used by Orange.
+The theme provides typography for the application which uses the ODS library. ODS library components relies on the `OdsTypography` defined by the used theme.
 
-ODS library uses the Material type system.
-TextStyles are accessed via `MaterialTheme.typography`. Retrieve the TextStyles like so:
+Through the `OdsTypography` class, you can set the `fontFamily` which will be applied to the typography text styles and you can define text styles you want to be in capitals by adding it into the `allCapsTextStyles` list.
+
+We recommend you to use `OdsText` composable and provide an `OdsTextStyle` to display texts:
+
+```kotlin
+OdsText(
+    text = "Hello",
+    style = OdsTextStyle.BodyL,
+)
+```
+
+However, you can directly use ODS typography in a `Text` composable as shown below:
 
 ```kotlin
 Text(
-    text = "Subtitle2 styled",
-    style = MaterialTheme.typography.titleS
+    text = "Hello",
+    style = OdsTheme.typography.bodyL,
 )
 ```
 
-### OdsText composables
+### OdsText composable
 
-ODS library also provides `OdsText` composables already using specific styles. They are here to simplify the code you write.
+ODS library also provides `OdsText` composable which is here to simplify the code you write.
 
-For example, to display a text styled with subtitle2 typo, you can write:
+The two differences between `OdsText` and `Text` are:
 
-```kotlin
-OdsTextSubtitle2(text = "Subtitle2 styled")
-```
+- `OdsText` uses theme text colors automatically taking into account the parameters provided like the `enabled` one,
+- `OdsText` takes directly an `OdsTextSyle` as parameter and manage all caps text style if needed (an `OdsTextStyle` can be set all caps in the `OdsTypography` of the theme).
 
-Optional parameters are:
-- a `Modifier`
-- an `OdsDisplaySurface` which allow to force elements appearance to be displayed on light or dark surface.
+Example of use:
 
+```kotlin
+OdsText(
+    text = "Big title",
+    style = OdsTextStyle.HeadlineL
+)
+```

theme-contract/src/main/java/com/orange/ods/theme/colors/OdsColors.kt

@@ -24,7 +24,7 @@ import androidx.compose.runtime.setValue
  * Default components' colors are based on the provided [materialColors] but you can override these colors by providing your colors for each component. As an
  * example, if you need to change the switches' colors you can provide your own [OdsSwitchColors] in the ODS color system.
  */
-open class OdsColors(
+class OdsColors(
     val materialColors: Colors,
     functionalColors: OdsFunctionalColors,
     private var componentColors: OdsComponentColors

theme-contract/src/main/java/com/orange/ods/theme/typography/OdsTypography.kt

@@ -17,8 +17,16 @@ import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.unit.sp
 
+/**
+ * ODS typography system.
+ *
+ * The ODS typography system can help you create an ODS typography theme that reflects your brand or style.
+ * By default, the ODS typography is built with Orange values but you can override these values in your theme as you want.
+ * The [fontFamily] applied to the typography text styles can be changed and you can define text styles you want to be in capitals by adding it into
+ * the [allCapsTextStyles] list.
+ */
 class OdsTypography(
-    defaultFontFamily: FontFamily = FontFamily.Default,
+    fontFamily: FontFamily = FontFamily.Default,
     headlineL: TextStyle = TextStyle(
         fontWeight = FontWeight.Bold,
         fontSize = 34.sp,
@@ -95,16 +103,16 @@ class OdsTypography(
     private val allCapsTextStyles: List<TextStyle>
 
     init {
-        this.headlineL = headlineL.withDefaultFontFamily(defaultFontFamily)
-        this.headlineS = headlineS.withDefaultFontFamily(defaultFontFamily)
-        this.titleL = titleL.withDefaultFontFamily(defaultFontFamily)
-        this.titleM = titleM.withDefaultFontFamily(defaultFontFamily)
-        this.titleS = titleS.withDefaultFontFamily(defaultFontFamily)
-        this.bodyL = bodyL.withDefaultFontFamily(defaultFontFamily)
-        this.bodyM = bodyM.withDefaultFontFamily(defaultFontFamily)
-        this.bodyS = bodyS.withDefaultFontFamily(defaultFontFamily)
-        this.labelL = labelL.withDefaultFontFamily(defaultFontFamily)
-        this.labelS = labelS.withDefaultFontFamily(defaultFontFamily)
+        this.headlineL = headlineL.withDefaultFontFamily(fontFamily)
+        this.headlineS = headlineS.withDefaultFontFamily(fontFamily)
+        this.titleL = titleL.withDefaultFontFamily(fontFamily)
+        this.titleM = titleM.withDefaultFontFamily(fontFamily)
+        this.titleS = titleS.withDefaultFontFamily(fontFamily)
+        this.bodyL = bodyL.withDefaultFontFamily(fontFamily)
+        this.bodyM = bodyM.withDefaultFontFamily(fontFamily)
+        this.bodyS = bodyS.withDefaultFontFamily(fontFamily)
+        this.labelL = labelL.withDefaultFontFamily(fontFamily)
+        this.labelS = labelS.withDefaultFontFamily(fontFamily)
         this.allCapsTextStyles = allCapsTextStyles.map { textStyle ->
             when (textStyle) {
                 OdsTextStyle.HeadlineL -> this.headlineL

theme-orange/src/main/java/com/orange/ods/theme/orange/OrangeTypography.kt

@@ -23,5 +23,5 @@ private val Roboto = FontFamily(
 )
 
 val OrangeTypography = OdsTypography(
-    defaultFontFamily = Roboto
+    fontFamily = Roboto
 )