Merge pull request #404 from gini/IPC-207-payment-component-ui-custom…

…ization-guide

Ipc 207 payment component UI customization guide

health-sdk/sdk/src/doc/source/customization.rst

@@ -1,33 +1,165 @@
-Customization
-=============
+UI Customization Guide
+======================
 
-Customization is achieved through Android's resourcing system.
-This means that all `resources of the library <https://github.com/gini/gini-mobile-android/tree/main/health-sdk/sdk/src/main/res>`_
-can be overridden by providing resources with the same name in the
-application.
+..
+  Headers:
+  h1 =====
+  h2 -----
+  h3 ~~~~~
+  h4 +++++
+  h5 ^^^^^
 
-When overriding the Health SDK's
-`styles <https://github.com/gini/gini-mobile-android/blob/main/health-sdk/sdk/src/main/res/values/styles.xml>`_
-make sure to keep their name and parent style the same. You can see examples
-of overridden styles in the
-`example app <https://github.com/gini/gini-mobile-android/blob/main/health-sdk/example-app/src/main/res/values/styles.xml>`_.
+.. contents::
+   :depth: 1
+   :local:
 
-Material components are used in the ReviewFragment and those components will pick attributes of the hosting activity
-if it uses a material theme.
+Overview of UI customization options
+------------------------------------
 
-Dark Mode
----------
+Styles
+~~~~~~
 
-To enable and customise dark mode you will need to do the following:
+We leverage the power of Material Design to configure a theme for the SDK with a global color palette and typography
+that is applied on all the screens. By using global styles for the various widgets, we enable you to customize them in a
+single place. They are then consistently applied on all screens.
 
-#. Set the parent of the ``Root.GiniHealth`` style to a DayNight theme as described
-   `here <https://developer.android.com/guide/topics/ui/look-and-feel/darktheme#support-dark-theme>`_:
+Theme
++++++
 
-   .. code-block:: xml
+The theme style is based on Material Design v3 and is named ``GiniHealthTheme``. To override the theme in your
+application, use ``Root.GiniHealthTheme`` as the parent:
 
-       <style name="Root.GiniHealth" parent="Theme.MaterialComponents.DayNight"/>
+.. code-block:: xml
 
-#. Override the Gini Health SDK’s
-   `styles <https://github.com/gini/gini-mobile-android/blob/main/health-sdk/sdk/src/main/res/values/styles.xml>`_,
-   `colors <https://github.com/gini/gini-mobile-android/blob/main/health-sdk/sdk/src/main/res/values/colors.xml>`_
-   and icons for dark mode in night-qualified resource directories (i.e., ``values-night``).
+    <style name="GiniHealthTheme" parent="Root.GiniHealthTheme">
+      (...)
+    </style>
+
+Widgets
++++++++
+
+The style of buttons and other widgets is based on Material Design v3. To override them in your application, use the
+root style as the parent, for example:
+
+.. code-block:: xml
+
+    <style name="GiniHealthTheme.Widget.Button.OutlinedButton" parent="Root.GiniHealthTheme.Widget.Button.OutlinedButton">
+      (...)
+    </style>
+
+.. note::
+
+    If you wish to change the button height please override ``android:minHeight``. We are using ``android:minHeight`` to
+    support text resizing for accessibility.
+
+    You may also force the height to a certain dimension by overriding both
+    ``android:minHeight`` and ``android:height``, although we don't recommend this as it will prevent the button from increasing
+    height to fit larger font sizes.
+
+.. warning::
+
+    Material Design buttons include insets which will decrease the visible height of the buttons. You can override
+    ``android:insetTop`` and ``android:insetBottom`` to remove or adjust the vertical insets.
+
+Colors
+~~~~~~
+
+We provide a global color palette which you are free to override. The custom colors are then applied to all screens.
+Customization of colors is done via overriding of color resources. For example to override the color ``ghs_accent_01`` add
+the following snippet to one of your resources XML file (e.g, ``colors.xml``):
+
+.. code-block:: xml
+
+    <color name="ghs_accent_01">#424242</color>
+
+.. note::
+
+    If you overridde the ``GiniHealthTheme``, the theme colors you set there override the color palette customization.
+
+Find the names of the color resources in the color palette (you can also view it in Figma `here
+<https://www.figma.com/file/AJTss4k0M6R2OxH0VQepdP/Android-Gini-Health-SDK-3.0.0-UI-Customisation?type=design&node-id=8502%3A357&mode=design&t=A1pTQWjJWSBUR6Zi-1>`_): 
+
+.. raw:: html
+
+    <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="600" height="450"
+    src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FAJTss4k0M6R2OxH0VQepdP%2FAndroid-Gini-Health-SDK-3.0.0-UI-Customisation%3Ftype%3Ddesign%26node-id%3D8502%253A357%26mode%3Ddesign%26t%3DA1pTQWjJWSBUR6Zi-1"
+    allowfullscreen></iframe>
+
+|
+
+Images
+~~~~~~
+
+Customizing of images is done via overriding of drawable resources. Find the drawable resource names in the
+screen-by-screen UI customisation sections below. We mostly use vector drawables.
+Due to the limitations of vector drawables, some images had to be added as PNGs.
+
+.. note::
+
+    If you use vector drawables, add them to the ``drawable-anydpi`` and ``drawable-night-anydpi`` folders so that they also
+    override any density specific PNGs.
+
+If you want to override specific SDK images:
+
+1. Add your own images to your app's ``res/drawable-*`` folders using the image names from the UI customization guide.
+   It is important to name the images you wish to override exactly as shown in the UI customization guide, otherwise
+   overriding won't work.
+2. If you use vector drawables, add them to the ``drawable-anydpi`` (``drawable-night-anydpi`` for dark mode) folders so
+   that they also override any density specific images.
+
+Typography
+~~~~~~~~~~~
+
+We provide global typography based on text appearance styles from Material Design v2. To override them in your
+application, use the root style as the parent, for example:
+
+.. code-block:: xml
+
+    <style name="GiniHealthTheme.Typography.Body1" parent="Root.GiniHealthTheme.Typography.Body1">
+       (...)
+    </style>
+
+.. note::
+
+    If you override the ``GiniHealthTheme``, the text appearances you set there override the typography customization. The
+    same applies to the override of widget styles where you set a custom text appearance. 
+
+Preview our typography and find the names of the style resources (you can also view it in Figma `here
+<https://www.figma.com/file/AJTss4k0M6R2OxH0VQepdP/Android-Gini-Health-SDK-3.0.0-UI-Customisation?type=design&node-id=8503%3A491&mode=design&t=zZkiuvx3neNm8Tmv-1>`_):
+
+.. raw:: html
+
+    <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="600" height="450"
+    src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FAJTss4k0M6R2OxH0VQepdP%2FAndroid-Gini-Health-SDK-3.0.0-UI-Customisation%3Ftype%3Ddesign%26node-id%3D8503%253A491%26mode%3Ddesign%26t%3DzZkiuvx3neNm8Tmv-1"
+    allowfullscreen></iframe>
+
+|
+
+Text
+~~~~
+
+Text customization is done via overriding of string resources.
+
+Dark mode
+~~~~~~~~~~
+
+To customize resources for dark mode, add them to resource folders containing the -night resource qualifier.
+
+UI customization options
+------------------------
+
+Payment Component
+~~~~~~~~~~~~~~~~~
+
+You can also view the UI customisation guide in Figma `here
+<https://www.figma.com/file/AJTss4k0M6R2OxH0VQepdP/Android-Gini-Health-SDK-4.0.0-UI-Customisation?type=design&node-id=8663%3A1324&mode=design&t=prjCS8vTcjIzTtvT-1>`_.
+
+.. note::
+
+    To copy text from Figma you need to have a Figma account. If you don't have one, you can create one for free.
+
+.. raw:: html
+
+    <iframe style="border: 1px solid rgba(0, 0, 0, 0.1);" width="600" height="450"
+    src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2FAJTss4k0M6R2OxH0VQepdP%2FAndroid-Gini-Health-SDK-4.0.0-UI-Customisation%3Ftype%3Ddesign%26node-id%3D8663%253A1324%26mode%3Ddesign%26t%3DprjCS8vTcjIzTtvT-1"
+    allowfullscreen></iframe>

