first draft of UI spec

2 files changed, 290 insertions, 0 deletions

diff --git a/design-documents/053-wallet-ui.rst b/design-documents/053-wallet-ui.rst
new file mode 100644
index 00000000..5891eb37
--- /dev/null
+++ b/design-documents/053-wallet-ui.rst
@@ -0,0 +1,289 @@
+DD 53: Wallet UI Design
+#######################
+
+Summary
+=======
+
+This document proposes designs wallet UI. It defines what Android, iOS and 
+WebExtension should follow in order to have a coherent UI between platforms.
+
+Motivation
+==========
+
+We want user to be able to help each others independent of the implementation
+they are using.
+We want user to be able to capitalize the effort of learning how to use one 
+wallet and be able to use a different one without the need to learn 
+anything new.
+Currently development of different platform specific implementation are independent
+and every developer needs to choose the layout, texts and buttons and navigation.
+
+Requirements
+============
+
+Every screen MUST be defined in a document with the following information:
+
+* **Identifiable UI screens**: every UI should have an unique identifier that will
+  be use for development discussion and bug reports. There should be an option
+  in the application to enable an active rendering of the id. 
+
+* **Description**: the reason to be of the screen, should help to define what will
+  be included into, what is going to left for other screens and when and from
+  where should be linked.
+
+The screen MAY also have:
+
+* **Predefined assets**: every implementation should resue the same icons, images,
+  fonts and sounds.
+
+Additionaly the document COULD defined the components of the UI. If one of this
+properties is defined in the spec the implementation must implement it. The specification
+should be minimal to achieve the objective in the description.
+
+* **Info**: Spec of information that the user should have access. The type of info
+  could be a field (id and value) or a banner (information and instructions). 
+  The spec will help to reuse the text for i18n across apps and defined 
+
+* **Inputs**: Spec of information need to provide in current screen. The type of input,
+  range of values and validation should be defined if necessary.
+
+* **Actions**: Spec of buttons and interactable elements that will have a significant 
+  change in the current state. It should also mention navigation when applicable.
+  
+* **Layout**: Spec position of elements when needed. The spec should be "soft" in a sense
+  that elements should be easy to find following directions like "close to X" or 
+  "at the start/end of the screen".
+
+Screen should be defined using the most relaxed definition that are good enough to 
+be clear for the user. Platform will use this definition and adapt to the differences
+on the platform taking advantange of platform API and screen sizes.
+
+When a screen have multiple uses for the same purpose, a substate section should be 
+included with the difference with the main definition.
+
+Part of the screens that are reused shoud also be defined in this document as screen.
+
+Common definition:
+ * navigation between screen should not happen if the user didn't take any action
+
+
+Proposed Solutions
+==================
+
+List of   dall screens with the defined properties
+
+cta-withdraw
+------------
+
+``Description``: this screen is used for the confirmation of a manual withdrawal,
+bank-integrated witdrawals and exchange withdrawals.
+the success of this operation will be an increase of the balance in the wallet.
+fee, restrictions and ETA should be clear for the user.
+
+``Info``:
+ * exchange to be used showing the URL
+ * table of details of the operation: use the ``operation-table-details`` screen
+ * starting currency: if the exchange has the currency conversion service enabled user should be able to the details based on the wire transfer currency
+ * taler URI: show copy button or QR to complete the operation with another device 
+
+``Inputs``:
+ * age restriction: allow the selection of the restriction in the age group possible by the exchange
+ * service provider: allow the selection of different exchange 
+
+``Actions``:
+ * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
+ * review and confirm ToS: if the current selected exchange has a version  of ToS that the user didn't yet accepted, use the ``accept-tos`` screen
+ * cancel: user will be redirected to ``balance``
+
+.. attention::
+  User should be able to play with the amount, not possible in the current design
+
+cta-payment
+------------
+
+``Description``: this screen is used for the confirmation of a payment to a merchant.
+the success of this operation will be an decrease of the balance in the wallet
+and save a ticket/invoice of the purchase.
+fee, restrictions and ETA should be clear for the user.
+
+``Info``:
+ * merchant offering the order showing the URL
+ * order summary
+ * table of details of the operation: use the ``operation-table-details`` screen
+ * receipt: order id
+ * payment deadline: absolute time before the claimed order expires 
+ * taler URI: show copy button or QR to complete the operation with another device 
+ * cant pay desc: if the user has enough balance but unable to use it
+ * payment status: if the 
+
+``Actions``:
+ * confirm operation: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
+ * get more cash: if there is not enough balance, it will be redirected to ``cta-witddraw``
+ * cancel: user will be redirected to ``balance``
+
+cta-deposit
+------------
+
+``Description``: this screen is used for the confirmation of a deposit.
+the success of this operation will be an decrease of the balance in the wallet
+and save a deposit ticket for reference.
+fee, restrictions and ETA should be clear for the user.
+
+``Info``:
+ * bank account where the money is going to
+ * table of details of the operation: use the ``operation-table-details`` screen
+
+``Actions``:
+ * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
+ * cancel: user will be redirected to ``balance``
+
+.. attention::
+  User should be able to play with the amount, not possible in the current design
+
+cta-peer-pull-initiate
+----------------------
+
+``Description``: this screen is used for the confirmation of the creation of
+a peer pull transaction or invoice to request money from another wallet.
+the success of this operation will not change the balance immediately in the wallet
+and allow the user to share a taler URI to the payer.
+fee, restrictions and ETA should be clear for the user.
+
+``Info``:
+ * exchange to be used showing the URL
+ * table of details of the operation: use the ``operation-table-details`` screen
+
+``Inputs``:
+ * subject: short description of the transaction
+ * expiration: absolute time/date after which the invoice is not valid anymore
+ * service provider: allow the selection of different exchange 
+
+``Actions``:
+ * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
+ * review and confirm ToS: if the current selected exchange has a version  of ToS that the user didn't yet accepted, use the ``accept-tos`` screen
+ * cancel: user will be redirected to ``balance``
+
+.. attention::
+  Is the invoice creation always free of charge or does the exchange have a mechanism
+  to impose a fee to pay on creation?
+
+
+cta-peer-pull-confirm
+---------------------
+
+``Description``: this screen is used for the confirmation of the payment of
+a peer pull transaction or invoice to send money from another wallet.
+the success of this operation will be an will decrease the balance in the wallet.
+fee, restrictions and ETA should be clear for the user.
+
+``Info``:
+ * exchange to be used showing the URL
+ * subject: short description of the transaction
+ * table of details of the operation: use the ``operation-table-details`` screen
+ * expiration: absolute time/date after which the invoice is not valid anymore
+
+``Actions``:
+ * confirm operation: if the payment is possible, on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
+ * get more cash: if there is not enough balance, it will be redirected to ``cta-witddraw``
+ * cancel: user will be redirected to ``balance``
+
+cta-peer-push-initiate
+----------------------
+
+``Description``: this screen is used for the confirmation of the creation of
+a peer push transaction or transfer money to another wallet.
+the success of this operation will reduce the balance immediately in the wallet
+and allow the user to share a taler URI to the receiver.
+fee, restrictions and ETA should be clear for the user.
+
+``Info``:
+ * table of details of the operation: use the ``operation-table-details`` screen
+
+``Inputs``:
+ * subject: short description of the transaction
+ * expiration: absolute time/date after which the transfer is not valid anymore
+
+``Actions``:
+ * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
+ * cancel: user will be redirected to ``balance``
+
+cta-peer-push-confirm
+---------------------
+
+``Description``: this screen is used for the confirmation of the acceptance of
+a peer push transaction or transfer money to this wallet.
+the success of this operation will be an will decrease the balance in the wallet.
+fee, restrictions and ETA should be clear for the user.
+
+``Info``:
+ * subject: short description of the payment
+ * expiration: absolute time/date after which the invoice is not valid anymore
+ * table of details of the operation: use the ``operation-table-details`` screen
+
+``Actions``:
+ * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
+ * review and confirm ToS: if the current selected exchange has a version of ToS that the user didn't yet accepted, use the ``accept-tos`` screen
+ * cancel: user will be redirected to ``balance``
+
+cta-reward
+-----------
+
+``Description``: this screen is used for the confirmation of the acceptance of
+a reward from a merchant.
+the success of this operation will be an will decrease the balance in the wallet.
+fee, restrictions and ETA should be clear for the user.
+
+``Info``:
+ * amount: effective amount to receive
+ * exchange: from where this money comes from
+ * merchant: offering the reward
+
+``Actions``:
+ * confirm operation: on success will be redirected to the ``transaction-details`` screen where the detail of the current transaction will be displayed
+ * review and confirm ToS: if the current selected exchange has a version  of ToS that the user didn't yet accepted, use the ``accept-tos`` screen
+ * cancel: user will be redirected to ``balance``
+
+
+operation-table-details
+-----------------------
+
+``Description``: with the table it should be clear how much the operation will cost,
+the initial amount and the final amount with all the items related to the operations (like fee)
+
+``labels``: initial amount of the operation, and final amount are always shown.
+Fee should be shown as an extra row in the table if it is non-zero.
+Converted amount should be shown as an extra row if initial amount currency is not the same 
+as the final amount currency.
+
+Initial amount label by operation:
+
+ * payment -> Price 
+ * deposit -> Send
+ * peer-pull-credit -> Invoice
+ * peer-pull-debit -> Invoice
+ * peer-push-debit -> Send
+ * peer-push-credit -> Transfer
+ * withdrawal -> Transfer
+ * refund -> Refund
+
+
+accept-tos
+----------
+
+``Description``: this screen can be use everytime that the user is going to interact
+with an exchange. since at any moment wallet may find that ToS changed the user needs
+to be prevented from continue before reading/accepting new rules. If possible, this
+screen should be used inplace of other actions and hidden if not required (for example,
+user already accepted ToS)
+
+``Inputs``:
+ * format: allow the selection of a ToS format
+ * languange: allow the selection of a languange different from system lang
+
+``Actions``:
+ * accept tos: will mark this version as accepted in wallet core and redirect the user to the screen from where it was invoked
+ * save/print tos: will save the ToS outside of the wallet
+
+Q / A
+=====
+
diff --git a/design-documents/index.rst b/design-documents/index.rst
index b37d8860..1199b1fc 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -64,4 +64,5 @@ Design documents that start with "XX" are considered deprecated.
   050-libeufin-nexus.rst
   051-fractional-digits.rst
   052-libeufin-bank-2fa.rst
+  053-wallet-ui.rst
   999-template