Code of conduct

This project has adopted the Contributor Covenant in version 2.0 as our code of conduct. All contributors must abide by the code of conduct.

How to contribute

We always welcome and encourage contributions and feedback. For more information on how to contribute, the project structure, as well as additional information, see our Contribution Guidelines. By participating in this project, you agree to abide by its Code of Conduct at all times.

Our commitment to open source means that we are enabling all interested parties to contribute and become part of its developer community.

NPM Packages

Enabling Prop Type Declaration on Hover in VS Code

To ensure prop types and descriptions are viewable on hover:

1. Make sure you are using TypeScript for prop declarations in Stencil components.

2. Enable TypeScript IntelliSense by verifying that TypeScript > Hover is turned on in VS Code settings..

3. Restart VS Code if prop type declarations are not displaying immediately on hover.

Following these steps will set up your development environment for building, testing, and deploying the project.

The Font used in a digital product represents a piece of the brand’s values and hence we made sure that you would be able to easily apply your font to your application.

By just adding a simple style tag you can ensure that your brand font is reflected across your application in a cohesive manner.

body{
 font-family: "your_font_family"
}

1.00 (15 Nov 2024)

What's New

We are excited to announce the launch of a unified design system developed specifically for all government entities. This design system provides a flexible, cohesive framework that ensures consistency across platforms while allowing each entity the customization they need to meet their unique objectives and user needs.

Key Benefits of the Design System:

Consistency Across Platforms: By using standardized components, colors, typography, and layouts, we ensure a cohesive look and feel across all government digital interfaces, reinforcing trust and recognition for users.

Customizable and Flexible: The design system is built to be adaptable. Each entity can modify and personalize components as needed, ensuring that the system supports your specific content, users, and objectives without sacrificing overall visual harmony.

Accessibility and Usability: All components in the design system are designed with accessibility standards in mind, ensuring compliance with WCAG guidelines. This makes it easier to create accessible, user-friendly content for all citizens, residents, and tourists.

Efficiency in Development: The design system includes ready-made components and templates, reducing the time and resources required for design and development. This allows teams to focus more on content and functionality rather than creating new designs from scratch.

How to Use the Design System:

The design system is available to all entities as a downloadable file and can be accessed in the Downloads section. GitBook includes detailed documentation covering each component's usage, anatomy, and dos and don’ts.

HTML Templates

Figma UI Library

Note: Figma does not currently support automatic library updates to external teams.

1. Download Figma Library

For access to the Figma file, please contact us at saleh.lootah@digitaldubai.ae

2. Add Library

After downloading the library, you must then upload the .fig file into your team's projects. To do this, open Figma (in-app or browser) and drag the file into the Figma window. Alternatively, you may click on the "Import File" button and select the correct file from your local directory. Once imported, you should publish the library within your team.

3. Updating the Library

Due to the above-noted limitation of Figma, updates to the library must be manually accomplished. Please routinely check this page for future updates to the UI Library. Additionally, we will notify you of any updates to the library.

To update your library, repeat steps 1 & 2 with the latest version of the library. Once the updated version is added to your team, use the swap libraries feature in Figma, which will allow you to replace the old library with the latest one without disconnecting any instances of the library you may have used in your designs.

DubaiAI

For DubaiAI design guidelines and the logo, please refer back to the Figma file.

URLs for DubaiAI Chatbot Landing Page:

Entities can use the following URLs to access the DubaiAI chatbot landing page. Each entity should append their unique code at the end of the URL to direct users to their specific landing pages:

• English (EN):

• https://chat.dubai.ae/?lang=en-US&mode=modal&source= [entity code]

• Arabic (AR):

• https://chat.dubai.ae/?lang=ar-SA&mode=modal&source= [entity code]

For example, for MBRHE, the URLs would be:

• English (EN):

• https://chat.dubai.ae/?lang=en-US&mode=modal&source=mbrhe

• Arabic (AR):

• https://chat.dubai.ae/?lang=ar-SA&mode=modal&source=mbrhe

Entities should replace "[entity code]" in the URLs with their specific identifier. If you don't know what your identifier is, please refer back to the Excel sheet attached to ensure users are directed to the appropriate landing page within the DubaiAI chatbot platform.

Happiness Meter

Web:

1. Happiness Meter Web Widget Integration and Development Guide : A document that outlines and explains the required development activities for departments to integrate with the Happiness Meter on the web.

2. Happiness Meter .Net Sample Web Guide: Example implementation of the happiness widget on the web using .Net language.

3. Happiness Meter Java Sample Web Guide: Example implementation of the happiness widget on the web using Java language.

4. Happiness Web Test Cases Guide: A list of test cases that departments need to execute and share with Digital Dubai Government Establishment to certify the web implementation.

5. Happiness Meter Inquiry Service Specification Guide: A document describing the “Happiness Index Vote Inquiry” Web Service specification, designed to enable departments to inquire about the votes.

Mobile App:

1. Happiness Meter Mobile App Integration and Development Guide: A document that describes and explains the necessary development activities for departments to integrate with the Happiness Meter on mobile apps.

2. Happiness Meter iOS Sample App Guide: Example iOS application of happiness widget on Mobile in iOS language.

3. Happiness Meter Android Sample App Guide: Sample Android application of happiness widget on mobile in Android language.

4. Happiness Mobile Test Cases Guide: A list of test cases that departments need to execute and share with Digital Dubai Government to certify the implementation on mobile apps.

Tablet - Service Center:

1. New Service Centers Request Form Guide: A form to be filled out with the service center details where the Happiness Meter will be implemented.

2. Happiness Meter iOS Tablet Sample App Guide: Example iOS application of the happiness widget on tablets using iOS language.

3. Happiness Meter Android Tablet Sample App Guide: Sample Android application of happiness widget on Tablets in Android language.

DDA with Web Components

This is a step-by-step guide to use vanilla web components.

Setup

First, import the package script:

Next, add the material-icons package which is the icon package used by DDA:

Start by adding the material-icons package inside the <head> tag

