docs: update documentation in DocC catalogs and sources about colors (#124)

Signed-off-by: Pierre-Yves Lapersonne <[email protected]>

Author: pylapp

OUDS/Core/OUDS/Sources/OUDSTheme/OUDSTheme+SemanticTokens/OUDSTheme+ColorSemanticTokens.swift

@@ -25,6 +25,8 @@ import OUDSTokensSemantic
 
 /// Defines basic values common to all themes for `ColorSemanticTokens`.
 /// These values can be overriden inside `OUDSTheme` subclasses (in extensions or not, in the same module or not) thanks to the `@objc open` combination.
+/// Some tokens do not have values assigned in the design system, and must be overriden.
+/// Some tokens must be overiden in `OrangeTheme` side because they rely on Oange brand colors.
 extension OUDSTheme: ColorSemanticTokens {
 
     // MARK: Semantic token - Colors - Background
@@ -33,12 +35,12 @@ extension OUDSTheme: ColorSemanticTokens {
 
     @objc open var colorBackgroundSecondary: ColorSemanticToken { MultipleColorTokens(light: ColorRawTokens.colorFunctionalLightGray80, dark: ColorRawTokens.colorFunctionalDarkGray800) }
 
-    // WARNING: #124 - Colors to use are part of OUDSOran MultipleColorTokens(light: ColorRawTokens., dark: ColorRawTokens.)heme so are not reachable at this level, as a workaround add raw values
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorBackgroundTertiary: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorBackgroundBrandSecondary!") }
 
     @objc open var colorBackgroundEmphasized: ColorSemanticToken { MultipleColorTokens(light: ColorRawTokens.colorFunctionalDarkGray880, dark: ColorRawTokens.colorFunctionalDarkGray640) }
 
-    // WARNING: #124 - Colors to use are part of OUDSOran MultipleColorTokens(light: ColorRawTokens., dark: ColorRawTokens.)heme so are not reachable at this level, as a workaround add raw values
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorBackgroundBrandPrimary: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorBackgroundBrandPrimary!") }
 
     @objc open var colorBackgroundBrandSecondary: ColorSemanticToken { fatalError("🤖 No value defined for colorBackgroundBrandSecondary!") }
@@ -73,8 +75,10 @@ extension OUDSTheme: ColorSemanticTokens {
 
     @objc open var colorBackgroundStatusNegativeEmphasized: ColorSemanticToken { MultipleColorTokens(ColorRawTokens.colorFunctionalScarlet600) }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorBackgroundStatusAccentMuted: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorBackgroundStatusAccentMuted!") }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorBackgroundStatusAccentMutedOnBackgroundEmphasized: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorBackgroundStatusAccentMutedOnBackgroundEmphasized!") }
 
     @objc open var colorBackgroundStatusAccentEmphasized: ColorSemanticToken { MultipleColorTokens(ColorRawTokens.colorFunctionalSun500) }
@@ -93,6 +97,7 @@ extension OUDSTheme: ColorSemanticTokens {
 
     @objc open var colorContentContentDisabledOnBackgroundEmphasized: ColorSemanticToken { MultipleColorTokens(ColorRawTokens.colorFunctionalDarkGray400) }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorContentBrandPrimary: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorContentBrandPrimary!") }
 
     @objc open var colorContentBrandSecondary: ColorSemanticToken { fatalError("🤖 No value defined for colorContentBrandSecondary!") }
@@ -159,8 +164,10 @@ extension OUDSTheme: ColorSemanticTokens {
 
     @objc open var colorBorderFocus: ColorSemanticToken { MultipleColorTokens(light: ColorRawTokens.colorFunctionalWhite, dark: ColorRawTokens.colorFunctionalDarkGray880) }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorBorderBrandPrimaryOnBackgroundEmphasized: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorBorderBrandPrimaryOnBackgroundEmphasized!") }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorBorderBrandPrimary: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorBorderBrandPrimary!") }
 
     @objc open var colorBorderBrandSecondary: ColorSemanticToken { fatalError("🤖 No value defined for colorBorderBrandSecondary!") }
@@ -185,8 +192,10 @@ extension OUDSTheme: ColorSemanticTokens {
 
     // MARK: Semantic token - Colors - Action
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorActionSelected: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorActionSelected!") }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorActionSelectedOnBackgroundEmphasized: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorActionSelectedOnBackgroundEmphasized!") }
 
     @objc open var colorActionDisabled: ColorSemanticToken { MultipleColorTokens(light: ColorRawTokens.colorFunctionalLightGray400, dark: ColorRawTokens.colorFunctionalDarkGray400) }
@@ -205,12 +214,16 @@ extension OUDSTheme: ColorSemanticTokens {
 
     @objc open var colorActionPrimaryHoverOnBackgroundEmphasized: ColorSemanticToken { MultipleColorTokens(ColorRawTokens.colorFunctionalLightGray400) }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorActionPrimaryPressed: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorActionPrimaryPressed!") }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorActionPrimaryPressedOnBackgroundEmphasized: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorActionPrimaryPressedOnBackgroundEmphasized!") }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorActionPrimaryLoading: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorActionPrimaryLoading!") }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorActionPrimaryLoadingOnBackgroundEmphasized: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorActionPrimaryLoadingOnBackgroundEmphasized!") }
 
     @objc open var colorActionPrimaryFocus: ColorSemanticToken { MultipleColorTokens(light: ColorRawTokens.colorFunctionalDarkGray400, dark: ColorRawTokens.colorFunctionalLightGray400) }