health-sdk/sdk/src/main/res/drawable/ghs_payment_details_info_bar_background.xml

@@ -4,5 +4,5 @@
         android:topLeftRadius="@dimen/ghs_medium_12"
         android:topRightRadius="@dimen/ghs_medium_12">
     </corners>
-    <solid android:color="@color/ghs_success"/>
+    <solid android:color="@color/ghs_success_01"/>
 </shape>

health-sdk/sdk/src/main/res/drawable/ghs_payment_input_edit_text_error_background.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <shape android:shape="rectangle" xmlns:android="http://schemas.android.com/apk/res/android">
     <corners android:radius="@dimen/ghs_small"/>
-    <stroke android:color="@color/ghs_error" android:width="1dp"/>
+    <stroke android:color="@color/ghs_feedback_01" android:width="1dp"/>
     <solid android:color="@color/ghs_payment_input_border_color"/>
 </shape>

health-sdk/sdk/src/main/res/values/colors.xml

@@ -22,8 +22,16 @@
     <color name="ghs_light_05">#565656</color>
     <color name="ghs_light_06">#353535</color>
     <color name="ghs_light_07">#212121</color>
-    <color name="ghs_success">#B0B347</color>
-    <color name="ghs_error">#FA1C1C</color>
+
+    <color name="ghs_success_01">#B0B347</color>
+    <color name="ghs_success_02">#D5D6A0</color>
+    <color name="ghs_success_03">#E7E8CD</color>
+    <color name="ghs_success_04">#F2F2E7</color>
+
+    <color name="ghs_feedback_01">#FA1C1C</color>
+    <color name="ghs_feedback_02">#F19597</color>
+    <color name="ghs_feedback_03">#ECD0D0</color>
+    <color name="ghs_feedback_04">#EEDEDE</color>
 
     <color name="ghs_payment_component_caption">@color/ghs_dark_04</color>
     <color name="ghs_bank_selection_bottom_sheet_caption">@color/ghs_dark_03</color>

health-sdk/sdk/src/main/res/values/styles.xml

@@ -142,7 +142,7 @@
         <item name="boxBackgroundColor">@android:color/transparent</item>
         <item name="boxCornerRadiusBottomStart">@dimen/ghs_small</item>
         <item name="boxCornerRadiusBottomEnd">@dimen/ghs_small</item>
-        <item name="errorTextColor">@color/ghs_error</item>
+        <item name="errorTextColor">@color/ghs_feedback_01</item>
     </style>
     <style name="GiniHealthTheme.PaymentInputLayout" parent="Root.GiniHealthTheme.PaymentInputLayout"/>