You should now be able to use DDA components:

Overview

The Expectation Levels Progress Bar visually represents a user's progression toward specific achievement levels or benchmarks. It provides feedback on current progress, motivating users and guiding them toward completing all steps or reaching all set goals.

Usage

When to use this component?

Use the Expectation Levels Progress Bar in applications where tracking progress toward specific milestones or goals is important, such as completing onboarding tasks, reaching skill levels, or meeting performance benchmarks. It’s ideal for interfaces that encourage users to reach incremental achievements.

How it works

The Expectation Levels Progress Bar displays progress through segmented levels or stages, with each segment representing a specific milestone. As users advance, the bar fills up to show their proximity to the next level or the completion of all stages. This component enhances user engagement by offering a clear visual of goals and progress, motivating users to achieve each level.

Anatomy

Anatomy Options

Label: Displays the status or expectation level of the progress. In this example, it is labeled as "Met Expectation," indicating the status being represented.

Filled Bar: Shows the portion of the bar that has been completed or that meets the specified expectations. The filled sections indicate achieved progress or met criteria.

Unfilled Bar: Represents the remaining portion of the bar that has not yet been reached or that does not meet the specified expectations. It shows what is left to achieve.

Dos and Don'ts

DDA with Angular

This is a step-by-step guide to use the DDA components in Angular.

Setup

Next, add the material-icons package which is the icon package used by DDA:

Start by adding the material-icons package inside the <head> tag

Import and add the following to your app.module.ts file

You should now be able to use DDA components inside your app.component.html file:

Our component library supports Right-to-Left (RTL) layouts, but RTL handling should be implemented on your side as a developer. To enable RTL, you need to set the dir="rtl" attribute on the <body> or relevant container element programmatically in your project.

Core colors

Core colors are used to support user interface design by calling attention to specific elements, such as buttons, callouts, icons, etc.

Color Generation

You can use the DDS Color Generation Figma Plugin to generate custom color palettes for this design system.

  /*Primary Variants*/
  --dda-primary-0: #000000;
  --dda-primary-4: #001110;
  --dda-primary-5: #001413;
  --dda-primary-6: #001716;
  --dda-primary-10: #00201F;
  --dda-primary-12: #002423;
  --dda-primary-17: #00302F;
  --dda-primary-20: #003735;
  --dda-primary-22: #003C3A;
  --dda-primary-24: #00413F;
  --dda-primary-25: #004341;
  --dda-primary-30: #00504E;
  --dda-primary-35: #005D5A;
  --dda-primary-40: #006A67;
  --dda-primary-50: #008582;
  --dda-primary-60: #00A19E;
  --dda-primary-70: #21BEBA;
  --dda-primary-80: #4DDAD6;
  --dda-primary-87: #66EEE9;
  --dda-primary-90: #6FF7F2;
  --dda-primary-92: #76FDF8;
  --dda-primary-94: #99FFFA;
  --dda-primary-95: #D0F5F4;
  --dda-primary-96: #C2FFFB;
  --dda-primary-98: #E3FFFD;
  --dda-primary-99: #F2FFFD;
  --dda-primary-100: #FFFFFF;


  /*Secondary Variants*/
 --dda-secondary-0: #000000;
  --dda-secondary-4: #000836;
  --dda-secondary-5: #000A3D;
  --dda-secondary-6: #000C43;
  --dda-secondary-10: #001257;
  --dda-secondary-12: #001561;
  --dda-secondary-17: #092072;
  --dda-secondary-20: #132778;
  --dda-secondary-22: #192C7D;
  --dda-secondary-24: #1E3181;
  --dda-secondary-25: #213484;
  --dda-secondary-30: #2E4090;
  --dda-secondary-35: #3B4C9C;
  --dda-secondary-40: #4758A9;
  --dda-secondary-50: #6071C4;
  --dda-secondary-60: #7A8BE0;
  --dda-secondary-70: #95A6FD;
  --dda-secondary-80: #B9C3FF;
  --dda-secondary-87: #D2D8FF;
  --dda-secondary-90: #DDE1FF;
  --dda-secondary-92: #E5E6FF;
  --dda-secondary-94: #ECECFF;
  --dda-secondary-95: #F0EFFF;
  --dda-secondary-96: #F3F2FF;
  --dda-secondary-98: #FBF8FF;
  --dda-secondary-99: #FEFBFF;
  --dda-secondary-100: #FFFFFF;

Our component library supports Dark Mode and Light Mode Layouts with Light Mode as the default Option, but the handling should be implemented on your side as a developer. To enable Dark Mode, you need to set the data-theme="dark" attribute on the <body> or relevant container element programmatically in your project.

Typeface

To present a unified we recommend using the Dubai font for both the Arabic and English languages.

Type Scale Specification

Type Scales create a structured and effective visual hierarchy, guiding users through content with clarity and purpose. Each style serves a unique role in presenting information.

We recommend the Minor Third (1.2) type scale.

Best Practices

Hierarchy

Designers should emphasize clarity and readability by using a balanced type scale to establish a clear visual hierarchy. Instead of relying on color for emphasis, type size and weight should guide users through the content.

Use distinct headline levels (e.g., H1, H2, H3) with progressively smaller sizes as levels deepen. Consistent spacing between text elements reinforces this hierarchy; for example, ensure that headline-to-body spacing is larger than body-to-caption spacing. For optimal readability, apply bold weights to titles and headlines, while keeping body text and labels lighter for balanced visuals.

Ensure that headings follow a proper hierarchical order: H1 first, then H2, followed by H3, etc. This structure enhances accessibility by assisting screen readers and search engines in understanding the content layout, making navigation logical and efficient. Refer to WCAG recommendation.

Readability

For optimal readability and visual consistency, avoid altering line height to maintain proper vertical spacing and alignment. Limit line length to 80 characters or fewer, enhancing readability while allowing for occasional exceptions. Use left alignment or centering as standard practice, reserving right alignment for Arabic text. Adjust font weights strategically to create emphasis and establish a clear content hierarchy. Ensure letter spacing remains consistent across products, with body text spacing and minor increases applied to larger headlines to improve clarity without overcrowding. Refer to WCAG.