@@ -357,6 +370,7 @@ extension OUDSTheme: ColorSemanticTokens {
 
     // MARK: Semantic token - Colors - Decorative
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorDecorativeBrandPrimary: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorDecorativeBrandPrimary!") }
 
     @objc open var colorDecorativeBrandPrimaryMuted: ColorSemanticToken { fatalError("🤖 No value defined for colorDecorativeBrandPrimaryMuted!") }
@@ -433,6 +447,7 @@ extension OUDSTheme: ColorSemanticTokens {
 
     @objc open var colorChartCategoricalNeutral: ColorSemanticToken { MultipleColorTokens(light: ColorRawTokens.colorFunctionalLightGray160, dark: ColorRawTokens.colorFunctionalDarkGray720) }
 
+    // WARNING: #124 - Colors to use are part of Orange Theme so are not reachable at this level, as a workaround add raw values
     @objc open var colorChartCategoricalBrand: ColorSemanticToken { fatalError("🤖 Raw token unavailable for colorChartCategoricalBrand!") }
 
     @objc open var colorChartCategoricalPositive: ColorSemanticToken { MultipleColorTokens(ColorRawTokens.colorFunctionalMalachite500) }

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

@@ -40,8 +40,9 @@ extension YourCustomTheme {
     override var ftiBorderWidth: BorderWidthSemanticToken { borderWidthThick }
 
     // Override colors semantic tokens if needed
-    override var colorBackgroundDefaultPrimaryLight: ColorSemanticToken! { ColorRawTokens.colorFunctionalSun500 }
-    override var colorBackgroundDefaultPrimaryDark: ColorSemanticToken! { ColorRawTokens.colorFunctionalSun800 }
+    override var colorBackgroundPrimary: ColorSemanticToken { 
+        MultipleColorTokens(light: ColorRawTokens.ColorRawTokens.colorFunctionalSun500, dark: ColorRawTokens.ColorRawTokens.colorFunctionalSun800)
+    }
 
     // Etc.
 }
@@ -79,10 +80,9 @@ extension OrangeCustomTheme { // For FormsTextInputComponentTokens, used in comp
     override public var ftiSubtitleFontSize: TypographyFontSizeSemanticToken { fontSizeLabelMedium }
     override public var ftiSubtitleColor: ColorSemanticToken { ColorRawTokens.colorFunctionalMalachite500 }
 
-    override public var ftiBackgroundColorLight: ColorSemanticToken { colorBackgroundDefaultPrimaryLight }
-    override public var ftiBackgroundColorDark: ColorSemanticToken { colorBackgroundDefaultPrimaryDark }
+    override public var ftiBackgroundColor: ColorSemanticToken { colorBackgroundDefault }
 
-    override public var ftiBorderColor: ColorSemanticToken { colorBorderEmphasizedDark ?? MyThemeColorRawTokens.someAwesomeThemeExclusiveColor }
+    override public var ftiBorderColor: ColorSemanticToken { colorBorderEmphasized }
 
     override public var ftiBorderStyle: BorderStyleSemanticToken { borderStyleDrag }
 
@@ -91,8 +91,9 @@ extension OrangeCustomTheme { // For FormsTextInputComponentTokens, used in comp
 
 extension OrangeCustomTheme { // For ColorSemanticTokens using anywhere
 
-    override var colorBackgroundDefaultPrimaryLight: ColorSemanticToken! { ColorRawTokens.colorFunctionalSun500 }
-    override var colorBackgroundDefaultPrimaryDark: ColorSemanticToken! { ColorRawTokens.colorFunctionalSun800 }
+    override var colorBackgroundPrimary: ColorSemanticToken { 
+        MultipleColorTokens(light: ColorRawTokens.ColorRawTokens.colorFunctionalSun500, dark: ColorRawTokens.ColorRawTokens.colorFunctionalSun800)
+    }
 }
 ```
 

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

@@ -63,6 +63,7 @@ struct OUDSFormsTextInput: View {
 
     // ...
     @Environment(\.theme) var theme
+    @Environment(\.colorScheme) var colorScheme
 
     public var body: some View {
         VStack(spacing: theme.spacePaddingBlockComponentTall) {
@@ -82,8 +83,8 @@ struct OUDSFormsTextInput: View {
             TextField(placeholder, text: $value)
         }
         .padding(theme.spacePaddingBlockComponentTall)
-        .background(colorScheme == .light ? theme.ftiBackgroundColorLight.color : theme.ftiBackgroundColorDark.color)
-        .border(theme.ftiBorderColor.color, width: theme.ftiBorderWidth)
+        .background(theme.ftiBorderColor.color(for: colorScheme))
+        .border(theme.ftiBorderColor.color(for: colorScheme), width: theme.ftiBorderWidth)
     }
 }
 ```

OUDS/Core/Themes/Inverse/Sources/InverseTheme+ColorSemanticTokens.swift

@@ -24,6 +24,7 @@ import OUDSTokensSemantic
 // swiftlint:disable file_length
 
 /// Overrides some colors using values defined in extension of `ColorRawTokens` in this current module.
+/// Some tokens do not have values assigned in the design system, and must be overriden.
 extension InverseTheme {
 
     // MARK: Semantic token - Colors - Background

OUDS/Core/Themes/Inverse/Sources/_OUDSThemesInverse.docc/OUDSThemesInverse.md

@@ -7,6 +7,8 @@ This theme overrides the [Orange theme](https://ios.unified-design-system.orange
 This is an override of the [Orange theme](https://ios.unified-design-system.orange.com/documentation/oudsthemesorange/) with some inverted colors.
 It can override any properties from its superclass, and can be derived too.
 
+The aim of the theme is to provide a particular set of colors for dedicated applications and use cases, like for example B2B apps or teams needing eye comfort. It can be seen as an extended dark mode.
+
 ❗**More details coming soon.**❗
 
 ## Topics

OUDS/Core/Themes/Orange/Sources/_OUDSThemesOrange.docc/OUDSThemesOrange.md

@@ -4,7 +4,9 @@ The Orange theme overrides some tokens from the basic `OUDSTheme` and should be
 
 ## Overview
 
-It defines its own colors and override the semantic tokens to use the right colors. This is the default theme any app should used, and can be subclassed to define for example themes dedicated to countries. It embeds also in its target the brand colors which are not shared not exposed in lower level targets.
+It defines its own colors and override the semantic tokens to use the right colors.
+This is the default theme any app should use, and can be subclassed to define for example themes dedicated to countries.
+It embeds also in its target the brand colors which are not shared not exposed in lower level targets.
 
 ## Topics
 

OUDS/Core/Tokens/ComponentTokens/Sources/_OUDSTokensComponent.docc/OUDSTokensComponent.md

@@ -61,8 +61,8 @@ struct OUDSFormsTextInput: View {
             TextField(placeholder, text: $value)
         }
         .padding(theme.spacePaddingBlockComponentTall)
-        .background(colorScheme == .light ? theme.ftiBackgroundColorLight.color : theme.ftiBackgroundColorDark.color)
-        .border(theme.ftiBorderColor.color, width: theme.ftiBorderWidth)
+        .background(theme.ftiBorderColor.color(for: colorScheme))
+        .border(theme.ftiBorderColor.color(for: colorScheme), width: theme.ftiBorderWidth)
     }
 }
 ```

OUDS/README.md

@@ -116,8 +116,8 @@ struct OUDSFormsTextInput: View {
             TextField(placeholder, text: $value)
         }
         .padding(theme.spacePaddingBlockComponentTall)
-        .background(colorScheme == .light ? theme.ftiBackgroundColorLight.color : theme.ftiBackgroundColorDark.color)
-        .border(theme.ftiBorderColor.color, width: theme.ftiBorderWidth)
+        .background(theme.ftiBorderColor.color(for: colorScheme))
+        .border(theme.ftiBorderColor.color(for: colorScheme), width: theme.ftiBorderWidth)
     }
 }
 ```
@@ -246,10 +246,9 @@ extension OrangeCustomTheme { // For FormsTextInputComponentTokens, used in comp
     override public var ftiSubtitleFontSize: TypographyFontSizeSemanticToken { fontSizeLabelMedium }
     override public var ftiSubtitleColor: ColorSemanticToken { ColorRawTokens.colorFunctionalMalachite500 }
 
-    override public var ftiBackgroundColorLight: ColorSemanticToken { colorBackgroundDefaultPrimaryLight }
-    override public var ftiBackgroundColorDark: ColorSemanticToken { colorBackgroundDefaultPrimaryDark }
+    override public var ftiBackgroundColor: ColorSemanticToken { colorBackgroundPrimary }
 
-    override public var ftiBorderColor: ColorSemanticToken { colorBorderEmphasizedDark ?? MyThemeColorRawTokens.someAwesomeThemeExclusiveColor }
+    override public var ftiBorderColor: ColorSemanticToken { colorBorderEmphasized }
 
     override public var ftiBorderStyle: BorderStyleSemanticToken { borderStyleDrag }
 
@@ -258,8 +257,9 @@ extension OrangeCustomTheme { // For FormsTextInputComponentTokens, used in comp
 
 extension OrangeCustomTheme { // For ColorSemanticTokens using anywhere
 
-    override var colorBackgroundDefaultPrimaryLight: ColorSemanticToken! { ColorRawTokens.colorFunctionalSun500 }
-    override var colorBackgroundDefaultPrimaryDark: ColorSemanticToken! { ColorRawTokens.colorFunctionalSun800 }
+    override var colorBackgroundPrimary: ColorSemanticToken { 
+        MultipleColorTokens(light: ColorRawTokens.ColorRawTokens.colorFunctionalSun500, dark: ColorRawTokens.ColorRawTokens.colorFunctionalSun800)
+    }
 }
 ```