commit 2b2699b944ea513bcf85abb391e2a855d8249c0b
parent 3e9602d696641337a5fc53e313669f884661e571
Author: Vlada Svirsh <svirv1@bfh.ch>
Date: Sat, 7 Mar 2026 15:57:40 +0100
DD 90: branding guidelines
Diffstat:
7 files changed, 228 insertions(+), 0 deletions(-)
diff --git a/design-documents/090-branding.rst b/design-documents/090-branding.rst
@@ -0,0 +1,225 @@
+DD 90: Branding Guidelines
+##########################
+
+Summary
+=======
+This document defines visual and UX guidelines for Taler payment pages/components to give user a consistent experience
+across different implementations and platforms.
+
+Motivation
+==========
+Make Taler QR code pages/components recognizable and consistent to increase user trust and confidence when using Taler.
+A consistent payment components also reduce user hesitation and makes troubleshooting easier.
+Provide guidelines for logo usage and provide main colors to be used.
+
+Requirements
+============
+
+Proposed Solution
+=================
+
+Logo
+~~~~
+The Taler logo is the most recognizable visual element of the brand and must be used consistently across all products,
+websites, documents, and payment-related screens. This section defines the approved logo versions, when each version
+should be used, and the rules that protect the logo’s visibility and integrity.
+
+Primary Logo (Light Mode)
+-------------------------
+The primary logo is the default Taler logo version and should be used on light backgrounds whenever possible.
+It is the preferred option for websites, wallet screens, documentation, printed materials etc. with a white or very light surface.
+
+This version should always appear with sufficient contrast against the background so that all logo elements remain clearly visible.
+It must be reproduced exactly as provided in the official assets, without modification to its colors, proportions, or internal spacing.
+
+.. image:: wallet-designs/taler-logo-light.png
+ :alt: Taler Logo - Light Mode
+ :width: 50%
+
+Download logo for light mode: :download:`PNG <wallet-designs/taler-logo-light.png>`, :download:`SVG <wallet-designs/taler-logo-light.svg>`
+
+Logo for Dark Mode
+------------------
+The dark mode logo is a dedicated version of the Taler logo optimized for dark backgrounds. It should be used in wallet dark theme screens,
+dark websites, dark presentation slides, and any surface where the primary light-mode logo would lose visibility or contrast.
+
+Download logo for dark mode: :download:`PNG <wallet-designs/taler-logo-dark.png>`, :download:`SVG <wallet-designs/taler-logo-dark.svg>`
+
+Incorrect usage examples
+------------------------
+The Taler logo must always appear in its approved form. Any distortion or reinterpretation weakens the identity and creates inconsistency across products.
+
+The following uses are not allowed:
+
+- changing the logo colors outside approved variants
+- placing the light-mode logo on a light background with poor contrast
+- placing the dark-mode logo on additional background
+- stretching, compressing, or otherwise distorting the proportions
+- rotating the logo
+- adding shadows, outlines, gradients, or glow effects
+- rearranging the logo symbol and wordmark
+- placing the logo on visually busy backgrounds that reduce readability
+- cropping the logo
+
+Every implementation should use the original source files supplied by the Taler design assets. When in doubt,
+choose the version that gives the highest contrast and clearest presentation while preserving the official logo artwork.
+
+
+Colors
+~~~~~~
+The Taler color system defines the visual foundation of the brand across product interfaces, websites, documentation,
+and payment-related screens. Colors should support clarity, trust, accessibility, and consistency. This section identifies
+the main brand colors that represent Taler visually, as well as secondary colors used to support interface design and communication.
+
+Primary colors
+--------------
+
+The primary color should be used on light backgrounds for the most important brand and interface elements, such as primary actions,
+highlights, and key visual accents.
+
+.. 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>
+
+
+The dark primary color should be used in dark mode interfaces, where the default primary color would not provide the desired
+visual balance or contrast.
+
+.. raw:: html
+
+ <code>#b4c5ff</code> <div style="display:inline-block;width:14px;height:14px;
+ background:#b5c5ff;border:1px solid #aaa;margin-left:6px;vertical-align:middle;"></div>
+
+Secondary colors
+----------------
+
+The secondary color supports the primary color and can be used for less prominent accents, supporting interface elements,
+and complementary highlights.
+
+.. 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>
+
+The dark secondary color should be used in dark mode where the standard secondary color is not suitable.
+
+.. 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>
+
+
+Additional color definitions
+----------------------------
+
+Detailed color values and any future extensions of the palette are available here: :doc:`Color scheme <066-wallet-color-scheme>`.
+
+
+
+Payment QR code design
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: wallet-designs/payment-qr.png
+ :alt: Taler QR code component design
+ :width: 50%
+
+The payment QR code is displayed inside a dedicated rounded frame that occupies ``100%`` of the component size.
+This frame defines the full visible area of the QR payment element and serves as the main reference for all internal proportions.
+
+The frame uses the color ``#F1F1F4``. Inside the frame, the QR code itself is rendered on a white background to preserve maximum
+contrast and scanning reliability.
+
+Frame
+-----
+The QR payment component uses a rounded rectangular frame with the following properties:
+
+- frame size: ``100%``
+- frame background color: ``#F1F1F4``
+- frame shape: rounded rectangle
+- frame corner radius: ``8%`` relative to the frame size
+
+
+QR code
+-------
+.. image:: wallet-designs/payment-qr-1.png
+ :alt: Taler QR code design
+ :width: 50%
+
+The QR code is centered inside the frame and occupies ``87.5%`` of the frame size.
+
+The QR code must always use:
+- white background
+- black QR modules
+- centered placement inside the frame
+
+The QR code background must remain white even though the surrounding frame uses ``#F1F1F4``. This separation ensures good readability and reliable scanning.
+
+Animated lines
+--------------
+
+Two animated lines move clockwise along the outer edge of the QR code frame as a subtle branded accent.
+The animation adds a sense of activity and visual focus while keeping the QR code itself visually stable and easy to scan.
+
+The animated lines have the following properties:
+
+- direction: clockwise
+- stroke width: ``2.6%`` relative to the frame size
+- line height: ``57%`` relative to the frame size
+- color: linear gradient from ``#F1F1F4`` to ``#0042B3`` to ``#F1F1F4``
+- placement: along the inner edge of the frame, between the frame border and the QR code area
+
+Logo inside the QR code
+-----------------------
+.. image:: wallet-designs/payment-qr-2.png
+ :alt: Taler logo placement inside QR code
+ :width: 50%
+
+The Taler logo is placed in the center of the QR code. The logo must always appear together with its dedicated white
+background shape so that it remains visually separated from the QR modules behind it.
+
+The approved asset for this usage is available here: :download:`PNG <wallet-designs/qr-logo.png>`, :download:`SVG <wallet-designs/qr-logo.svg>`.
+
+The total height of the logo together with its white background is ``12.5%`` relative to the frame size.
+
+The logo treatment must always follow these rules:
+- the logo is centered inside the QR code
+- the logo always includes the white background
+- the logo background must match the white QR background
+- the logo must not be recreated manually
+- only the approved asset may be used
+
+Size summary
+------------
+
+The payment QR component uses the following proportions:
+
+- frame size: ``100%``
+- QR code size: ``87.5%``
+- animation width: ``2.6%``
+- logo with background height: ``12.5%``
+
+
+
+Test Plan
+=========
+
+(If this DD concerns a new or changed feature, describe how it can be tested.)
+
+Definition of Done
+==================
+
+(Only applicable to design documents that describe a new feature. While the
+DoD is not satisfied yet, a user-facing feature **must** be behind a feature
+flag or dev-mode flag.)
+
+Alternatives
+============
+
+Drawbacks
+=========
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/design-documents/index.rst b/design-documents/index.rst
@@ -101,4 +101,5 @@ Design documents that start with "XX" are considered deprecated.
087-wallet-onboarding
088-wallet-withdraw
089-merchant-2fa
+ 090-branding
999-template
diff --git a/design-documents/wallet-designs/payment-qr-1.png b/design-documents/wallet-designs/payment-qr-1.png
Binary files differ.
diff --git a/design-documents/wallet-designs/payment-qr-2.png b/design-documents/wallet-designs/payment-qr-2.png
Binary files differ.
diff --git a/design-documents/wallet-designs/payment-qr.png b/design-documents/wallet-designs/payment-qr.png
Binary files differ.
diff --git a/design-documents/wallet-designs/qr-logo.png b/design-documents/wallet-designs/qr-logo.png
Binary files differ.
diff --git a/design-documents/wallet-designs/qr-logo.svg b/design-documents/wallet-designs/qr-logo.svg
@@ -0,0 +1 @@
+<svg width="200" xmlns="http://www.w3.org/2000/svg" height="95" id="screenshot-b8718ead-4592-805f-8007-a9ef55f0a41b" viewBox="0 0 200 95" xmlns:xlink="http://www.w3.org/1999/xlink" fill="none" version="1.1"><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a41b"><g class="frame-container-wrapper"><g class="frame-container-blur"><g class="frame-container-shadows"><g fill="none"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a41b"><rect width="200" height="95" class="frame-background" x="0" transform="matrix(1.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000)" style="fill: rgb(255, 255, 255); fill-opacity: 1;" ry="47.5" rx="47.5" y="0"/></g><g class="frame-children"><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a41c" width="670" height="300" rx="0" ry="0" style="fill: rgb(0, 0, 0);"><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a41d" style="display: none;"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a41d"><rect width="180" height="80.76923076923094" x="10" transform="matrix(1.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000)" style="fill: none;" ry="0" fill="none" rx="0" y="7.115384615384301"/></g></g><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a41e" rx="0" ry="0" style="fill: rgb(0, 0, 0);"><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a424"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a424"><path d="M87.60791015625,8.12158203125C101.56881713867188,8.12158203125,113.69378662109375,16.55859375,119.81179809570312,28.943603515625L114.60223388671875,28.943603515625C108.9432373046875,19.34130859375,98.96926879882812,12.96484375,87.60791015625,12.96484375C69.97454833984375,12.96484375,55.679962158203125,28.32177734375,55.679962158203125,47.265380859375C55.679962158203125,56.53759765625,59.105865478515625,64.94921875,64.67062377929688,71.121826171875C63.468505859375,72.1279296875,62.188629150390625,73.031494140625,60.841827392578125,73.8203125C54.84014892578125,66.8427734375,51.1715087890625,57.515380859375,51.1715087890625,47.265380859375C51.1715087890625,25.64697265625,67.48464965820312,8.12158203125,87.60791015625,8.12158203125ZM119.71417236328125,65.7861328125C113.56512451171875,78.06298828125,101.49423217773438,86.409423828125,87.60791015625,86.409423828125C86.66519165039062,86.409423828125,85.73080444335938,86.370849609375,84.80609130859375,86.29541015625C87.53939819335938,84.894287109375,90.10183715820312,83.171875,92.45233154296875,81.17333984375C101.69497680664062,79.661865234375,109.63381958007812,73.891845703125,114.48382568359375,65.7861328125Z" style="fill-rule: evenodd; stroke: none; stroke-width: 0.327943; fill: rgb(0, 66, 179); fill-opacity: 1;"/></g></g><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a425"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a425"><path d="M67.50363159179688,8.12158203125C68.44625854492188,8.12158203125,69.380615234375,8.16015625,70.305419921875,8.235595703125C67.57211303710938,9.63671875,65.00958251953125,11.35888671875,62.659088134765625,13.357666015625C47.324951171875,15.865234375,35.575653076171875,30.091064453125,35.575653076171875,47.265380859375C35.575653076171875,60.06689453125,42.10455322265625,71.228759765625,51.77911376953125,77.1220703125C50.351959228515625,77.362060546875,48.8892822265625,77.4873046875,47.399322509765625,77.4873046875C46.289306640625,77.4873046875,45.19500732421875,77.416015625,44.118560791015625,77.281494140625C36.14129638671875,70.10107421875,31.067230224609375,59.32080078125,31.067230224609375,47.265380859375C31.067230224609375,25.64697265625,47.38037109375,8.12158203125,67.50363159179688,8.12158203125ZM72.34814453125,81.17333984375C81.5909423828125,79.661865234375,89.52969360351562,73.8916015625,94.3797607421875,65.78564453125L99.61007690429688,65.78564453125C93.46109008789062,78.062744140625,81.39016723632812,86.409423828125,67.50363159179688,86.409423828125C66.56088256835938,86.409423828125,65.62661743164062,86.370849609375,64.70181274414062,86.29541015625C67.4349365234375,84.89404296875,69.99777221679688,83.172119140625,72.34814453125,81.17333984375ZM94.497802734375,28.943603515625C91.6864013671875,24.174072265625,87.81045532226562,20.2001953125,83.22808837890625,17.40869140625C84.65524291992188,17.1689453125,86.11785888671875,17.04345703125,87.60791015625,17.04345703125C88.71786499023438,17.04345703125,89.81222534179688,17.114990234375,90.888671875,17.249267578125C94.485107421875,20.486572265625,97.49151611328125,24.455810546875,99.70870971679688,28.943603515625Z" style="fill-rule: evenodd; stroke: none; stroke-width: 0.327943; fill: rgb(0, 66, 179); fill-opacity: 1;"/></g></g><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a426"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a426"><path d="M47.399322509765625,8.12158203125C48.352447509765625,8.12158203125,49.296783447265625,8.161376953125,50.23150634765625,8.238525390625C47.5032958984375,9.637451171875,44.945098876953125,11.356689453125,42.59844970703125,13.35107421875C27.242950439453125,15.839111328125,15.47137451171875,30.074951171875,15.47137451171875,47.265380859375C15.47137451171875,66.208984375,29.766082763671875,81.56591796875,47.399322509765625,81.56591796875C58.68267822265625,81.56591796875,68.59854125976562,75.277587890625,74.27731323242188,65.78564453125L79.50582885742188,65.78564453125C73.35687255859375,78.062744140625,61.285888671875,86.409423828125,47.399322509765625,86.409423828125C27.276123046875,86.409423828125,10.963043212890625,68.884033203125,10.963043212890625,47.265380859375C10.963043212890625,25.64697265625,27.276123046875,8.12158203125,47.399322509765625,8.12158203125ZM74.39288330078125,28.943603515625C73.218017578125,26.950927734375,71.857666015625,25.096435546875,70.337158203125,23.40966796875C71.53936767578125,22.40380859375,72.81900024414062,21.49951171875,74.1656494140625,20.7109375C76.29071044921875,23.181640625,78.12283325195312,25.947021484375,79.60369873046875,28.943603515625Z" style="fill-rule: evenodd; stroke: none; stroke-width: 0.327943; fill: rgb(0, 66, 179); fill-opacity: 1;"/></g></g></g><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a41f"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a41f"><path d="M78.18096923828125,37.995361328125L86.3848876953125,37.995361328125L86.3848876953125,33.469482421875L65.39480590820312,33.469482421875L65.39480590820312,37.995361328125L73.59881591796875,37.995361328125L73.59881591796875,61.259765625L78.18096923828125,61.259765625Z"/></g></g><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a420"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a420"><path d="M92.96798706054688,54.550537109375L105.19992065429688,54.550537109375L107.82388305664062,61.259765625L112.62802124023438,61.259765625L101.24588012695312,33.27099609375L97.03329467773438,33.27099609375L85.651123046875,61.259765625L90.30743408203125,61.259765625ZM103.53701782226562,50.222900390625L94.63125610351562,50.222900390625L99.06564331054688,39.10693359375Z"/></g></g><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a421"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a421"><path d="M120.87139892578125,33.469482421875L116.76959228515625,33.469482421875L116.76959228515625,61.259765625L135.17013549804688,61.259765625L135.17013549804688,56.853271484375C130.4039306640625,56.853271484375,125.63763427734375,56.853271484375,120.87139892578125,56.853271484375Z"/></g></g><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a422"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a422"><path d="M159.07958984375,33.469482421875L139.93722534179688,33.469482421875L139.93722534179688,61.259765625L159.264404296875,61.259765625L159.264404296875,56.853271484375L144.445556640625,56.853271484375L144.445556640625,49.428955078125L157.41665649414062,49.428955078125L157.41665649414062,45.0224609375L144.445556640625,45.0224609375L144.445556640625,37.876220703125L159.07958984375,37.876220703125Z"/></g></g><g id="shape-b8718ead-4592-805f-8007-a9ef55f0a423"><g class="fills" id="fills-b8718ead-4592-805f-8007-a9ef55f0a423"><path d="M181.21524047851562,42.541259765625C181.21524047851562,43.976806640625,180.73483276367188,45.121826171875,179.767822265625,45.968505859375C178.80709838867188,46.822265625,177.5074462890625,47.245361328125,175.87518310546875,47.245361328125L169.20486450195312,47.245361328125L169.20486450195312,37.876220703125L175.83828735351562,37.876220703125C177.54434204101562,37.876220703125,178.86849975585938,38.2666015625,179.80490112304688,39.053955078125C180.74722290039062,39.8349609375,181.21524047851562,40.999267578125,181.21524047851562,42.541259765625ZM186.64749145507812,61.259765625L179.6632080078125,50.739013671875C180.5745849609375,50.474365234375,181.40618896484375,50.09765625,182.15771484375,49.607666015625C182.908935546875,49.1181640625,183.55581665039062,48.5224609375,184.09768676757812,47.8212890625C184.63983154296875,47.11962890625,185.06466674804688,46.312744140625,185.37261962890625,45.399658203125C185.68048095703125,44.486572265625,185.83438110351562,43.447509765625,185.83438110351562,42.282958984375C185.83438110351562,40.93310546875,185.61279296875,39.709228515625,185.16928100585938,38.610595703125C184.72586059570312,37.512451171875,184.09158325195312,36.5859375,183.26632690429688,35.83154296875C182.44088745117188,35.077392578125,181.43087768554688,34.4951171875,180.236083984375,34.084716796875C179.04104614257812,33.67431640625,177.70452880859375,33.469482421875,176.22647094726562,33.469482421875L164.696533203125,33.469482421875L164.696533203125,61.259765625L169.20486450195312,61.259765625L169.20486450195312,51.572998046875L174.91445922851562,51.572998046875L181.28903198242188,61.259765625Z"/></g></g></g></g></g></g></g></g></g></svg>
+\ No newline at end of file