Contrast

Contrast Ratios: Text should have a minimum contrast ratio of 4.5:1 against its background for regular text and 3:1 for large text (over 24px or bold text above 19px).

Accessible Color Choices: Ensure text on colored backgrounds meets appropriate contrast ratios, verified through a contrast checker.

Interactive Elements: Buttons, links, and other interactive elements should meet contrast standards and provide visual feedback on focus and hover states.

The W3C's Web Content Accessibility Guidelines (WCAG) 2.1 include Success Criterion 1.4.12, which focuses on text spacing to enhance readability for users with visual or cognitive disabilities. This criterion ensures that content remains functional and readable when users adjust text spacing. The key requirements are:

• Line Height (Line Spacing): At least 1.5 times the font size.

• Spacing After Paragraphs: At least 2 times the font size.

• Letter Spacing (Tracking): At least 0.12 times the font size.

• Word Spacing: At least 0.16 times the font size.

Authors are not required to set these exact spacings but must ensure that their content can adapt to these settings without loss of content or functionality. This adaptability allows users to modify text spacing according to their needs, improving their reading experience.

Tools to Check Contrast

1. WCAG Checker: Contrast

2. Figma Plugin: Contrast

Responsive Typography and Mobile Scaling

Responsive Typography: To ensure scalability across different screen sizes, use relative units like rem or em rather than fixed px units for a seamless, adaptive experience.

Mobile Scaling: For smaller screens, use appropriately scaled-down versions of display or headline fonts while maintaining legibility. Avoid reducing body text below 14px for secondary content to ensure readability on mobile devices.

Color System

Base Tonal Palette

The below is an example of the base tonal palette generated with the DDA blue primary color as the seed color. A seed color is the color provided to the material color generator on which it bases the palette on.

Key Colors

Key colors are the core colors selected from the tonal palette that serve as the foundational hues for an interface.

Primary Colors:

The main colors are prominently used for key elements like icons, headers, and primary action buttons, representing the core of the brand and its identity. This primary color signifies core interactions, appearing on primary buttons for actions like "Submit" or "Next," encouraging user focus and reinforcing brand presence. Variants of this color are applied to hover, focus, and pressed states to enhance interactive feedback and maintain consistency across the interface.

Primary Light

Primary Dark

Secondary Colors

The complementary color in the primary palette adds flexibility and depth, enhancing visual interest without overshadowing the primary brand elements. It is used for secondary buttons, like "Back" or "Learn More," and serves as an accent for highlights within content. This color also appears in navigation elements, such as tabs, icons, and links, to guide users through supplementary interactions. Supporting the primary colors, the secondary palette offers contrast for backgrounds, secondary buttons, and icons, adding layered sophistication to the interface.

Secondary Light

Secondary Dark

Color Schemes:

Info

This color provides informational messages or highlights additional details. It is used for info messages, including notification backgrounds and icons with helpful or instructional content. Tooltips and help text also use this color to distinguish them from primary or secondary content, as well as for non-critical icons or informational links.

Error

This color signals errors or critical issues that require user attention. It is used for error messages, including backgrounds or text in error notifications, tooltips, and alert boxes. It indicates invalid input fields with borders or icons and is applied to critical buttons for actions that may result in data loss or deletion, such as “Delete Account”.

Warning

This color cautions users about non-critical issues or potential risks. It is used for warning messages, alert backgrounds, and icons. Form warnings use this color to indicate fields requiring attention but are not strictly errors, and it appears in notification badges for cautionary but non-critical alerts.

Success

This color represents positive actions and feedback, used in backgrounds for success messages, like "Action completed successfully." It also highlights valid input in form validation and serves as a status indicator, marking completion statuses or achievement badges.

Surface Colors

The surface colors in the palette establish a balanced foundation, providing structure and depth without competing with the primary brand elements. These colors are used for background layers, defining areas such as cards, modals, and section dividers to create a cohesive and organized interface. They subtly support primary and secondary colors by ensuring interactive elements and key content stand out clearly. Applied across different layers, surface colors enhance readability and separation, adding a refined visual hierarchy that contributes to a polished and sophisticated design experience.

Surfaces Light

Surfaces Dark

Disabled Colors

The disabled colors in the palette provide subtlety and restraint, ensuring that inactive elements remain visible without drawing attention away from active content. These colors are used for elements like disabled buttons, text fields, and icons, signaling non-interactivity in a clear yet understated manner. By blending seamlessly with primary and secondary colors, disabled tones maintain a consistent visual language while gently fading into the background. Applied across various components, disabled colors enhance usability by distinguishing interactive from non-interactive elements, contributing to a cohesive and refined interface that respects user focus and intention.

Disabled Light

Disabled Dark

Accessibility

Contrast in Material

Material’s color system provides standard tone values and measurements that can be used to meet accessible contrast ratios.

Material’s tonal system corresponds to Web color contrast standards as follows:

1. Colors that are at least 40 steps apart in tonal value achieve a contrast ratio of at least 3:1

2. Colors that are at least 50 steps apart in tonal value achieve a contrast ratio of at least 4.5:1

3. Colors that are at least 70 steps apart in tonal value achieve a contrast ratio of at least 7:1

To ensure accessibility across tonal palettes, follow specific contrast guidelines to maintain readability and usability.

Primary and Secondary Colors:

1. 40-step difference: Use this for elements needing a 3:1 contrast ratio, such as large text and secondary UI elements.

2. 50-step difference: Use this for essential text and interactive elements that need a 4.5:1 contrast ratio.

3. 70-step difference: Reserve this for small or critical text that requires a 7:1 contrast ratio.

Error, Warning, Success, and Info Colors:

1. 50-step difference: Ensure readability for general alerts and feedback.

2. 70-step difference: Use for high-priority messages that need higher visibility.

Neutral and Neutral-Variant Colors:

