diff --git a/features/0756-oca-for-aries-style-guide/README.md b/features/0756-oca-for-aries-style-guide/README.md index dc1dc2e07..0cbef37b5 100644 --- a/features/0756-oca-for-aries-style-guide/README.md +++ b/features/0756-oca-for-aries-style-guide/README.md @@ -6,7 +6,7 @@ - Status Note: Implemented in the [Bifold Wallet](https://github.com/openwallet-foundation/bifold-wallet) - Supersedes: N/A - Start Date: 2022-11-15 -- Version: 1.0 +- Versions: 1.0 and 1.1 - Tags: [feature](/tags.md#feature) [RFC0755 OCA for Aries]: ../0755-oca-for-aries/README.md @@ -23,6 +23,8 @@ also for Aries holder and verifier software makers about how to use the OCA data provided from issuers for a given credential type. It is up to the software makers to use OCA data provided by the issuers as outlined in this guide. +There are 2 versions of the OCA that can be used. Version 1.1 does not remove version 1.0, but rather propose a different view for credential layout. It is to the wallet maintainer to chose which one would be used in their application. + For more information about the use of OCA in Aries, please see [RFC0755 OCA for Aries] @@ -132,7 +134,7 @@ This style guide defines three layouts for credentials, the credential list layo The stacked list is the same as the credential layout, with the credentials that are stacked cutoff between elements 6 and 7. Examples of the stacked layout can be seen in the [Stacking](#heading=h.27voxgccn7kf) section of this document. In the Stacked layout, one of the credentials in the stack may be displayed using the full credential list layout. - +**Version 1.0**
@@ -153,6 +155,26 @@ The stacked list is the same as the credential layout, with the credentials that
+**Version 1.1** + + + + + + + + + +
+alt_text + + +alt_text + +
Credential List Layout + Single Credential Layout +
+ **_Figure: Credential Layouts_** The numbered items in the layouts are as follows. In the list, the OCA data element(s) is provided first, and, where the needed data element(s) is not available through an OCA Bundle, a calculation for a fallback is defined. It is good practice to have code that populates a per credential data structure with data from the credential’s OCA Bundle if available, and if not, populated by the fallbacks. That way, the credentials are displayed in the same way with or without an OCA Bundle per credential. Unless noted, all of the data elements come from the “branding” overlay. Items 10 and 11 are not included in the layouts but are included to document the fallbacks for those values. @@ -182,15 +204,29 @@ The numbered items in the layouts are as follows. In the list, the OCA data elem 11. `expiry_date_attribute` * Fallback: Empty +**added with version 1.1** + +12. `Contact detail button` + * Fallback: Empty + + +**Version 1.0** ![alt_text](images/image3.png "image_tooltip") + +**Version 1.1** +![alt_text](images/image3_1.png "image_tooltip") + + **_Figure: Template layers_** The font color is either black or white, as determined by calculating contrast levels (following [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG2AA-Conformance)) against the background colors from either the OCA Bundle or the generated defaults. +**Version 1.0** +
@@ -205,12 +241,32 @@ The font color is either black or white, as determined by calculating contrast l
+**Version 1.1** + + + + + + +
+alt_text + + +alt_text + +
+ + **_Figure: example of a credential with no override specifications_** ### Logo Image Specifications -The image in the top left corner is a space for the issuer logo. This space should not be used for anything other than the issuer logo. The logo image may be masked to fit within a rounded square with varying corner radii. Thus, the logo must be a square image (aspect ratio 1:1), as noted in the table below. The background is default white, therefore logo files with a transparent background will overlay a white background. +This space should not be used for anything other than the issuer logo. The logo image may be masked to fit within a rounded square with varying corner radii. Thus, the logo must be a square image (aspect ratio 1:1), as noted in the table below. The background is default white, therefore logo files with a transparent background will overlay a white background. + +For version 1.0, the issuer logo is located at the top left of the credential. + +With version 1.1, the issuer logo is located on the bottom of the credential, left of the issuer's name. The following are the specifications for the credential logo for issuers. @@ -245,7 +301,6 @@ Images should be as small as possible to balance quality and download speed. To - ### Background Image Slice Specifications For issuers to better represent their brand, issuers may specify an image slice that will be used as outlined in the samples below. Note the use of the image in a long, narrow space and the dynamic height. The image slice will be top aligned, scaled (preserving aspect ratio) and cropped as needed to fill the space. @@ -253,14 +308,22 @@ For issuers to better represent their brand, issuers may specify an image slice Credential height is dependent on the content and can be unpredictable. Different languages (English, French, etc.) will add more length to names, OS level settings such as font changes or text enlargement will unpredictably change the height of the credential. The recommended image size below is suggested to accommodate for most situations. Note that since the image is top aligned, the top area of the image is certain to be displayed, while the bottom section of the image may not always be visible. +**Version 1.0** + ![alt_text](images/image6.jpg "image_tooltip") +**Version 1.1** + +![alt_text](images/image6_1.png "image_tooltip") + **_Figure: Examples of the image slice behavior_** Types of images best used in this area are abstract images or graphical art. Do not use images that are difficult to interpret when cropped. +**Version 1.0** +
@@ -285,6 +348,31 @@ Use images that are hard to interpret when cropped. Avoid words
+**Version 1.1** + + + + + + + + + + +
+alt_text + + +alt_text + +
Do +

+Use an abstract image that can work even when cropped unexpectedly. +

Don’t +

+Use images that are hard to interpret when cropped. Avoid words +

+ **_Figure: Background image slice Do’s and Don’ts_** @@ -322,6 +410,8 @@ Use images that are hard to interpret when cropped. Avoid words The background image is to give issuers more opportunities to represent their brand and is used in some credential display screens. Avoid text in the background image. +**Version 1.0** +
@@ -346,6 +436,31 @@ Use this image as a marketing platform. Avoid the use of text.
+**Version 1.1** + + + + + + + + + + +
+alt_text + + +alt_text + +
Do +

+Use an image that represents your brand. +

Don’t +

+Use this image as a marketing platform. Avoid the use of text. +

+ **_Figure: Background image Do’s and Don’ts_** @@ -388,10 +503,15 @@ To reduce visual clutter, the issued date (if present), expiry date (if present) * A credential is revoked, if the credential is revocable and is known to have been revoked. * A credential is expiring soon or expired, based on _expiry_date_attribute_, if set. +**Version 1.0** ![alt_text](images/image11.png "image_tooltip") +**Version 1.1** + +![alt_text](images/image11_1.png "image_tooltip") + **_Figure: An example demonstrating how the revocation date, expiry date or issued date may be represented._** The interpretation of the issued date, expiry date and revocation status may be dependent on the holder software, such as a wallet. For example, the specific icons used may vary by wallet, or the full status data may be printed over the credential. @@ -402,18 +522,30 @@ The interpretation of the issued date, expiry date and revocation status may be Issuers should be mindful of the length of text on the credential as lengthy text will dynamically change the height of the credential. Expansive credentials risk reducing the number of fully visible credentials in a list. - +**Version 1.0** + ![alt_text](images/image12.png "image_tooltip") +**Version 1.1** + +![alt_text](images/image12_1.png "image_tooltip") + **_Figure: An example demonstrating how lengthy credentials can limit the number of visible credentials._** Be mindful of other factors that may increase the length of text and hence, the height of the credential such as translated languages or the font size configured at the OS level. +**Version 1.0** + ![alt_text](images/image13.png "image_tooltip") +**Version 1.1** + +![alt_text](images/image13_1.png "image_tooltip") + + **_Figure: Examples showing the treatment of lengthy names_** @@ -426,6 +558,8 @@ Note that wallet builders or holders may limit the visibility of the primary and To limit personal information from being displayed on a card face, only specify what is absolutely necessary for wallet holders to differentiate between credentials of the same type. Do not display private information such as medical related attributes. +**Version 1.0** +
@@ -450,6 +584,31 @@ Display attributes that contain private information.
+**Version 1.1** + + + + + + + + + + +
+alt_text + + +alt_text + +
Do +

+Use attributes that help users identify their credentials. Always consider if a primary and secondary attribute is absolutely necessary. +

Don’t +

+Display attributes that contain private information. +

+ **_Figure: Primary/secondary attribute Do’s and Don’ts_** @@ -468,6 +627,9 @@ Example text include: * DEVELOPMENT * DO NOT USE + +**Version 1.0** +
@@ -493,32 +655,77 @@ Use long works or words that do not describe non-production credentials.
+**Version 1.1** + + + + + + + + + + +
+ +alt_text + + +alt_text + +
Do +

+Use succinct words to describe the type of issued credential. This ensures legibility and does not increase the size of the credential unnecessarily. +

Don’t +

+Use long works or words that do not describe non-production credentials. +

+ ### Credential resizing Credential size depends on the content of the credential and the size of the device. Text areas are resized according to the width. +**Version 1.0** + ![alt_text](images/image18.png "image_tooltip") +**Version 1.1** + +![alt_text](images/image18_1.png "image_tooltip") + **_Figure: Treatment of the credential template on different devices_** +**Version 1.0** + ![alt_text](images/image19.png "image_tooltip") +**Version 1.1** + +![alt_text](images/image19_1.png "image_tooltip") **_Figure: An example of credential on different devices_** ### Stacking -Credentials may be stacked to overlap each other to increase the number of visible credentials in the viewport. The header remains unchanged. The issuer name, logo and credential name will always be visible but the primary and secondary attributes and the image slice will be obscured. +Credentials may be stacked to overlap each other to increase the number of visible credentials in the viewport. The header remains unchanged. The issuer name, logo and credential name will always be visible, but the primary and secondary attributes and the image slice will be obscured. +In version 1.1, the credential name will always be visible. The issuer name, logo, attributes and the image slice will be obscured. + + +**Version 1.0** ![alt_text](images/image20.png "image_tooltip") +**Version 1.1** + +![alt_text](images/image20_1.png "image_tooltip") + **_Figure: An example of stacked credentials with default and enlarged text._** diff --git a/features/0756-oca-for-aries-style-guide/images/image 4_1.png b/features/0756-oca-for-aries-style-guide/images/image 4_1.png new file mode 100644 index 000000000..f97f9cc00 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image 4_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image10_1.png b/features/0756-oca-for-aries-style-guide/images/image10_1.png new file mode 100644 index 000000000..a884b90d5 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image10_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image11_1.png b/features/0756-oca-for-aries-style-guide/images/image11_1.png new file mode 100644 index 000000000..ba69fc2a4 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image11_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image12_1.png b/features/0756-oca-for-aries-style-guide/images/image12_1.png new file mode 100644 index 000000000..e24f10c7d Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image12_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image13_1.png b/features/0756-oca-for-aries-style-guide/images/image13_1.png new file mode 100644 index 000000000..283645835 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image13_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image14_1.png b/features/0756-oca-for-aries-style-guide/images/image14_1.png new file mode 100644 index 000000000..e20283d6f Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image14_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image15_1.png b/features/0756-oca-for-aries-style-guide/images/image15_1.png new file mode 100644 index 000000000..2c46d826f Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image15_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image16_1.png b/features/0756-oca-for-aries-style-guide/images/image16_1.png new file mode 100644 index 000000000..84e82ab12 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image16_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image17_1.png b/features/0756-oca-for-aries-style-guide/images/image17_1.png new file mode 100644 index 000000000..b8ecf203a Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image17_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image18_1.png b/features/0756-oca-for-aries-style-guide/images/image18_1.png new file mode 100644 index 000000000..32ddc2647 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image18_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image19_1.png b/features/0756-oca-for-aries-style-guide/images/image19_1.png new file mode 100644 index 000000000..ff29055fc Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image19_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image1_1.png b/features/0756-oca-for-aries-style-guide/images/image1_1.png new file mode 100644 index 000000000..1e13458ff Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image1_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image20_1.png b/features/0756-oca-for-aries-style-guide/images/image20_1.png new file mode 100644 index 000000000..85707b047 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image20_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image2_1.png b/features/0756-oca-for-aries-style-guide/images/image2_1.png new file mode 100644 index 000000000..9e876d6c1 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image2_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image3_1.png b/features/0756-oca-for-aries-style-guide/images/image3_1.png new file mode 100644 index 000000000..31aedc182 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image3_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image5_1.png b/features/0756-oca-for-aries-style-guide/images/image5_1.png new file mode 100644 index 000000000..2ceb3962d Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image5_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image6_1.png b/features/0756-oca-for-aries-style-guide/images/image6_1.png new file mode 100644 index 000000000..11de4a743 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image6_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image7_1.png b/features/0756-oca-for-aries-style-guide/images/image7_1.png new file mode 100644 index 000000000..fafdfd821 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image7_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image8_1.png b/features/0756-oca-for-aries-style-guide/images/image8_1.png new file mode 100644 index 000000000..8e3db3d40 Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image8_1.png differ diff --git a/features/0756-oca-for-aries-style-guide/images/image9_1.png b/features/0756-oca-for-aries-style-guide/images/image9_1.png new file mode 100644 index 000000000..3edbec93d Binary files /dev/null and b/features/0756-oca-for-aries-style-guide/images/image9_1.png differ