| layout | in-navbar | id | title |
|---|---|---|---|
page |
true |
developer-docs |
Developer documentation |
UNICEF has defined a visual design specification for our internal web applications. This specification follows our brand guidelines, takes into account accessibility and is rooted in a set of principles that are defined on our UX/UI design guidelines.
Additionally to those specs, UNICEF has created a technology agnostic reference implementation, so it can be used with any modern development framework such as React or Angular. One of the main goals of this implementation is to:
- Speed up the development of our applications by providing developers with a set of CSS classes that comply with usability, branding and accessibility best practices.
- Improve the quality of the interfaces with a well thought and designed framework.
This document is for developers that have to implement the user interface of a UNICEF web application. Here you will find the technical documentation with examples of the HTML and CSS classes.
This implementation is based on bootstrap 4.x, one of the most popular and widely used frameworks on the Internet. For brevity, we assume the reader is familiar with this framework, and has a good understanding of HTML as well as CSS.
If you need to design a user interface for a UNICEF application you will need to understand how and when to use each of the elements described in this document. To get that knowledge, please, read our UX/UI design guidelines.
This is an example of a full page.
In order to use the UNICEF's UI in your project you can reference a CDN or download using npm.
CDNs can offer a performance benefit by hosting on servers spread across the globe. This also offers an advantage that if the visitor to your webpage has already downloaded a copy of the files from the same CDN, it won't have to be re-downloaded.
For the CSS:
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@unicef/design-system/dist/css/unicef.css">If you need to include the JavaScript, you have two options. The first one, a minified javascript bundle file that includes all bootstrap JavaScript (bootstrap, popper, jquery). You need this if you require dropdowns, tabs, etc.
<!-- All js bundled -->
<script src="https://cdn.jsdelivr.net/npm/@unicef/design-syste/dist/js/unicef-bundle.min.js"></script>
<!-- only the scripts that were created by UNICEF (no requirement)-->
<script src="https://cdn.jsdelivr.net/npm/@unicef/design-system/dist/js/unicef.min.js"></script>This bootstrap customization is based on SASS, and therefore you can easily override the CSS classes for your particular project.
First, install the npm package
npm install @unicef/design-system
Import unicef.scss in your global scss file. For example:
/* you may need to change the path to the node_modules dir */
@import "../node_modules/@unicef/design-system/scss/unicef"We have used bootstrap variables whenever possible. Custom created variables are defined in scss/_variables.scss.
The default typography is the one defined by user's operating system. That way we don't need to download any font.
{% capture example %}
Lead paragraph. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
{% endcapture %} {% include example.html content=example %}Alerts use the .alert class followed by the type of alert .alert-success,
.alert-warning, .alert-danger.
{% capture example %}
Alerts support strong and links.
{% capture example %}
There are 4 types of buttons. The .btn class is common to all of them:
.btn-primaryfor the main button..btn-outline-primary, for the default button..btn-outline-danger, for the danger button..btn-link, for the link button.
{% capture example %}
Normal Active Disabled
Normal Active Disabled
Normal Active Disabled
Link button Normal Link button
{% endcapture %} {% include example.html content=example %}Also, it is possible to group an input with a button:
{% capture example %}
{% capture example %}
Application Name
{% endcapture %}
{% include example.html content=example %} {% capture example %}
Application name
{% endcapture %} {% include example.html content=example %} {% capture example %}
Application name {% endcapture %} {% include example.html content=example %}To support skip navigation, always add the .skip navigation before the navigation bar pointing to the element in which the content starts.
Adding this helps users that browse the web with keyboards, allowing them to skip all the links in your main menu.
<a class="skip" href="#contents" tabindex="0">Skip Navigation</a>
<!-- navbar goes here--->
<nav class="navbar navbar-expand-md flex-md-row bd-navbar">
....
</nav>
<!-- your contents start here -->
<div id="contents">
</div>{% capture example %}
Irure magna elit commodo anim ex veniam culpa eiusmod id nostrud sit
cupidatat in veniam ad.
Eiusmod consequat eu adipisicing minim anim aliquip cupidatat culpa
excepteur quis.
Occaecat sit eu exercitation irure Lorem incididunt nostrud.
Aliquip ex eiusmod voluptate exercitation cillum id incididunt elit sunt.
Qui minim sit magna Lorem id et dolore velit Lorem amet exercitation
duis deserunt.
Anim id labore elit adipisicing ut in id occaecat pariatur ut ullamco
ea tempor duis.
Images should weight the least amount possible.
-
Use the format that weights for the size and quality you require. Typically, it is recommended to use JPG format for pictures and SVG for graphics and icons.
-
Use size optimizers such as svgo or jpeg optim.
-
It is necessary to set the
altdescription on all images. Keep this description brief, describe what you see and do not interpret the contents of the image. For decorative images, use an empty stringaltattribute (alt="").
Form fields have different status:
{% capture example %}
Form elements can include short texts that provide important information to users.
{% capture example %}
To add a counter at the bottom of a field add the attributes data-counter="true" and maxlength="100", where 100 is the max number of characters. Add data-autoresize="true" to allow auto resize.
{% capture example %}
These two enhancements require Javascript.
Required fields are those that are mandatory to fill in order to submit a form.
For required fields we mark <label> contents with an <em> and the form field (input, select, textarea,...) with the attribute required.
{% capture example %}
UNICEF's reference implementation uses Bootstrap conventions to display errors in forms as base. We slightly customized the look and feel and we only use the .is-invalid class to provide visual feedback.
Example the HTML and classes to display errors (no actual validation is performed)
{% capture example %}
Use .card-deck to have same all cards of a row with the sam length.
{% capture example %}
This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.
Last updated 3 mins ago
This card has supporting text below as a natural lead-in to additional content.
Last updated 3 mins ago
{% capture example %}
This is a longer card with supporting text below as a natural lead-in to additional content. This content is a little bit longer.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Morbi elit justo, finibus consequat facilisis eget, dictum in justo.
- Cras justo odio
- Dapibus ac facilisis in
- Morbi leo risus
- Porta ac consectetur ac
- Vestibulum at eros
List group with a button:
- Cras justo odio
- Dapibus ac facilisis in
- Morbi leo risus
- Porta ac consectetur ac
-
Add an element
Add an element to the list Add to list
{% capture example %}
| Main Element | Date | Amount(USD) |
|---|---|---|
| Text is a link | 29-May-2018 | $23.33 |
| This is another link. Vertically align cells to the middle | 12-Aug-2017 | $99.44 |
| Text is left-aligned | 29-May-2018 | $1,223.00 |
Everytime a asynchronous request is done in the client side, the app should display that status.
We use .spinner-border or .spinner-border.spinner-border-sm (small one).
For accessibility, notice you need to include role=status
{% capture example %}
To specify the action that is being performed: {% capture example %}
When the action is performed within a button
{% capture example %} Loading...
Loading... {% endcapture %} {% include example.html content=example %}More info in bootstrap spinners documentation.
Indicates the status of completeness of a process.
There are different background colors available (.bg-success, .bg-warning, etc..)
Please, notice the accessibility attributes role, aria-valuenow,
aria-valuemin and aria-valuemax.
{% capture example %}
Allocated funds: $87,500 (75%)
{% endcapture %} {% include example.html content=example %}
For more information see bootstrap docs