1. 50-step difference: Necessary for readable text with a 4.5:1 contrast ratio.

2. 40-step difference: Suitable for subtle separations, such as backgrounds and dividers, with a 3:1 contrast ratio.

3. 70-step difference: Use for focus indicators and interactive elements where high contrast is required.

By following these tonal palette guidelines, you create a cohesive and accessible visual experience across UI components and interaction states.

Breakpoints for Design

Breakpoints are predefined screen widths that dictate how a responsive layout adapts to different devices. At each breakpoint, CSS rules change to optimize the design for that screen size, ensuring a seamless and user-friendly experience across desktops, tablets, and mobile devices. We have selected the following 5 breakpoints based on the most common screen resolutions:

Inner Container Widths

Define container widths based on each breakpoint to keep content visually balanced:

Small (sm): 100% width with minimum 8px padding.

Medium (md): Max width 720px.

Large (lg): Max width 960px.

Extra Large (xl): Max width 1140px.

2XL (2xl): Max width 1280px.

Gutters and Margins

Gutter Width: 16px between columns, ensuring consistent spacing.

Outer Margins: 112px on both left and right edges for a contained look on desktop screens.

Alignment and Balance: Ensure content aligns with columns, maintaining balance and structure. Adjust columns if needed to keep gutters and margins consistent.

Spacing and Padding

Spacing is a crucial tool for enhancing clarity and usability in design. GWU follows a structured approach:

• Up to the base font size (1rem), spacing increases in 2px increments.

• Beyond 1rem, spacing increments increase by 4px up to a maximum of 48px.

Layout Patterns

Header & Footer: Keep headers and footers consistent across breakpoints, with a compact version for smaller screens.

Sidebar Navigation: Display sidebars with fixed positioning on larger screens if needed.

Content Layouts

One-Column Layout: For narrow screens, focusing on vertical scrolling.

Two-Column Layout: Adds a secondary column at the medium breakpoint.

Three-Column Layout: Available at larger breakpoints, ideal for data-heavy pages or dashboards.

Images

Adaptive Images: Serve different image sizes based on breakpoints for optimized loading times and quality.

Techniques: Use srcset or CSS to ensure images adapt effectively to varying screen resolutions.

Testing and Accessibility

Testing on Devices: Test layouts on multiple devices to confirm that breakpoints provide a consistent experience.

Accessibility Considerations: Ensure layouts are keyboard navigable and compatible with screen readers. Confirm that text and interactive elements resize appropriately for users who adjust browser zoom settings.

DDA with React

This is a step-by-step guide to use the DDA components in React.

Setup

First, install the package @dubai-design-system/componts-react

npm i @dubai-design-system/components-react

Next, add the material-icons package which is the icon package used by DDA:

Start by adding the material-icons package inside the <head> tag

<style>
    <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
</style>

You should now be able to use DDA components:

import React from 'react';
import { DdaButton } from "@dubai-design-system/components-react";

const App = () => (
  <div>
    <DdaButton
    button_color="default-primary"
    start_icon="sentiment_satisfied"
    end_icon="arrow_forward"
    custom_class=""
    component_mode=""
    button_id="button"
    aria_label="button"
    onclick="console.log('clicked')"
    >Button</DdaButton>
  </div>
);

export default App;

DDA with Vue

This is a step-by-step guide to use the DDA components in Vue.

Setup

First, install the package @dubai-design-system/components-vue

npm i @dubai-design-system/components-vue

Next, install the font-awesome package which is the icon package used by DDA:

Start by adding the material-icons package inside the <head> tag

<style>
    <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
</style>

In your main.js file, import your component library plugin and use it:

<script>

// src/main.js

import { ComponentLibrary } from '@dubai-design-system/components-vue';

createApp(App).use(ComponentLibrary).mount('#app');

</script>

<script>    
    import { DdaButton } from '@dubai-design-system/components-vue';
</script>

<template>
    <div>
        <DdaButton
            button_color="default-primary"
            start_icon="sentiment_satisfied"
            end_icon="arrow_forward"
            custom_class=""
            component_mode=""
            button_id="button"
            aria_label="button"
            onclick="console.log('clicked')"
        ><!---->Button</DdaButton>
    </div>
</template>

Overview

Usage

When to use this component?

Accordions are used to manage large amounts of content by dividing it into sections that can be expanded or collapsed. They are suitable for FAQs, content-heavy pages, or any interface where space is limited, and users need to access different sections of content without overwhelming them with too much information at once.

How it works

An accordion component typically includes a series of sections, each with a header that, when clicked, expands or collapses the section's content. Optional elements like icons can indicate the expanded or collapsed state. The accordion can be configured to display one section at a time or allow multiple sections to be expanded simultaneously.

Code

<dda-accordion 
  design="bg-border" 
  header_text="Accordion Header" 
  body_description="This is the accordion body content." 
  custom_class="" 
  component_mode="">
</dda-accordion>

     <DdaAccordion 
        design="bg-border" 
        header_text="Accordion Header" 
        body_description="This is the accordion body content." 
        custom_class="" 
        component_mode="">
        </DdaAccordion>

       <DdaAccordion 
        design="bg-border" 
        header_text="Accordion Header" 
        body_description="This is the accordion body content." 
        custom_class="" 
        component_mode="">
        </DdaAccordion>

<dda-accordion 
  design="bg-border" 
  header_text="Accordion Header" 
  body_description="This is the accordion body content." 
  custom_class="" 
  component_mode="">
</dda-accordion>

Properties

Anatomy

Anatomy Options

Lead-Icon: An icon positioned at the start of the accordion title, providing visual context or indicating the type of content.

Title: The main text that describes the section of the accordion and prompts users to expand for more details.

Dropdown Icon: An icon that indicates the expandable and collapsible nature of the accordion, usually changing direction when clicked.

Dos and Don'ts

Overview

Usage

When to Use This Component

Alert banners are used to communicate critical information, warnings, or updates that require the user’s attention. They are ideal for displaying system messages, error notifications, success confirmations, and other significant alerts.

