commit 717550395d515455933c7f81115fe768e514c4eb
parent 71a20478b626a13385fe920726e2f86d977a1708
Author: Vlada Svirsh <svirv1@bfh.ch>
Date: Wed, 16 Jul 2025 20:41:09 +0200
DD 66: Wallet UI color scheme
Diffstat:
2 files changed, 569 insertions(+), 0 deletions(-)
diff --git a/design-documents/066-wallet-color-scheme.rst b/design-documents/066-wallet-color-scheme.rst
@@ -0,0 +1,568 @@
+DD 66: Wallet UI color scheme
+=============================
+
+Summary
+-------
+
+This design document defines the unified color scheme for the GNU Taler Wallet, based on the Material Design 3 color system. It provides semantic color roles used across the wallet UI for consistency, accessibility, and maintainability.
+
+The document outlines the purpose and application of each color role in the UI design system.
+
+Motivation
+----------
+
+The wallet UI currently lacks a consistent and documented color strategy. As the application grows and adds more features, visual coherence and accessibility become increasingly important.
+
+By adopting Material 3 semantics and defining roles like ``primary``, ``onPrimary``, ``success``, ``errorContainer``, etc., the UI gains:
+
+- Consistent appearance across features
+- Easier onboarding for new contributors
+
+Requirements
+------------
+
+- Colors must be defined semantically, not by hex codes directly in UI components.
+- The theme must support both light and dark modes.
+- Roles must maintain WCAG 2.1 AA contrast ratios.
+- Roles must cover error, warning, and success states.
+
+Proposed solution
+-----------------
+
+The color system will be structured using semantic **Material 3 color roles**. Each role is explained below with its usage and associated hex values.
+
+General concepts
+~~~~~~~~~~~~~~~~
+
+- **Primary / Secondary / Tertiary**: Accent colors used to emphasize UI elements.
+- **Container**: A lighter or darker version of an accent color used for background fills (e.g. buttons, chips).
+- **On \***: A foreground color (text/icon) to be placed on top of its paired color.
+- **Surface / Background**: Base UI areas or layout surfaces.
+- **Outline**: Used for strokes, borders, and dividers.
+- **Error / Warning / Success**: Semantic feedback colors.
+- **Dark \***: Role variants used in dark mode.
+
+Color role definitions
+~~~~~~~~~~~~~~~~~~~~~~
+
+Primary
+^^^^^^^
+
+Used for the most important UI elements.
+
+.. list-table::
+ :widths: 20 30 50
+ :header-rows: 1
+
+ * - Role
+ - Hex
+ - Usage
+
+ * - primary
+ - .. raw:: html
+
+ <code>#0042b3</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#0042b3;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Main action color (e.g. filled buttons, tabs, icons)
+
+ * - onPrimary
+ - .. raw:: html
+
+ <code>#ffffff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#ffffff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons placed on top of ``primary``
+
+ * - primaryContainer
+ - .. raw:: html
+
+ <code>#d3deff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#d3deff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Background for FABs, cards, filled fields
+
+ * - onPrimaryContainer
+ - .. raw:: html
+
+ <code>#00134a</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#00134a;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground for ``primaryContainer``
+
+ * - darkPrimary
+ - .. raw:: html
+
+ <code>#b4c5ff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#b4c5ff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - ``primary`` in dark mode
+
+ * - darkOnPrimary
+ - .. raw:: html
+
+ <code>#002a78</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#002a78;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons on ``darkPrimary``
+
+ * - darkPrimaryContainer
+ - .. raw:: html
+
+ <code>#0042b3</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#0042b3;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Container in dark mode
+
+ * - darkOnPrimaryContainer
+ - .. raw:: html
+
+ <code>#e5ebff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#e5ebff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground on container in dark
+
+
+
+Secondary
+^^^^^^^^^
+
+Used for less prominent or supporting elements.
+
+.. list-table::
+ :widths: 20 30 50
+ :header-rows: 1
+
+ * - Role
+ - Hex
+ - Usage
+
+ * - secondary
+ - .. raw:: html
+
+ <code>#586a88</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#586a88;border:1px solid #aaa;margin-left:6px;
+ vertical-align:middle;"></div>
+ - Secondary buttons, chips, and passive UI states
+
+ * - onSecondary
+ - .. raw:: html
+
+ <code>#ffffff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#ffffff;border:1px solid #aaa;margin-left:6px;
+ vertical-align:middle;"></div>
+ - Foreground on ``secondary``
+
+ * - secondaryContainer
+ - .. raw:: html
+
+ <code>#d9e3f9</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#d9e3f9;border:1px solid #aaa;margin-left:6px;
+ vertical-align:middle;"></div>
+ - Background for secondary surfaces
+
+ * - onSecondaryContainer
+ - .. raw:: html
+
+ <code>#111c2b</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#111c2b;border:1px solid #aaa;margin-left:6px;
+ vertical-align:middle;"></div>
+ - Foreground on ``secondaryContainer``
+
+ * - darkSecondary
+ - .. raw:: html
+
+ <code>#a4c9ff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#a4c9ff;border:1px solid #aaa;margin-left:6px;
+ vertical-align:middle;"></div>
+ - Secondary color in dark mode
+
+ * - darkOnSecondary
+ - .. raw:: html
+
+ <code>#00315d</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#00315d;border:1px solid #aaa;margin-left:6px;
+ vertical-align:middle;"></div>
+ - Foreground in dark mode
+
+ * - darkSecondaryContainer
+ - .. raw:: html
+
+ <code>#72a3e5</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#72a3e5;border:1px solid #aaa;margin-left:6px;
+ vertical-align:middle;"></div>
+ - Background container in dark
+
+ * - darkOnSecondaryContainer
+ - .. raw:: html
+
+ <code>#003869</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#003869;border:1px solid #aaa;margin-left:6px;
+ vertical-align:middle;"></div>
+ - Foreground for container in dark
+
+
+
+
+
+Tertiary
+^^^^^^^^
+
+Used for accents, badges, or attention-grabbing components.
+
+.. list-table::
+ :widths: 20 30 50
+ :header-rows: 1
+
+ * - Role
+ - Hex
+ - Usage
+
+ * - tertiary
+ - .. raw:: html
+
+ <code>#338af0</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#338af0;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Used for tags, emphasis markers
+
+ * - onTertiary
+ - .. raw:: html
+
+ <code>#ffffff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#ffffff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons on ``tertiary``
+
+ * - tertiaryContainer
+ - .. raw:: html
+
+ <code>#d1e4ff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#d1e4ff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Input field backgrounds, selected indicators
+
+ * - onTertiaryContainer
+ - .. raw:: html
+
+ <code>#001c39</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#001c39;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons on ``tertiaryContainer``
+
+ * - darkTertiary
+ - .. raw:: html
+
+ <code>#8dd1e5</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#8dd1e5;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Accent color in dark mode
+
+ * - darkOnTertiary
+ - .. raw:: html
+
+ <code>#003641</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#003641;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground in dark
+
+ * - darkTertiaryContainer
+ - .. raw:: html
+
+ <code>#166577</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#166577;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Container fill in dark
+
+ * - darkOnTertiaryContainer
+ - .. raw:: html
+
+ <code>#9ce0f5</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#9ce0f5;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons on dark container
+
+
+Error
+^^^^^
+
+.. list-table::
+ :widths: 20 30 50
+ :header-rows: 1
+
+ * - Role
+ - Hex
+ - Usage
+
+ * - error
+ - .. raw:: html
+
+ <code>#b3261e</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#b3261e;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Main error color for messages or outlines
+
+ * - onError
+ - .. raw:: html
+
+ <code>#ffffff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#ffffff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons on error surfaces
+
+ * - errorContainer
+ - .. raw:: html
+
+ <code>#f9dedc</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#f9dedc;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Background fill for error components
+
+ * - onErrorContainer
+ - .. raw:: html
+
+ <code>#410e0b</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#410e0b;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons on error container
+
+ * - darkError
+ - .. raw:: html
+
+ <code>#ffb4aa</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#ffb4aa;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Error color in dark mode
+
+ * - darkOnError
+ - .. raw:: html
+
+ <code>#690003</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#690003;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground in dark mode
+
+ * - darkErrorContainer
+ - .. raw:: html
+
+ <code>#b3261e</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#b3261e;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Background container in dark
+
+ * - darkOnErrorContainer
+ - .. raw:: html
+
+ <code>#ffcbc4</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#ffcbc4;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground on dark container
+
+
+Success
+^^^^^^^
+
+.. list-table::
+ :widths: 20 30 50
+ :header-rows: 1
+
+ * - Role
+ - Hex
+ - Usage
+
+ * - success
+ - .. raw:: html
+
+ <code>#337a40</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#337a40;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Status indicators, confirmation icons
+
+ * - onSuccess
+ - .. raw:: html
+
+ <code>#ffffff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#ffffff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground on success
+
+ * - successContainer
+ - .. raw:: html
+
+ <code>#2e8534</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#2e8534;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Background for success banners or chips
+
+ * - onSuccessContainer
+ - .. raw:: html
+
+ <code>#f7fff1</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#f7fff1;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons on success container
+
+ * - darkSuccess
+ - .. raw:: html
+
+ <code>#337a40</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#337a40;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Same in dark mode (stable tone)
+
+ * - darkOnSuccess
+ - .. raw:: html
+
+ <code>#ffffff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#ffffff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground for dark mode
+
+ * - darkSuccessContainer
+ - .. raw:: html
+
+ <code>#1d3522</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#1d3522;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Background container in dark
+
+ * - darkOnSuccessContainer
+ - .. raw:: html
+
+ <code>#eaf6ec</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#eaf6ec;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons on dark container
+
+
+Warning
+^^^^^^^
+
+.. list-table::
+ :widths: 20 30 50
+ :header-rows: 1
+
+ * - Role
+ - Hex
+ - Usage
+
+ * - warning
+ - .. raw:: html
+
+ <code>#f99c06</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#f99c06;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Alert banners, passive warnings
+
+ * - onWarning
+ - .. raw:: html
+
+ <code>#000000</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#000000;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground text on warning
+
+ * - warningContainer
+ - .. raw:: html
+
+ <code>#fdedd3</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#fdedd3;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Background fill for warning containers
+
+ * - onWarningContainer
+ - .. raw:: html
+
+ <code>#6b4706</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#6b4706;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground on warning container
+
+ * - darkWarning
+ - .. raw:: html
+
+ <code>#f99c06</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#f99c06;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Warning in dark mode
+
+ * - darkOnWarning
+ - .. raw:: html
+
+ <code>#000000</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#000000;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground in dark
+
+ * - darkWarningContainer
+ - .. raw:: html
+
+ <code>#664200</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#664200;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Background in dark
+
+ * - darkOnWarningContainer
+ - .. raw:: html
+
+ <code>#fdedd3</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#fdedd3;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground on container in dark
+
+
+Background
+^^^^^^^^^^
+
+.. list-table::
+ :widths: 20 30 50
+ :header-rows: 1
+
+ * - Role
+ - Hex
+ - Usage
+
+ * - background
+ - .. raw:: html
+
+ <code>#fdfdff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#fdfdff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - App-wide background color
+
+ * - onBackground
+ - .. raw:: html
+
+ <code>#1a1c1f</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#1a1c1f;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Foreground text/icons on background
+
+ * - darkBackground
+ - .. raw:: html
+
+ <code>#11131a</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#11131a;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Background in dark mode
+
+ * - darkOnBackground
+ - .. raw:: html
+
+ <code>#e2e2eb</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#e2e2eb;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Text/icons in dark mode background
+
+
+Outline
+^^^^^^^
+
+.. list-table::
+ :widths: 20 30 50
+ :header-rows: 1
+
+ * - Role
+ - Hex
+ - Usage
+
+ * - outline
+ - .. raw:: html
+
+ <code>#767880</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#767880;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Used for input borders, field outlines
+
+ * - outlineVariant
+ - .. raw:: html
+
+ <code>#c4c6d0</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#c4c6d0;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+ - Decorative borders, dividers
+
+
+
+Definition of Done
+------------------
+
+- Theming system supports all defined roles
+- All components use semantic color tokens
+- Tokens switch correctly in light/dark mode
+- WCAG 2.1 AA contrast verified
+- Color role documentation added to developer onboarding
+- Feature flag enables color system switch before full rollout
+
+Alternatives
+------------
+
+- Use raw hex codes per component (violates consistency and accessibility)
+- Derive from OS/system color settings (limits branding control)
+
+Drawbacks
+---------
+
+- To be fully and correctly implemented, all ui screeens must be updated with references to the new color roles.
+- Might requires UI refactor to override system styles
+- Slight learning curve for developers unfamiliar with semantic roles
+
+Discussion / Q&A
+----------------
+
+
+
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -77,4 +77,5 @@ Design documents that start with "XX" are considered deprecated.
063-libeufin-conversion-rate-classes
064-kyc-operation-algo
065-exchange-base-url-migration
+ 066-wallet-color-scheme
999-template
