Frequently asked questions
General 8 questions
The UAE Design System is the official design and front-end framework for UAE federal government websites and digital services. It is an initiative of the Telecommunications and Digital Government Regulatory Authority (TDRA), which also maintains it.
It brings together everything a team needs to build consistent, accessible, bilingual services:
- Guidelines for colour, typography, iconography, imagery, layout, content, actions, accessibility and mobile applications
- Components such as buttons, inputs, tabs, modals, headers and footers, delivered as
aegov-*Web Components - Blocks and patterns that combine components into ready-made page sections and proven solutions for common inputs
Version 4.0 ships the components as framework-agnostic Web Components with wrappers for React, Vue and Angular. Start with the documentation or read more about the design system.
Yes. Watch the introductory video on YouTube for a quick overview, then read the About page to understand who the design system is for and how it is governed.
If you are a designer, continue with the guidelines. If you are a developer, go straight to installation.
They are three levels of the same system, from smallest to largest:
| Level | What it is | Examples |
|---|---|---|
| Components | Single, reusable interface elements | Button, Input, Tabs, Modal |
| Blocks | Page sections built from several components | News, Newsletter, Statistics, Team |
| Patterns | Proven solutions for a recurring user need | Emirates ID, Address, Date, Name |
Use a component when you need one element, a block when you need a whole section, and a pattern when you are asking users for common information such as an Emirates ID or a phone number.
Yes. The design system is recommended for both public-facing service portals and internal portals, not only for informational websites. Forms, validation, steps, uploads and feedback components are all designed for transactional services.
For sign-in, the Actions guideline recommends UAE Pass as the way users sign in. When a user signs in with UAE Pass, prefill the details you already have, such as their name and Emirates ID, instead of asking for them again.
Mobile-first means you design and build for the smallest screen first, then progressively enhance the layout for tablets and desktops. It forces you to prioritise the content and actions that matter most, which benefits every user.
In the UAE Design System, layouts start at 320 px wide and scale up through the standard breakpoints. Components and blocks are already responsive, so your job is mainly to plan content and test on real devices first.
Further reading:
Yes. Arabic and English are supported equally. Every component works in both left-to-right and right-to-left layouts, and the guidelines include specific rules for Arabic:
- Typography: Noto Kufi Arabic for body text and Alexandria for headings. See Typography.
- Content: write each language natively in Modern Standard Arabic and English rather than translating word for word. See Content.
- Icons: directional icons such as arrows are mirrored in Arabic. See Iconography.
Developers should set lang="ar" and dir="rtl" on Arabic pages and use logical spacing utilities. See the Development tab for details.
Choose the channel that fits your question:
- Report a bug or problem: open an issue on GitHub Issues.
- Ask a question or share an idea: start a conversation in GitHub Discussions, where other teams can benefit from the answer.
- Email the team: designsystem@tdra.gov.ae.
Before you get in touch, search the documentation and this FAQ, as your answer may already be there.
Compliance & assessment 6 questions
All federal government entities must comply with the UAE Design System, and federal government websites and mobile applications are expected to comply with it. How strictly depends on the type of entity:
| Entity | What applies |
|---|---|
| Ministries | Must use the guidelines, components and blocks exactly as provided, in line with the UAE Government branding guidelines. |
| Federal authorities | Must use the design system, but may apply limited branding, such as their own primary colour. |
| Initiatives and supporting websites | Not mandatory, but strongly recommended. |
Read more about the design system.
The purpose of the design system is a consistent experience across government. Every component is based on research and accessibility testing, so changing it can break both.
- Ministries must use components and blocks as they are, without any modification.
- Federal authorities may make limited changes, such as applying their brand colour through the theme configuration. Core component structure and behaviour must not change.
- Initiatives may choose whether to use the design system, although using it is recommended.
External agencies can build your website, but your internal team owns the result. The internal team should:
- Know the guidelines well enough to review work against them.
- Lead planning and decisions, rather than leaving them to the vendor.
- Write the content first. The design brief should include at least 50% of the approved copy, because design without real content leads to rework.
- Check development against the standards before launch, using the assessment criteria.
Self-evaluation is the best preparation for an assessment:
- Review your pages against the guidelines, especially colour, accessibility, layout and typography.
- Review your copy against the content guideline.
- Run automated accessibility and performance checks, then test manually with a keyboard and screen readers in Arabic and English.
- Score yourself against the assessment criteria and document the reasons for any justified deviation.
Yes. Federal government mobile applications are expected to follow the design system, and the Mobile applications guideline covers them in detail, including:
- UAE Pass as the primary sign-in method
- Bottom navigation with three to five destinations, mirrored in Arabic
- Customer Pulse, which is mandatory in every federal government app
- An accessibility statement and support for the device's language setting
Hybrid apps that use a WebView can use the web components directly. Fully native apps built with SwiftUI or Jetpack Compose should follow the guidelines, as native component libraries are not yet available.
The Excellence Program recognises professionals and organisations that apply the design system to a high standard. It has two tracks:
- Private Sector Excellence Track, leading to the Approved UAE Design System Expert recognition
- Government Adoption Track, leading to the Design System Pioneer recognition
Training is delivered through accredited partners, including Conceptualize, Future Internet and Quality Professionals.
Guidelines 8 questions
No. Colour rules depend on the type of entity:
- Ministries must use the core palette without changing any colour swatch. There are no exceptions.
- Federal authorities may replace the primary colour with their own brand colour. The 600 shade must still reach a WCAG AA contrast ratio of at least 4.5:1 against the 50 shade.
The core palette uses AE Gold, AE Red, AE Green and AE Black, and was approved by the UAE Cabinet Office for use across federal government entities. AE Gold (#B68A35) does not have enough contrast as a background for text, which is why components use a darker gold (#90702a).
The palettes in the Colour guideline are already contrast-tested, so using them as they are is the safest choice. Developers can apply a brand colour through the theme configuration.
| Language | Body text | Headings |
|---|---|---|
| English | Roboto | Inter |
| Arabic | Noto Kufi Arabic | Alexandria |
All four are open-source Google Fonts served in WOFF2 format. The body text size is 16 px with a line height of 1.5, and headings follow a 1.2 (minor third) scale. Use five or fewer font weights on a page. See the Typography guideline for the full type scale.
The design system uses Phosphor Icons, an open-source (MIT licensed) library of 1,512 icons, each in six weights: thin, light, regular, bold, fill and duotone.
The default icon size is 24 × 24 px. Match the icon weight to the weight of the text next to it, and mirror directional icons in Arabic. Inline SVG is the recommended way to add icons. See the Iconography guideline.
First, search Phosphor Icons using synonyms, because most concepts are covered by one of its 1,512 icons. If you still cannot find a suitable icon, your design team may create a custom one that matches the library:
- Use the same canvas size and grid as Phosphor icons.
- Match the stroke width and corner style of the weight you use.
- Provide it in the same weights you use elsewhere on the page.
- Make sure it meets a 3:1 contrast ratio if it conveys information.
Follow the Iconography guideline so that custom icons sit naturally alongside library icons.
Use icons from the recommended library as described in the Iconography guideline, placed next to the button label rather than behind it. Icons behind text reduce contrast and make labels harder to read. If a service needs a custom icon, it must follow the same style rules as the library.
Use one solid (primary) button per view, for the main action users came to do. Secondary actions use the outline or soft style, and minor actions use a link.
Button labels should start with a verb and be four words or fewer, for example Start service or Download requirements. Do not disable a submit button to signal errors; let users submit and then show clear error messages. See the Actions guideline.
The voice is corporate yet approachable. Speak directly to users as "you" and refer to your entity as "we".
- Use sentence case for headings and buttons.
- Follow British English spelling, as in the Oxford dictionary, and use the serial comma.
- Avoid jargon and internal terms, such as "e-services".
- Write Arabic and English content natively instead of translating word for word.
See the Content guideline for examples.
Use modern formats to keep pages fast:
- WebP is supported by all modern browsers and is typically 25–35% smaller than an equivalent JPEG.
- AVIF usually compresses even further than WebP.
- SVG is best for logos, icons and simple illustrations.
Serve different sizes with srcset, keep a JPEG fallback through the <picture> element, and add loading="lazy" to images below the fold. Every meaningful image needs alternative text. See the Imagery guideline.
Accessibility 8 questions
The design system targets WCAG 2.2 level AA (Web Content Accessibility Guidelines 2.2). This exceeds the minimum of WCAG 2.1 level AA set by the UAE National Policy for Digital Accessibility.
Components are built and tested to meet these criteria, but your content, images and page structure also need to conform. See the Accessibility guideline.
No. Level AA is required and level AAA is not. Level AA contrast requirements are:
| Element | Minimum contrast |
|---|---|
| Normal text | 4.5:1 |
| Large text (24 px, or 18.66 px bold) | 3:1 |
| Icons, input borders and focus indicators | 3:1 |
The colour palettes in the Colour guideline are tested against these ratios. You may go beyond AA where it is practical, but it is not a requirement.
The National Policy for Digital Accessibility, issued by TDRA in March 2024, applies to all federal ministries, authorities and institutions. Among other things, it requires each entity to:
- Meet at least WCAG 2.1 level AA
- Appoint a Digital Accessibility Officer
- Publish an accessibility statement
Using the design system helps you meet the technical requirements, but appointing an officer and publishing a statement are your entity's responsibility.
WCAG 2.2 level AA (success criterion 2.5.8) requires targets of at least 24 × 24 CSS pixels, or enough space around smaller targets.
For touch interfaces, aim higher: 44 × 44 pt on iOS and 48 × 48 dp on Android, as recommended in the Mobile applications guideline. Floating action buttons must be at least 44 × 44 px. Design system components already meet these sizes.
Yes, if they move on their own. WCAG success criterion 2.2.2 (level A) requires any content that moves automatically for more than five seconds to have a way to pause, stop or hide it.
Pausing on hover alone is not enough, because keyboard, touch and screen reader users cannot hover. Provide a visible pause control, or do not auto-advance at all. Also respect the user's reduced-motion setting.
For performance reasons, limit banners to three slides. See the Performance tab.
Yes. Under WCAG 2.2 level AA:
- Pre-recorded video with audio needs captions and audio description (or a full text alternative).
- Live video with audio needs live captions.
- Audio-only content needs a transcript.
Provide captions in both Arabic and English where the audience needs them. The W3C Making audio and video media accessible guide explains how.
Yes. Users must be able to zoom to 200% without losing content or functionality, and content must reflow without horizontal scrolling at a width of 320 CSS pixels (equivalent to 400% zoom on a 1280 px window).
Text must also stay readable when users increase line height, letter spacing and word spacing. Avoid fixed heights on text containers. See the Accessibility guideline.
Combine automated and manual testing, because automated tools find only part of the issues:
- Automated checks with a tool such as axe-core on every page whenever something new is added.
- Keyboard testing: reach and use every control without a mouse, with a visible focus indicator that is never hidden behind sticky elements.
- Screen reader testing in both Arabic and English.
- Zoom and reflow testing at 200% zoom and at 320 px width.
Then publish the results in your accessibility statement. Our own accessibility policy is an example.
Layout 11 questions
Partly. A homepage must start with these sections, in this order:
- The header and navigation, using the
<aegov-header>component - A hero section
- The service catalogue
After that, you may add and arrange sections creatively, although initiatives and news are recommended. The page must end with the <aegov-footer> component.
Base every decision on user value and page speed. For example, social media feeds add weight and take users away from your website, when the goal of social media is to bring users to it.
The design system uses the Tailwind CSS breakpoints, plus an extra small xs breakpoint:
| Breakpoint | Minimum width |
|---|---|
xs |
480 px |
sm |
640 px |
md |
768 px |
lg |
1024 px |
xl |
1280 px |
2xl |
1536 px |
Wrap content in .aegov-container (up to 1536 px wide), use a six-column grid with a 24 px gutter, and build spacing from the 4 px base unit. See Layout and spacing.
Yes. The design system is mobile-first: start every layout at 320 px wide, test on mobile first, then enhance for larger screens. Components and blocks are responsive by default.
See Layout and spacing for breakpoints and grids, and Mobile applications for native and hybrid apps.
Yes, it is optional. Scrolling is natural on the web, so add it only if your pages are long enough to need it.
If the button is sticky, it must never cover clickable content or the keyboard focus indicator, as required by WCAG 2.2 for floating elements. A good approach is to show the button only when the footer is in view, signalling that the user has reached the end of the page.
Place app download links in a banner directly above the footer, not inside the footer component. You may show this banner on every page, on selected pages or only on the homepage.
It is not recommended. Every element on a page should give value to users, and a total visit count does not.
Collecting analytics for every page visit is mandatory, and you may use any analytics tool. If you want to share visitor data publicly, an open data section with meaningful visualisations is more useful than a counter.
If your entity still decides to show a counter, place it below the contact number section of the footer and explain your reasons in the assessment criteria.
No. Services differ, so describe each one in the way that helps users most. A good service page usually includes:
- A description of the service in at least 100 words
- The procedure the user should expect
- Conditions and requirements, including documents
- Service-specific FAQs, if any
- Service attributes, such as fees, processing time and channels
Use any component that suits the content, such as the Timeline for procedures that vary, Accordion for FAQs, or Tabs for different user groups.
No. The contact form in the template is a placeholder, and you may add or remove fields. Every field must use the design system form components, such as Input, Select, Radio, Checkbox and Textarea, and follow the form guidance in the Actions guideline.
Ask only for what you need. For phone numbers and names, use the Contact number and Name patterns.
Yes, as long as the extra sections follow the content, layout and accessibility guidelines. Common additions include a map of service centres, working hours and social media links.
Yes. You may show the form inline on the page or in a Modal. If you use a modal, make sure it works well on mobile first and that keyboard focus moves into the modal and returns when it closes.
We strongly recommend a dedicated sustainability page that explains how your entity contributes to the UN Sustainable Development Goals. Showing which services, initiatives or documents relate to which goal is optional.
If you use the official SDG icons, give each one alternative text with the goal's name, because the icon alone does not explain its meaning.
Components & Blocks 8 questions
Components cover everything from form controls to page structure, including:
- Forms: Input, Select, Checkbox, Radio, Datepicker, File upload, OTP, Toggle
- Navigation: Header, Navbar, Breadcrumbs, Pagination, Tabs
- Feedback: Callout, Toast, Progress, Badge
- Content and overlays: Card, Accordion, Modal, Drawer, Tooltip
Browse the full list in the components documentation.
Yes. Patterns show how to ask for information that government services collect often:
Using these patterns keeps forms consistent across government, so users recognise them from one service to the next.
Form components have built-in support for validation states. You can mark a field as invalid, show an error message and a hint, and listen for the aegovValidate event, with no extra package needed.
The design system does not ship its own validation rules, so you can use native browser validation or any validation library you already use. See Validation and Bring your own validator.
Yes. Decide how favourites are stored and shown before you add it:
- Signed-in users: save favourites to their account so they are available on every device.
- Guests: if you use cookies or local storage, mention this in your privacy and cookie policy.
- Moving between the two: consider moving a guest's favourites to their account when they sign in.
Use a library icon with an accessible label, such as "Add Business licence renewal to favourites", and announce the change to screen reader users.
Decide first whether the alert can be dismissed:
- A dismissible alert is closed on purpose, and closing it means the user has read it. It does not need to come back.
- An alert that must stay visible, such as a service outage, should not be dismissible.
The Callout component supports both. For short, temporary messages, use a Toast.
Yes. Filters and sorting help users find content, as long as they are relevant to the content being searched. Build them from standard components:
- Select for sort order, such as Newest first or A to Z
- Checkbox for categories
- Datepicker for date ranges
On mobile, consider showing filters in a Drawer to save space.
You may adapt blocks to fit your content. For example, add a Select labelled Document type to choose a document, or list each document with its own download button.
Use the same library download icon throughout, and include the file type and size in each link, for example Application form (PDF, 240 KB), so users know what to expect.
- Themes: custom colour themes are not recommended, because consistency across government is the goal.
- Virtual tour: treat it as content, linked from the relevant navigation, rather than a setting.
- User preferences: a settings menu is acceptable if preferences are saved to the user's account or locally, and your cookie policy explains this.
- Accessibility settings: respect what users have already set on their device, such as text size, contrast and reduced motion, before offering extra controls.
Development 10 questions
Install the package and Tailwind CSS (shown here with Vite):
npm install @aegov/designsystem
npm install -D tailwindcss @tailwindcss/vite
Import the styles in this exact order in your main CSS file:
@import "tailwindcss";
@import "@aegov/designsystem/base";
@import "@aegov/designsystem/theme";
Then register the Web Components:
import { defineCustomElements } from '@aegov/designsystem/loader';
defineCustomElements();
You can now use any aegov-* element in your HTML. The installation guide also covers Webpack, Parcel, Rollup and using the design system without a bundler.
Yes. The components are standard Web Components, so they work in any framework. Official wrappers make them feel native:
| Framework | Package | Minimum version | Guide |
|---|---|---|---|
| React | @aegov/designsystem-react |
React 18 | Using with React |
| Vue | @aegov/designsystem-vue |
Vue 3.5 | Using with Vue |
| Angular | @aegov/designsystem-angular |
Angular 18 | Using with Angular |
Install the wrapper alongside the core @aegov/designsystem package.
Yes, with some care around server-side rendering:
- Next.js: server rendering can currently cause a React hydration mismatch, so load the components on the client only. See Using with React.
- Nuxt: avoid
v-modeldirectly onaegov-*elements when rendering on the server. See Using with Vue.
The design system is built on Tailwind CSS v4, and the documented setup uses it. Tailwind CSS v4 is configured in CSS, so there is no tailwind.config.js file; you customise the design system with an @theme block placed after the three imports. See Installation and Extending the configuration.
Federal authorities may replace the primary colour. Override the primary colour tokens in an @theme block after the design system imports:
@theme {
--color-primary-50: oklch(…);
/* …through… */
--color-primary-950: oklch(…);
}
Provide the full 50–950 scale, and check that the 600 shade reaches at least 4.5:1 contrast against the 50 shade. Ministries must not change the primary colour. See Extending the configuration and the Colour guideline.
| Browser | Minimum version |
|---|---|
| Chrome and Edge | 111 |
| Firefox | 128 |
| Safari (macOS and iOS) | 16.4 |
| Samsung Internet | 22 |
Internet Explorer is not supported. On older browsers, use graceful degradation so core content and tasks still work. See Browser support.
Because no single resolution or browser is preferred. The design system is responsive and uses graceful degradation, so pages adapt to any screen size and supported browser. Choose your testing breakpoints and devices from your own analytics.
If a feature cannot work in a user's browser, show a specific notice that names the detected browser, explains what does not work and tells the user what to do, rather than a generic "outdated browser" message. See Browser support.
- Set the language and direction on the page:
<html lang="ar" dir="rtl">. - Use logical utilities, such as
ms-*,me-*andtext-start, instead of left and right, so layouts mirror automatically. - Mirror directional icons, such as arrows, with
rtl:-scale-x-100. - Load the Arabic fonts, Noto Kufi Arabic and Alexandria.
- Test with an Arabic screen reader.
Components handle their own direction once dir is set. See Layout and spacing and Typography.
Yes. Colours, spacing, typography and other values are defined as design tokens, as CSS variables in code and as variables in the Figma design file. This keeps design and development in sync. Read What are design tokens and how to use them.
Change component values only through the supported tokens, such as the colour definitions, so your website keeps working when you upgrade.
Hybrid apps that display web content in a WebView can use the web components directly. Native component libraries for SwiftUI and Jetpack Compose are not yet available, so native apps should follow the Mobile applications guideline and recreate the design with platform components. The minimum supported iOS version is 16.4.
Performance 6 questions
Measure loading speed with Largest Contentful Paint (LCP), the time it takes for the main content of a page to appear.
- Google considers an LCP of 2.5 seconds or less good, measured for at least 75% of page visits.
- The UAE Design System sets a stricter target: LCP should not exceed 2 seconds on any page.
Test your pages with PageSpeed Insights and include the results in your assessment criteria.
Track the three Core Web Vitals, measured for at least 75% of page visits:
| Metric | Measures | Good |
|---|---|---|
| Largest Contentful Paint (LCP) | Loading | 2.5 s or less (design system target: 2 s) |
| Interaction to Next Paint (INP) | Responsiveness | 200 ms or less |
| Cumulative Layout Shift (CLS) | Visual stability | 0.1 or less |
Check them on mobile as well as desktop, because most users visit on their phones.
It is a recommendation rather than a hard limit, based on performance. A homepage banner is usually the largest element on the page, so it directly affects LCP.
- Use no more than three slides.
- Load only the first image straight away, and lazy-load the rest.
- Use up to five slides only if the page still meets the LCP target.
Remember that auto-advancing slides need a pause control. See the Accessibility tab.
Usually not. A fast page does not need one, and a loader that covers the page can make it feel slower. Improve real loading speed first.
If you do use a loading indicator, for example while a service fetches data, it must announce its status to screen readers (WCAG success criterion 4.1.3). Read Is adding a page loader to a website necessary?
- Serve WebP or AVIF instead of JPEG or PNG.
- Use
srcsetso mobile phones download smaller files. - Add
loading="lazy"to images below the fold, but never to the main hero image. - Set
widthandheighton every image to prevent layout shifts. - Use SVG for logos and icons.
See the Imagery guideline.
It is not recommended. Embedded feeds load heavy third-party scripts that slow your page down, and they lead users away from your website. The purpose of social media is to bring users to your website, not the other way around. Link to your social media accounts from the footer instead.
Using AI 6 questions
Yes. AI coding and design assistants can speed up your work, but you remain responsible for the result. Anything an AI tool produces must meet the same standard as work done by hand: the guidelines, WCAG 2.2 level AA and your entity's security policies.
Read The disappearing handoff: how AI is collapsing the gap between design and code.
AI tools produce better results when you give them the right context:
- Ask them to use the
aegov-*components instead of writing custom HTML and CSS. - Share the relevant component documentation and guidelines with the tool.
- Ask for the installation set-up described in the installation guide.
- Check that the output does not change component structure or hard-code colours.
An MCP server that connects AI coding tools directly to the design system is on the roadmap.
Yes, always. AI tools often produce code that looks right but fails accessibility, for example with missing labels, wrong heading order, poor focus handling or images without alternative text.
Test AI-generated work in the same way as any other work: automated checks, keyboard testing, and screen reader testing in Arabic and English. The Accessibility tab on this page and the Accessibility guideline explain how.
You may use AI to help draft content, but do not publish machine translation without review. The Content guideline asks teams to write each language natively rather than translate word for word, using Modern Standard Arabic.
Have a native Arabic writer review and edit every AI-assisted text for accuracy, tone and government terminology before it goes live.
Treat public AI tools like any external service. Do not paste:
- Personal data about users, such as names, Emirates ID numbers or contact details
- Confidential or classified government information
- Credentials, API keys or access tokens
- Unpublished source code, unless your entity has approved the tool
Follow your entity's information security and data classification policies, and use tools your entity has approved.
Use them with care. Images on government websites should be authentic and represent the UAE and its people accurately, so check every AI-generated image for errors, such as distorted hands, incorrect text, or inaccurate national dress, landmarks and symbols.
Never use AI to create or alter images of real officials, national symbols or official documents. Every image still needs alternative text and must follow the Imagery guideline.
Try a different word, or ask the design system team.
Didn’t find your answer?
Ask the community in GitHub Discussions, report a problem on GitHub Issues, or email the design system team.