How It Works

An alert banner component typically includes a message and may also feature optional elements like icons, titles, and action buttons. Alert banners are usually displayed prominently at the top of the interface or within a designated alert area to ensure visibility. They can appear in different states—such as success, warning, error, or information—to reflect the nature of the message.

Code

<dda-alert
    type="primary"
    variation="info"
    title_text="Alert Title"
    description="This is an informational alert."
    button_text="Learn more"
    button_text="Learn more"
    custom_class=""
    component_mode=""
    first_link=""
    second_link=""
    onclick="console.log("clicked!")">
</dda-alert>

    <DdaAlert
            type="primary"
            variation="info"
            title_text="Alert Title"
            description="This is an informational alert."
            button_text="Learn more"
            custom_class=""
            component_mode=""
              onclick="console.log('clicked!')"
            >
        </DdaAlert>

   <DdaAlert
            type="primary"
            variation="info"
            title_text="Alert Title"
            description="This is an informational alert."
            button_text="Learn more"
            custom_class=""
            component_mode=""
              onclick="console.log('clicked!')"
            >
        </DdaAlert>

<dda-alert
    type="primary"
    variation="info"
    title_text="Alert Title"
    description="This is an informational alert."
    button_text="Learn more"
    custom_class=""
    component_mode=""
      onclick="console.log('clicked!')"
    >
</dda-alert>

Properties

Anatomy

Anatomy Options

Lead Icon: Positioned to the left of the alert title, the lead icon provides a visual cue about the nature of the alert (e.g., information, warning, or error). This icon helps users quickly recognize the alert type, enhancing clarity.

Title: The main label for the alert, summarizing the purpose of the message. It provides a clear and concise headline, drawing attention to the alert's content.

Message Body: Located below the title, the message body contains additional information or details about the alert. This text provides context, helping users understand the specifics of the alert.

Close Icon: Positioned in the top right corner, the close icon allows users to dismiss the alert. This feature provides users with control over the visibility of the alert, making it dismissible when no longer needed.

Primary Button: A prominent action button within the alert, often used for the main call-to-action related to the alert. It encourages users to take the primary action required by the alert message.

Secondary Button: A secondary action button that offers an alternative choice or a less critical action. Positioned next to the primary button, it gives users an additional option for interaction.

Dos and Don'ts

Overview

Usage

When to Use This Component

Avatars are used in user interfaces to visually represent individuals, groups, or objects. They are ideal for user profiles, messaging apps, social media, dashboards, and any interface requiring visual identification of users or entities.

How It Works

An avatar component displays a graphical representation, such as a photo, icon, or text (e.g., initials), within a shape (typically a circle or rounded square). Avatars can also include status indicators to show user status (e.g., online, verified). The component is configurable to display various sizes and styles based on the application’s needs.

Code

<dda-avatar
    type="photo"
    size="md"
    design="default"
    rounded="circle"
    src="https://img.freepik.com/premium-vector/traditional-arabic-man-head-icon-vector-avatar_55610-6301.jpg"
    icon="sentiment_satisfied"
    text="AB"
    options='["Option 1","Option 2","Option 3"]'
    notification-number="20"
    custom_class=""
    component_mode=""
    aria_label="avatar"
    button_id="button"
>
</dda-avatar>

       <DdaAvatar
                type="photo"
                size="md"
                design="default"
                rounded="circle"
                src="https://img.freepik.com/premium-vector/traditional-arabic-man-head-icon-vector-avatar_55610-6301.jpg"
                icon="sentiment_satisfied"
                text="AB"
                options='["Option 1","Option 2","Option 3"]'
                notification-number="20"
                custom_class=""
                component_mode=""
                aria_label="avatar"
                button_id="button"
            >
            </DdaAvatar>

   <DdaAvatar
            type="photo"
            size="md"
            design="default"
            rounded="circle"
            src="https://img.freepik.com/premium-vector/traditional-arabic-man-head-icon-vector-avatar_55610-6301.jpg"
            icon="sentiment_satisfied"
            text="AB"
            options='["Option 1","Option 2","Option 3"]'
            notification-number="20"
            custom_class=""
            component_mode=""
            aria_label="avatar"
            button_id="button"
        >
        </DdaAvatar>

    <dda-avatar
        type="photo"
        size="md"
        design="default"
        rounded="circle"
        src="https://img.freepik.com/premium-vector/traditional-arabic-man-head-icon-vector-avatar_55610-6301.jpg"
        icon="sentiment_satisfied"
        text="AB"
        options='["Option 1","Option 2","Option 3"]'
        notification-number="20"
        custom_class=""
        component_mode=""
        aria_label="avatar"
        button_id="button"
    >
    </dda-avatar>

Properties

Anatomy

Anatomy Options

Image: Displays the user’s profile picture, icon or text, providing visual identification. It helps users quickly recognize the individual represented.

Badge: Positioned in the top right corner of the avatar, the badge displays a notification count or status, such as "20+." This provides users with information at a glance, such as unread messages or notifications related to the user.

Status Icon: Positioned at the bottom of the avatar, the status icon indicates the user’s current status (e.g., online, offline, busy). It is often color-coded, enhancing visibility and making it easy to understand the user’s availability.

Dos and Don'ts

Overview

Usage

When to Use This Component

Breadcrumbs are used in websites and applications to provide users with a navigational trail from the current page back to the homepage or root of the content hierarchy. They are ideal for complex structures with multiple levels of navigation, helping users understand their current position and navigate easily.

How It Works

A breadcrumb component typically displays a series of links representing the path from the homepage to the current page. Each link corresponds to a level in the hierarchy, enabling users to navigate back to previous levels. Breadcrumbs can feature icons, text, or a combination of both to represent each level, with dividers visually separating the links for clarity.

Code

<dda-breadcrumb
    design="text"
    separator="chevron_right"
    custom_class=""
    component_mode=""
    data-breadcrumbs='[{"text":"Home","icon":"home","url":"/"},
                        {"text":"Library","icon":"menu_book","url":"/library"},
                        {"text":"Data","icon":"storage"}]'
></dda-breadcrumb>

<dda-breadcrumb
    design="text"
    separator="chevron_right"
    custom_class=""
    component_mode=""
    data-breadcrumbs='[{"text":"Home","icon":"home","url":"/"},
                        {"text":"Library","icon":"menu_book","url":"/library"},
                        {"text":"Data","icon":"storage"}]'
></dda-breadcrumb>

  <DdaBreadcrumb
            design="text"
            separator="chevron-right"
            custom_class=""
            component_mode=""
            data-breadcrumbs='[{"text":"Home","icon":"home","url":"/"},{"text":"Library","icon":"menu_book","url":"/library"},{"text":"Data","icon":"storage","url":"/data"}]'
        ></DdaBreadcrumb>

<dda-breadcrumb
    design="text"
    separator="chevron-right"
    custom_class=""
    component_mode=""
    data-breadcrumbs='[{"text":"Home","icon":"home","url":"/"},{"text":"Library","icon":"menu_book","url":"/library"},{"text":"Data","icon":"storage","url":"/data"}]'
></dda-breadcrumb>

Properties

Anatomy

Anatomy Options

Lead Icon: Positioned at the beginning of the breadcrumb trail, the lead icon (e.g., a home icon) visually represents the starting point or main category in the navigation path. It provides a quick visual cue for users to identify the home or root page.

Label: Each label in the breadcrumb trail represents a level or section within the navigation hierarchy, showing users their current location relative to previous pages. Labels guide users through the navigation path, helping them understand how they reached the current page.

Trail Icon: Positioned at the end of the breadcrumb trail, the trail icon represents the final destination or current page within the navigation path. This icon provides a visual indicator of the endpoint, helping users identify the active or last section in the breadcrumb sequence.

Dos and Don'ts

Overview

Usage

When to Use This Component

Attach file fields are used in forms or other input scenarios where users need to provide files, such as documents, images, or other file types. They are ideal for applications that require file uploads as part of processes like submitting forms, attaching documents, or uploading images.

How It Works

An attach file field component typically includes a label, a button to open the file picker dialog, and a display area to show the selected file name. Optional elements, such as placeholder text and helper text, can provide guidance to the user. The component can also display various states to reflect its status (e.g., focused, filled, error). The attach file field ensures users can easily select and upload files.

Code

<dda-attach-file
    label="Attach File"
    helper_text="Helper or footer text"
    error_message=""
    size="default"
    validation_type="normal"
    input_type="normal"
    custom_class=""
    component_mode=""
    input_id="input"
    button_id="button"
    aria_label="input"
    button_aria_label="button"
    onchange=""
></dda-attach-file>

   <DdaAttachFile
            label="Attach File"
            helper_text="Helper or footer text"
            error_message=""
            size="default"
            validation_type="normal"
            input_type="normal"
            custom_class=""
            component_mode=""
            onchange=""
            input_id="input"
            button_id="button"
            aria_label="input"
            button_aria_label="button"
        ></DdaAttachFile>

    <DdaAttachFile
            label="Attach File"
            helper_text="Helper or footer text"
            error_message=""
            size="default"
            validation_type="normal"
            input_type="normal"
            custom_class=""
            component_mode=""
            onchange=""
            input_id="input"
            button_id="button"
            aria_label="input"
            button_aria_label="button"
        ></DdaAttachFile>

<dda-attach-file
    label="Attach File"
    helper_text="Helper or footer text"
    error_message=""
    size="default"
    validation_type="normal"
    input_type="normal"
    custom_class=""
    component_mode=""
    onchange=""
    input_id="input"
    button_id="button"
    aria_label="input"
    button_aria_label="button"
></dda-attach-file>

Properties

Anatomy

Anatomy Options

Label: Positioned above the file selection area, the label indicates the purpose of the component, prompting users to attach a file. It provides context for the file input field.

Status Text: Displays the current status of the file selection, such as "No File Selected" when no file has been chosen. This text updates to show the selected file name, helping users confirm their selection.

Lead Icon: Positioned to the left of the helper or footer text, the lead icon provides an additional visual cue, often indicating information or help related to the file attachment process.

Caption: Positioned below the file selection area, the caption provides additional information, instructions, or tips regarding the file upload, guiding users as they interact with the component.

Button: The main action button labeled "Choose File" initiates the file selection dialog. This button allows users to browse and select a file from their device for attachment.

Dos and Don'ts

Overview

Usage

When to Use This Component

Social Media Login Buttons are ideal for providing users with a quick, familiar login option via their social media accounts. They are commonly used on login or signup pages, offering a seamless alternative to traditional email or password-based authentication.

How It Works

A Social Media Login Button enables users to authenticate by connecting their social media account with a single click or tap. Each button displays the logo of the corresponding social media platform, ensuring instant recognition and a clear understanding of the login method.

Anatomy

Anatomy Options

Brand Logo: Positioned to the left of the button text, the brand logo (e.g., the Apple logo, Google, Facebook) represents the social media or service provider associated with the login. This logo provides quick brand recognition, helping users identify the service they’re using for authentication.

Text: The main label of the button, such as "Sign in with Apple," describes the action that will be taken when the button is clicked. This text clarifies the login method, making it easy for users to understand the purpose of the button.

Dos and Don'ts

Overview

Usage

When to Use This Component

Link buttons facilitate straightforward navigation, using text to direct users to different pages or resources. They are perfect for contexts like footers or menu items where clear labeling is crucial. Typically used for actions such as "View More" or "Sign Up", they guide users effectively through a digital environment.

How It Works

A Link Button consists of clear, concise text within a button outline, designed to direct users with straightforward language. It optimizes navigation by clearly stating its function, such as "Learn More" or "Register." Link Buttons feature distinct visual states (hover, active, disabled) and can be styled to match the design hierarchy, facilitating easy user interaction and guidance through different sections or pages.

Code

Properties

Anatomy

Anatomy Option

Lead Icon: Positioned at the beginning, the lead icon primes the user on the button's function, offering a visual cue that enhances recognition and usability.

Text: The central text on the button conveys the action or intent clearly and directly, guiding the user with explicit instructions or labels.

Trail Action: A secondary icon or element at the end, providing additional interaction options or indicating further actions, such as navigation arrows or dropdown indicators.

Dos and Don'ts

Overview

Usage

When to Use This Component

Icon buttons allow users to perform quick actions using only an icon, making them ideal for spaces like toolbars, headers, or mobile interfaces where space is limited. They’re best suited for familiar actions (e.g., "edit," "delete") .

How It Works

An icon button consists of a single icon within a button shape, designed to convey its purpose through the icon alone. Icon buttons enhance usability by providing efficient, space-saving interactions. Each button has distinct visual states (hover, active, disabled) and can be styled to indicate hierarchy or function, supporting user navigation and interaction.

Anatomy

Anatomy Option

Icon: The central element of the button, the icon visually represents the action associated with the button. It allows users to quickly understand the button's purpose, especially in interfaces where space is limited. The icon itself is the primary visual cue, making the button intuitive and easy to recognize.

Dos and Don'ts

Overview

Usage

When to use this component?

Checkboxes are used when users need to select one or more options from a list. They are ideal for forms, settings, and any interface where multiple selections are allowed or required. Common use cases include selecting multiple interests, choosing preferences, or marking tasks as complete.

How it works

Checkboxes are typically presented in groups, with each box representing a different option that users can check or uncheck independently. Each checkbox includes a square box and a label, with optional elements like subtitles or trailing icons for additional context or emphasis.

Code

Properties

Anatomy

Anatomy Options

Checkbox Icon: The visual checkbox element that indicates the selection state. Users can check or uncheck this icon to select or deselect an option.

Checkbox Label: The main label associated with the checkbox, providing a brief description of the option or action related to the checkbox.

Subtitle: Positioned below the checkbox title, the subtitle offers additional context or supporting information about the checkbox option, helping users understand the checkbox's purpose.

Dos and Don'ts

Image Resolution and Quality

Ensure high-resolution images with 72 DPI for web. Use PNG, JPEG, or SVG formats. Optimize images for web to reduce load time without quality loss. Images must be sharp, well-lit, and free from pixelation.

Image Dimensions and Aspect Ratios

Use standard sizes with a 3:2 aspect ratio for banners, featuring scenic or context-specific imagery. Maintain consistent aspect ratios to avoid distortion. Provide multiple sizes for different devices to ensure optimized display across various screen sizes.

Style and Composition

Follow a style aligned with the brand identity, whether minimalistic, vibrant, or otherwise, to ensure consistency. Each image should have a clear focal point, with clean backgrounds, especially for icons and standalone objects. Maintain neutral lighting and consistent color tones across all images.

Color and Tonal Adjustments

Adhere to the brand's color scheme, adjusting saturation and brightness as needed to maintain color consistency. Include tonal variations, such as light, medium, and dark tones, where relevant. Ensure color contrast meets accessibility standards, especially for overlays, to support readability.

Usage and Placement

Select context-specific images that align with the content's purpose and reflect the entity's mission, such as landscapes for tourism or tech hubs for business. Position overlay text and icons on less busy sections of the image to enhance readability and ensure legibility.

Entity-Specific Selection

Entities should choose images that align with their purpose or mission, reinforcing the brand’s relevance and message.

1. Tourism

Use vibrant images of Dubai landmarks, such as the Burj Khalifa, Palm Jumeirah, or Dubai Frame, to highlight Dubai's unique attractions and appeal to tourists.

2. Transportation

Focus on images of Dubai’s infrastructure, like Sheikh Zayed Road, metro stations, or buses, to convey efficient transport options and promote public transportation.

3. Health

Use images of health facilities, medical staff, and community wellness, such as hospitals, clinics, or preventative health services, to emphasize Dubai’s healthcare standards.

Copyright and Usage Rights

Ensure all images are legally sourced, whether through licensed stock or original photography. Include attribution where required to acknowledge image sources. Avoid using copyrighted images without permission, opting for generic representations if necessary to stay within legal guidelines.

Accessibility

Provide Text Alternatives for Images

Add descriptive alt text to each image, conveying content and purpose for non-sighted users. For complex visuals like infographics, add a detailed description or link to one on the page. Decorative images without informational value should use an empty alt attribute (alt="") so screen readers skip them.

Accessible Names for Functional Images

For icons or images functioning as interactive elements, the alt text should describe their action or function. For instance, an icon for submission should use alt text like "Submit" instead of a visual description like "Arrow icon."

Provide Context for Images

Avoid using images as the only means to convey essential information; add text-based explanations as support to assist visually impaired users.

Responsive and Resizable Images

Ensure images scale appropriately across devices without losing quality. They should not become pixelated or distorted when zoomed or resized.

Contrast and Legibility

For images with text, maintain sufficient contrast between text and background, meeting minimum accessibility standards, such as a 4.5:1 contrast ratio.

Use of Captions and Text Descriptions

Provide captions for images when they offer information that complements the main text. For complex visuals, such as charts, include links to detailed text descriptions for further accessibility.

Use of ARIA Labels for Enhanced Accessibility

When using interactive or dynamic images, employ ARIA attributes like aria-labelledby and aria-describedby to associate images with labels or descriptions, enhancing context for screen reader users.

References

Overview

Usage

When to Use This Component

Buttons enable users to initiate an action or command with a click or tap. They are used to start actions, apply functions to selected objects, and activate or deactivate features. Buttons typically trigger an immediate response and can be placed within dialogs, forms, modal windows, and other containers.

How It Works

A button’s label or text description clearly conveys its purpose, guiding users in performing actions such as starting an application or saving information. Buttons serve as a fundamental building block of our products. While the secondary button variant is most commonly used, other variants are available to indicate different levels of hierarchy or specific functionalities.

Code

Properties

Anatomy

Anatomy Options

Lead Icon: Positioned to the left of the button text, the lead icon visually represents the action or purpose of the button. It provides a quick visual cue that helps users understand the button's function at a glance.

Text: The main label of the button, describing the action that will be performed when the button is clicked. Clear and concise text improves usability by indicating the button’s purpose.

Trail Action: Positioned to the right of the button text, the trail action (such as an arrow) further emphasizes the direction or nature of the action. It visually reinforces the button’s function, often indicating forward movement or progression.

Dos and Don'ts

Icon Style

Consistency is key; use a unified style (e.g., line, filled, flat, or outlined) to ensure visual harmony. Keep icons minimalistic with clean lines for easy recognition and scalability. Icons should be vector-based (SVG format) to maintain clarity at various sizes. Match the icon style to the brand’s tone (e.g., modern for tech brands, classic for traditional sectors). Entities have the option to use their own custom icons or to choose Material Icons, which we recommend as a standard option.

Icon Sizes

Define standard sizes for specific use cases. Small: 16x16px, ideal for dense UI elements like toolbars or status indicators. Medium: 24x24px, suitable for navigation icons or primary action buttons. Large: 32x32px, best for prominent areas, such as section headers or feature icons. Use increments that maintain balance and proportion, ensuring readability and clarity at each size.

Color and Tone

Use primary or secondary brand colors consistently in icons, reserving additional colors for emphasis or interactive states (e.g., hover, active). Ensure contrast for visibility, especially for overlays on different backgrounds, and meet WCAG color contrast guidelines. Assign distinct colors for icons representing specific categories (e.g., health, transportation) to aid quick recognition.

Spacing and Placement

Maintain equal padding around each icon to ensure visual balance. Icons should align consistently within the grid or layout, respecting margins and other visual elements. Group related icons to indicate relationships, with consistent spacing to improve readability.

Icon Usage

Use icons that intuitively convey their function or category (e.g., a heart for health, a bus for transportation). Use icons selectively to avoid visual clutter, reserving them for interactive elements, navigation, or key content indicators. Accompany icons with labels where necessary, especially when the icon alone may not be universally understood.

Visuals for Illustrations and Enhancements

Use purpose-driven illustrations that directly enhance content, like simple illustrations for explanatory text, or visuals that align with the subject matter (e.g., scenic illustrations for tourism). Consider overlay icons to provide additional context (e.g., a pin overlay on a map icon for location-based services). Visuals should reflect the brand’s tone, whether dynamic, professional, or friendly.

Accessibility Considerations

To ensure accessibility, icons should include alt text if they convey essential information, while purely decorative icons should be marked to be ignored by screen readers. Icons must meet a minimum contrast ratio of 3:1 and should not rely on color alone for meaning, supporting users with low vision or color blindness. Consistent icon usage reduces cognitive load, making it easier for users to recognize functions at a glance. For complex icons, adding text labels or accessible names helps clarify their purpose, especially for screen reader users.

Icons should be responsive, scaling smoothly for readability up to 200% and adapting across devices. These best practices ensure icons are clear, usable, and accessible for everyone.

References

1. WCAG 1.1.1 Non-text Content

2. WCAG 1.4.11 Non-text Contrast

3. WCAG 1.4.1 Use of Color

4. WCAG 1.4.4 Resize Text

5. WCAG 1.4.10 Reflow

Overview

Usage

When to Use This Component

Credit card visualizations are used in financial applications and dashboards to display essential information like card number, cardholder name, balance, and other relevant details. They are ideal for account overviews, payment details, or any interface where users need to view or manage their credit card information.

How It Works

A credit card visualization component presents key credit card information in a design resembling a physical card, typically displaying details such as the card number, cardholder name, and balance. It may include various visual styles to represent different types of cards, enhancing the user’s understanding and organization of their financial information.

Code

<dda-credit-card
    balance="$5,750.20"
    name="MARIA GOMEZ"
    card_number="1289"
    card_type="https://www.mastercard.com/content/dam/public/brandcenter/assets/images/logos/mclogo-for-footer.svg"
    design="default"
    custom_class=""
    component_mode=""
></dda-credit-card>

   <DdaCreditCard
            balance="$5,750.20"
            name="MARIA GOMEZ"
            card_number="1289"
            card_type="https://www.mastercard.com/content/dam/public/brandcenter/assets/images/logos/mclogo-for-footer.svg"
            design="default"
            custom_class=""
            component_mode=""
        ></DdaCreditCard>

    <DdaCreditCard
            balance="$5,750.20"
            name="MARIA GOMEZ"
            card_number="1289"
            card_type="https://www.mastercard.com/content/dam/public/brandcenter/assets/images/logos/mclogo-for-footer.svg"
            design="default"
            custom_class=""
            component_mode=""
        ></DdaCreditCard>

<dda-credit-card
    balance="$5,750.20"
    name="MARIA GOMEZ"
    card_number="1289"
    card_type="https://www.mastercard.com/content/dam/public/brandcenter/assets/images/logos/mclogo-for-footer.svg"
    design="default"
    custom_class=""
    component_mode=""
></dda-credit-card>

Properties

Anatomy

Anatomy Options

Card Header: Displays the header text, such as "Current Balance," indicating the purpose or type of information presented on the card.

Card Balance: Shows the current balance amount, providing the user with financial information at a glance.

Cardholder's Name: Displays the name of the cardholder, confirming ownership and identity on the card.

Card Number: Shows a partially masked card number for security, typically showing only the last four digits to help the user identify the card.

Contactless Symbol: Positioned in the upper right corner, this symbol indicates that the card supports contactless payments.

Brand Logo: Displays the logo of the card provider (e.g., Mastercard), adding visual identification of the issuing brand.

Dos and Don'ts

Overview

Usage

When to use this component?

The header component should be used on all pages of the website to provide a consistent navigation experience for users. It serves as a central hub for accessing key sections of the site, ensuring users can easily locate important features or content regardless of their current location within the website.