# Introduction Welcome to Quantum, the Thales Group digital Design System. ## Who is this for? Quantum is for everyone involved in designing, building, and improving digital products and user interfaces across all entities of the Thales Group: primarily software designers and software developers, but also product teams, UX practitioners, and contributors involved in shaping consistent user experiences. ## What is this for? It’s designed to support software design and development across projects of every size, from simple interfaces to complex digital ecosystems. Quantum is also multi-platform and multi-device, helping teams create consistent experiences for websites, mobile apps, embedded systems, and desktop applications. ## Why a Design System? For a group like Thales, which delivers many different digital products, a Design System is essential to create consistency across user interfaces, but also across the teams who design and build them. It establishes a shared brand expression, a common language, and reusable foundations that help software designers and developers work toward the same goal, even when products, domains, and use cases differ. By reusing design assets, components, patterns, and code, teams can move faster, reduce duplication, and generate economies at scale in both design and development. At the same time, a Design System strengthens the front-end community around shared practices and standards, and helps maximize the final and perceived quality of products by delivering a more coherent, robust, and premium user experience. It also plays a key role in the age of AI. As its resources are structured, standardized, and validated as a shared pillar, Quantum provides the essential foundation to make product teams more AI-operable. By organizing design knowledge, components, patterns, and implementation assets in a reliable and reusable way, the Design System helps AI-enabled tools understand, support, and scale product creation with greater consistency and confidence. ## How does this take shape? Quantum is materialized through a complete ecosystem of shared resources for both design and development. It includes design foundations, guidelines, design tokens, reusable components, patterns, documentation, and implementation libraries that help teams create consistent user interfaces across digital products. These assets are made to support real product work across platforms and devices, while enabling software designers and developers to rely on the same principles, the same language, and the same building blocks. ## Where to start? Head over to the [Getting started](/docs/welcome/getting-started) section to explore the essentials and take your first steps with Quantum. # Getting started Quantum can be consumed through several layers, each layer corresponds to a different kind of system resource. Not every team will need every layer, but everyone should at least use the DNA and the Foundations: DNA defines the guiding principles of the system, while Foundations provide the key visual attributes needed to apply them consistently across products and experiences. The main Quantum layers are: 1. **DNA** 1. **Foundations** 1. **Components** 1. **Extensions** 1. **Templates** In addition to these layers, Quantum also provides **Patterns** and **Processes**, which support the system but do not belong strictly to the layer architecture. ## DNA DNA is the expressive layer of Quantum. It captures the brand guidelines, the design intent, and the principles that shape the overall identity and character of the system. This layer helps teams understand not only what to build, but also the spirit in which Quantum should be applied. ## Foundations Foundations define the design decisions that make the system coherent across products. They include all the subatomic visual attributes of a user interface, such as color, typography, spacing, and so on. Along with DNA, Foundations are part of the minimum layers that everyone should use. Design tokens belong to this layer as structured foundation resources. They translate foundational decisions into reusable values that can be consumed across design and development tools. Check out the following resources for more details: - [Foundations](/docs/foundations/) - [GitLab | Quantum Design Tokens](https://gitlab.thalesdigital.io/thales-design-system/quantum-tokens/) ## Components Components are the reusable UI building blocks of Quantum, such as buttons, inputs, cards, navigation elements, and other interface atoms and molecules. They help teams design and build faster while staying aligned with system standards. Component-related tokens can also support this layer by encoding reusable component values and behaviors. Depending on your workflow, Quantum components can be consumed through design libraries or development libraries. Check out the following resources for more details: - [Components](/docs/components/) - [Figma | Quantum component libraries](https://www.figma.com/files/915304642490219366/project/25113705/%F0%9F%8C%8D-Thales-Design-System?fuid=812250648660319132) - [Penpot | Quantum component library](https://forms.cloud.microsoft/e/3n7KHWQ285) - [Web development libraries](https://developers.quantum.thalesdigital.io) ## Extensions Extensions are larger functional assemblies built around broader product needs or domain capabilities. They go beyond isolated components and cover bigger concepts such as data visualization. This layer is useful when teams need reusable solutions for complex and specific capabilities. On the implementation side, they often depend on dedicated external libraries and ecosystems. Check out the [Extensions](/docs/extensions/) for more details. ## Templates Templates are higher-level starting points that help teams work from complete page structures, UI references, and reusable layouts. They are useful when teams need to accelerate delivery, align around concrete page-level examples, or start from pre-assembled references rather than from individual components alone. Check out the following resources for more details: - [Figma | UI references](https://www.figma.com/files/915304642490219366/project/25113705/%F0%9F%8C%8D-Thales-Design-System?fuid=812250648660319132) - [Templates](/docs/patterns-templates/) ## Patterns Patterns are not a layer of the system itself. They are reusable solutions to common UX problems and interaction needs. They help teams address recurring needs consistently and align with how the company delivers these user experiences, including the underlying engineering decisions and supporting systems behind them, such as data infrastructure and authentication management. Check out the [Patterns](/docs/patterns-templates/) for more details. ## Processes Processes are also outside the layer architecture. They describe how projects interact with Quantum through recurring workflows and collaboration practices, including how they use and extend it. This includes topics such as design-development hand-off, component creation and maintenance, documentation workflows, accessibility-first practices, contribution models, review processes, and other recurring interactions around Quantum. The processes currently documented in Quantum are: - [Working with AI](/docs/working-with-ai/) Processes help teams use Quantum effectively across the full product lifecycle, and more process-oriented documentation will be added over time. # Meet the Core Team The Quantum core team guides the product vision, design direction, and technical execution for the platform. Below is a quick overview of the folks working full-time on Quantum. | Name | Role | | ---------------- | ---------------------- | | Aurélien Brigaud | Designer (Contractor) | | Bogdan Vasile | Developer | | Edgar Lechaudel | Design Lead | | Emilien Vivier | Developer (Apprentice) | | Julien Déramond | Tech Lead | | Oana Vasilescu | Designer | # Colors Color is one of the fastest things the human brain is able to process and interpret. So yes, big deal. In Thales Design System, color help us bring brand identity and consistency to our products. ## Color themes Color themes are designed to be harmonious, ensure accessible text, and distinguish UI elements and surfaces from one another. Multiple color themes ensure that we can support various environmental requirements from our users. ### Quantum themes Quantum Design System currently offers 2 color themes: light, and dark. However, a dark color theme is being evaluated with the Guild to ensure that we create a theme that delivers the correct expectations for our designers and end-users. Thales products can support a number of color themes, allowing users to switch between them. The choice of which color themes to support should be based on the content, platform and user experience. #### Recommendation Quantum is aimed at being compatible with multiple background colors, to allow designers to choose the best for their users: - Light theme: White 100, bg25, bg50 and bg100. - Dark theme: Black 100, bg900, bg850, bg800. ## Digitalizing Thales Light & Dark Blue In the Thales Brand Standards, the Thales blue had been modified for use on digital medium. For the Thales Design System to optimize the communication of Thales Signature while meeting accessibility standards, colors needed a rework. ### Group color palette The two main Group colors, Thales dark blue and Thales light blue, have a direct correlation with the Thales logo. These colors must be used at values of 100% only (transparency set to 0). On pages inside publications and in online documents/pages, the colors may be used with different transparency levels but not different hue values. ### Initial proposal for digital use In the Thales Brand Standards, the light blue had been modified for use on digital medium. It was intended to be used as the primary color. No change had been applied to the digital dark blue compared to the dark blue from the Thales group palette. These choices arise some issues that were pinpointed by digital teams at Thales: - The light blue is not a colour that can be easily compliant with accessibility standards. - The light blue digital rework did not follow a clear formula based on the colour model approach. - The dark blue does not have enough vibrancy to really thrive on digital medium. By consequence, some decisions had to be made: - The light blue must not be used as the primary colour in order to preserve Thales signature while meeting [accessibility standards on the web](https://www.w3.org/WAI/standards-guidelines/wcag/). - The dark blue colour must be reworked to be optimised for digital use. - The reworked dark blue colour must be contrast compliant and become the primary colour. ### Creating a dark blue colour for digital use To achieve a digitalised dark blue for the Thales Design System, a HSL (for hue, saturation, lightness) formula was created in order to generate the Thales dark blue in a digitalised format. The formula was taken from the Thales Digital Light Blue: - **H (Hue)** = (original value) - 2 - **S (Saturation)** = (original value) + 42 - **L (Lightness)** = (original value) - 17 The purpose of the dark blue is to compliment the TDS light theme, therefore it has been decided that the lightness of the original colour will be maintained to ensure a reasonable level of contrast with black and other dark colours. Hence, the adapted formula has been agreed to maintain this level of contrast. ## Color palettes Thales Design System’s colours are designed to be clear and accessible. They come in different colour themes. Each theme is constituted of greys, semantic colours (e.g., blue, red, orange, green), and label colours. ### Blue Palette Our primary palette is derived from the Thales Brand Standards, comprised of neutrals, white and blue. These colours are designed to be clear and accessible. We use blue (`$color.blue.500`) for primary actions, buttons, text links. Text (`$color.bluegrey.900`) is used primarily for body text and headings, white (`$color.white`) is used for surfaces such as cards, and light neutral (`$color.bluegrey.25`) is used for page backgrounds. ### Secondary Palette Our secondary palette contains a variety of colours derived from the Thales Brand Standards additional colour palette. These colours are used to emphasize elements within your user interface and to keep things fresh and interesting. It is made up of red (`$color.red.500`), yellow (`$color.yellow.500`), green (`$color.green.500`), light blue (`$color.secondary.500`), and magenta (`$color.purple.500`). Each colour is selected intentionally to provide meaningful feedback within our products. See the semantic colour guidelines below for more information. ### Color usage Find appropriate usage for the base Light Theme in Quantum in the palette below. ### Colour Ramps The Colour Ramps are a comprehensive set of tint shades, based on Core and Secondary Palettes. This palette is complementary to the main colours to create emphasis on the colour choice. Every colour has been tested for WCAG 2.1 contrasts and the results are displayed on the cards. To check your colour contrasts, we encourage using the [Figma | Stark – Contrast & Accessibility AI Checker](https://www.figma.com/community/plugin/732603254453395948) plugin, available by default for all Thales Figma users. ## Semantic Colors Semantic colours have assigned meanings and are consistently used throughout TDS to set expectations for our users. Semantic colour helps users to identify status, see actions, locate help, and understand next steps. The consistent use of colour keeps cognitive load low and makes for a unified and engaging user experience. TDS has different semantic colours (accessible with white to support our light theme) that are associated with the following predefined value states: Semantic colours are to be used if: - You want to highlight an important status. - You want to validate fields using form field validation. - Your platform needs message or alert handling. - You want to use the value states for a control. Do not use semantic colours if: - The colour has no meaning and is used only for decoration. - You want to use colours in an industry-specific context, where the meaning of the colours differs from the standard semantic meaning. Use industry-specific colours instead. ### When to use which Semantic Colour Only use a semantic colour if you need to convey the meaning defined for that colour. #### Accessibility Most themes are [WCAG AA+](https://www.w3.org/TR/WCAG20/) accessible. If a higher level of accessibility is required, allow the user to activate an accessible theme as a user preference. AA has a contrast level of 4.5:1 or higher, and AAA has a contrast of at least 7:1. AA Large means the font size must be at least 18 points or 14 points bolded to be AA accessible. #### Primary/Informative Use this colour for a main action or an informative state. Use the primary colour if: - You want to draw attention to a control for an important purpose. - You want to highlight newly added items, such as a new table row. Don’t use this colour if you want to highlight an information text. The blue text color is explicitly reserved for links. Use bold or italic formatting instead. #### Neutral Use this colour as the neutral state of all UI elements. Use the neutral colour if: - You want to use the default state of a UI element. - There is no reason to use another semantic state. - You want to indicate a neutral object status. - A message contains non-critical, additional information for users. #### Success/Positive Use this colour as the positive state when reinforcing that an action was successful/complete. Use the positive colour if: - You want to highlight a good or positive status. - A message contains information about a process that was completed without any issues. To indicate a successfully completed process, a short notification is enough. In this case, you can use a message toast. #### Warning/Critical This colour indicates a critical situation, a warning or an action that requires caution. Use the warning/critical colour if: - You want to highlight a critical status. - A minor problem has occurred. The user can carry on working, but might run into an error later on. - The user input was validated and a minor problem occurred. The user can continue without fixing the problem, but might run into an error later on. - A message contains information about a warning. #### Danger/Error/Negative This colour is to be used for errors, or to indicate a bad or negative status/consequence. Use the negative/critical colour if: - Something bad has happened, or is about to happen. The issue requires the user’s attention. Until the issue is resolved, the user can’t continue working. - You want to indicate that a value has caused an error. - The user needs to be prevented from completing an action. - The user input failed a validation, and the problem must be fixed before the user can continue. - A message contains information about an error. #### Focused This colour is used for focus ring on interactive elements. ### Sources and references - [Designing Semantic Colours](https://uxplanet.org/designing-systematic-colors-b5d2605b15c) - UX Planet - [Using Semantic and Industry-Specific Colors](https://www.sap.com/design-system/fiori-design-web/v1-148/foundations/best-practices/ui-elements/how-to-use-semantic-colors) - SAP Fiori Design Guidellines - [Colours](https://spectrum.adobe.com/page/color/) - Adobe Spectrum - [DefStan 23-009](https://en.wikipedia.org/wiki/Generic_Vehicle_Architecture#GVA_Defence_Standard_23-009) - Wikipedia - [ISO 9241](https://www.iso.org/obp/ui/#iso:std:iso:9241:-1:ed-2:v1:en) - ISO ## Dark Mode Colors To cater for a more various range of display capabilities, we have worked on specific color addition to complete the palette, and make it more friendly for Dark Mode usage. ### Overview of the main palette Our primary palette is derived from the Thales Brand Standards, comprised of neutrals, white and blue. These colours are designed to be clear and accessible. ### Semantic colours for Dark Mode Our semantic colour palette contains a variety of colours derived from the Thales Brand Standards additional colour palette. These colours are used to emphasize elements within your user interface and to keep things fresh and interesting. It is made up of red (`$color.dark.red.500`), yellow (`$color.dark.orange.500`), green (`$color.dark.green.500`), bluegreen (`$color.bluegreen.500`). Each colour is selected intentionally to provide meaningful feedback within our products. See the semantic colour guidelines below for more information. ### Color usage Find appropriate usage for the base Dark Theme in Quantum in the palette below. ### Colour Ramps The Colour Ramps are a comprehensive set of tint shades, based on Core and Secondary Palettes. This palette is complementary to the main colours to create emphasis on the colour choice. Every colour has been tested for WCAG 2.1 contrasts and the results are displayed on the cards. To check your colour contrasts, we encourage using the [Figma | Stark – Contrast & Accessibility AI Checker](https://www.figma.com/community/plugin/732603254453395948) plugin, available by default for all Thales Figma users. ## Accessible color combinations Accessibility is of paramount importance when it comes to building products, hence we have provided a collection of the TDS colour combinations that satisfy the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/). All background/foreground combinations in this section are relative to each tint shade. If you want to know combinations for universal text colours (white for dark backgrounds, bluegrey-900 for light ones), please refer to the AA/AAA ratings on the extended palette. ## International colors Thales provides solutions for customers across the globe, each with their own cultures where colour and language exist at the root. As designers and solution providers, we must always keep this in mind when building new products. ### Best Practices Always assume that the colors you are using might have a significant impact on your end users’ understanding according to their culture. For example, in Western Europe and Americas, red is synonym for error, criticality, failure. Whereas in China the red is symbol of happiness, prosperity. In order to be more inclusive and design for the broadest audience, we recommend to never assume the color can be self-explanatory. Textual indicators or other visual indicators (i.e icons) should always come jointly with the color to express a message. As expressed in the WCAG 1.4.1 rule. More information about this can be found at [informationisbeautiful.net](https://informationisbeautiful.net/visualizations/colours-in-cultures/). # Typography ## Overview Typography in Thales Design System plays an essential role in interface readability. It helps to create a clear visual hierarchy and organize information for a better user’s experience. ### Typeface Roboto font is used for the Thales Design System. It is designed and maintained by Google Fonts. Roboto is a copyright free font, which gives it the advantage of being free with no copyright attached and hosted by the Google server (meaning it receives updates easily, each time the font is updated). Moreover, it has many style variations (thin, light, regular, medium, bold, black, condensed…), which gives a wide variety of font format choice for your design. Note that it also remains perfectly readable, even in small font sizes and paragraphs of dense text. Modern and sober, it is suitable for Thales products. [Link to Roboto on Google Fonts](https://fonts.google.com/specimen/Roboto) (No need to download if you use Figma. Roboto is available by default in Figma). #### Specific aeronautic fonts Note that other font such as B612 can be used if necessary to improve accessibility and comfort of reading. Provided by collaboration between ENAC and Toulouse III College, it results from a prospective study, which aims to define and validate a font for aeronautical use cases. (Study called: Definition and Validation of an Aeronautical Font). The font called PolarSys B612 allows to better highlight information on the aircraft cockpit according to readability, reading comfort and cockpit information uniformity. Their principal characteristics are to maximize the distance between shape and letters, respect the primitive shape of letters and uniform their shapes and separations. Find more information about this font: [B612 Google Font page](https://fonts.google.com/specimen/B612) and [B612 GitHub repository](https://github.com/polarsys/b612). ### Scale Typography scale is built on a modular scale based on a 4px baseline grid : All font sizes have a ratio of 1.25, known as the major third type scale. It means that each size is multiplied or divided by 1.25 from the previous size, starting with the base size (16 px or 1rem), and rounded up or down. ### Weights Font weight adds contrast to lead your reader down the page by adding emphasis and differentiate content hierarchy. It must be carefully balanced with size pairings. A bold weight will always have more emphasis than a lighter weight font of the same size. However, a lighter weight font can rank hierarchically higher than a bold font if the lighter weight type size is significantly larger than the bold one. We suggest using Roboto Regular, Medium, Bold and Black for digital experiences. The Bold and Black weight are ideal for section headers, but should not be used for long text. ## Text styles Typography in Thales Design System plays an essential role in interface readability. It helps to create a clear visual hierarchy and organize information for a better user experience. Always use the text styles to stay synchronized with the library and keep consistency in visual hierarchy. If you need to use a new text style, you can add one by following these steps. ### Titles Titles are the first level of hierarchy text that draws users into the design. They are used to create clear various levels of hierarchies between text or blocs. Titles provide core information or draw attention to the key benefit. #### Usage - Main layout title - Main section title - Core informations - Component Heading #### Recommended colors
For more color combinations, refer to [Accessible Groupings](/docs/foundations/colors#accessible-color-combinations). ### Subtitles Subtitles are a level lower in the hierarchy than Titles and are reserved for medium-emphasis text. They are used to create vertical rhythm along with the higher level titles. They help to keep the attention of the user with the design and quickly navigate through the content. #### Usage - Subtitles should never appear as the first navigation element in a layout - Categories - Sub-section - Field group heading - Component heading #### Recommended colors For more color combinations, refer to [Accessible Groupings](/docs/foundations/colors#accessible-color-combinations). ### Body Body text is the most common text. It is used for main content and long or short paragraphs. It is a good size for comfortable, long-form reading. Use this for longer body copy in components such as accordion or structured list. #### Usage - Paragraphs - Text line #### Recommended colors For more color combinations, refer to [Accessible Groupings](/docs/foundations/colors#accessible-color-combinations). ### Caption Captions are the smallest font size with Overline. They are used sparingly to annotate imagery or add indications that can helps the user. #### Usage - Annotations - Legal content - Explanatory helper text - Complementary content - Legend #### Recommended colors For more color combinations, refer to [Accessible Groupings](/docs/foundations/colors#accessible-color-combinations). ### Overline An overline is a single line above a chunk of text. When associated with a title or a subtitle, it is used sparingly to add context for the user. It can also be used to name categories in small components. #### Usage - Add context indication - Category title in small components #### Recommended colors For more color combinations, refer to [Accessible Groupings](/docs/foundations/colors#accessible-color-combinations). ### Code Roboto Mono is used to display code or snippets. It makes code easier to read and understand for developers. #### Usage - Code - Snippets #### Recommended colors For more color combinations, refer to [Accessible Groupings](/docs/foundations/colors#accessible-color-combinations). ## Links Links are used to navigate to another page, or section by clicking on it. They can appear within a sentence or paragraph, or also can exist on their own. ### Usage When to use: Links should be use sparingly to: - Navigate to a different page within the application - Navigate to an external website - Scroll quickly to a specific section of the current page - Link to emails or phone numbers When not to use: - Users need to trigger an action. - Users need to manipulate data. In these cases, consider using [Buttons](/docs/components/button) instead. ### Text styles When introducing links into your design, it’s recommended to use the ‘Foundations’ library text styles to stay synchronized with the library. When you need to create a link using another text style or another style library, we recommend still using the underline to highlight that the text is a link. You can achieve this in the text decoration menu, or with Cmd+u / Ctrl+u. #### Body #### Caption #### Colour styles By default, links use the primary blue as it provides the strongest perceived affordance of clickability. However, it is possible to use a neutral variant that can be more appropriate when you need to deprioritize its focus on the screen. #### States ### Underlining In addition of the colour, underlining a link is important for low-vision users’ accessibility and it is recommended to maximize the affordance. Users shouldn’t have to guess or scrub the page to find out where they can click. However, there are some cases where it is not necessary to underline a link, such as: - Navigation menus, breadcrumbs - Lists of links. These cases are true only when the page design clearly indicates the area's function. **Exception:** Underlining is essential if you use link colours such as reds or greens, which cause problems for users with common forms of colour-blindness. ### Sources and references - [Guidelines for Visualizing Links](https://www.nngroup.com/articles/guidelines-for-visualizing-links/) - Nielsen Norman Group - [Link](https://carbondesignsystem.com/components/link/usage/) - IBM Carbon - [Link](https://designsystem.digital.gov/components/link/) - U.S. Web Design System ## Usage guidelines #### Use library text styles It is recommended to use library text styles to stay synchronized with the library and keep consistency in visual hierarchy. Sometimes the style options aren’t suitable for specific scenarios. In these situations, it’s ok to deviate from the size options by taking a font size specified in the scale system. A consistent typo hierarchy helps the user to navigate through the content and easily find what they are looking for. #### Typography component pairing Titles, subtitles, body, caption, and overline typography components can be paired together in order to enforce hierarchy of content. It is recommended to use the same sizes while using multiple styles to create balanced relationships between them. Relationships may sometimes need to be more or less pronounced, so in those use cases, it’s acceptable to combine your own selection of sizes as long as you’re maintaining consistent hierarchy. ### Formatting #### Bold Bold is used to add emphasis within a sentence or tall attention. Use it sparingly to enhance visual hierarchy. #### Underline Underline text exclusively for text links. It should never be used to emphasize text. #### Avoid using all caps All caps is difficult to read and scan and makes the reading speed slowed about 13 to 20 percent. Excepting for specific text styles (e.g. Overline ), prefer using mixed-case. ### Readability Readability allows users to efficiently read and process informations in the content. Poor readability can make it challenging for the user to stay focused on the content and scares them away from it. The following guidelines promote good readability. #### Spacings White space or negative space, is the area between elements in a design composition. It affects how the user focuses their attention on the content and makes it easier to know what to read and where to begin. Spacing between typographic elements should be open enough to feel light, but close enough to establish a proper relationship between elements. When setting titles or subtitles and body copy, the white space should be 16px or 32px. #### Alignment We recommend to use Left-aligned text for left-to-right languages such as English. It provides the eye a constant starting point for each line, making text easier to read. ##### Don't fully-justify text By using block-justified text, white spaces are created within paragraphs and make it harder to read, especially for those with cognitive disabilities or dyslexia. #### Line length Comfortable line length allows the user’s eyes to flow easily from the end of one line to the beginning of the next. Ideally, blocks of text should be roughly 70 characters wide. Be sure to keep them at least between 50 and 120 characters wide. ### Accessibility #### Text contrast The WCAG (Web Content Accessibility Guidelines) are part of a series of web accessibility guidelines that provides sets of recommendations for making content accessible by everyone, regardless of any disability or user device. To ensure text remains compliant with WCAG 2.1 standards, we provide you in the recommended colors section of each text style the colors that can be used depending of the usage. For black or white usage, you can refer to the contrasts indicated in the Extended Palette. For other color combinations, you can refer to the Accessible Groupings section. #### References To learn more about WCAG 2.1, refer to the https://www.w3.org/TR/WCAG21/ To check your color contrasts, we encourage using the [Figma | Stark – Contrast & Accessibility AI Checker](https://www.figma.com/community/plugin/732603254453395948) plugin, available by default for all Thales Figma users. ### Links #### Don’t underline body text that’s not a link In a paragraph, underline text exclusively for text links. It should never be used to emphasize text. If you need to emphasize certain words or sentences, using italics or bold is much safer. #### Avoid using colour for text unless it’s a link Avoid using primary blue for non-link text because it’s the colour with the strongest perceived affordance of clickability. If an user try to click on a blue text that is not clickable, this can results in frustation. Using a colour for a text is not recommanded unless it’s a link. However, assuming it differs from the link colour, you can sometimes use coloured text without causing major usability problems. For example, in a card, you could show the word "Success" in green and the word "Error" in red. (The fact that the word meanings are clearly different provides the required redundant cue for colour-blind users.) #### Use meaningful link text Links should explain the link’s purpose and help the user understand the link’s destination. # Spacing ## Spacing system Using a consistent spacing system across our products helps bring visual balance in our interfaces, and leads to a better overall UI quality. The Thales Design System spacing system relies on very simple yet solid principles: rhythm and flexibility. ### Spacing scale As it is the case for the Typography Scale, the spacing method relies on a 4px baseline. The spacing scale is the key to composing everything, starting at the layout, to the most complex components. Every scale has a name (token), a rem value to ensure interface scalability with the system, and pixels relative equivalences. | Asset | Token name | Pixels value | Rem value | | -------------------------- | ------------ | ------------ | --------- | | | $spacing.3xs | 2px | 0.125rem | | | $spacing.xxs | 4px | 0.25rem | | | $spacing.xs | 8px | 0.5rem | | | $spacing.s | 12px | 0.75rem | | | $spacing.m | 16px | 1rem | | | $spacing.l | 24px | 1.5rem | | | $spacing.xl | 32px | 2rem | | | $spacing.xxl | 40px | 2.5rem | | | $spacing.3xl | 48px | 3rem | | | $spacing.4xl | 56px | 3.5rem | | | $spacing.5xl | 64px | 4rem | | | $spacing.6xl | 72px | 4.5rem | | | $spacing.7xl | 80px | 5rem | | | $spacing.8xl | 88px | 5.5rem | | | $spacing.8xl | 96px | 6rem | ### Application Choosing the right spacing at the right place is crucial. To help you choose wisely while designing interfaces, we have gathered some good practices. #### Use space to create relationships In interfaces and design in general, it is stated that elements that are close to each other are seen as related on the functional part. Therefore, the more space you have between elements, the more you tend to seperate them. **Use small spacings to group related elements (an text input and its label should be very close).** [Read more about Gestalt’s Principles, and specifically the Law of Proximity.](https://ixdf.org/literature/topics/gestalt-principles#:~:text=Gestalt%20principles%20or%20laws%20are,the%20separate%20simpler%20elements%20involved.) #### Use space to create structure When mixing small and large values inside components but also with more structural assets like sections or widgets, you can create visual groups of related things. By keeping a consistent spacing strategy within your interfaces, the end user will easily find what they are looking for. It’s all about choosing the good combinations, and this system gives space for creativity, and gives you the capacity to adjust spacing for any kind of device, screen size, or context of use. # Grids & layout ## The layout system The entire layout system of Thales Design System is based on the 8px baseline, and is built upon the spacing scale. All the grids provided in the library are made to help you build better experiences, and bring consistency across your different products, and within product themselves. ### Baseline grid The baseline grid is a vertical baseline of 8px (0.5 rem) increments. Use the baseline grid in Figma to help you always keep an eye on your vertical rhythm. **Figma trick: to help you adjust your spacings, we encourage you to change the nudge default amount to 8px Press “cmd + /” and search “nudge amount” then use shift + arrow keys to nudge elements in the interface.** #### How to use? To apply the baseline grid to your interfaces, follow these steps: 1. Make sure your layout grids are shown by pressing: Ctrl + G (Windows) or ⌃ + G (macOS) 2. Select the frames you want to apply the grid on. 3. In the right panel, click on the styles in Layout Grids section. 4. Select “Grids > Baseline Grid 8” ### Columns Grids and breakpoints There are countless options when it comes to creating breakpoints. We wanted to make sure that the Designers could design with reliable and adapted grids that would fit most of the cases. Based on the most commonly used devices and resolutions, we cut down to 5 major breakpoints. If you need more grids to be created, please contact the Thales Design System Core Team. You can find the associated statistics by clicking [on this link](https://gs.statcounter.com/screen-resolution-stats/tablet/worldwide/2020). #### How to use? To apply grids to your interfaces, follow these steps: 1. Make sur you layout grids shown by pressing: Ctrl + G (Windows) or ⌃ + G (macOS) 2. Select the frames you want to apply the grid on. 3. In the right panel, click on the styles in Layout Grids section. 4. Select “Grids > Select your grid” To help you select the right grid according to your screen size, please follow the breakpoints recommendations below. #### Breakpoints system Thales Design System provides layouts with different column structures. You will find 4, 6, 8 and 12 columns grids. For each breakpoint, you will find recommendations on number of columns, gutters and margins to apply. ##### Fluid containers The fluid grid system is based on fluidity, so the size of columns adapts according to gutters and margin, in this way, the grid will scale with your screen size. | Breakpoint | Range (px) | Devices | Columns | Gutters | Margins | | ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | ------- | | xxsmall | 0-360 | smartwatches | 4 | 8px | 16px | | xsmall | **360** - 640 | mobile, small tablets | 4 | 8px | 16px | | small | **640** - 767 | small tablets P, small mobiles L | 8 | 16px | 32px | | medium | **768** - 991 | tablets (P/L), large mobiles (L) | 8 | 16px | 32px | | large | **992** - 1199 | medium to large tablets | 12 | 16px | 32px | | xlarge | **1280** and above | large tablets, desktop, large devices | 12 | 16px | 32px | ##### Responsive scale The breakpoint should always be defined by the min-width value (e.g the breakpoint value for medium should be min-width: 768px) The columns widths are fluid and should scale according to the viewport size and the associated breakpoint. ##### Fixed width containers The fixed grid system is based on defined layout sizes, triggered by breakpoints. The maximum width of every containers is based on the breakpoint value and its relative minimum width. | Breakpoint | Range (px) | Devices | Columns | Column Size | Gutter | | ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------- | ------ | | xxsmall | 0-360 | smartwatches | 4 | Fluid | 8px | | xsmall | **360** - 640 | mobile, small tablets | 4 | 84px | 8px | | small | **640** - 767 | small tablets P, small mobiles L | 8 | 66px | 16px | | medium | **768** - 991 | tablets (P/L), large mobiles (L) | 8 | 82px | 16px | | large | **992** - 1199 | medium to large tablets | 12 | 68px | 16px | | xlarge | **1280** and above | large tablets, desktop, large devices | 12 | 92px | 16px | ##### Available grids To make it easier, we cut down the number of grid to their initial utility. This means some breakpoints share the same grid. ## Usage guidelines The entire layout system of Thales Design System is based on the 8px baseline, and is built upon the spacing scale. All the grids provided in the library are made to help you build better experiences, and bring consistency across your different products, and within product themselves. ### Create regions To help prepare your designs for responsiveness, you should define regions in your layouts to create a consistent structure in the product. To create regions, use the gutters and the margins as limits to the zones you want to define. To optimize responsiveness, design the regions for every breakpoint. ### Don’t align everything to the grid When creating regions, you create an enclosed environnement to contextualize components that belong together. Those elements need to be aligned according to their relationships and purpose. Only align layout regions strictly to the grid and do not compromise the design by doing it with individual components.
### Don’t fall in the gutter/gap The grid gutters are here to create space and breathing room between the regions. Do not, ever, extend a layout region in the gutters and only span them from a column edge to another. ## Layout Grid Examples ### Desktop Fluid Grid Desktop | 1366 \* 768 ### Tablet Fluid Grid Portrait Tablet | 768 \* 1024 Landscape Tablet | 1200 \* 800 ### Mobile Fluid Grid Mobile | 360 \* 640 ### Breakpoint: 1280px (x large) Desktop | 1366 \* 768 ### Breakpoint: 992px (large) Small Desktop | 1152 \* 700 ### Breakpoint: 768px (medium) Tablet | 768 \* 1024 ### Breakpoint: 640px (small) Landscape Mobile | 640 \* 360 ### Breakpoint: 360px (x small) Mobile | 360 \* 640 # Borders Borders are used across composition elements to visually contain, separate or highlight some part of the interface. In combination to space and size hierarchy, borders strengthen the visual flow of an interface and offer discrete visual hints to help the user scan through the content and get their bearings. Borders are made of a set of properties: - Size (width) - Radius - Style - Color In the last section below, you’ll find some examples of borders combining those properties and also presets that are approved in the Quantum design system. ## Specifications ### Border size The size of a Border refers to its thickness. Why the term “size” has been favoured against the term “width” is explained later in the documentation below. | Asset | Token name | Raw value | Rem value | Usage | | ----------------------- | ------------------- | --------- | --------- | -------------------------------------- | | | $border.size.none | 0px | 0rem | Equivalent to no border (border: none) | | | $border.size.thin | 1px | 0.0625rem | Used for dividers and form inputs | | | $border.size.medium | 2px | 0.125rem | Used as the default value | | | $border.size.thick | 4px | 0.25rem | Used for active indicators | ### Border radius The radius of a Border refers to the roundness of any of its angles. | Asset | Token name | Raw value | Rem value | Usage | | ------------------------------- | --------------------- | --------- | --------- | ------------------------------------------------- | | | $border.radius.none | 0px | 0rem | Equivalent to sharp borders (border-radius: none) | | | $border.radius.medium | 2px | 0.125rem | Used as the default value | | | $border.radius.large | 4px | 0.25rem | Used for focus rings | | | $border.radius.full | 1000px | 62.5rem | Used to get a full rounded style effect | | | $border.radius.circle | 50% | - | For developer usage only | ### Border style The style of a Border refers to its appearance. Different border styles exist but only the solid style is allowed in Quantum for now. | Asset | Token name | Value | Usage | | ------------------------ | --------------------- | ----- | ------------------------- | | | $border.style.default | solid | Used as the default value | ### Border color See the [semantic colors in Quantum Foundations](/docs/foundations/colors#semantic-colors) to know which color to apply on a Border. ## Application The use and application of border token values is pretty straightforward but can be hijacked in some use cases where it visually appears as a border but is, in reality, a container element. ### Examples #### No border is still border For example, with the Button component. The Button outline variant has a clear visual border but the Button filled variant, even if no visual border is visible, still has border properties applied to it. #### Full rounded Vs. Circle Even if the visual end result can be similar in some setups, there is a difference between the full rounded radius and the circle radius. Full rounded radius is used when the shape does not require to be a circle. Circle radius has to be used when the shape must be a circle. For designers in Figma, there is no difference between the two because a % value is not allowed. You have to use a large pixel value like 1000px so whatever the size of your element will be you can guarantee that the visual end result is full rounded. For the developers however, the circle value is better suited when you need a circle shape like an avatar (see example on the right). #### Indicator & Separator Some visual elements look like borders but in reality are container elements with height and width. For example an active Tab indicator or a section separator. In this case, border guidelines are adapted to a container element. The container element width is used as the border width and the block background color as the border color. As stroke/outline/border lookalike, they must use the specific tokens for borders. This also explain why the term “size” has been favoured against “width” to name the tokens for borders. ### Regular border presets #### Active indicator - Is a container element - Always use a thick size in width or height - Always use a medium radius on relevant corners #### Divider line - Is a container element - Always use a medium size in width or height - Always use a medium radius on all corners #### Button - Is the border of the component container - Always use a medium border size for Button outline - Always use a medium border radius - Use the large border radius for the focus ring #### Input - Is the border of the component container - Always use a thin border size - Always use a medium border radius - If not a circle, use the large border radius for the focus ring # Shadows & Elevation Shadows and elevations are used across components and patterns to establish and maintain functional boundaries between them. It helps to create visual hierarchy and focus through depth. The elevation system is made mainly from [Material Design Elevation system](https://m2.material.io/design/environment/elevation.html#elevation-in-material-design) in which you can find more recommendations and guidelines. ## Shadows Shadows are used to express the degree of elevation between surfaces. This degree of elevation depends of the size of the shadow and its softness. The closer is the surface from the surface behind it, the smaller and sharpest will be its shadow. In contrary, if the surface is far, the shadow will be larger and softer. | Token name | Preview | Elevation (dp) | Shadow values | Usage | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | $shadow-xs-strong
$shadow-xs-light
$shadow-xs-ultralight |
| 2 | Strong
0 2px 2px 0 hsla(235, 96%, 10%, 0.14)
0 3px 4px 0 hsla(235, 96%, 10%, 0.14)
0 1px 5px 0 hsla(235, 96%, 10%, 0.2)

Light
0 2px 2px 0 hsla(235, 96%, 10%, 0.04)
0 3px 4px 0 hsla(235, 96%, 10%, 0.04)
0 1px 5px 0 hsla(235, 96%, 10%, 0.08)

Ultralight
0 2px 2px 0 hsla(235, 96%, 10%, 0.02)
0 3px 4px 0 hsla(235, 96%, 10%, 0.02)
0 1px 5px 0 hsla(235, 96%, 10%, 0.04)
|
  • Cards
| | $shadow-s-strong
$shadow-s-light
$shadow-s-ultralight |
| 4 | Strong
0 2px 4px 0 hsla(235, 96%, 10%, 0.14)
0 4px 5px 0 hsla(235, 96%, 10%, 0.12)
0 1px 10px 0 hsla(235, 96%, 10%, 0.20)

Light
0 2px 4px 0 hsla(235, 96%, 10%, 0.04)
0 4px 5px 0 hsla(235, 96%, 10%, 0.04)
0 1px 10px 0 hsla(235, 96%, 10%, 0.08)

Ultralight
0 2px 4px 0 hsla(235, 96%, 10%, 0.02)
0 4px 5px 0 hsla(235, 96%, 10%, 0.02)
0 1px 10px 0 hsla(235, 96%, 10%, 0.04)
|
  • Tooltips
  • Headers
| | $shadow-m-strong
$shadow-m-light
$shadow-m-ultralight |
| 8 | Strong
0 8px 10px 0 hsla(235, 96%, 10%, 0.14)
0 3px 14px 0 hsla(235, 96%, 10%, 0.12)
0 4px 5px 0 hsla(235, 96%, 10%, 0.20)

Light
0 8px 10px 0 hsla(235, 96%, 10%, 0.04)
0 3px 14px 0 hsla(235, 96%, 10%, 0.04)
0 4px 5px 0 hsla(235, 96%, 10%, 0.08)

Ultralight
0 8px 10px 0 hsla(235, 96%, 10%, 0.02)
0 3px 14px 0 hsla(235, 96%, 10%, 0.02)
0 4px 5px 0 hsla(235, 96%, 10%, 0.04)
|
  • Contextual overlays
  • Select
  • Menu Bar
| | $shadow-l-strong
$shadow-l-light
$shadow-l-ultralight |
| 12 | Strong
0 16px 24px 0 hsla(235, 96%, 10%, 0.14)
0 6px 30px 0 hsla(235, 96%, 10%, 0.12)
0 8px 10px 0 hsla(235, 96%, 10%, 0.20)

Light
0 16px 24px 0 hsla(235, 96%, 10%, 0.04)
0 6px 30px 0 hsla(235, 96%, 10%, 0.04)
0 8px 10px 0 hsla(235, 96%, 10%, 0.08)

Ultralight
0 16px 24px 0 hsla(235, 96%, 10%, 0.02)
0 6px 30px 0 hsla(235, 96%, 10%, 0.02)
0 8px 10px 0 hsla(235, 96%, 10%, 0.04)
|
  • Dialogs
  • Modals
| | $shadow-xl-strong
$shadow-xl-light
$shadow-xl-ultralight |
| 16 | Strong
0 24px 38px 0 hsla(235, 96%, 10%, 0.14)
0 9px 46px 0 hsla(235, 96%, 10%, 0.12)
0 11px 15px 0 hsla(235, 96%, 10%, 0.20)

Light
0 24px 38px 0 hsla(235, 96%, 10%, 0.04)
0 9px 46px 0 hsla(235, 96%, 10%, 0.04)
0 11px 15px 0 hsla(235, 96%, 10%, 0.08)

Ultralight
0 24px 38px 0 hsla(235, 96%, 10%, 0.02)
0 9px 46px 0 hsla(235, 96%, 10%, 0.02)
0 11px 15px 0 hsla(235, 96%, 10%, 0.04)
|
  • Notifications
| ## Elevations ### Principles The elevation is measured as the distance between surfaces. The distance from the front of one surface to the front of another is measured along the z-axis in density-independent pixels (dps) and depicted (by default) using shadows. Each shadow is corresponding to a unit along the elevation scale going from 2dp to 24dp. Depending of the surface behind them, surfaces with the same elevation can appear differently. In the example below, both surfaces A and B are at the same 8dp elevation. Because the surface B is in front of another surface (C) that already has 4dp elevation, it will cast a different shadow that is also 4dp. ### Elevation hierarchy Like typography styles, elevation can be used in order to enforce hierarchy of content depending on whether they are at similar or different elevations. #### Content at different elevations Surfaces in front of other surfaces typically: - Contain more important content. The example below demonstrates how more important content that is of primary focus appears in front of content that is of secondary focus. - Focuses attention while maintaining context #### Content on coplanar surfaces Contents that are placed at the same elevation (or coplanar surfaces) indicate they contain content of same level of hierarchy that have equal importance as one another. For example, all cards in a collection have equal importance. # Iconography Iconography in Thales Design System plays an essential role. It helps to create visual indicators and enhance readability of components, and guide users through a better understanding of actions when used correctly. Thales Design System uses Material Icons. Material Design icons–Open sourced Material Design icons in all 5 themes ## Google Material Icons (main icons library) Material Icons library serves as the default and main icons library within Quantum Design System. **Your first reflex should be to look at the [Figma | Material Icons library in Quantum](https://www.figma.com/design/HZQxgQAzw5ZSjkeWNsAIax/Quantum---3.1-Material-Design-Icons--Community-?node-id=557-18875&p=f&t=gCuUZS7fJwi4UfX4-0)** to search for icons. This library alone can cover most of your needs in interface design. Google Material provides a wide range of day-to-day icons. **It also comes in a variety of styles and rely on a clean, simple form factor style, perfect for carrying functional visual representations.** Quantum Design System aims **to be as flexible as possible** for product creators like you, designers and developers. Apart from these reasons, the decision to use Material Icons for our icon base was also taken because **many Thales digital products already use them, thus this brings consistency along the way!** - Material Icons are available in five styles and a range of downloadable sizes and densities. - We strongly recommend using only one style set of icon per product (either choose solid, outline or any other style and stick to it). You can also visit the [Material Icons library](https://fonts.google.com/icons) online to have a better search experience for specific icons. ### How to use this library? You can use Material icons as a Figma library in your project file. Search for the library [Figma | Material Design icons](https://www.figma.com/community/file/1014241558898418245) in your Figma assets panel. # Button ## Overview Buttons should be used to trigger an action by guiding users to achieve the desired actions of a page. Depending on the need and the context, several buttons types and variants are available to help you build meaningful interfaces and prevent mistakes. **Note:** Buttons should never be used for an alternative purpose to what it was initially intended for. Avoid using buttons for navigational purposes (menus, tabs, etc.) or clickable elements within sentences. Instead, please refer to the dedicated component available in the TDS. ### Usage When to use: - To offer a default action as well as the possibility of choosing a different action by selecting from a set of alternatives. - In complex applications, to not visually overwhelm users with too much cognitive load. - For repeat-use interfaces with a large number of commands that need to be consolidated. When not to use: - If default action and alternatives don’t have a strong relationship. - Proposing too much alternatives and struggling with choice paralysis. - Using split buttons for navigation menus on websites. ### Sources - [Split Buttons: Definition](https://www.nngroup.com/articles/split-buttons/#:~:text=Definition%3A%20A%20split%20button%20is,list%20of%20other%20possible%20actions) by Nielsen Norman Group - [Split Buttons: Documentation](https://developers.arcgis.com/calcite-design-system/components/split-button/) by ArcGIS Developer ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ Component: Button | Property | Values | Default | | ------------------ | ------------------------------------------------------ | ----------------- | | **size** | small / medium / large / xlarge | medium | | **color** | primary / success / warning / danger / neutral / white | primary | | **\*state** | default / hover / focused / pressed / loading | default | | **disabled** | false / true | false | | **\*manualSize** | false / true | false | | **label** | text | "Download" | | **\*hasLeftIcon** | boolean | true | | **leftIcon** | instance swap | arrow_circle_down | | **\*hasRightIcon** | boolean | true | | **rightIcon** | instance swap | arrow_forward | #### ❖ Component: Icon Button | Property | Values | Default | | ------------ | --------------------------------------------- | --------------- | | **size** | small / medium / large / xlarge | medium | | **\*state** | default / hover / focused / pressed / loading | default | | **disabled** | false / true | false | | **icon** | instance swap | swap_horizontal | ## Behaviour ### Sizes Buttons support four sizes: - Small (S) for very small layouts - Medium (M) as default for desktop devices - Large (L) as default for tablet and mobile devices - Extra large (XL) for emphasized actions These buttons have been specially designed with accessibility in-mind, backed by industry standard practices from [Google’s Material Design](https://m2.material.io/design/usability/accessibility.html#layout-and-typography) and [Apple’s Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/accessibility). ### Variants **Primary buttons** are the main call to action on any page. It is advised that a primary button is only used once on a single page. This avoids drawing the user’s attention away from the primary action you intended for the page. **Outline buttons** are for secondary call to actions on any page. Often the secondary button is the alternative we give users to the primary action. Multiple secondary buttons can be used on a single page, however it is advised that you ensure the content of your page is balanced. Too many calls to action can make it hard for users to know what to do next. **Ghost buttons** are for miscellaneous actions on any page. Multiple tertiary buttons can be used on a single page, however it is advised that you ensure the content of your page is balanced. Too many calls to action can make it hard for users to know what to do next. ### Severity **Primary** buttons represent the main action or primary call to action on a page. It should be used sparingly to draw attention to important actions. **Success** buttons represent successful actions or completion of a task. This could include actions that result in a successful operation or confirmation message. **Warning** buttons represent potentially harmful or irreversible actions. This could include actions that delete data or cancel a process, or that require additional caution and confirmation. **Danger** buttons represent potential issues or warnings. This could include actions that require additional confirmation or that might result in data loss or other negative consequences. ### Left & Right icons **Usage of Left or Right icons depends on the context, the usage and the goal of the button.** **Left icons** feel visually anchored and more consistent with the left-alignment of the text. Moreover, it’s the more common pattern among other applications, and being consistent is a positive behavior for users - Jakob’s Law. Last but not least, large menu width do not impact the comprehension of the button and the left of the button can be used for counters. **Right icons** can be used to keep text from different button aligns. It also adds a rightward movement because text demands more cognitive load than icons. A consideration is that it can visually trapped space, between the icons and the menu title spaces, and create unpleasant reading. ### Auto layout & manual resize By default, the button has an automatic horizontal sizing based on its content. It will grow depending on the length of the label inside of it. To manually adjust the size, for full width buttons for example, you need to apply a “Fill container” sizing setting to the “Base Button” layer ## Usage Guidelines ### Labelling Buttons labels describe the action that will occur when the user uses it. It is important to choose the right words to make the action clear for the user, and facilitate its decisions. Using the wrong words on button labels can create confusion, more work, and slower task times for the users. #### Prefer action verbs than generic terms Words should describe the action or result of pressing/clicking the button. According to some studies, (e.g. [Paradox of the Active User](https://www.nngroup.com/articles/paradox-of-the-active-user/)) most people avoid reading whenever it is possible. That is is why naming a button with “Ok” or “Yes/No” won’t help them in any way. Instead, use action verbs to encourage users to take action without necessarily read the dialog. #### Choose precise and specific words Each action verb can have a specific connotation. Using imprecise diction can make users misinterpret the button. Moreover, a vague and generic label can cause uncertainty in users, who won’t be sure of the result of their actions. - For example, “delete” and “remove” are similar in meaning, but can have a different connotation. “Delete” implies that the button will erase something from the system while “remove” implies that the button will separate something from a group. Using these words in the wrong context can cause users concern when they want to press the button. - “Submit” can be used for many contexts and make the action vague and unclear. In contrast the word “publish” is specific to online publishing, so users will be sure that their post will be posted after they press the button. #### Text format Capitalization style of the button affects the emotional reaction and can either engage or repel them. [TDS Foundations](/docs/foundations/typography#formatting) recommends that all buttons use **sentence case**. Sentence cases make the button easier to read, and natural. In contrast, title-style capitalization has a more impersonal tone, while all-uppercase style decrease readability and conveys a loud and strict tone. Finally, all-lower case style conveys a casual and lazy tone, with a lack of professionalism and trust. ### Icons Icons in buttons can make information easier to find and scan. We recommend to place the icon **on the left** of the label so users can see it first. Putting the icon to the right of the label won’t help the users scan the button. However, right icon can be set for right-to-left reading usages. An exception to this is **directional call to actions**, where it is more appropriate to place the icon in the correct direction of travel for the user on the page (e.g. in order for a user to progress to the next step, in a left-to-right country, they will anticipate an arrow pointing right on the right-hand side of the button). ### Icon buttons Icon buttons are buttons without visible text labels by default. They are used to perform a quick action on an object (e.g. add, delete, add an item, send…) or trigger a new element to appear on the page (e.g. open a modal, reveal a menu…) Since icon buttons don’t display an explicit labelling, it is important to use a clear visual representation of the action it will trigger. #### Use the 5-second rule Icons should always communicate meaning. Don’t overuse them or use them for decoration. When you are trying to come up with your design for icon, consider adopting the **five-second rule**. “If you take more than 5 seconds to come up with that object that will represent that idea or concept, then it is less likely that your users can see that design and associate it with that object.” #### Icon Usability [Find more informations about Icon Usability and how to use it effectively to help the users understand the meaning and reduce ambiguity.](https://www.nngroup.com/articles/icon-usability/) ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284249&t=244StnnCdoCtO9oW-4) # Split Button ## Overview Split Buttons are dual-function menu buttons with two components: a label and an arrow; clicking on the label selects a default action, and clicking on the arrow opens up a list of other possible actions: the alternatives. ### Usage When to use: - To offer a default action as well as the possibility of choosing a different action by selecting from a set of alternatives. - In complex applications, to not visually overwhelm users with too much cognitive load. - For repeat-use interfaces with a large number of commands that need to be consolidated. When not to use: - If default action and alternatives don’t have a strong relationship. - Proposing too much alternatives and struggling with choice paralysis. - Using split buttons for navigation menus on websites. ### Sources - [Split Buttons: Definition](https://www.nngroup.com/articles/split-buttons/#:~:text=Definition%3A%20A%20split%20button%20is,list%20of%20other%20possible%20actions) by Nielsen Norman Group - [Split Buttons: Documentation](https://developers.arcgis.com/calcite-design-system/components/split-button/) by ArcGIS Developer ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇◇❖ Component: Split Button | Property | Values | Default | | ------------- | ------------------------------------------------------------------------------------- | ------- | | **size** | small / medium / large | medium | | **\*hasIcon** | false / true | true | | **visible** | false / true | false | | **placement** | none / bottom-left / bottom-center / bottom-right / top-left / top-center / top-right | none | #### ❖ Sub-component: [Dropdown Menu Item](/docs/components/dropdown-menu) #### ❖ Sub-component: [Button](/docs/components/button) ## Behaviour ### Sizes Split buttons exist with 3 different sizes: small, medium and large. ### Icons Icons can be used in split buttons items, and should be used as often as possible to add clarity and context. Icons in split buttons can make information easier to find and scan. The only option is to place the icon **on the left** of the label so users can see it first. Putting the icon to the right of the label won’t help the users scan the button. ### Menu (dropdown) By default, split button doesn’t have an open menu to show alternatives. Alternatively, the open state can be used to show alternatives or to animate prototypes. ### Menu position By default, split button’s menu is closed. The open state allows the user to choose the menu’s position to fit perfectly with their unique context. As the menu is a dropdown component, it offers all the possible customizations with this element. ### Color variations #### Ghost split button #### Ghost Neutral split button ## Usage Guidelines ### Use split buttons to combine relevant button actions - **Don’t:** use multiple primary actions at the same place - **Do:** combine them in a split button when relevant ### Use split buttons not as a group - **Don’t:** use split buttons if the intention is to use it as a group - **Do:** use them if the intention is to use it as a single element ### Propose related alternatives - **Don’t:** use split button for proposing unrelated alternatives - **Do:** choose wisely the alternatives to avoid cognitive overload ### The lesser the better - **Don’t:** use split button for proposing a huge amount of alternatives - **Do:** choose wisely the alternatives to avoid cognitive overload and impact on the time to make a choice - Hick's law ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284241&t=244StnnCdoCtO9oW-4) # Floating Button ## Overview A Floating Action Button (FAB) emphasizes the main action of the page. It is an action button placed in the foreground of the interface. It can also be used in specific situations such as map navigation or multi edition. You can refer to our documentation about [Shadows & Elevation](/docs/foundations/shadows-elevation) to understand how to embed it well in your interfaces. ### Usage When to use: - To simplify access to the main action of the page - To provide a panel of common actions of several items - To keep a fixed action despite a scroll When not to use: - As a secondary action: if there are already some actions in the interface - By putting several FABs on the same interface ### Sources [Floating Action Button](https://m3.material.io/components/floating-action-button/overview) by Material Design. ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ FAB - Button Filled / Outline / Flat | Property | Values | Default | | ------------------ | ---------------------------------------------- | ---------- | | **size** | small / medium / large / xlarge | medium | | **color** | primary / success / warning / danger / neutral | primary | | **\*state** | default / hover / focused / pressed | default | | **disabled** | false / true | false | | **label** | text | Download | | **\*hasLeftIcon** | boolean | true | | **leftIcon** | instance swap | swap_horiz | | **\*hasRightIcon** | boolean | false | | **rightIcon** | instance swap | swap_horiz | #### ❖ FAB - Icon button Filled / Outline / Flat | Property | Values | Default | | ------------------- | ---------------------------------------------- | ---------- | | **size** | small / medium / large / xlarge | medium | | **color** | primary / success / warning / danger / neutral | primary | | **\*state** | default / hover / focused / pressed | default | | **disabled** | false / true | false | | **leftAnnotation** | boolean | false | | **rightAnnotation** | boolean | false | | **icon** | instance swap | swap_horiz | #### ❖ FAB - Icon buttons stack Primary / Neutral | Property | Values | Default | | ------------------- | ---------------------- | ------- | | **color** | primary / neutral | primary | | **size** | small / medium / large | medium | | **items** | 2 / 3 / 4 / 5 / 6 / 7 | 7 | | **showAnnotations** | false / true | false | | **textPosition** | none / left / right | none | | **isOpen** | boolean | false | ## Behaviour ### Sizes FAB supports four sizes: - Small (S) for very small layouts - Medium (M) as default for desktop devices - Large (L) as default for tablet and smartphone devices Note: we recommend to avoid to use individually the XSmall size because it is designed for the Icon Buttons Stack as a sub-item. ### Style variations The Floating Action Button is available in 3 styles: Filled, Outlined and Flat. **Filled** style is appropriate to emphasize one main action or open the sub-actions stack. It will pop on your screen if your interface is mainly light-themed. If it is not the case we recommend to use the **Outlined** version which will be more visible in colourful screens. Eventually you can use the **Flat** one as a sub-action when an overlay is active. We do not recommend this use as a main action due to the lack of contrast in that case. ### Severity **Primary** FAB buttons represent the main action or primary call to action on a page. It should be used sparingly to draw attention to important actions. **Success** FAB buttons represent successful actions or completion of a task. This could include actions that result in a successful operation or confirmation message. **Warning** FAB buttons represent potentially harmful or irreversible actions. This could include actions that delete data or cancel a process, or that require additional caution and confirmation. **Danger** FAB buttons represent potential issues or warnings. This could include actions that require additional confirmation or that might result in data loss or other negative consequences. Use **Neutral** FAB for action that doesn’t need to grab too much user attention. ### FAB Types **We provide you three types of Floating Action Button:** **FAB - Icon Button** which is the well-know FAB. We advise to use it in small interfaces such as Smartphone or Tablet app for an individual usage. In the case of applications with a full screen display, this FAB can also be used to provide different interactions to the users (i.e. mapping tool) **FAB - Button**: more explicit, it allows the same uses as the FAB - Icon Button with a textual description. Be careful to ensure that the label is not too long in restricted interfaces. **FAB - Sub-Actions Drawer** has a particular use because it allows to display several actions at the trigger of the main button. This stack gather actions consistently with the context and hideable by triggering once again the main button. Furthermore, we advise you to add an overlay behind your FAB to put the light on these sub-actions. ### FAB Icon: Annotation You can **display additional text** to your FAB - Icon Button in case you want to add context to your action. We recommend hover usage for a FAB - Icon Button and permanent display for a FAB - Sub-Actions Drawer. ## Usage Guidelines ### Chose one action to emphasize - **Don’t**: stack multiple FAB over your content. - **Do**: choose one main action or store them in a FAB - Drawer. ### Be as concise as you can - **Don’t**: write very long sentences for your actions. - **Do**: either chose wisely one icon or shorten your text to be direct. ### Select a color that contrast with your interface - **Don’t**: chose a FAB with a background close to your interface’s theme. - **Do**: accentuate the contrast by choosing a color that your users will see without effort. ### Gather FAB to minimize eye strain - **Don’t**: scatter actions and force the user to navigate the entire screen. - **Do**: bring everything together in one place with consistent actions. ### Isolate FABs to avoid confusion - **Don’t**: displaying a FAB near another action area, making it difficult to access. - **Do**: put the FAB in an area where it is easily recognizable. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=21944-519388&t=244StnnCdoCtO9oW-4) # Group Buttons Group Buttons consist of a group of buttons that are visually grouped together to represent a set of related actions or options. ## Overview Group Buttons consist of a group of buttons that are visually grouped together to represent a set of related actions or options. When a button in the group is selected, the selected state is visually highlighted. This can be used for selecting one item among others, renderings of multi-select, as in a style for selecting multiple exposed items in a form or list, or as filters. ### Usage When to use: - Use Group Buttons when you have a set of related options and want to allow users to select one or many options from the group. - Use Group Buttons when you want to provide a visual appealing and interactive way for users to make a selection, or change a view. When not to use: - Avoid using Group Buttons when the options in the group are unrelated or independent. In such cases, consider using separate buttons. - It is not recommended to use Group Buttons for navigation purposes, as this component is primarily designed for input or selection. In such cases, consider using other UI elements like tabs. - Don’t use Group Buttons when you have too many actions: separate them into multiple Group Buttons or use a Dropdown instead to overwhelm them. ## Anatomy The component anatomy is used to illustrate the general make up of your component, including the spacing and positioning of elements that sit within it. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇❖ Group Buttons | Property | Values | Default | | --------------- | ------------------------------- | ---------- | | **size** | small / medium / large / xlarge | medium | | **variant** | outline / ghost | outline | | **type** | text / icon | label | | **color** | primary / neutral / white | primary | | **orientation** | horizontal / vertical | horizontal | | **spacing** | false / true | false | | **fullWidth** | false / true | false | | **3,4,5,6,7,8** | boolean | 3 | #### ◇❖ Sub-component: Group Buttons - Button | Property | Values | Default | | ------------------ | ---------------------------- | ---------- | | **size** | small / medium / large | medium | | **active** | false / true | false | | **activeEmphasis** | medium / high | medium | | **type** | text / icon | text | | **style** | outline / ghost | outline | | **color** | primary / neutral / white | primary | | **orientation** | horizontal / vertical | horizontal | | **position** | start / between / end / full | start | | **◇ Button** | Nested properties | -- | | **◇ Icon Button** | Nested properties | -- | #### ◇ Nested properties: [Button](/docs/components/button) #### ◇ Nested properties: [Icon Button](/docs/components/button#icon-buttons) ## Behaviour Component behaviour helps to present the states and use cases that the component might encounter. ### Group Buttons #### Size Group buttons exist with 3 different sizes (small, medium and large) to provide flexibility in visual hierarchy and adapt to different layout requirements. #### Variants Group buttons can be designed with an outline or ghost variant, which provide different visual styles for buttons, allowing designers to create varied and distinct button styles to suit different design needs. **Outline**: Outline variants are designed with a border around the buttons, providing a clear visual separation from the background and other elements on the screen. They can be used for various purposes, such as primary actions, secondary actions, or for buttons that need to stand out in a particular context. **Ghost**: Ghost variants are designed with a transparent background, allowing the background or the content underneath the buttons to be visible, while still providing a clear visual indication of the button's presence. Ghost buttons have a subtle and understated appearance, and they can be used for various purposes, such as for secondary actions, or for buttons that need to blend in with the surrounding content. #### Colors Group buttons can be designed with different color variants to provide visual hierarchy and convey different meanings or actions to users. The primary, neutral, and white color variants offer distinct visual styles that can be used for different design purposes : **Primary**: The primary color is typically used to convey the main action or primary call-to-action in a user interface. Primary buttons often have a bold and prominent appearance, drawing the user's attention and encouraging them to take the intended action. **Neutral**: Neutral buttons provide a more subdued and understated appearance, and are often used for secondary actions or for buttons that are less prominent but still important in the user interface. **White**: White color variants are designed with a contrasting color palette, such as primary or dark background. Please note that the white variant is designed for light theme only and may not be suitable for dark theme usage. If you need to design for dark theme, use the component from the dark theme library. #### Type We provide you two types of Group Buttons: **Text Group Buttons**: Text group buttons are a type of group of buttons, each containing text labels. Text group buttons are designed to convey information and provide clear and concise labels to help users understand the purpose of each button. **Icon Group Buttons**: Icon group buttons are another type of a group of buttons, each containing icons or graphical symbols. These buttons are designed to convey actions or commands through visual representations rather than text labels. To enhance accessibility, tooltips can be added to provide additional context or descriptions for the icons. #### Orientation Group buttons can be designed with different orientations, including **horizontal** and **vertical**, to suit different layout requirements. #### Spacing You can choose between a clustered arrangement, where the buttons are placed close together with no spacing between them, or a spaced-out arrangement, where the buttons are spaced apart with a gap between them. **Clustered**: Use when you want to group related buttons closely together, such as for a set of related actions or filters. **Spacing**: Use when you want to visually separate the buttons from each other, such as for a navigation menu or a set of mutually exclusive options. #### Full Width The full width property determines how the buttons are sized in relation to the container they are placed in. You can choose between a hug content option, where the buttons are sized to fit their contents with no extra space on either side, or a full width option, where the buttons are stretched to fill the entire available width with equal spacing on either side. **Hug content**: Use when you want the button width to match the content width, such as for a short label or icon-only button. **Full width**: Use when you want the buttons to span the full width of the container, such as for a call-to-action button or a tab navigation. ### Group Buttons: Button #### Active Description about the behaviour, including any relevant links from research and internal Thales use cases. #### Active emphasis The active emphasis property determines how the active button is visually distinguished from the other buttons in the group when active. **Medium emphasis**: Use when you want to visually differentiate the active button from the other buttons, but not to the point of overwhelming them. **High emphasis**: Use when you want to draw significant attention to the active button. #### Position The position property of a button within the group determines its visual position relative to the other buttons in the group. **Start**: The button is aligned to the left edge of the group **Between**: The button is aligned between other buttons in the group **End**: The button is aligned to the right edge of the group **Full**: The button is full ## Usage Guidelines Usage guidelines help depict the best practices when using this component by giving examples of the do’s and don’ts. ### Appearance #### Maintain visual consistency among Group buttons - **Don’t**: Mix different button types or colors within the same Group Buttons component, as this can create visual clutter and confusion for users. - **Do**: Consistently use one style for all buttons within a Group Buttons component. #### Use icons with label only to reinforce action - **Don’t**: Avoid using icons in action buttons for merely aesthetic purposes and icons that do not intuitively reinforce the action of the button. - **Do**: Icons may be used in combination with button group text labels to further reinforce the explanation of the setting or view associated with interacting with the button. **Note**: You can add a left icon for Group Buttons - Button by editing its nested properties. #### Icon position for labels - **Don’t**: Position icon to the right, as this may disrupt the typical reading direction and create confusion for users. - **Do**: Align icon to the left as it is the typical reading direction for most languages, and helps to create a clear visual hierarchy for the user. #### Wrapping label - **Don’t**: Wrap label text onto multiple lines, as this can disrupt the visual flow of the buttons and reduce their effectiveness. - **Do**: Keep the label text for each button to a single line to maintain a consistent and visually balanced layout, improving the readability of the buttons. ### Arrangement #### Arrange buttons in logical order - **Don’t**: Use inconsistent or illogical ordering of the buttons, as this can create confusion and frustration for the user. This order can vary depending on the product and user needs. - **Do**: Do consider the relative importance of each button, and order them accordingly. For example, more frequently used or higher-priority actions should be placed first. #### Multiple Groups Buttons arrangement - **Don’t**: Bury important primary actions among less important secondary actions - **Do**: Position primary actions at first, and differentiate them from secondary actions. **Note**: Use multiple Group Buttons with dividers to organize related actions or options into sections, making it easier for users to find what they need. ### Examples and recommendations of usage #### Single Select Single selection allows users to choose only one option from a group of buttons at a time. This is useful when the options are mutually exclusive, and the user needs to select only one option. In a single selection group button, selecting one button automatically deselects any previously selected button. #### Multi Select Multi-selection allows users to choose more than one option from a group of buttons. This is useful when the options are not mutually exclusive, and the user needs to select multiple options simultaneously. In a multi-selection group button, selecting one button does not automatically deselect any previously selected button. Users can select multiple options until they have made all the desired choices. #### Single Select Group Button vs Toggle switch - **Don’t**: Avoid using Group buttons for a single setting such as On/Off. - **Do**: Instead, consider using a [toggle switch](/docs/components/toggle-switch). #### Single Select Group Button vs Dropdown select - **Don’t**: use Group Button for a large amount of options - **Do**: Instead, consider using a [Dropdown Select](/docs/components/dropdown-select). #### Don’t use Group Buttons for navigation purposes - **Don’t**: Use group buttons for site navigation. - **Do**: Consider using [Tabs](/docs/components/tabs) since they are better suited for navigation, as they provide a consistent and intuitive way for users to move between different sections or pages on a website or application. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=30198-547199&t=244StnnCdoCtO9oW-4) # Dropdown Menu ## Overview A Dropdown Menu displays a list of actions or options to a user. ### Usage When to use: - Users need to select one item exclusively from a short list of options (for example, fewer than 12 items). - The values of the option list contain secondary information that does not need to be displayed right away. When not to use: - Users need to select from a list of two options, where one of the options can be implied as on and off or yes and no. Consider using a [Toggle Switch](/docs/components/toggle-switch) control instead. - Users need to pick one item from a large set of options. In this case, you should consider using the [Combo Box](/docs/components/combo-box) instead. - Your use case requires all available options to be displayed right away, without any user interaction. In this case, consider using [Radio Buttons](/docs/components/radio-button) or a [Radio Button Group](/docs/components/radio-button) instead. - Do not nest dropdowns or use them to display overly complex information. Keep option selections as straight forward as possible. ### Sources and references - [10 Ways to Improve Dropdowns in UI & UX Design](https://uxdesign.cc/10-ways-to-improve-dropdowns-in-ui-ux-design-59d61a304b70) - UX Design - [Dropdowns](https://getbootstrap.com/docs/4.3/components/dropdowns/#overview) - Bootstrap - [Dropdown Menu](https://atlassian.design/components/dropdown-menu/examples) - Atlassian - [Menus](https://m3.material.io/components/menus/) - Material Design - [Popover](https://spectrum.adobe.com/page/popover/) - Adobe Spectrum - [Popper.js](https://popper.js.org/) - Popper - [Dropdown](https://www.carbondesignsystem.com/components/dropdown/usage) - IBM Carbon - [Web components punch list](https://www.tpgi.com/web-components-punch-list/) - TPGi - [Alice Bartlett: Burn your select tags - EpicFEL 2014](https://www.youtube.com/watch?v=CUkMCQR4TpY) - YouTube - [Dropdown](https://developer.microsoft.com/en-us/fluentui#/controls/web/dropdown) - Microsoft Fluent UI Web - [Action list](https://polaris-react.shopify.com/components/actions/action-list) - Shopify Polaris - [Combo Box](https://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/combo-box) - SAP Design System ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇❖ Component: Dropdown Menu | Property | Values | Default | | -------------- | ------------------------------------------------ | ------- | | **size** | small / medium / large | medium | | **items** | 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 | 6 | | **scrollable** | true / false | false | #### ❖ Sub-component: Dropdown Menu Item | Property | Values | Default | | ---------------- | ----------------------------------- | --------------- | | **size** | small / medium / large | medium | | **state** | default / hover / focused / pressed | default | | **active** | true / false | false | | **disabled** | true / false | false | | **hasCheckbox** | boolean | true | | **hasIcon** | boolean | true | | **icon** | instance swap | person | | **hasLabel** | text | “dropdown item” | | **hasCaption** | boolean | true | | **caption** | text | “caption” | | **rightContent** | boolean | true | ## Behaviour ### Size Dropdowns are available in three sizes to cater for the diverse range of use cases and devices that our business uses. By default, the medium dropdown is typically used for desktop/tablet devices. But for mobile devices, it is advised that you upscale the dropdown, to increase the touch area and make sure you reach the minimum requirements considering your target screen size and density. For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html). ### Sorting Items in a dropdown list should be sorted in the most logical way for the user. The following options are suggested when considering which sorting method to use… - Logical: sorted into a meaningful order such as days of the week. - Alphabetical: sort names, and similar content alphabetically. - Numeric: sort numeric values into a sequential order, with the lowest number first. - Chronological: sort time-related information into chronological order, with the most recent first. ### Text overflow When a dropdown menu item label is too long for the available horizontal space, they wrap to form another line. The field text itself truncates at the end, but the text can be shown in full in the dropdown menu. ### Position Menus should be positioned relative to the edge of the screen or browser. They typically appear next to (or in front of) the element that generates them. If they are in a position to be cut off by the browser or screen’s edge, the menu can instead appear to the left, right, or above the element that generates it. ### Scrolling Menus can be scrollable if not all menu items are shown at once. In this state, menus show a persistent scroll bar. However, scroll bars may not always be enabled so we recommend showing 50% of the last item’s container height to indicate there is more to see within the menu. ## Usage Guidelines ### Keep menu items concise - **Don’t**: use lots of text to describe the action behind a menu item in the dropdown. It will cause the text to wrap making it difficult for the user to quickly scan the list. - **Do**: keep the label in the dropdown menu item short and concise. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284233&t=244StnnCdoCtO9oW-4) # Alert & Toast ## Overview - Alerts inform the user of important information or important action required. They are non-disruptive to a user's experience and do not require to interrupt the user’s task. - Toasts are temporary pop-up alerts that displays briefly on the screen to provide feedback or information to the user. Toasts can be closed by the user or can automatically disappear after a set amount of time. ### Usage When to use: - Use alerts/toasts when displaying a highlight, a message to confirm an action, an error and make someone aware of important information. - When you do not want to interrupt users while they are performing an action. When not to use: - When you need to interrupt users while they are performing an action. - You want to make sure that users read the message before they leave the page. ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇◇❖ Alert | Property | Values | Default | | ------------------- | ------------------------------------------------- | -------------- | | **size** | small / medium / large | medium | | **severity** | informative / neutral / success / warning / error | informative | | **emphasis** | low / medium / high | low | | **leftIcon** | instance swap | true | | **informativeIcon** | instance swap | info | | **successIcon** | instance swap | check_circle | | **warningIcon** | boolean | warning_amber | | **errorIcon** | instance swap | error_outline | | **hasTitle** | boolean | false | | **title** | text | title | | **message** | text | Alert message. | | **rightActions** | boolean | true | | **actionButton** | boolean | true | | **dismissible** | boolean | true | #### ❖ Sub-Component: Button Note: this component is composed of other Quantum elements ([Button](/docs/components/button) & [Icon Button](/docs/components/button#icon-buttons)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. #### ❖ Sub-Component: Icon Button Note: this component is composed of other Quantum elements ([Button](/docs/components/button) & [Icon Button](/docs/components/button#icon-buttons)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. #### ◇❖ Toast | Property | Values | Default | | ------------------ | ------------------------- | ------- | | **slideDirection** | none / ↑ / ↓ / ← / → | none | | **dismissible** | false / true | true | | **hidden** | false / true | false | | **◇ Alert** | → Alert nested properties | | ## Behaviour Note: this component is composed of other Quantum elements ([Button](/docs/components/button) & [Icon Button](/docs/components/button#icon-buttons)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. ### Low / Medium / High emphasis The Quantum supports three levels of emphasis style alerts. High-emphasis alerts are best for critical messaging while low-emphasis and mid-emphasis alerts are less visually disruptive for users. It’s up to the product team to decide which notification style to use in their product. However, it is important to not mix the styles when they are applied at the same level hierarchy. When in doubt, use low-contrast notifications. ### Neutral variant The neutral variant is the default alert option. It uses the Quantum bluegrey and does not have an icon. This is used when the message is neutral in tone or when its semantics do not fit in any of the other variants. Note: this variant also uses the general interaction states such as hover, active, focused. ### Informative variant The informative alert uses the informative semantic colour (primary) and has an info icon to help those with colour vision deficiency discern the message tone. Similar to the call to action button, this should be used when the message should call extra attention compared to the neutral variant. Note: this variant also utilises the general interaction states such as hover, active, focused. ### Success variant The success alert uses the positive semantic colour (green) and has a checkmark icon to help those with colour vision deficiency discern the message tone. This can be used to inform the user of a successful operation. Note: this variant also utilises the general interaction states such as hover, active, focused. ### Warning variant The warning alert uses the warning semantic colour (orange) and has an warning icon to help those with colour vision deficiency to discern the message tone. This can be used to show an attention point to the user. Note: this variant also utilises the general interaction states such as hover, active, focused. ### Error variant The error alert uses the error semantic colour (red) and has an alert icon to help those with colour vision deficiency to discern the message tone. This can be used to show an attention point to the user. Note: this variant also utilises the general interaction states such as hover, active, focused. ### Action An alert can have up to one button, to ensure consistency and maintain focus on the message being presented to the user. This means that the button can only be used if its action directly relates to the message. Note: the dismissible button is not considered as an action in the same context, therefore you can have a dismissible button and a single action in one alert. ### Links An alert message may also contain a link that directly relates to a file or location in which an action has either successfully or unsuccessfully been achieved. For example: > All files archived. Find archived files in [My Documents](#). This can only be used if an action is not already in place. ### Toast #### Slide direction When disappearing, toasts can slide out from different directions, depending on the design requirements and the desired user experience. It is recommended to use the same slide direction as the position of the toast for avoiding obstruction of the content on the screen when it disappears. #### Dismissible / Non-dismissible - Dismissible toasts provide a close button or icon for the user to manually dismiss the toast if desired. You can also add a time-out to make it disappear after a set duration of time. - Non-dismissible toasts automatically disappear after a a set duration of time. They provide a convenient way for the user to quickly view and take into account the message, without having to take any action to dismiss the toast. #### Change the toast duration You can change the timer to dismiss the toast after a set amount of time has elapsed : - Select the toast (Non-dismissible) - Go to Prototype > Variant interactions > Delay - Change the “After delay” timer to the desired time-out time As a general rule, toasts should be displayed for just enough time to allow the user to read the content, but not long enough to become annoying or obstructive. A common recommendation for the duration of a toast is 3-5 seconds. For toasts that display critical or important information, a longer duration may be appropriate, while for toasts that display simple confirmation messages, a shorter duration may be sufficient. ## Usage Guidelines ### Alert or Toast? - **Alert**: Alerts should be used sparingly to highlight important information that requires the user's attention, without interrupting the user's current task. These alerts can either remain visible permanently or disappear once the user takes action, such as clicking a button. - **Toast**: use Toasts for temporary confirmation, simple notifications, and low-priority alerts that do not need to completely interrupt the user experience. Toasts automatically disappear after a set duration, or can be dismissed by the user by clicking on a button. ### Alert or modal dialog? - **Don’t**: use a Modal Dialog to present a simple notification as it will distract the users attention, interrupting the user experience. Dialog is only ideal when a situation requires the user’s attention, either for displaying important information or prompting for a response. - **Do**: use Toasts for confirmation, simple notifications, and low-priority alerts that do not need to completely interrupt the user experience. ### Use one action only - **Don’t**: display more than one action in an alert, it can overwhelm and distract the user. - **Do**: use only one action to focus the user’s attention on the message in the alert. ### Use sentence case - **Don’t**: use any other text formatting such as capitalization, as it can affect the users emotional reaction, slows down the reading and can either engage or repel them. - **Do**: use sentence case as it is easier to read, and more natural when reading. ### Overuse of alerts - **Don’t**: Overuse alerts, too many alerts is annoying and obstructive and can lead users to disregard them. - **Do**: Use alerts sparingly and only to highlight information that requires the user’s attention. ### Avoid stacking multiple toasts Quantum recommends presenting single toasts as opposed to stacking or overlaying. However, we do recognise that sometimes toasts are consecutively or simultaneously triggered and so they must be presented somehow - in this case, we recommend the stacked approach. ### Examples of usage #### Alerts as a banner You can use alerts as a banner to display non-critical information or messages that do not require immediate action from the user. #### Alerts in notifications You can use alerts in notifications to inform the user of important information or events that require their attention. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=16305-478406&t=244StnnCdoCtO9oW-4) # Modal Dialog ## Overview A Modal Dialog focuses the user’s attention exclusively on one task or piece of information via a window that sits on top of the page content. It does this by disabling the main content until the user explicitly interacts with the modal dialog. - Modal dialog should be used when you need to: - Grab the user’s attention - Get input from the user ### Usage When to use : - Grab the user’s attention - Get input from the user ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇◇❖ Component: Dialog Box | Property | Values | Default | | -------------------- | ---------------------- | ------- | | **size** | small / medium / large | medium | | **content** | custom / textArea | custom | | **verticalResizing** | true / false | false | #### ❖ Sub-Component: Header | Property | Values | Default | | --------------- | ---------------------- | ------- | | **size** | small / medium / large | medium | | **hasLeftIcon** | boolean | true | | **hasCaption** | boolean | true | | **dismissible** | boolean | true | #### ❖ Sub-Component: Footer | Property | Values | Default | | ------------------- | ---------------------- | ---------- | | **size** | small / medium / large | medium | | **alignment** | horizontal / vertical | horizontal | | **divider** | boolean | true | | **primaryAction** | boolean | true | | **secondaryAction** | boolean | true | | **tertiaryAction** | boolean | false | ## Behaviour ### Choosing an escaping pattern The header is customizable and you can easily turn on and off the presence of the close button. By doing so, you must consider choosing and documenting in your designs the right escape pattern: - Pressing **‘x’** button - Pressing **‘ESC’** on the keyboard - Clicking outside of the dialog box - Using a **‘Cancel’** option ### Customize content To swap the default content with your own, follow these simple steps: 1. **Create your composition in a frame and apply Auto layout to it** 2. **Create a local component with this frame** 3. **Drag & drop it from your assets panel while pressing CTRL+ALT or CMD+OPT to swap the default content** 4. **Make sure to apply the right constraints for resizing the lower components in the content area** ### Action buttons group A dialog can have up to 3 buttons in its footer compartment. When horizontal space is limited, button groups stack vertically. They should appear in ascending order based on importance, with the most critical action at the bottom. ### Manual resizing (Vertical) The modal component comes in 2 versions when it comes to resizing: - Automatic sizing based on the content you will put in the swap zone. (default) - Manual override to manage yourself the vertical size of the dialog box. ### Overlay or Scrim To focus the attention on the modal and indicate that any interaction with the main content behind is disabled, the modal includes an overlay or scrim layer. The overlay sits right behind the modal and cover the full page. The overlay uses the color black-30: black color with a transparency of 30%. ## Usage Guidelines ### Naming your dialog - **Don’t**: use dialog titles that pose an ambiguous question to the user. - **Do**: name a dialog with a specific question or statement that concisely explains what’s involved in the request, and provides clear actions. ### Naming your actions - **Don’t**: name your actions with ambiguous words, otherwise it creates a sense of doubt to the user. - **Do**: name actions with specific and actionable words, allowing the user to make a confident decision. ### Provide important information - **Don’t**: make things unclear about the impact for the user. - **Do**: clearly state what the action taken will impact from the user’s perspective. ### Don’t stack dialog boxes - **Don’t**: make a dialog appear on top of another. - **Do**: avoid visual complexity by sticking to one dialog at a time. ### Avoid multiple steps dialog - **Don’t**: do multi step dialog. If the interaction is complex enough to have this many inputs or information to retrieve, it might be worth having its own page. - **Do**: consider making it a dedicated page in the process. ## Layout Grid Examples [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284209&t=244StnnCdoCtO9oW-4) ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284217&t=244StnnCdoCtO9oW-4) # Tooltip ## Overview Tooltips are contextual, non-actionable and informative floating labels. They can be activated by hover, focus, or even click to display additional information to help the users understand something. They should always be non-essential to the global understanding. ### Usage When to use: - When you want to display additional information for an interface element. - To describe an icon when it is not labelled, such as the menu items in the [Rail](/docs/components/rail). When not to use: - Don’t use tooltips to display crucial information. This kind of information should always be accessible without any interaction from the users. - To propose new actions: tooltips must **always** be informative only, and never actionable ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ Component: Tooltip | Property | Values | Default | | --------------- | --------------------------- | --------------------------------- | | **size** | small / medium / large | medium | | **orientation** | left / right / bottom / top | left | | **tipPosition** | start / center / end | center | | **lowContrast** | true / false | false | | **\*hasTitle** | boolean | true | | **\*title** | text | “Tooltip title.” | | **content** | text | “Write the tooltip content here.” | ## Behaviour ### Sizes Tooltips are available in three sizes to cater for the diverse range of use cases and devices that our business uses. By default, the medium tooltip is used typically for desktop. But for mobile devices, it is advised that you upscale the tooltip, to maximize the visual impact. For more information about text sizes and readability, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html). ### Tooltip title Use the title property if you need to summarize a long description. Therefore, we strongly recommend being as concise as possible to not strain the attention of the user in their business context. ### Tip direction The tooltip component should always be positioned according to its target. The tip direction variants help you initiate this orientation. Coupled with the tip position, this component caters for the diverse range of use cases and positions you might need to contextualize it. Main directions include: - Bottom - Top - Left - Right ### Tip position The tooltip component should always be positioned according to its target. The tip position variants help you complete the tip direction variant to be even more precise. For all directions, the tip position options are: - Start - Center - End ### Low contrast option To lower the visual emphasis on the tooltip component, you can activate the Low contrast option. This option will apply a lighter background to the tooltip while remaining always accessible. ## Usage Guidelines ### Tooltips aren’t made for crucial information. - **Don’t**: hide information that is crucial to the experience. - **Do**: always make them visible instead and use tooltip for additional information. ### Be as concise as possible - **Don’t**: overflow the tooltip with too much information. Tooltips are supposed to carry additional information so avoid taking too much of your user’s attention. - **Do**: keep the tooltips content 1 or 2 (short) sentences long. ### Use orientation options to avoid obstructions - **Don’t**: mask important information under a tooltip. - **Do**: choose the best orientation option so the tooltip doesn’t obstruct helpful contextual information. ### Use tip position options when constrained by the window’s edge/corner - **Don’t**: resize the tooltip to bring the tip closer to its target. - **Do**: Choose the right tip position to visually connect the tooltip with its target (start, center or end). ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284177&t=244StnnCdoCtO9oW-4) # Checkbox ## Overview Checkboxes allow users to select multiple options from a list, or to mark an individual item as selected. They are often familiar to users, as checkboxes originated on paper forms and are incredibly useful for scanning a list of items before making one or more selections. ### Usage When to use: - Select one or more options from a list - Present a list containing sub-selections - Turn an item on or off ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇❖ Component: Checkbox | Property | Values | Default | | --------- | ---------------------- | ------- | | **size** | small / medium / large | medium | | **items** | 2 to 10 | 3 | | **color** | primary / neutral | primary | #### ❖ Component: Checkbox | Property | Values | Default | | ----------------- | ----------------------------------- | --------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **state** | default / hover / focused / pressed | default | | **checked** | false / true | false | | **indeterminate** | false / true | false | | **error** | false / true | false | | **disabled** | false / true | false | | **\*hasLabel** | boolean | true | | **label** | text | “Label” | | **\*hasCaption** | boolean | false | | **\*caption** | text | “Caption” | ## Behavior ### Sizes Checkboxes are available in three sizes to cater for the diverse range of use cases and devices that our business uses. By default, the medium checkbox is used typically for desktop/tablet devices. But for mobile devices, it is advised that you upscale the checkbox, to increase the touch area. For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html). ### Selection Checkboxes can be unchecked, checked, or in an indeterminate state. The indeterminate state is used when a value is neither selected or unselected. For example, a parent checkbox showing several checkbox children, with some checked and some unchecked. ### Emphasis By default, checkboxes are emphasized (primary theme). Providing a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a checkbox is required. For visual components, like application panels, where a checkbox shouldn't be a standout element, choose the neutral theme to de-emphasize its visual presence on the screen. ### Error Checkboxes can also have an error state to show that a selection needs to be made in order to move forward, or that a selection that was made is invalid. ### Text overflow When the label is too long for the horizontal space available, it can be wrapped to form another line. Use the following steps in order to configure the TDS component to do this: 1. Set **‘Label Base’** layer to fill container (horizontally). 2. Set **‘input-and-label’** layer to fill container (horizontally). 3. Set **‘Checkbox - Base’** layer to fill container (horizontally). 4. Set **‘Checkbox’** layer to fill container (horizontally). 5. As a result of changing the layer in step 4 you will need to reset the **‘Checkbox - Base’** layer to fill container (horizontally). ### Internationalization For RTL (right-to-left) languages, the layout of the checkbox is mirrored. The checkmark is placed on the right side of the text. To build your own (BYO) version of this, either detach the **Checkbox** component or use the **Checkbox Input** component with the correct font scale and spacing as seen in the LTR version. ## Usage Guidelines ### When to choose a checkbox over radio buttons - **Don’t:** use checkbox groups if the selection only requires a single option from a list of mutually exclusive options. - **Do:** use checkboxes when a user needs to select as many options as desired. ### When to choose a checkbox over a switch - **Don’t**: use a checkbox to communicate activation (e.g. on/off states) as they can have an error state and this could confuse users about the action they’re about to take. - **Do**: use a checkbox for communicating selection. ### Label groups of related checkboxes - **Don’t**: expect the users to understand a group of checkboxes, if they are not provided with a header or caption text. - **Do**: provide a label with your checkboxes to describe what the list of options represents and guides the users in what to do. Especially for those using a screen reader. ### Representing mixed values - **Don’t**: use the unchecked state for mixed state for sub-items. - **Do**: use the indeterminate state to represent a mixed state for sub-items. ### Concise labelling - **Don’t**: use complicated labels. - **Do**: use explicit and concise labels. ### Using the “other option” - **Don’t**: force the user to choose an option they don’t want to. - **Do**: add the input field component to support the “other option” if not all options are available in the list. ### Text wrapping - **Don’t**: not vertically centre wrapped text with the checkbox. - **Do**: let the text wrap beneath the checkbox so the control and the label are top aligned. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284169&t=kOWgyuqnVCEtliGV-4) # Combo Box ## Overview Combo Boxes combine a text entry with a dropdown menu, allowing users to filter longer lists to only the selections matching a query. ### Usage - Users need to select a single item from a long list of items. - The values of the option list are secondary information and do not need to be displayed right away. - You want to allow users to be able to quickly search or filter through the item list. When not to use: - Users need to select from a list of two options, where one of the options can be implied as on and off or yes and no. Consider using a [toggle switch](/docs/components/toggle-switch) control instead. ### Sources and references - [Combo box](https://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/combo-box) - SAP Fiori ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇◇❖ Combo Box | Property | Values | Default | | ------------ | ------------------------ | ------- | | **size** | small / medium / large | medium | | **state** | default / hover / filled | default | | **open** | false / true | false | | **error** | true / false | false | | **disabled** | false / true | false | #### ◇❖ Sub-component: Text input Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. #### ◇❖ Sub-component: Dropdown menu Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. ## Behaviour Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. ### Sizes Combo boxes are available in three sizes to cater for the diverse range of use cases and devices that our business uses. When the menu is open, each option in the menu should be the same height as the field. Use a consistent size of form components on the same page. For example, if you are using a medium size combo box menu also use the same size text inputs, buttons, and so on. ### Filterable input When the dropdown menu gets longer than 10-20 items, a searchable input can allow a user to search items easier through a large list of choices instead of scrolling down. ### Autosuggest & autocomplete The two types of selection suggestion should not be confused. - Autosuggestion: filters through the list of items to give the user a smaller range of options to choose from. - Autocompletion: when the input field puts forward a way to complete the sentence or the word. ### Completed input When the user has selected an option, the dropdown should return to the default state with the selection as replacement of the placeholder. This is the “**filled**” state. When the user opens back the dropdown, the component should highlight the last selection with the **hover/active state as default**. ## Usage Guidelines ### Choosing radio buttons over dropdowns - **Don’t**: use dropdowns for 5 options or less. - **Do**: use radio buttons instead. ### Choosing text inputs over dropdowns - **Don’t**: propose a dropdown if selecting an option takes more time than typing. - **Do**: use text inputs (for example) instead. ### Avoid dropdowns for binary choices (On/Off - Yes/No - …) - **Don’t**: make the user select between two binary and opposed options in a list. - **Do**: use a toggle switch or a checkbox instead. ### Avoid dropdowns for numeric choices - **Don’t**: use a dropdown if the user has to select in a list of numeric items (years, numbers, …) - **Don’t**: give the user a too long, scrollable list of options to choose from without helping them. - **Do**: use a solution like auto-suggest or auto-complete to give them opportunity to search in your list. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284161&t=kOWgyuqnVCEtliGV-4) # Date Picker ## Overview Date Pickers are used when you have to select dates, whether dates are displayed in a calendar view or simply in an input field. They allow you to select a single value from a predetermined set, or a range of values depending on context. ### Usage When to use: - If you want users to indicate a single date or a range of dates. When not to use: - If the dates are really restrictive and could be filled with a predefined list or checkbox. ### Sources - [Date-Input Form Fields](https://www.nngroup.com/articles/date-input/) by Nielsen Norman Group - [Date picker](https://carbondesignsystem.com/components/date-picker/usage/) by Carbon Design System - [Date Picker](https://mui.com/x/react-date-pickers/date-picker/) by MUI X - [Datepicker](https://material.angular.dev/components/datepicker/overview) by Material Angular ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### Component: Date Picker | Property | Values | Default | | ---------------- | ------------------------ | ------- | | **size** | small / medium / large | medium | | **range** | off / on | off | | **state** | default / hover / filled | default | | **color** | neutral / primary | primary | | **error** | false / true | false | | **disabled** | false / true | false | | **showCalendar** | boolean | true | | **footer** | boolean | true | | **caption** | boolean | true | #### Component: Date Bounding Box | Property | Values | Default | | --------------- | ---------------------------------------------- | ------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **state** | default / hover / focused / pressed / in range | default | | **selected** | false / true | false | | **disabled** | false / true | false | | **label** | text | 1 | | **current day** | boolean | true | | **first date** | boolean | false | | **last date** | boolean | false | #### Component: Header Menu | Property | Values | Default | | ---------------- | ------------------------------------------------------ | -------------- | | **size** | small / medium / large | medium | | **style** | single picker / right range picker / left range picker | single picker | | **yearCalendar** | false / true | false | | **dropdown** | boolean | true | | **label** | text | “october 2022” | ## Behaviour ### Date Picker #### Sizes Date Picker exist with 3 different sizes: small, medium and large. When the calendar is open, each nested component should be the same height as the date input field. Use a consistent size of form components on the same page. For example, if you are using a medium size dropdown multiselect, also use the same size text inputs, buttons, and so on. #### Range Picker Range Picker should be used when the user is asked to specify a range of dates, for example for the dates of departure and return of a trip. Range Picker is basically two Date Pickers joined. First Child and Last Child properties should be used on selected state dates to produce a more realistic prototype. #### Calendar By default, the calendar is visible (On state), but it is possible to hide it and show only the date input label. #### Footer By default, Footer is not visible (Off state). When activated, it allows the user to control the date picker component with explicit action buttons, primary, secondary and tertiary buttons. It offers the possibility to confirm or cancel the current selection, and use “Today” shortcut to return to today's date. ### Date Bounding Box #### State States, similar to the Button component are proposed to cover every use case. #### Current Day By default, current day state is deactivated within a Date Picker component. The indication is materialized by a dot under the day number. The goal is to allow the user to know the current day from the date picker, to speed up his decision making. #### First and Last Date First Date and Last Date are properties only available for Date Bounding Box component with selected state. It should be used when a date range is indicated, to keep visual consistency between the Selected and In Range states of the Date Bounding Box. ### Header Menu #### Year Calendar By default, Year Calendar is not visible (Off state). When activated, it allows the user to select the targeted year efficiently. States, similar to the Button component are proposed to cover every use case. ## Usage Guidelines Usage guidelines help depict the best practices when using this component by giving examples of the do’s and don’ts. ### Never without my Date Input - **Don’t**: suppress the date input field - **Do**: always allow users to type the date ### A good Date Input is a personalized one - **Don’t**: only use pre-filled date input provided by Quantum - **Do**: adapt the input field to the localisation or the need of your user ### Drag selection behavior - **Don’t**: only use click option to select a date range - **Do**: propose a drag selection to adapt to user ease ### Date Input for a Mobile usage - **Don’t**: use date picker as a push - **Do**: use date picker as a modal ### What about the reset feature - **Don’t**: prevent the user's right to error - **Do**: express the user’s right to error by displaying the Footer or with click-to-cancel mechanism ### Uses of disable on days - **Don’t**: limit yourself to using the default calendar - **Do**: use date picker by adapting the days of unavailability to it’s context ## Showcase Showcase of a component - like a usage demonstration - help to make the complexity of a component more understandable, via the presentation of a concrete use by a hypothetical end user. ### Date Picker demonstration **Hypothetical goal** Select your travel dates - March 12, 2025 to April 5, 2025 **Steps** - Use Range Date Picker - Change years - Change months - Change days 1. Open the Range Date Picker by clicking on the Date Input & open the Start date’s Year Picker by clicking on the arrow. 2. Select the year & select the month within Header Menu by clicking on the chevron. 3. Select the day within Calendar View & repeat the process for the End date. 4. Enjoy your filled Range Date Picker. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=17017-416805&t=kOWgyuqnVCEtliGV-4) # Dropdown Multiselect ## Overview Dropdown Multiselect allow users to select multiple items from a list of predefined items in a dropdown menu. Items are displayed as checkbox items to make the user understand the multiselection capability. ### Usage When to use: - Users need to select items from a long list of items. - The values of the option list are secondary information and do not need to be displayed right away. When not to use: - Users need to select from a list of two options, where one of the options can be implied as on and off or yes and no. Consider using a [toggle switch](/docs/components/toggle-switch) control instead. - You want the user to select one entry only. In this case, use the [text input](/docs/components/text-input) or [combo box](/docs/components/combo-box) instead. ### Sources and references - [Combo box](https://www.sap.com/design-system/fiori-design-web/v1-148/ui-elements/combo-box) - SAP Fiori ## Anatomy This component is almost entirely configurable, thanks to the Figma ‘Variants’ feature. To find out how you can use this flexible component, check out the following areas within the component to customise. All the sub-components can be accessed via the component’s layers list or by double-clicking in the corresponding zones highlighted with the purple boxes. Want to learn more? Check out the [Figma Variants Tutorial on YouTube](https://www.youtube.com/watch?v=y29Xwt9dET0), to understand how we build flexible components with Variants. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇◇❖ Component: Dropdown multiselect | Property | Values | Default | | -------------- | ------------------------ | ------- | | **size** | small / medium / large | Medium | | **state** | default / hover / filled | Default | | **disabled** | false / true | False | | **error** | false / true | False | | **\*isOpen** | false / true | False | | **searchable** | false / true | False | | **placement** | bottom / top | False | #### Composition This component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. ##### ❖ Sub-component: Text input ##### ❖ Sub-component: Dropdown menu ## Behaviour Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. ### Sizes Dropdown multiselects are available in three sizes to cater for the diverse range of use cases and devices that our business uses. When the menu is open, each option in the menu should be the same height as the field. Use a consistent size of form components on the same page. For example, if you are using a medium size dropdown multiselect, also use the same size text inputs, buttons, and so on. ### Filterable input When the dropdown menu gets longer than 10-20 items, a searchable input can allow a user to search items easier through a large list of choices instead of scrolling down. ### Autosuggest & autocomplete The two types of selection suggestion should not be confused. - Autosuggestion: filters through the list of items to give the user a smaller range of options to choose from. - Autocomplete: when the input field puts forward a way to complete the sentence or the word. ### Completed input When the user has selected an option, the dropdown multiselect should return to the default state with the selection as replacement of the placeholder. This is the “**filled**” state. When the user opens back the dropdown, the component should highlight the last selection with the **hover/active state as default**. To indicate the values in the field, we recommend using commas to separate items, or use removable tags to display the values. [Find associated documentation on tags here](/docs/components/tag). ## Usage Guidelines ### Choosing radio buttons over dropdowns - **Don’t**: use dropdowns for 5 options or less. - **Do**: use radio buttons instead. ### Choosing text inputs over dropdowns - **Don’t**: propose a dropdown if selecting an option takes more time than typing. - **Do**: use text inputs (for example) instead. ### Avoid dropdowns for binary choices (On/Off - Yes/No - …) - **Don’t**: make the user select between two binary and opposed options in a list. - **Do**: use a toggle switch or a checkbox instead. ### Avoid dropdowns for numeric choices - **Don’t**: use a dropdown if the user has to select in a list of numeric items (years, numbers, …) - **Do**: prefer using a text input (see below) to let them type in, or use a stepper. (coming soon) ### Help the user for long lists of choices - **Don’t**: give the user a too long, scrollable list of options to choose from without helping them. - **Do**: use a solution like auto-suggest or auto-complete to give them opportunity to search in your list. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284153&t=kOWgyuqnVCEtliGV-4) # Dropdown Select ## Overview Dropdown Selects allow the user to select a value from a list of choices with a single click. Combined with searching capability or text entry in the field, dropdown selects become combo boxes. [You can refer to the dedicated combo box documentation here.](/docs/components/combo-box) ### Usage When to use: - Users need to select a single item from a list of items. - The values of the option list are secondary information and do not need to be displayed right away. When not to use: - Don’t use tooltips to display crucial information. This kind of information should always be accessible without any interaction from the users. - To propose new actions: tooltips must always be informative only, and never actionable ## Anatomy This component is almost entirely configurable, thanks to the Figma ‘Variants’ feature. To find out how you can use this flexible component, check out the following areas within the component to customise. All the sub-components can be accessed via the component’s layers list or by double-clicking in the corresponding zones highlighted with the purple boxes. Want to learn more? Check out the [Figma Variants Tutorial on YouTube](https://www.youtube.com/watch?v=y29Xwt9dET0), to understand how we build flexible components with Variants. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇◇❖ Component: Dropdown select | Property | Values | Default | | ------------- | ------------------------ | ------- | | **size** | small / medium / large | medium | | **state** | default / hover / filled | default | | **disabled** | false / true | false | | **error** | false / true | false | | **\*isOpen** | false / true | true | | **placement** | bottom / top | bottom | #### Nested properties This component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. ##### ❖ Sub-component: Text input ##### ❖ Sub-component: Dropdown menu ## Behaviour Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu) & [Text Input](/docs/components/text-input)) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. ### Sizes Dropdown selects are available in three sizes to cater for the diverse range of use cases and devices that our business uses. When the menu is open, each option in the menu should be the same height as the field. Use a consistent size of form components on the same page. For example, if you are using a medium size dropdown select also use the same size text inputs, buttons, and so on. ### Completed input When the user has selected an option, the dropdown should return to the default state with the selection as replacement of the placeholder. This is the “**filled**” state. When the user opens back the dropdown, the component should highlight the last selection with the **hover/active state as default**. ### Using a combo box as a select As referred previously in the documentation, you can use the dropdown select jointly with a text entry pattern to search or filter through the data in the dropdown menu. This component is called a Combo box. [Please refer to the dedicated documentation here.](/docs/components/combo-box) ## Usage Guidelines ### Choosing radio buttons over dropdowns - **Don’t**: use dropdowns for 5 options or less. - **Do**: use radio buttons instead. ### Choosing text inputs over dropdowns - **Don’t**: propose a dropdown if selecting an option takes more time than typing. - **Do**: use text inputs (for example) instead. ### Avoid dropdowns for binary choices (On/Off - Yes/No - …) - **Don’t**: make the user select between two binary and opposed options in a list. - **Do**: use a toggle switch or a checkbox instead. ### Avoid dropdowns for numeric choices - **Don’t**: use a dropdown if the user has to select in a list of numeric items (years, numbers, …) - **Do**: prefer using a text input (see below) to let them type in, or use a stepper. (coming soon) ### Help the user for long lists of choices - **Don’t**: give the user a too long, scrollable list of options to choose from without helping them. - **Do**: use a solution like auto-suggest or auto-complete to give them opportunity to search in your list. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284145&t=kOWgyuqnVCEtliGV-4) # Radio Button ## Overview Radio Buttons are used when you have a group of mutually exclusive choices and only one selection from the group is allowed. ### Usage When to use: - Forms of any kind. - Settings: used to change from one setting to another. - Selection in lists: used to choose a singular item within a list or table. ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇❖ Component: Radio Button Group | Property | Values | Default | | --------- | ---------------------- | ------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **items** | 2 to 10 | 3 | #### ❖ Component: Radio Button | Property | Values | Default | | ---------------- | ----------------------------------- | --------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **state** | default / hover / focused / pressed | default | | **error** | true / false | false | | **disabled** | true / false | false | | **checked** | boolean | true | | **label** | text | “Label” | | **\*hasCaption** | boolean | false | | **\*caption** | text | “Caption” | ## Behaviour ### Sizes Radio buttons are available in three sizes to cater for the diverse range of use cases and devices that our business uses. By default, the medium radio button is used typically for desktop/tablet devices. But for mobile devices, it is advised that you upscale the radio button, to increase the touch area. For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html). ### Emphasis By default, radio buttons are emphasized (primary theme). Providing a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a radio button is required. For visual components, like application panels, where a radio button shouldn't be a standout element, choose the neutral theme to de-emphasize its visual presence on the screen. ### Error Radio buttons can also have an error state to show that a selection needs to be made in order to move forward, or that a selection that was made is invalid. ### Text overflow When the label is too long for the horizontal space available, it can be wrapped to form another line. Use the following steps in order to configure the TDS component to do this: - Set ‘**Label Base**’ text layer to fill container (horizontally). - Set ‘**input-and-label**’ layer to fill container (horizontally). - Set ‘**Base - Radio Button**’ layer to fill container (horizontally). - Set ‘**Radio Button**’ layer to fill container (horizontally). ### Internationalization For RTL (right-to-left) languages, the layout of the radio button is mirrored. The radio button input is placed on the right side of the text. To build your own (BYO) version of this, either detach the **Radio Button** component or use the **Radio Button Input** component with the correct font scale and spacing as seen in the LTR version. ## Usage Guidelines ### Use radio buttons for mutually exclusive options - **Don’t**: use radio buttons if a user needs to select as many options as desired (or none). - **Do**: use checkbox groups if the selection only requires a single option from a list of mutually exclusive options. ### When to choose a radio button over a switch - **Don’t**: use a radio button to communicate activation (e.g. on/off states) as they can have an error state and this could confuse users about the action they’re about to take. - **Do**: use a radio button for communicating selection of mutually exclusive options. ### Label groups of related radio buttons - **Don’t**: expect the users to understand a group of radio buttons, if they are not provided with a header or caption text. - **Do**: provide a label with your radio buttons to describe what the list of options represents and guides the users in what to do. Especially for those using a screen reader. ### Text wrapping - **Don’t**: vertically centre wrapped text with the radio button. - **Do**: let the text wrap beneath the radio button so the control and the label are top aligned. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284113&t=kOWgyuqnVCEtliGV-4) # Slider ## Overview Sliders are form elements with which users can set a value by dragging a cursor along a bar. It uses a knob or lever moved horizontally to control a variable, such as volume on a radio or brightness on a screen. ### Usage When to use: - When adjusting settings contained in a range - When selecting a value from a predefined range - When it’s possible to have a real-time feedback by dragging the handle - When the specific value does not matter to the user, but an approximate value is good enough. ### Sources - [Slider Design: Rules of Thumb](https://www.nngroup.com/articles/gui-slider-controls/) by Nielsen Norman Group - [Slider Components overview](https://material.angular.dev/components/slider/overview) by Material Angular ## Anatomy This component is almost entirely configurable, thanks to the Figma ‘Variants’ feature. To find out how you can use this flexible component, check out the following areas within the component to customise. All the sub-components can be accessed via the component’s layers list or by double-clicking in the corresponding zones highlighted with the purple boxes. Want to learn more? Check out the [Figma Variants Tutorial on YouTube](https://www.youtube.com/watch?v=y29Xwt9dET0), to understand how we build flexible components with Variants. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇◇◇◇❖ Legend Mark | Property | Values | Default | | ---------------- | ---------------------- | ------- | | **size** | small / medium / large | medium | | **priority** | main / secondary | main | | **text** | true / false | true | | **textPosition** | top / bottom / none | top | | **color** | primary / neutral | primary | | **active** | true / false | false | | **value** | text | “0” | | **tick** | true / false | true | #### ◇◇◇❖ Legend | Property | Values | Default | | ---------------- | ---------------------- | ------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **textPosition** | top / bottom / none | top | | **tick** | true / false | true | #### ◇◇❖ Slider | Property | Values | Default | | -------------- | ---------------------------------------------- | --------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **state** | default / hover / focused / pressed / disabled | default | | **two handle** | true / false | false | | **tick** | true / false | false | | **hasTitle** | true / false | true | | **title** | text | “label” | | **hasCaption** | true / false | true | | **caption** | text | “caption” | | **showValue** | true / false | true | | **value** | text | “value” | #### ◇❖ Sub-component: Range Slider | Property | Values | Default | | ------------------ | ---------------------------------------------------------- | ------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **legendPosition** | top / bottom / none | bottom | | **start** | 0% / 10% / 20% / 30% / 40% / 50% / 60% / 70% / 80% / 90% | 10% | | **length** | 10% / 20% / 30% / 40% / 50% / 60% / 70% / 80% / 90% / 100% | 60% | #### ◇❖ Sub-component: One Handle Slider | Property | Values | Default | | ------------------ | --------------------------------------------------------------- | ------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **legendPosition** | top / bottom / none | bottom | | **start** | center / left | left | | **length** | 0% / 10% / 20% / 30% / 40% / 50% / 60% / 70% / 80% / 90% / 100% | 40% | | **direction** | left / right / none | right | ## Behaviour ### One & two handles The slider can be used with one or two handles. Thus, it can be used to select a value by dragging a handle along the axis or to define a range with the two-handled one. ### Sizes Sliders are available in three sizes to cater for the diverse range of use cases and devices that our business uses. ### State By default, the slider is in Default state. The Hover state provides tooltips to display the value selected thanks to the handle. ### Steps The component has a wide variety of positions. By choosing a start and end value you can adapt it to most situations. The slider offers three behaviors: - start at left, at zero, to the right for a linear selection - start at the center, to the right or left for a positive or negative selection (for example.) - a range for more flexibility in the choice of values ### Colour By default, sliders are emphasized (primary theme). Providing a visual prominence. For visual components, like application panels, where colour shouldn't be a standout element, choose the neutral theme to de-emphasize its focus on the screen. ## Usage Guidelines ### Use slider for imprecise or pre-determined ranges - **Don’t**: use slider for large (e.g. 1-1000) or small (e.g. 1-3) ranges - **Do**: use slider for medium range ### Use slider without tick for imprecise range - **Don’t**: use tick when the steps looks approximative - **Do**: use slider without tick and give contextual labels ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284113&t=kOWgyuqnVCEtliGV-4) # Text Area ## Overview A text area lets a user input a longer amount of text than a standard text field. It can include all of the standard validation options supported by the text field component. ### Usage When to use: - Use the text area if you want users to enter multiple lines of text. When not to use: - Users need to enter a single line of text. For this we recommend using the text input instead. ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ Component: Text Area | Property | Values | Default | | --------------- | ----------------------------------- | ------------- | | **size** | small / medium / large | medium | | **state** | default / hover / active / filled | default | | **severity** | default / success / warning / error | default | | **disabled** | false / true | false | | **hasLabel** | boolean | true | | **label** | text | “Label” | | **required** | boolean | true | | **charCounter** | boolean | true | | **placeholder** | text | “Placeholder” | | **hasCaption** | boolean | true | | **caption** | text | “Caption” | | **resize** | boolean | true | | **scrollable** | boolean | true | | **successIcon** | instance swap | check_circle | | **warningIcon** | instance swap | warning | | **errorIcon** | instance swap | error | ## Behaviour ### Minimum height Text areas are ideal for long sentences or paragraphs, and should comfortably accommodate large amounts of text. They should have a minimum height of 80px (medium) or 64px (small) on a desktop and 96px (large) on mobile (when the height of the text area is a defined number). ### Overflow When typing into a text area and reaching the end of the field on a fixed-height text area, the cursor should continue to follow the text as the user types, while the rest of the text above overflows through the top of the field. Note: in Figma to reflect the active typing behaviour, you can change the text alignment to **align bottom** as opposed to align top. When the field loses focus, text should overflow through the bottom of the text area, showing the beginning of the text. ### Caption text overflow When the caption text is too long for the available horizontal space, it wraps to form another line. ### Character count Text areas can display a character count indicator when the length of the text entry needs to be kept under a predefined value. Character count indicators can be used in conjunction with other indicators (e.g., validation icon, “optional” or “required” indicators) when necessary. We have intentionally left this specific error state out of our design, as it can be reflected in many ways and this component is flexible enough to customise it how you need it. ### Drag icon Text areas can either be a fixed size or can be resizable with a drag icon in the bottom right corner. The drag icon should be hidden if the fixed variant is turned on, or if the text area should not be resizable. ### Caption text (description or error message) A text area can have caption text below the field to give extra context or instruction about what a user should input in the field. The caption text area has two options: a description and an error message. The description communicates a hint or helpful information, such as specific requirements for correctly filling out the field. The error message communicates an error for when the field requirements aren’t met, prompting a user to adjust what they had originally input. ## Usage Guidelines ### Use captions instead of placeholder text - **Don’t**: put important instructions as placeholder text, otherwise that text will no longer be viewable when the user begins typing. - **Do**: use the caption text to convey requirements or to show any formatting examples that would help user comprehension. ### Switch caption text with error text - **Don’t**: use the same caption text when presenting an error. Use the error text as an opportunity to help the user understand why something is incorrect. - **Do**: replace the caption text with error text. Then once the error is resolved, the help text description reappears below the text area. ### Write error text that shows a solution - **Don’t**: state an error and then leave the user guessing why their value is incorrect. - **Do**: use a helpful tone to convey a hint or tip to resolve the error, guiding them to understand what needs to go in the missing field. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284137&t=kOWgyuqnVCEtliGV-4) # Text Input ## Overview Text Inputs are box-shaped input fields that helps the user enter data to communicate to the machine, a system or a product. Various options exist in the Thales Design System and are presented in this documentation. ## Anatomy Elements highlighted below can be configurable by you within the component itself. To find out how to customize these elements, please refer yourself to the properties table at the end of this section. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ Component: Text Input | Property | Values | Default | | ---------------- | ----------------------------------- | ------------- | | **size** | small / medium / large | medium | | **state** | default / hover / active / filled | default | | **severity** | default / success / warning / error | default | | **disabled** | false / true | false | | **hasLabel** | boolean | true | | **label** | text | “Label” | | **required** | boolean | true | | **hasLeftIcon** | boolean | true | | **leftIcon** | instance swap | person | | **placeholder** | text | “Placeholder” | | **hasRightIcon** | boolean | true | | **rightIcon** | instance swap | expand_more | | **successIcon** | instance swap | check_circle | | **warningIcon** | instance swap | warning | | **errorIcon** | instance swap | error | | **hasCaption** | boolean | true | | **caption** | text | “Caption” | ## Behaviour ### Minimum width To ensure that small text fields are easily readable and touchable on screen devices, we recommend a **minimum width of 1.5x the height** of the button. This means 48px (small), 60px (medium) and 72px (large) ### Label usage Text inputs can be used either with a label on top of the field, or inside as a placeholder. If you use the second option, make sure your label is explicit enough for the user to understand the data they should enter. You can also use icons to help guide the user. ### Required and optional options Depending on your forms structure, you might need to present “Required” or “Optional”. We recommend using the dedicated asterisk for the labelled input, and the caption for the placeholder label option. ### Use required and optional correctly In a complete form, you will always have required and optional fields. To decrease cognitive load, **always indicate the less frequent option** and mark them. For instance, if most of the fields are optional, only mark the required with an asterisk. If most of the fields are required, only mark the few optional ones with “(optional)” in the label. ### Validation and error states To help guide the user in the completion of the form, you can use the embedded validation states. Available today are: - Success - Warning - Error The semantic text temporarily replaces the help text underneath the text input, as the language should be more specific to how to user can resolve the error. ### Icon usage The icon placeholders can help the user understand the expected input even more. You should use left **OR** right icons to illustrate the label/placeholder. Using both icons is a unique use case and is only reserved for the following use cases: - Validation - Dropdown arrow button ## Usage Guidelines ### Choose the best type in your context - **Don’t**: mix top label and placeholder label in the same form. - **Do**: make the one choice that fit the most your product. ### Keep labels short and precise - **Don’t**: describe too much within the label. - **Do**: stay clear, precise and explicit. ### Adapt length and related groups relatively to the data - **Don’t**: employ same length for very different data input sizes. - **Do**: adapt and create related groups of data inputs. ### Use sentence case for everything - **Don’t**: Mix or use different types of cases than sentence case, exception is made for acronyms. - **Do**: use sentence case for everything. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284129&t=kOWgyuqnVCEtliGV-4) # Toggle Switch ## Overview Toggle Switch are On/Off switches. They are meant to ask the user to choose between two mutually opposed options, and always have a default value, whether it’s off or on. Toggles, and in that case switches, always have a direct impact and provide immediate results. ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ Component: Toggle switch | Property | Values | Default | | ----------------- | --------------------------- | ------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **state** | default / pressed / focused | default | | **checked** | false / true | false | | **disabled** | false / true | false | | **labelPosition** | left / right | right | | **hasLabel** | boolean | true | | **labelOn** | text | “Label” | | **labelOff** | text | “Label” | | **displayIcon** | boolean | true | | **iconOff** | instance swap | check | | **iconOn** | instance swap | check | ## Behaviour ### Sizes Switches are available in three sizes to cater for the diverse range of use cases and devices that our business uses. By default, the medium switch is used typically for desktop/tablet devices. But for mobile devices, it is possible that you need to upscale the switch, to increase the touch area. For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html). ### Switch activation The “activated” parameter allows you to easily switch from off to on and the other way around with a simple press of a button. ### Label For flexibility purposes, you can choose to integrate a switch without label. Therefore, the toggle labels should describe what the control will do when the switch is on and a toggle should always indicate to the user the impact. ### Emphasis By default, switches are emphasized (primary theme). Providing a visual prominence that is optimal for forms, settings, lists or grids of assets, and other situations where a switch is required. For visual components, like application panels, where a checkbox shouldn't be a standout element, choose the neutral theme to de-emphasize its visual presence on the screen. ### Resizing to fit Sometimes, you will need to change the base auto-layout model from “Packed” to “Space between” in order to make your component horizontally fit its container. You can change this setting directly at the top level of the component in the auto-layout panel ### Text overflow When the label is too long for the horizontal space available, it can be wrapped to form another line. Use the following steps in order to configure the TDS component to do this: 1. Set ‘**Switch label**’ text layer to fill container (horizontally). 2. Resize the main component to the right width. ## Usage Guidelines ### Deliver immediate results - **Don’t**: ask the user to save the changes or apply changes when switching a toggle. - **Do**: deliver immediate effect on your interfaces. ### Use concise and clear labels - **Don’t**: write labels like “Do you want to see the next flights?” - **Do**: write “Show next flights” instead ### Choosing a switch over a checkbox - **Don’t**: use a checkbox to ask the user to choose between two exclusive and mutually opposed options, implying an on/off state. - **Do**: use a toggle switch instead ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284121&t=kOWgyuqnVCEtliGV-4) # Breadcrumb ## Overview A breadcrumb, or breadcrumb trail is a graphical control element frequently used as a navigational aid in user interfaces and on web pages. It allows users to keep track and maintain awareness of their locations within programs, documents, or websites. The term is a reference to the trail of bread crumbs left by Hansel and Gretel in the German fairy tale of the same name. (Wikipedia) ### Sources and references - [Breadcrumbs: 11 Design Guidelines for Desktop and Mobile](https://www.nngroup.com/articles/breadcrumbs/) - Nielsen Norman Group - [When You Should Use a Breadcrumb Navigation](https://uxmovement.com/navigation/when-you-should-use-a-breadcrumb-navigation/) - UX Movement ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇❖ Component: Breadcrumbs | Property | Values | Default | | ---------------- | ---------------------- | ------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **\*itemNumber** | 2 to 5 and more | 3 | | **separator** | > / / | > | #### ❖ Sub-component: Breadcrumb item | Property | Values | Default | | ------------- | ----------------------------------- | ---------- | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **\*state** | default / focused / hover / pressed | default | | **active** | false / true | false | | **\*hasIcon** | boolean | true | | **icon** | swap instance | home | | **label** | text | Breadcrumb | ## Behaviour ### Sizes Breadcrumbs are available in three sizes to cater for the diverse range of use cases and devices that our business uses. By default, the medium breadcrumbs are used typically for desktop/tablet devices. But for mobile devices, it is advised that you upscale the component, to increase the touch area. For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html). ### Colour emphasis By default, breadcrumbs are not emphasized (primary theme). Providing a visual prominence that is optimal for a navigation system. The neutral theme is more appropriate when you need to de-prioritize its focus on the screen. ### Separator options The breadcrumbs have 2 options of separators which are “/” and “>”. Prefer using the chevron as your separator because of the visual representation that indicates movement, and emphasize more on the content’s cascading structure. ### Long breadcrumbs management When you have a long breadcrumb trail, you should consider improving readability by shrinking the breadcrumb down to 5 items. To make this happen, you can create a “…” item - already included in the “5 and more” item option - and insert the hidden items in a dropdown menu. ### Icons option By default, the home link has an included icon. You can also add icons on every label, but need to use them properly (cf. usage guidelines on this) ## Usage Guidelines ### The first item must be the home page - **Don’t**: put a first item that is not the starting point. - **Do**: display the starting point as first item to recognize hierarchy. ### The last item is where the user is, so it should not be clickable - **Don’t**: let the user click the last item (current location). This will prevent an unnecessary page refresh. - **Do**: keep it recognizable, but different from the others. ### Keep your labels short to avoid wrapping issues - **Don’t**: clutter your breadcrumbs with too long page titles. If you see your breadcrumbs have wrapping issues, this might be the chance to consider cleaning up your page names. - **Do**: keep it short and efficient. ### Icons are not page links. - **Don’t**: use icons only as links in your breadcrumbs. - **Do**: always have a label when using icons to ensure readability and understandability. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284105&t=kOWgyuqnVCEtliGV-4) # Rail ## Overview Navigation rails increase the level of product’s discoverability by letting the user know exactly where they are in the product, and taking them to where they want to go quickly and effortlessly. It is often used as a first level of navigation. ### Usage When to use: - Navigating between unrelated destinations - Your product has five or more top-level destinations (single-level) For more information about layout and when/how to choose between a Navigation rail and a Navigation drawer, please visit the dedicated section in [Foundations / Grids & Layout](/docs/foundations/grids-layout). ## Anatomy Elements highlighted below can be configurable by you within the component itself. To find out how to customize these elements, please visit the Customization page where it introduces you to the variants that define the make up of the **Navigation Rail**. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇❖ Component: Rail | Property | Values | Default | | --------------- | ---------------------- | ------- | | **size** | small / medium / large | medium | | **bottom menu** | true / false | true | #### ❖ Sub-Component: Menu Item | Property | Values | Default | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | | **size** | small / medium / large | medium | | **state** | default / hover / focused / active (ltr) / active (rtl) / active + hover (ltr) / active + hover / active + pressed (ltr) / active + pressed (rtl) / disabled | default | | **icon** | swap instance | train | | **hasLabel** | true / false | true | | **label** | text | “menu item” | #### ◇❖ Sub-Component: Menu Item List | Property | Values | Default | | ---------------- | ---------------------- | ------- | | **size** | small / medium / large | medium | | **no. of items** | 1 to 8 | 5 | ## Behaviour ### Icon and label You can use the icons and labels option to ensure good reading to your end user. Labels will help the end user contextualize the icon. When writing labels, always consider the length of your word. If the word is too long the end should be truncated with “…” ### Icon only Even if it’s not recommended to use this pattern, you can use an icon only rail. If you choose to do so, make sure to use icons that indicate explicitly the feature behind, and make sure you have the right alternative text for browser readers. ## Usage Guidelines ### Navigation items - **Don’t**: include navigation item names that are irrelevant or may seem redundant alongside other items - **Do**: make information easier to find with navigation items names that are meaningful, concise and consistent. ### Sentence case - **Don’t**: use anything else, unless bespoke design decisions warrant a change. - **Do**: use sentence case for menu items. ### Icon and labels usage - **Don’t**: alternate the usage of icon and text-only menu items in the same sections. Try to choose one consistent pattern for your navigation zones. - **Do**: use icon and labeled items in a consistent fashion to keep a clear hierarchy. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284081&t=kOWgyuqnVCEtliGV-4) # Search ## Overview Search is a text input field specifically designed to help users browse and navigate around a platform. ### Sources and references - [Best practices for search](https://www.uxbooth.com/articles/best-practices-for-search/) - UX Booth - [Search](https://m2.material.io/design/navigation/search.html) - Material Design - [ARIA Search Landmarks](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/search.html) - W3C - [Search Fields](https://developer.apple.com/design/human-interface-guidelines/search-fields) - Apple - [Best Practices for Search Results](https://uxplanet.org/best-practices-for-search-results-1bbed9d7a311) - UX Planet ## Anatomy Elements highlighted below can be configurable by you within the component itself. To find out how to customize these elements, please refer yourself to the properties table at the end of this section. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇◇◇❖ Component: Search | Property | Values | Default | | --------------- | -------------------------------------------- | ------- | | **size** | small / medium / large | medium | | **state** | default / hover / filled / active / disabled | default | | **leftIcon** | true / false | false | | **showResults** | true / false | false | | **button** | none / iconButton / button | none | #### Composition Note: this component is composed of other TDS elements ([Dropdown Menu](/docs/components/dropdown-menu), [Text Input](/docs/components/text-input) & [Button](/docs/components/button) and therefore we recommend you refer to the documentation of those components to ensure that you use the component in the most appropriate way. ##### ❖ Sub-component: Text input ##### ❖ Sub-component: Dropdown menu ##### ❖ Sub-component: Buttons ## Behaviour ### Manual search Manual search is triggered explicitly after the user enters text in the search field and clicks the Search button or presses the Enter key. ### Live search Also known as “incremental search” or “search-as-you-type”, the live searching capability is triggered by each character that is entered/deleted by the user. ### Persistent search Use persistent search when it is a primary focal point for your application. The persistent search is always available to users and typically used as a global search. ### Expandable search Use expandable search when search is not the primary focus of your app. Expandable search displays a search icon in the toolbar, instead of an open search text box. ## Usage Guidelines ### Use effective autosuggest - **Don’t**: mix all the results visually to avoid confusion from the users. - **Do**: help users speed up the search process by keeping them on-task toward conversion. ### Don’t include a label - **Don’t**: mix top label and placeholder label in the same form. - **Do**: make the one choice that fit the most your product. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284065&t=kOWgyuqnVCEtliGV-4) # Stepper ## Overview A stepper keeps users informed about their progress in a multi-step process by indicating what step they are on, what has been done and what is waiting to be completed. ### Usage When to use: - Users need to accomplish a larger goal through manageable steps that would otherwise be overwhelming to do it in one go. - Users need to go through a sequence of logical and numbered steps with smaller goals. - Users need to track the progress of a process (e.g. delivery, service, …). When not to use: - Users need to be informed of their current location during navigation, consider using [breadcrumbs](/docs/components/breadcrumb) instead. ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇❖ Component: Stepper | Property | Values | Default | | ----------------------------- | ---------------------- | ---------- | | **size** | small / medium / large | medium | | **direction** | horizontal / vertical | horizontal | | **steps** | 3 / 4 / 5 / 6 | 3 | | **style** | number / icon / dot | number | | **caption** | true / false | true | | **textPosition (horizontal)** | right / bottom | right | | **content (vertical)** | true / false | false | #### ❖ Sub-Component: Step horizontal | Property | Values | Default | | ---------------- | ---------------------------------------------- | --------- | | **size** | small / medium / large | medium | | **status** | waiting / current / done / error | waiting | | **state** | default / hover / focused / pressed / disabled | default | | **style** | number / icon / dot | number | | **textPosition** | bottom / right | right | | **label** | text | “step” | | **showCaption** | true / false | true | | **caption** | text | “caption” | | **track** | true / false | true | #### ❖ Sub-Component: Step vertical | Property | Values | Default | | --------------- | ---------------------------------------------- | --------- | | **size** | small / medium / large | medium | | **status** | waiting / current / done / error | waiting | | **state** | default / hover / focused / pressed / disabled | default | | **style** | number / icon / dot | number | | **label** | text | “step” | | **showCaption** | true / false | true | | **caption** | text | “caption” | | **content** | true / false | true | | **track** | true / false | true | ## Behaviour ### Direction Steppers are available in two different directions depending of the space of the screen and the user’s needs. For smaller devices, horizontal steppers can be implemented with a horizontal scroll. Or vertical steppers can be used with minimal adjustments required. ### Sizes Steppers are available in three sizes to cater for the diverse range of use cases and devices that our business uses. By default, the medium stepper is used typically for desktop/tablet devices. But for mobile devices, it is advised that you upscale the stepper, to increase the touch area. For more information about target size, check out [W3’s website](https://www.w3.org/WAI/WCAG21/Understanding/target-size.html). ### Status To keep the user engaged in different tasks, step status give an indication of where in the process they are, what has been done, and what are the next steps. **Waiting**: This shows an upcoming step that isn’t completed yet by the user. **Current**: This shows the step that the user is currently on. **Done**: This shows a step the user has already completed. **Error**: This shows a step the user has not finished ### Step styles Depending of the goal of the stepper, different styles can be used : **Number**: Indicating the step number, making it easier for the user to keep of where they are in a process. This is recommended when used to display a fixed linear process that requires information from the previous step. **Icon**: Icons can be used to enhance the step’s goal, in addition to the label and the caption. This is recommended for use when the linear process can be navigated back and forth with no fixed direction. **Dot**: A dot can be used to simplify the stepper for narrower screens, such as mobiles or a complex desktop design. ### Linear stepper Linear steppers require users to complete tasks step-by-step in order to move to the next one. Users can only navigate forward, or backward to the adjacent steps. ### Non-linear stepper Non-linear steppers allow users to complete any step in a random order. Users can also navigate to another non-adjacent step. ### Horizontal - Text position Depending of the density of your screen, text position can be placed either at the left or the bottom of the indicator. For processes with many steps and a narrow screen, bottom text helps improving readability across steps. ### Vertical - Adding content When using a horizontal stepper, content associated to the step can be added. To swap the default content with your own, follow these simple steps: 1. Create your composition in a frame and apply Auto layout to it. 2. Create a local component with this frame. 3. Drag-and-drop the local component from your assets panel while pressing CMD+OPT (CTRL+ALT for Windows) to swap the default content. 4. Make sure you apply the correct resizing constraints for the content area so that it hugs the next contents in the stepper. ### Vertical - Make the stepper fluid By default, the vertical stepper has a fixed height with all steps set to “Hug contents”. In order to make the vertical stepper fluid, non-current steps excepting the last one can be set to “Fill container”. ## Usage Guidelines ### Keep step labels short and concise - **Don’t**: Use long names for steps - **Do**: Use labels that clearly indicate the purpose of the step. You can also use the labels to enumerate the step, and use the caption as step label. ### Consistent use of nouns or verbs throughout all steps - **Don’t**: Mix nouns and verbs - **Do**: Use the same naming type through all steps ### Avoid using multiple steppers on one page - **Don’t**: Use multiple steppers on one page. - **Do**: Organize content by theme within one step to avoid decision fatigue. ### Use between 3 and 6 steps - **Don’t**: Use the stepper for processes with fewer than 3 or more than 6 steps. - **Do**: Simplify the process by organizing your content by theme or breaking up into multiple tasks. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=16676-485553&t=kOWgyuqnVCEtliGV-4) # Tabs ## Overview Tabs organize content into multiple sections and allow users to navigate between them. The content under tabs should be contextual to the page it sits within. When to use tabs: - Locally navigate between content at the same level of your navigation hierarchy. - To alternate between views within the same context. Want to learn more? [Jakob Nielsen describes how to use tabs - the right way](https://www.nngroup.com/articles/tabs-used-right/). ## Anatomy Elements highlighted below can be configurable by you within the component itself. To find out how to customize these elements, please visit the Customization page where it introduces you to the variants that define the make up of the **Tabs**. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇❖ Component: Tabs | Property | Values | Default | | ------------------ | ------------------------------------ | ---------- | | **size** | small / medium | medium | | **items** | 2 to 8 | 8 | | **fluid** | false / true | false | | **fullHeight** | false / true | false | | **\*iconOnly** | false / true | false | | **\*iconPosition** | none / left / right / top / iconOnly | none | | **tabDirection** | horizontal / vertical | horizontal | | **divider** | false / true | true | #### Component: Tab Item #### ❖ Sub-component: Tab Item | Property | Values | Default | | ------------------ | ----------------------------------- | ----------- | | **size** | small / medium | medium | | **state** | default / hover / pressed / focused | default | | **active** | true / false | true | | **disabled** | true / false | true | | **\*hasLabel** | boolean | true | | **label** | text | “Item” | | **\*hasIcon** | boolean | true | | **icon** | instance swap | layers | | **\*hasLeftIcon** | boolean | true | | **\*leftIcon** | instance swap | settings | | **\*hasRightIcon** | boolean | true | | **\*rightIcon** | instance swap | expand_more | ## Behaviour ### Sizes Tabs exist with 2 different sizes, small and medium. ### States A tab has several interactive states - Default, Hover, Focused, Pressed, Active, Active & Hover, Disabled. ### Icons Icons can be used in tab items, but should only be used when it is absolutely necessary. Icons should not be used just as decoration. If the tab item does not have a visible label, it must still have a **tooltip** to disclose the label. Icons in tabs can make information easier to find and scan. We recommend to place the icon **on the left** of the label so users can see it first. Putting the icon to the right of the label won’t help the users scan the button. However, right icon can be set for right-to-left reading usages. ### Divider By default, tabs have a divider that spans across all tab items. This style works as a way to anchor them to the page. These types of tabs are best used at the top of a page, as a top-level navigation. Alternatively, tabs can be used without a divider. These should be used as sub-level navigation or for containers. ### Fixed tabs #### Fluid fixed tabs (Container based) Fixed tabs have equal width, which can be calculated either as: - The width of the screen divided by the number of tabs - The width of the widest tab label When using fixed tabs, ensure they can all be seen on mobile, without truncating their text. Don’t use more than four fixed tabs at once. #### Clustered fixed tabs (Content based) Clustered fixed tabs aren’t divided equally across the screen. The tabs can be centred, right-aligned, or left-aligned. Clustered fixed tabs should be used in wide horizontal layouts, such as landscape mode on tablets or desktops. ### Scrollable tabs When a set of tabs cannot fit on the screen, use scrollable tabs. Scrollable tabs can use longer text labels and a larger number of tabs. They are best used for browsing on touch interfaces. ## Usage Guidelines ### Equal level of importance - **Don’t**: use tabs for varying levels of importance. - **Do**: use tabs for organizing content of equal importance. ### Consistent icon usage - **Don’t**: mix the use of icons in tabs, as navigation controls require a clear spacial relationship to one another. - **Do**: use consistent and relevant icons for tabs to establish a clear visual balance and presence for each tab item. ### Avoid nesting of tabs - **Don’t**: nest a tab within another tab. - **Do**: use single-level tabs. ### Sentence case - **Don’t**: use anything else, unless bespoke design decisions warrant a change. - **Do**: use sentence case for tab items. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284057&t=kOWgyuqnVCEtliGV-4) # Progress Bar ## Overview A progress bar is a progress indicator, either determinate (indicating a percentage of progression) or indeterminate (indicating a state of loading). ### Usage When to use: - When managing action like download, upload, retrieval of data, … - When the system is temporarily disabled, to block the screen - When the processing takes more than a few seconds - Generally, to provide feedback to the user about progression. ### Sources and references - https://www.nngroup.com/articles/progress-indicators/ ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ Component: Progress Bar | Property | Values | Default | | ----------------- | ------------------------------------------------------------------------- | ------------------- | | **variant** | determinate / indeterminate | determinate | | **size** | small / medium / large | medium | | **color** | primary / neutral | primary | | **state** | loading / error / success | loading | | **\*animated** | false / true | true | | **animation** | none / load (determinate) / bounce (indeterminate) / loop (indeterminate) | load (determinate) | | **value** | N/A / 1% / 17% / 34% / 67% / 100% | N/A | | **\*label+value** | boolean | true | | **\*hasLabel** | boolean | true | | **\*label** | text | Downloading | | **showValue** | boolean | true | | **\*hasCaption** | boolean | true | | **\*caption** | text | Caption placeholder | ## Behaviour ### Determinate & Indeterminate The progress bar comes in two different variants: The determinate type, when progress can be calculated against a target (download, upload, know sizes, …) The indeterminate type, when there is progress but the completion cannot be determined (connection to a server, retrieving unknown amount of data, …) ### Sizes Progress bars are available in three sizes to cater for the diverse range of use cases and devices that our business uses. ### Progress Different percentage indications are available in the variants to be chosen. Percentages are 1%, 17%, 34% and 67% for the static component. ### State By default, the progress bar is in Loading state. We recommend using the Completed state to emphasize the end of the progress. We also recommend using the Error state to make it obvious when the loading is encountering some issues. ### Color By default, progress bars are emphasized (primary theme). Providing a visual prominence. For visual components, like application panels, where a checkbox shouldn't be a standout element, choose the neutral theme to de-emphasize its visual presence on the screen. ### Animation The progress bar is animated by default thanks to the Interactive Components feature on Figma. If you would like to remove this capacity, uncheck the “animate” property. All animations can be manually overwritten if you need other timings. ### Animation type The indeterminate variant comes either as a bar bouncing from left to right or as an infinite loop. You can select each one in the property menu of the component. ## Usage Guidelines ### Use percentage based progress bar for longer loading delays. - **Don’t**: use percentage based progress bar for delays between 2 and 9 seconds - **Do**: use percentage based progress bar for delays > 10 seconds ### Use loop based progress bar for shorter loading times. - **Don’t**: use loop based progress bar for delays over 10 seconds - **Do**: use loop based progress bar for delays < 10 seconds ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=12100-289548&t=kOWgyuqnVCEtliGV-4) # Progress Circle ## Overview A progress circle is a progress indicator, either determinate (indicating a percentage of progression) or indeterminate (indicating a state of loading). ### Usage When to use: - When managing action like download, upload, retrieval of data, … - When the system is temporarily disabled, to block the screen - When the processing takes more than a few seconds - Generally, to provide feedback to the user about progression. ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ Component: Progress Circle | Property | Values | Default | | ------------ | -------------------------------------------------- | ----------- | | **variant** | determinate / indeterminate | determinate | | **size** | xsmall / small / medium / large / xlarge / xxlarge | xsmall | | **color** | primary / neutral | primary | | **progress** | 0% / 50% / 100% / N/A | 0% | | **step** | step-1 / step-2 / step-3 / step-4 / N/A | N/A | | **track** | true / false | true | ## Behaviour ### Determinate & Indeterminate The progress circle comes in two different types, segregated into two main components. The determinate type, when progress can be calculated against a target (download, upload, know sizes, …) The indeterminate type, when there is progress but the completion cannot be determined (connection to a server, retrieving unknown amount of data, …) ### Sizes Progress circles are available in five sizes to cater for the diverse range of use cases and devices that our business uses. ### Background The Progress circle has a background (track) by default. You can choose to remove the background to adapt for different use cases and interfaces styles. ### Colour emphasis By default, progress circles are emphasized (primary theme). Providing a visual prominence. For visual components where you don’t want to emphasize the progress circle component, the neutral theme is more appropriate for this de-prioritize its focus on the screen. ### Progress indication The determinate variant comes in 3 main progress steps: 0%, 50% and 100%. Those steps are mainly used for animation purpose, but you can choose to use them as static. The indeterminate variant comes in 4 main progress steps: Step 1, Step 2, Step 3 & Step 4. Those steps are mainly used for animation purpose, but you can choose to use them as static. ### Progress Animation The progress circle is animated by default thanks to the Interactive Components feature on Figma. If you would like to remove this capacity, you need to deactivate it in the prototyping panel. The indeterminate variant comes as an infinite loader with a 360° rotation every second. The determinate variant moves from 0% to 50% in 3s, and from 50% to 100% in 2.5s for a total cycle of 5.5s. This can be manually overwritten if you need other timings. ## Usage Guidelines ### Use the different sizes to match the use cases - **Don’t**: try to fit large sizes in non-adapted layouts. - **Do**: adapt the size for each use case (matching contextual icon sizes, for example) ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284041&t=kOWgyuqnVCEtliGV-4) # Card ## Overview Cards are surfaces that display content and actions on a single topic. They should be easy to scan for relevant and actionable information. Elements, like text and images, should be placed on them in a way that clearly indicates hierarchy. The Card component needs strong Figma skills from designers, with the use of auto layout and layer constraints. These skills are needed to customize the create by creating your own assets to suit your needs, but default assets are already created to help you. ### Usage When to use: - To wrap linked informations into a container. - To display content and actions on a single topic inside a container. - To visually separate specific parts of content in a view using a padded background color. - To show data visualisation. - Use in groups to link similar items and to show homogeneous or heterogeneous content. When not to use: - When you need to capture user’s attention in a prominent way. - To inform the user about important changes or conditions in the interface. - When you need to have multiple primary action buttons. ### Sources - [Cards: UI-Component Definition](https://www.nngroup.com/articles/cards-component/) by Nielsen Norman Group - [Card UI Examples and Best Practices](https://www.eleken.co/blog-posts/card-ui-examples-and-best-practices-for-product-owners) by eleken - [Card UI design: fundamentals and examples](https://www.justinmind.com/ui-design/cards) by Justinmind ## Anatomy The component anatomy is used to illustrate the general make up of your component, including the spacing and positioning of elements that sit within it. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### Component: Card (Horizontal & Vertical) | Property | Values | Default | | ---------- | ------------- | ------------ | | **border** | false / true | false | | **shadow** | false / true | true | | **Slot 1** | false / true | true | | **Slot 1** | instance swap | Layout block | | **Slot 2** | false / true | true | | **Slot 2** | instance swap | Layout block | | **Slot 3** | false / true | true | | **Slot 3** | instance swap | Layout block | | **Slot 4** | false / true | true | | **Slot 4** | instance swap | Layout block | #### Sub-component: Custom Slot | Property | Values | Default | | ------------- | --------------------- | -------- | | **direction** | horizontal / vertical | vertical | ## Assets The assets are the small bricks made available to the designers to easily complete their cards. They are intended to be placed in the blue swap areas. These assets are the foundations on which designers will have to create and add their own assets in order to fit their needs perfectly. ### How to create your own asset Here is a short tutorial to allow the designer to create custom content. #### Tutorial #1 #### Tutorial #2 - Recreate a horizontal card #### Tutorial #3 - Recreate a vertical card ### Assets library Your favourite design system team has prepared a few assets for you in advance, which are available in the "Card/Assets/" folder when swapping a custom slot from the properties panel. It's your starter pack to get you rolling! #### Header #### Title with text #### Button kit #### Image and button #### Icon #### Weather ## Templates Find here some card templates to help make the complexity of the card component more understandable, via the presentation of tangible applications from a end-user perspective. ### 1. Card as contextual indicator ### 2. Card as an horizontal tile with visual ### 3. Card as a vertical tile with visual ### 4. Card as a data visualisation ## Usage Guidelines ### Be concise in the card content - **Don’t**: Overwhelm the space with excessive content - **Do**: Include essential, summarized information ### Be consistent in the content of grouped cards - **Don’t**: Group different cards that use different elements - **Do**: Use consistent elements from card to card to represent clear listing pattern ### Make cards easy to read - **Don’t**: Unaligned elements make the card hardly scannable - **Do**: Card correctly aligned make the action buttons easier to use ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=17815-446838&t=kOWgyuqnVCEtliGV-4) # Divider ## Overview Dividers help you bring rhythm and clarity to your interfaces by separating elements. Separation of elements also comes in pair with the grouping of ones, thus a powerful tool to raise your information architecture. ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ Component: Divider | Property | Values | Default | | --------------- | ---------------------- | ---------- | | **size** | small / medium / large | medium | | **orientation** | horizontal / vertical | horizontal | | **shape** | rounded / sharp | rounded | ## Behaviour ### Sizes The divider comes in three sizes to cater for the diverse range of use: - Small - Medium - Large By default, the divider comes in Medium size but should always be adapted to match the layout density of your interfaces. ### Orientation The divider can be used in two main directions: - Horizontal - to separate items on the vertical axis - Vertical - to separate items on the horizontal axis ### Shape The divider can be used in two main shapes: - Rounded - should be used when the divider is not 100% of the height/width of its container - Sharp - should be used when the divider is 100% of the height/width of its container ## Usage Guidelines ### Don’t use rounded dividers edge on edge - **Don’t**: let rounded edge touch container edges. - **Do**: use sharp variant instead. ### Overuse of dividers - **Don’t**: add too much noise by overusing dividers. - **Do**: use them sparingly to highlight your information architecture. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=11135-284049&t=kOWgyuqnVCEtliGV-4) # Tag ## Overview Tags allow users to categorize, label or organise content using keywords. ### Usage When to use: - Filter data, using the tags to show only items within that particular category. - Map content to multiple categories or statuses, helping the user to differentiate between them. - Trigger actions, such as page filters or routing. When not to use: - It is purely for decorative purposes. ## Anatomy ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ❖ Components: Tags (All colours) | Property | Values | Default | | --------------- | ----------------------------------- | ------- | | **size** | small / medium | medium | | **shape** | rounded / sharp | rounded | | **\*state** | default / hover / pressed / focused | default | | **selected** | false / true | false | | **disabled** | false / true | false | | **label** | text | Label | | **\*hasIcon** | boolean | true | | **icon** | instance swap | train | | **dismissible** | boolean | true | ## Behaviour ### Using tags for input #### Simplifying information Tags can be used in text inputs to represent a complex piece of information in a compact form, such as an entity (person, place or thing). #### Placement Tags can be placed into input components in multiple ways. They can appear: - Inline with the text input cursor in a field - In a stacked list - In a horizontally scrollable list ### Using tags for selection #### Selecting a mutually exclusive option Tags can be used to select a single tag from a set of options. They clearly delineate and display options in a compact area. They are a good alternative to [radio buttons](/docs/components/radio-button), and [dropdown menus](/docs/components/dropdown-menu). ### Using tags to filter #### Filtering content Tags can be used to filter content. They clearly delineate and display options in a compact area. They are a good alternative to [checkboxes](/docs/components/checkbox). ### Using tags as actions #### Triggering actions Tags offer actions related to primary content. They should appear dynamically and contextually in a UI and are an alternative to [buttons](/docs/components/button). ## Usage Guidelines ### Use tags as a group - **Don’t**: use tags if the intention is to use it as a single element, use a button or a link as a better alternative. - **Do**: use tags in groups, that’s what they are made for. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=3897-97874&t=kOWgyuqnVCEtliGV-4) # Data Table ## Overview
This version of Data Table is a minimal version of the original component. You can access the [Figma | Data Table full version](https://www.figma.com/design/EmGJQrpKahu20roFakczvj/-Light--Data-Table-full-version--Copy-?node-id=24-157245&t=b0GunnHXUPzWUXrM-0). The Data Table component needs strong Figma skills from designers, with the use of auto layout and layer constraints. These skills are needed to customize the component by creating your own assets according to your needs. However, default assets are already created to help you. In addition, due to the complexity of the component, some visual bugs may occur.
### Usage When to use: - If you have a lot of information to display - If you want to organize your data in a grid-like format - If you want to list a bunch of items When not to use: - If you have little enough information to display - If you are constrained with space ### Sources - [Data table](https://carbondesignsystem.com/components/data-table/usage/) by Carbon Design System - [Data table](https://m2.material.io/components/data-tables) by Material Design ## Anatomy The component anatomy is used to illustrate the general make up of your component, including the spacing and positioning of elements that sit within it. ### Properties From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework. In Figma, these are defined as properties that help define each variant. A star or asterisk symbol (*) can be used as a prefix to some Figma component properties in order to inform that the corresponding property is only used that way on the design side (Figma component libraries). [Figma | More info](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=44051-1220&t=244StnnCdoCtO9oW-0) #### ◇◇◇◇❖ Cell | Property | Values | Default | | ------------------ | ---------------------- | ------- | | **Size** | Small / Medium / Large | Medium | | **Margin density** | Small / Medium / Large | Medium | | **Sub-item** | True / False | False | | **IsVisible?** | True / False | False | #### ◇◇◇❖ Item | Property | Values | Default | | ------------------ | ------------------------------------------------------------------------ | ------- | | **Size** | Small / Medium / Large | Medium | | **Margin density** | Small / Medium / Large | Medium | | **Type** | Text / Action button / Tag / Icon button / Checkbox / Icon / Custom slot | Text | #### ◇◇❖ Item list | Property | Values | Default | | ------------------ | ------------------------------------------------------------------------ | ------- | | **Size** | Small / Medium / Large | Medium | | **Margin density** | Small / Medium / Large | Medium | | **Type** | Text / Action button / Tag / Icon button / Checkbox / Icon / Custom slot | Text | | **Header cell** | True / False | True | | **Lines** | True / False | True | #### ◇❖ Array | Property | Values | Default | | ------------------ | ---------------------------- | ------- | | **Size** | Small / Medium / Large | Medium | | **Margin density** | Small / Medium / Large | Medium | | **Style** | Lines / Grid / Zebras / Flat | Lines | #### ❖ Data table | Property | Values | Default | | ---------------- | ---------------------- | ------- | | **Size** | Small / Medium / Large | Medium | | **◇ Toolbar** | Nested component | -- | | **◇ Array** | Nested component | -- | | **◇ Pagination** | Nested component | -- | ## Behaviour Component behaviour helps to present the states and use cases that the component might encounter. ### Toolbar You can customize your toolbar by modifying its content: either actions, or custom content, and support information architecture with title according to your needs. In case you don't want to display this component, an option is available in the Data Table properties. ### Pagination Note: a section dedicated to pagination is available here. The proposed pagination allows you to navigate through multi-page tables quickly. You will be able to navigate between pages, or even reach dedicated pages through the dropdown to instead consult the number of items in the table. In case you don't want to display this component, an option is available in the Data Table properties. ### Size The table is available in 3 sizes: small, medium and large. This refers to the width & height of the items inside, margins and heights of the rows inside the table. The component was designed in an average size of 1076px, which corresponds to desktop-sized usage with a drawer. You can adapt the width to your visuals in order to maintain a comfortable density of information, but we recommend you avoiding table usages with too many columns when the width is too small (like a smartphone). ### Margin density The margin density makes it possible to ventilate more or less a table, according to the available space and the purpose of the table. Indeed, a table presenting a large amount of data will be more relevant with a low density. ### Styles Tables are available in four styles: lines, grid, zebras and flat to help you enhancing the data and ease the reading. ### Columns types The Data Table is delivered with several cell types such as text area, action button, checkbox, icon etc. To be as flexible as possible these cells are sorted in two categories: - **default size** columns for common data and actions: it will fill all the space available - **small** columns for icons, icon buttons or checkboxes which has a fixed width to optimize space in your data table We recommend you to customize the behavior of each column if you have specific needs. ### Sub-items Each line can have sub-items. This can be helpful to display data related to the main item without having too much items shown at the same time. ### Header cell style The Header cell is available in different styles to support Data table emphasis. By default, Data tables are emphasized (primary color). Providing a visual prominence. In case you don’t want to emphasize the Data table component, Light and Neutral styles are more appropriate for visual de-prioritization on the screen. In Light variant, the background of the Header cell is transparent and adapts to the background of your surface. ### Cell types All columns can be switched with many options: - **Text cell**: the default cell with left-aligned text. You can adjust it to the data that it will contain. It is also possible to display an icon at the left or right. - **Action button & Icon button**: we recommend to use it at the end of the line to gather all the actions related to the lines. - **Tag**: it allows to highlight information such as status, contact, documents etc. - **Custom slot**: so you can add your own components. - **Checkbox**: the checkbox is by default hidden in the sub-items but you can display it if necessary. It is also visible in the Header cell for a "select all" behaviour. - **Icon**: as for the checkbox, the icon is by default hidden in the sub-items because we recommend its use in the first column as to signify an expand/collapse of the sub-items. ### Cell visibility Each cell has a property to show or hide its contents. This can be useful for information that is not presented in all the cells of the same column. ## Usage Guidelines Usage guidelines help depict the best practices when using this component by giving examples of the do’s and don’ts. ### Adapt the width to the data - **Don’t**: truncate text if you have more space in other columns - **Do**: adapt the width of big columns to their contents ### Small screen use case - **Don’t**: make the columns unreadable for small devices - **Do**: use an horizontal scroll with a fixed column if necessary ### Be consistent with your data - **Don’t**: put several cell types in a same column - **Do**: be consistent in your column types ### Deal with multiple lines - **Don’t**: center vertically the data and display various quantities of text according to the column - **Do**: set a maximum of 2 lines of text and align lines to the top ## Tips & tricks Data table is a complex component, which is why it is important to know how to handle it. ### Structure The Data Table has a column-based architecture, which allows you to change its structure quickly without having to go through all the different layers. So when we manipulate the table, we can quickly choose the number of columns to display. Note: If you delete an item in a component instance, it will be hidden but not deleted. This can be handy if you want to hide an entire line for example. ### Resize quickly If you are in the situation where you need to enlarge certain columns, the fastest and easiest way is to change the behavior of your columns. Select the column to enlarge and check that it is in "fill container", you can pass the others in "fixed width". If that's not enough, you can play with the "hug content" mode but it will depend on the content you want to display. ### Hide/Show cell’s content It is possible to make the content of a cell invisible by disabling its "IsVisible?" at the component level. This can be useful when using sub-items that do not contain all the elements of their parent, for example. ## Component Architecture [Link to Figma file](https://www.figma.com/design/zAzyG3fmBFKrdrVzFeEYAv/Quantum---2.-%F0%9F%8C%9E-Light-Components?node-id=21500-446142&t=kOWgyuqnVCEtliGV-4) # Data Visualisations Kit of resources to build charts in the Quantum Design System. ## Overview Welcome to the Quantum Dataviz Resources Kit. This file includes different assets to help you building data visualisations in the context of Quantum. The kit is based on a custom definition fo colors to match Thales visual identity and a well-established open source library data visualisation library, [Apache ECharts](https://echarts.apache.org/), for accelerating implementation. ## About Apache ECharts The Dataviz Resources Kit is relying on the well-established Apache ECharts open source library. This library is not a requirement but is highly recommended to accelerate your way to build charts in Figma but also in development. This library has been chosen for its large range of charts, its technical reliability as well as its theming capacity. **For your information, the Quantum Core Team is currently building an Apache ECharts theme to make it easier to go from Figma to Code.** The following tutorials explain how to make use of it to build charts in Figma. If your technical team has made the choice to use a different data visualisation library, that’s fine! You can still rely on this resources kit alone or grab your charts from another library to then apply the Quantum styles stored in this library. As a designer, it is highly recommended to know which data visualisation library will be used by your technical team and collaborate with the developers in charge to smooth the design-to-dev process. ## What’s inside - **Documentation**: Information about how the Dataviz resources kit is structured as well as guidelines and tutorials explaining how to make the most of it. - **Color Styles**: A collection of chart examples showcasing what you can build with the available resources and that you can directly copy/past in your projects. - **Charts Library**: A set of dedicated Figma Styles, published as a Figma Library, to cover all the styling needs to build data visualisations in your projects. - **Utility Components (not production ready)**: Lightweight building blocks used internally to assemble the Charts Library. There are not production-ready but you can use them as a starting point in your project. - **Quantum Apache ECharts Theme (alpha)**: A dedicated theme for the Apache ECharts web library in alpha version to ease the implementation of Quantum charts in code (see [GitLab repository](https://gitlab.thalesdigital.io/thales-design-system/theming/quantum-apache-echarts-theme)). ## Disclaimers - **Dataviz color is a complex discipline**: Making data visualisation intelligible and accessible is a craft in itself. This resources kit does not aim at providing all the keys to do this job perfectly out of the box so make sure to carefully consider your design decisions. - **Available colors are a starting point**: Chart types, data density, and rendering contexts can vary widely. Adapt the palette for your project’s needs. If a styles combination does not work as intended, modify it and document your changes. - **We’re here to help**: If the provided set does not cover your use case, or if a styles behaves unexpectedly, please get in touch with the Core Team. The system evolves through real-world usage. ## Other resources - **[Data visualisations Documentation](https://polaris-react.shopify.com/design/data-visualizations)**: by Polaris (Shopify Design System): Practical guidelines on chart types, color, labelling, and accessibility. - **[Apache ECharts Aria Best Practices](https://echarts.apache.org/handbook/en/best-practices/aria)** by Apache ECharts: ARIA labels and decal patterns in ECharts, for screen readers and color blind users. - **[Visually Accessible Data Visualisation](https://medium.com/plaid-design/visually-accessible-data-visualization-ff884121479b)** by Derek Torsani: A case study on high contrast dataviz using shapes, patterns, and fills. - **[Data visualisation Guide](https://data.europa.eu/apps/data-visualisation-guide/)** by data.europa.eu: A Comprehensive Guide to Unlocking Your Data’s Potential. ## Color Styles A specific set of Styles to manage data visualisation in the Quantum Design System. ### Palettes This file includes specific Figma Color Styles, published as a Figma Library, to create charts with the design system. Those Styles are defined around a semantic language clarifying their use and intent specifically in the context of data visualisation. They are broken down into two main groups: 1. **Role** Used for distinct data series themes: 1. **Brand**: based on Quantum blue color for high visual impact and low data complexity data visualisations. 2. **Functional**: based on Quantum red and green color to highlight positive and negative data points, trends, … 3. **Extended**: a broader set of up to eight colors for large data sets of highly contrasted data distinction. Each Role group covers design decisions for background, text and border visual attributes. 2. **Structural** Used for elements part of the charts anatomy. 1. **Axis**: Colors to style the x/y axis and horizontal/vertical grid lines. 2. **Area**: Colors to style the underneath surfaces of the chart like tracks and filling zones. 3. **Pointer**: Color to style elements that pinpoint specific data points on a chart. ### Modes Each palette is provided in Light and Dark mode and are separated into two specific groups of Styles: 1. **dataviz-light**: colors for designing in light mode 2. **dataviz-dark**: colors for designing in dark mode Even if this library brings semantic colors, the file does not support Variable mode in order to match the state of the current major version of the design system (Version 1) where the Light and Dark component libraries ar still two separated files wired on Figma Styles. This means that there is no automatic switch between Light and Dark mode via the native feature of Figma. Designing in Light and Dark modes mean adapting the Styles applied to your chart compositions manually. Color styles are not simple inversions, as contrast and luminance are tuned per mode to preserve series legibility to meet accessibility standards. ## Usage Guidelines ### Do not mix palettes Brand, functional, and extended subsets are designed to operate independently. - **Don’t**: Combine the brand palette with other palettes within the same dashboard. - **Do**: Combine functional and extended palettes; use brand palette alone. ### Use colors in the right order Colors are sequenced to ensure each pairs with the first have sufficient contrast and hue distance. Skipping or reordering breaks that guarantee. - **Don’t**: Reorder colors or apply them out of sequence. - **Do**: Apply colors in the order defined by the palette. ### Pair the first two colors When a chart needs only two colors, use data-1 and data-2. They sit at the right contrast and hue distance. A pairing further down the sequence can still work when it serves the brand. - **Don’t**: Pick two colors from further down the sequence. - **Do**: Use data-1 and data-2 to represent two sets of data across a dashboard. ### Keep series count low, keep charts readable The system supports up to eight data series, but readability degrades quickly beyond five or six. If your chart needs more, consider splitting it into smaller views or consolidated categories. - **Don’t**: Exceed 8 series. Some chart types can't handle it. Always aim for fewer. - **Do**: Aim for 5 or 6. Group or split your data first. ### Use the secondary styles to fill large areas, at 60% opacity Reserve primary styles for key elements. Use secondary to fill large areas like backgrounds or chart regions. - **Don’t**: Fill large zones with primary styles. - **Do**: Use secondary styles at 60% opacity for area charts and broad surfaces. ### Use neutrals for structure, not for data Neutral tones indicate structure or absence of value. They should never represent actual data series. - **Don’t**: Use neutral colors to encode data values. - **Do**: Use neutrals to highlight muted states (top) or to render background tracks (bottom). ### What is the area role for, and how do you use it? Area fills the surface that carries a data series, bars, segments, rings, shaded regions, so each value stays visible and distinct from the rest. - **Don’t**: Assign a raw palette value (grey 50, 500, 650) where an area role token belongs. - **Do**: Use the area role tokens (role/area/bg, role/area/border) instead. ### One color per data series Assign a single, consistent color to each series across all charts and views. - **Don’t**: Change the color of a series between charts. - **Do**: Use one color per series, and keep it consistent throughout the interface. ### Apply space between adjacent colors When using colors outside the Quantum palettes, adjacent contrast can drop even if each passes against the background. Add space between data elements to stay distinguishable. - **Don’t**: Let adjacent chart colors touch when they come from non Quantum palettes. - **Do**: Insert a visual separator between bars, segments, or stacks to restore separation. ### Ensure accessible visual distinctions Color alone isn’t enough for all users. When necessary, supplement color with patterns, textures, or labels. - **Don’t**: Rely solely on color to distinguish between data series. - **Do**: Combine color with patterns, or labels to ensure readability for everyone. Check our tutorials to learn how to [Figma | Apply a pattern to a chart segment](https://www.figma.com/design/uuMFPFKTMDx4mV1wE2zi7T/Quantum---5.1-Data-Visualisation?node-id=9035-49109&t=CL9drtqtFTz6cwnR-4). ### Do not mix border and stroke (brand only) Borders complement filled shapes with lighter contrast. Strokes carry data alone and need stronger contrast. Do not swap them. - **Don’t**: Apply **border/primary** to lines and **border/stroke** to shapes. - **Do**: Apply **border/stroke** to lines and **border/primary** to shapes. ### Use contrasted border for scatter view Scatter points overlap and sit close in hue, so the border has to hold the edge on its own. Use this pairing to pick the right token instead of guessing from the name. - **Don’t**: Use border/primary. It blends into the fill on dense points. - **Do**: Use border/contrasted. It holds against the surface, so points stay separated. ## Tutorials [Step-by-step guides for importing and customising charts in Figma using the Quantum Design System.](https://www.figma.com/design/uuMFPFKTMDx4mV1wE2zi7T/Quantum---5.1-Data-Visualisation?node-id=9035-44743&t=CL9drtqtFTz6cwnR-4) # Navigation ## Product architecture ### Overview People tend to be unaware of an product’s navigation until it fails to meet their expectations. Your job, as a designer, is to design your navigation in a way that supports the structure and purpose of your product without calling attention to itself. Navigation should feel natural and familiar, and shouldn’t dominate the interface or draw focus away from content. Based on your platforms information architecture (IA), a user can move in one of three navigational directions. #### Hierarchical Navigation Also referred to as **‘forward navigation’** and **‘reverse navigation’**, this navigation pattern refers to the moving between destinations at consecutive levels of your information architecture. For example, users may want to move through your platform to in order to complete a task, however they would also like to move back up the IA to get back home. Hierarchical navigation can be implemented using: - Content containers such as cards, lists, or image lists - Buttons that advance to another screen or return to previous - In-platform search on one or more screens - Links within content #### Flat Navigation Also referred to as **‘lateral navigation’**, this navigation pattern refers to movement between screens at the same level of hierarchy. It enables access to different destinations and features, at the same contextual level. Flat navigation can be implemented using: - Navigation drawer - Navigation rail - Tabs #### Experience-Driven Navigation This navigation pattern allows users to move freely through content, or the content itself defines the navigation. Legislative workflows, games, and other immersive apps generally use this navigation style. Experience-driven navigation can be implemented using: - Content containers such as cards, lists, or image lists - Buttons that advance to another screen or return to previous - In-platform search on one or more screens - Links within content | Component | Used for | # destinations | Devices | | ----------------- | ---------------------- | -------------- | ----------------------- | | Navigation drawer | Top-level destinations | 5+ | Mobile, Tablet, Desktop | | Navigation rail | Top-level destinations | 5+ | Mobile, Tablet, Desktop | | Tabs | Any level of hierarchy | 2+ | Mobile, Tablet, Desktop | ## Configuration The TDS navigation components are entirely configurable so that your product is built in the most appropriate way for your users. Simpler products have the flexibility of using a header or a navigation drawer, whereas more complex products may require a combination of navigation components to accommodate the depth of their information hierarchy. Want to learn more? Visit our [Top tips](#top-tips) area to find out more about composing effective information and visual hierarchies. ### Header only The Header component can be used as a standalone navigation for your product through the use of tabs. An example of header-only navigation ### Header with Navigation Drawer/Rail The Navigation Drawer or Rail allows for more navigational items to stack vertically and an additional level of hierarchy when paired with the header navigation. In this instance, the **header remains the highest level of navigation**. Therefore, it is important to place any product-level navigation/actions within the header and any subsequent pages of navigation underneath these in the drawer/rail. An example of a header with a navigation drawer ### Navigation Drawer/Rail only The Navigation Drawer/Rail can be used as a standalone navigation for your product. However, please ensure that if you are only using a drawer/rail, that the component has the header turned on. This is to keep the product identifiable to customers with the Thales branding. An example of a navigation rail only ## Responsiveness When designing your layout system, you may want to include some form of navigation to help your users better orientate themselves within your product. This page aims to promote best practices and the TDS standard for implementing navigation components, while optimising the pre-defined [layout system](/docs/foundations/grids-layout). ### So what is the ‘Safe zone’? The TDS provides a grid system based on a **fluid** grid type, designed for complex screens and web applications as it uses 100% of the screen’s width. When implementing a navigation system, it is important to adapt your grid layout based on the size of your **“safe zone”**. Safe zones are designed to keep your user interface (UI) in-view, taking into consideration internal factors, such as components that push content like the navigation drawer, and external factors, such as the edge of a TV display or under the notch and home bar of an iPhone X. It is often referred to as the **main viewport**. **When safe zones hit a breakpoint in the grid system, it is important to consider whether the UI needs to adapt for the new layout.** To help us calculate a navigation component’s correct size, we divide the viewport into zones. The more important one is the **safe zone**. As mentioned above, it is important to always consider the safe zone as your main viewport in which you apply the grid to. ### Choosing the right grid and component Depending on the size of your safe zone, you should consider making a consistent choice between which navigation pattern to choose (rail or drawer) and also which grid to apply on your safe zone frame. | Viewport size | Recommended navigation pattern | Safe zone grid | | ------------- | ------------------------------------------------------ | ----------------- | | 1440px | persistent drawer (240px width) | xlarge | | 1366px | persistent drawer (240px width)
Collapsible drawer | @
large | | 1024px | Overlay drawer
Rail (72px width) | medium
medium | | 768px | Overlay drawer
Rail (72px width) | xsmall
xsmall | | 320px | Overlay drawer | xsmall | ### Responsive sizing using the Navigation Drawer #### XLARGE GRID 1440px - High resolution desktops and laptops #### XLARGE GRID 1366px - Standard resolution desktops and laptops - Tablets in landscape mode. #### MEDIUM GRID 1024px - Standard resolution desktops and laptops - Tablets in portrait mode. #### MEDIUM GRID 768px - Small tablets in portrait mode. For any device that force the main content to fall within the ‘xsmall’ breakpoints (0-599px), the drawer must **overlay** rather than push the main content. #### XSMALL GRID 320px - Phones in portrait mode. For any device that force the main content to fall within the ‘xsmall’ breakpoints (0-599px), the drawer must **overlay** rather than push the main content. ## Top tips The handy guide is designed to help you build an effective navigation system using the TDS Navigation Drawer component. Through careful analysis of Thales’ own products, the TDS Core Team recognises that navigation can differ from product to product. We have produced this handy guide to help you, the designer 🎨, build the most effective navigation system for your product using our pre-built navigation drawer. It is almost entirely configurable through the diverse range of variants designed with you in mind. With tips on how to structure your navigation and a guide on building your very own navigation drawer using the diverse range of variants provided, we hope that you find this guide helpful and you enjoy designing with the Thales Design System (TDS). ### 💡Tip #1: Know your Information Architecture (IA) first Abby Cover, author of [How to Make Sense of Any Mess](http://www.howtomakesenseofanymess.com), describes information architecture as **“the way that we arrange the parts of something to make it understandable”**. Its as simple as that… A well-designed, user-friendly information architecture ensures that users spend less time and effort searching for information and are successful in finding what they need. IA is an essential part of user experience (UX) design and much like navigating a supermarket or shopping mall in real-life, information architecture for digital products must do these two things: - **Help the customer find whatever it is they’re looking for** - **Tell the customer where they are** When designing your products information architecture, it is important to think of it as a **user-flow** rather than a traditional hierarchy. Some examples of navigation use these common forms of layout: - Categorize by **topic**, letting the user know what’s here by revealing the content of the product. - Categorize by **audience groups**, such as - Categorise by **tasks**, such as ### 💡Tip #2: Create effective visual hierarchies An important way to make your product easy to grasp in a hurry is to make sure that the appearance of things on the page accurately portray the relationships between the things on the page. - **The more important something is, the more prominent it is** - **Things that are related logically are related visually** - **Things are “nested” visually to show what’s part of what** # Forms & Controls ## Form Structure ### Overview To help you build consistent forms in your product, the Thales Design System is providing a set of on-the-shelf components in the “Form Elements” section. This dedicated patterns section is made to help you correctly build with those elements, avoid common mistakes and give some empirically proven good practices. We have dedicated documentation for each component to help you use them well at their component level. If you need to refer to a specific component’s documentation please check the right page. ### Prefer multi-step forms over single step forms Sometimes, you need to gather lots of data from your users. This might end up in very long forms. To **avoid strain and frustration**, you can easily create sub-forms of related contents to slice your form into a **multi-step pattern**. Doing this will increase form completion **in B2B and Business** related environments. - First impression matters, so a first small form will always be less intimidating - By asking for sensitive data (i.e financial) at the end of a multi-step form, users are more likely to finish the form (rather than losing all the previous steps). It’s a cognitive bias know as “sunk cost fallacy”) - Seeing a progress indicator help users to be more motivated to complete the form. This is, again, based on numerous proven cognitive biases such as “the endowed progress effect”. ### Provide the related progress indicator If you are doing a multi step form, you need to provide the user a way to understand where they are in the process, and also what is coming next. Depending on the situation, several progress indicators can be used such as: - Steppers - Progress bars - Progress headers/footers Always choose the progress indicator that fits the most your product, there is no right or wrong component to choose in that case, only your users can tell. ### Forms should be in one column Google’s study on the subject showed that aligning labels above fields on the top-left side reduces form completion time because of the fewer visual fixations it requires to get the information. Also, as the eye scans from top to bottom, stacking your elements vertically will be more comfortable for the user. Multiple columns can have an unexpected and unwanted effect, and strain the user. [Reference here](https://ai.googleblog.com/2014/07/simple-is-better-making-your-web-forms.html). ### Always have readability in mind As mentioned in the Typography System in the Foundations, you should always set a consistent, maximum number of characters. Long form fields tend to make things harder to read, and are visually unbalanced. You should always go with form inputs that can fit **40 to 80 characters**. ### Name your forms correctly By giving your forms a clear title, you will help the user understand the goal and value of it. For example, if you are making a form for filling a Technical Issue ticket, you could clarify by naming it “Technical issue submission form” or “Declare a technical issue”. ### Create groupings, and name them If you have several sections in your form (Personal information, billing address, payment details, …), you should always keep them in groupings. And of course, give a name to those groupings. ### Form buttons must be specific to the task The “Submit” button at the end of your form should describe exactly the action it will invoke. Never confuse the user about what is going to happen when he clicks the button. You can also refer to our dedicated documentation on button labelling. ### Create visual density in your forms The form elements and text inputs are built with some natural spacing. But because a label is related to its field below and not the field before it in the form, you will always want to put more spacing between two form items than between the label and the field. This to follow Gestalt’s Law of Proximity and Similarity. [Reference here](https://www.interaction-design.org/literature/topics/gestalt-principles). ## Form flow [Find the relative content directly into Figma](https://www.figma.com/design/z6RoOdZKVzR2Yl588C22ku/Quantum---4.-%F0%9F%93%90Patterns---Templates?node-id=2008-15904&t=2wzDbA8VSKy75m1Y-4). ## Case study [Find the relative content directly into Figma](https://www.figma.com/design/z6RoOdZKVzR2Yl588C22ku/Quantum---4.-%F0%9F%93%90Patterns---Templates?node-id=2008-15911&t=2wzDbA8VSKy75m1Y-4). # Data Tables Tables are containers for displaying information. They allow users to quickly scan, sort, compare, and take action on large amounts of data. ## Problem When reviewing table components across the Thales organisation, the Core Team recognised that the tables were inconsistent - they had a diverse range of competing UX decisions. The sizing placement of links and CTAs, filtering, sorting and pagination were all over the place. We needed to define a pattern in Quantum that could universally serve all use cases across all digital products and serve future products and features. ## Purpose In order to define the patterns that shape the Quantum Table component, it is important to establish the purpose of the component. Hence, the following statements have been agreed to describe the purpose of the table component: 1. To browse large amounts of information at once, such as assessing showing multiple items and their statuses. 2. To determine and execute actions quickly, such as deleting or moving multiple items. 3. To compare information, such as how many items are completed versus how many are in progress ## Options The Table component needs to cater for a variety of user needs across the business lines and therefore, a diverse range of options to build your table must be available. These are outlined below: ### Types #### Standard table Simple data tables are intended to define a list of values of data types that have a simple structure. #### Expandable table Expanded view enables the users to expand and collapse the row for an optimum use of the display. This means they can instantly expand to view more details and collapse when not necessary. ### Layout #### Density Data tables support three densities: - Small (S) for condensed amount of data - Medium (M) as default - Large (L) When users view and interact with large amounts of information, high density components can improve the experience. ### Table Style The style of a row can be a big factor in how easy it is for users to scan and read when looking to find data quickly. So, when designing a table element, you should also try to choose the row style that best suits the overall style of your platform. #### Horizontal lines (Dividers) Only showing horizontal lines reduces the visual noise of a full grid. This style includes plenty of white space while still helping the user keep their place while reading. This style is the most common and recommended for all data set sizes. #### Grids Including both horizontal and vertical lines provides the most separation between data points, but the excess visual noise can be distracting. This spreadsheet-style is recommended for dense, data heavy tables. #### Zebra stripes Alternating different color backgrounds for each row is another good way to help users keep their place while reading. This style is recommended for larger data sets where the alternating pattern will be clear and not cause confusion that a particular row is highlighted. #### Free forms With no horizontal or vertical dividers, this style of row is effective in reducing visual noise and can also produce a very minimalistic look. This style is appropriate for small amounts of information, where users don’t need too much assistance when following the information. ### Row Behaviour Depending on the importance of the table and the information provided in each row, it is necessary to provide varying levels of abstraction within the row of a table. #### Single row Single rows are used to present primary information. #### Expandable row The expandable row is useful for displaying secondary information about an item, without having to navigate to a new page. Not only does this maintain the abstract information of the item, but it provides an expandable/collapsible option that is triggered by a chevron icon. #### Multi expandable row Multiple expanded rows are used when there is a list of sub-items within a row item. The columns within a Multiple Expanded Row can follow different column headers than the main table. ### Utilities Table utilities are best described as the “tools” that help customise the level of information that is presented to the user. Whether that be filtering a list of items or sorting them to improve scannability. #### Total entries Displaying number of data entries is recommended to help the user consider the quantity of data they are dealing with. Especially when using search and filtering features. #### Toolbar Some data tables require advanced features like search, settings, filtering… In these specific cases, you should create a dedicated toolbar for your data table to include these capacities. #### Pagination It is often recommanded to break long tables into several pages. When doing so, make sure to include a pagination system. Users need to understand on which page they are at the moment, and be able to navigate to other pages. When doing pagination, consider giving the users the freedom to choose how many rows they want to be displayed. ## Behaviour ### Resizing The data table component should provide two types of horizontal resizing methods: Fixed or Fluid. #### Fixed #### Fluid ### Sticky header & column #### Sticky header A sticky header allows the end user to always be aware of the data type they are looking at thanks to the header. It is very helpful in a very long data table situation or when you need to create scroll zones. #### Sticky column Sticky columns are used to emphasize on a certain type of data, allowing the user to quickly create a functional or logical link with the rest of the data. Also, very helpful when the data table is very wide or you have restricted space and need to create a scroll zone. ### Table interactions #### Resizing columns To optimize readability on the end user side, and when you have a cluttered amount of columns, it might be smart to consider giving the capacity to resize the columns as they need. #### Toggle density You can include toggle buttons to let the user switch between densities (Small, medium, large) depending on their preferences. #### Filtering data Include filtering capability to allow users to apply specific parameters in order to see only filtered data. This can be applied at the table level globally in the toolbar, or filter at a specific data type level in the header. When displaying filtered data, consider displaying the number of results. ### Row interactions #### More actions Allow the user to access multiple actions on the same row with a “More actions” button. This will save a lot of space and reduce information overload. #### Hover actions Presenting additional actions when a user hovers, helps to reduce visual clutter. However, it can cause discoverability issues because the user needs to interact with the table to expose the presentation of actions. #### Row details: modal To apply modifications, updates or actions on a row, you can allow the user to click on it to scale it up in a modal view. It can also allow you to display more information about the row (i.e full truncated texts, images, …) #### Row details: side panel The side panel has the same interest as the modal but doesn’t prevent the end user from interacting with the rest of the table, whereas the modal does. #### Multi-select & bulk actions Allow the user to select multiple items and update/edit them at the same time. Once the user has selected rows, actions in the header or above the table should have a common impact on them. This helps the users save a lot of time. ### Editing data #### Single cell edition Allow your users to edit a single data cell by providing a data input field when the user clicks (or press the Enter key if focused) on the cell or on the edit button. #### Modal Allow your users to edit the data when the users open the row details in a modal view. #### Side panel Allow your users to edit the data when they open the row details in a side panel view. ## Usage Guidelines ### Readability and discoverability #### Left align textual data Textual data is always left-aligned within a table to improve scannability. Column headers follow the alignment of the data and therefore will too be left aligned. #### Right align numerical data Numerical data should generally be right-aligned for the ease of scanning and comparing. However, numerical data can be left aligned if the numbers are arbitrary identifiers, also known as “nominal numbers,” which means they can’t be compared or combined arithmetically (e.g., postcodes, IP addresses, phone numbers). Column headers follow the alignment of the data. #### Units of measure Numerical data will sometimes require units of measure to help indicate to the user what data is necessary to communicate values of that physical quantity. It is recommended that units are presented alongside the data within the cell, for clear and consistent readability. #### All data should be centred vertically By vertically centring all data, the table offers a sense of visual balance regardless of the complexity of its contents. #### Arrange columns in order of importance from left to right - **Don’t**: put secondary information on the far left, it will imply to the user that it is most important. - **Do**: present columns in a logical order for the user. #### Use imagery where appropriate - **Don’t**: simplify the table with purely textual and numeric data if there is a more accessible opportunity to present information. - **Do**: use relevant imagery to elevate your data, and create a more obvious trigger for your users. #### Avoid using too many colors - **Don’t**: overcrowd the table with numerous states and visual indicators. It will confuse users and make the information difficult at the beginning. - **Do**: minimise the use of visual signs, providing clarity on the important pieces of information. #### Truncation - **Don’t**: use inconsistent row heights to cater for text wrapping, this makes the table harder to scan. - **Do**: use truncation for consistency and scannability, while maintaining visual balance in row height. # Data Table Filtering ## Introduction These patterns cover how to approach and use filtering in the context of Data Tables. ### Useful links Find researches material and details about the [Figma contribution process](https://www.figma.com/design/7qEttRJIyhDwlN3Tih320D?node-id=99-89). ## Common guidelines ### Distinguishing filtering from sorting #### Filtering The process of **narrowing down** a larger set of data or content by applying one or more criteria or conditions, so that only items matching those criteria are displayed. It hides items that do not match chosen criteria. #### Sorting The process of **arranging data** or items in a particular sequence or order based on defined criteria such as alphabetical, numerical, or chronological order. It changes the order of the items without removing any. #### Provide visual feedback When designing filters, it is essential to provide clear and consistent visual feedback to users about the active filters and their effect on the displayed data. It is therefore important to provide a visual indication following user actions, such as update success, loading time, absence of results or possible errors. Feedback should be delivered through means appropriate to context (such as color changes, inline messages, icons, or notifications) and should be discoverable and accessible to all users. #### Allow users to adjust their search criteria Allow users to easily add or remove filters to adjust their search criteria with options to select or unselect directly or use a “clear filters” quick action. Ensure real-time updates to the data when filters are adjusted, or provide an “apply” button for more complex scenarios/eco-design rules. #### Responsive Adapt the accessibility of your filters based on the device and available screen space. Avoid using floating sheets on touchscreens and overly intrusive filters on desktops or larger screens. Additionally, you may need to adjust the number of filters displayed on the page, making the prioritization of the order in which filters are shown a crucial aspect to address. Ensure filter controls are easily tappable on touch devices, optimize loading times to enhance performance, and maintain clear visibility and usability of filter options without requiring excessive scrolling or zooming. Make sure to test the filtering workflows on the targeted devices and viewport sizes where your user will perform the tasks. #### Eco-design Eco-design minimizes environmental impact by reducing data queries. For light datasets, use dynamic loading to apply filters instantly. For heavy datasets, an “Apply filters” button helps control queries. It groups modifications, reducing excessive server requests. This improves performance, lowers the carbon footprint, and enhances user experience. As a developer, it is important to test the cost and weight of the data requests. As a designers, it is important to know those considerations upfront so you can implement the most relevant loading and data request approach and getting the right balance between UX / Cost / Eco-design. #### Accessibility Be careful to make an accessible design. Test it with real users or use tools to simulate specific situations. Research and filtering in data table can be tricky. Here is the link to the internal accessibility guidelines. ## Usage ### Filters visibility & access #### Filters in the content flow Filters are part of the main page layout. They live alongside the content, typically in a sidebar, horizontal bar, or embedded within a results table. Even when collapsible, they are considered part of the main interface structure. Characteristics: - Always or mostly visible - Minimal disruption when used - Filters inputs are directly nearby the content Examples: - Dashboard filter bars above data tables / lists - Filters within columns in a data table - Faceted navigation (e.g. Amazon desktop) #### Off-canvas but non-obtrusive filters Filters are accessible through a toggleable side panel or area that slides or fades in, but does not block the main content. Users can interact with both the filters and the results at the same time. Characteristics: - Panel can be shown or hidden - Does not hide content area — either resizes it or floats beside it - Good for progressive disclosure: keep UI clean while retaining access - Ideal for cases where filtering is useful, but not the primary task Examples: - Sliding panels - Expandable filters on desktop with a floating sheet #### Off-canvas and obtrusive filters Filters are accessed through a modal or full-screen panel that fully or partially covers the content. Users must interact with the filters and apply them before returning to see the filtered results. Characteristics: - Used when space is constrained - Filtering is a separate step in the flow - Often includes “Apply” and “Cancel” buttons - Useful when filters are complex or rarely adjusted Layout examples: - Dedicated page for filtering It is possible to **combine these 3 types of access to filters**. If you have both novice and expert users, you may need to display the most used and simplest filters within the content, and leave the advanced filters off-canvas in a collapsible panel or modal for example. #### Summary | Access | Best when | Advantages | Disadvantages | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | **Filters in the content** | - When the filters are essential to the content and often used | - Intuitive and spontaneous
- Non-intrusive | -Limited space if too many options
- Might visually overload the interface | | **Off-canvas but non-obtrusive** | - When using filters is occasional but it is important to see both the filters and the filtered view | - Easy to access
- Non-intrusive
- Saves space when hidden | - Complex layout and responsive behaviour on small screens
- Reduced screen legibility, especially if there are charts or tables | | **Off-canvas and obtrusive** | - When using filters is occasional and/or when the space is constrained
- For deep filtering on complex load of data with many dimensions | - Plenty of space for filters combination
- Reduce distraction | - May cover the main content
- Users might feel interrupted in their task | ### Live filtering vs. applying filters on submit #### Behaviour selection | Behaviour | Description | When to use it | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Live filtering** |   Results update automatically as the user selects or modifies filters, without requiring any additional action (like clicking an "Apply" button). | - Low number and not complex filters
- Real-time feedback is important
- Smaller datasets
- Great for exploratory tasks where users iterate quickly | | **Submit to apply filters** |  Filters are only applied after user confirmation, typically by pressing a button labeled “Apply,” “Done,” or “Update.” | - For deep investigations in large datasets
- For complex or multi-steps filters
- Scenarios where performance is important
- Gives more control and adjustments before committing | #### Live filtering (auto apply) Results update automatically as the user selects or modifies filters, without requiring any additional action (like clicking an "Apply" button). Be mindful of performance impact, as each user interaction with instant filters can trigger a request to the database. #### Submit to apply filters (manual filter validation) Filters are only applied after user confirmation, typically by pressing a button labeled “Apply,” “Done,” or “Update”. Place the Apply button in a consistent and accessible location to avoid risk of forgotten changes. ### Loading states When the data is being loaded, it can take a long time to be displayed, so the user needs to be told that the table is being loaded. To do this, we recommend to display an explicit loading state depending of the development resources (time, finance), UX and performance relevancy Examples: #### Skeleton loading #### Loading overlay ### No Data scenarios #### Error case If a filtering request to the database fails, users should be informed clearly. Provide an error message indicating the failure and suggest actions such as retrying the filter, reloading the table (if so, with the same or previous filters ?), or refreshing the page. Ensuring clear error handling improves usability and prevents user frustration. **How to choose between the first option and the second option?** - If it is important to keep the filters generating the error and that replacing the previous working state is okay then no data is a relevant option. - If it is important to preserve the previous working state and it is not bad to remove the error filters then the banner is a relevant option. The following examples are non-exhaustive, and are intended only to inspire your future designs. In no way they represent the only truth. ### No Results An empty state can arise when a user searches for a product or item and no results are found. This may be due to misspellings, incorrect search criteria, the application of restrictive filters, or simply because the item does not exist in the catalog. Besides informing the user that no results were found, suggest they refine their search keywords or filters and verify their spelling. - **It is necessary to clearly indicate to the user when a query does not yield any results.** - **Some tips can also be displayed, such as changing the filter or the value of the filters applied to the research.** This component can display different messages like a loading error or simply the fact that the filters applied returned no results. ## Example ### Column filtering **Purpose:** Allow users to narrow down table data by applying specific filters on one or more columns. Helps users find relevant rows quickly based on column-specific criteria. #### Usage When to use: - For data table in which the users want to cross filters the different dimensions - Enable a granular and immediate filtering without losing the sight of the data - When you need independent and non obtrusive filtering by data table (i.e. dashboard view) - When the data table is the focus of the experience (i.e. data sheets like Excel) When not to use: - If the number of columns is very high, filtering by columns could be tiring for the users - When space is limited, especially if the area is too narrow for tactile interaction Refer to the previous sections for common guidelines, how to select between live filtering and submit to apply filters, loading states and no data usages. #### Behaviour - Filter icon or component is placed in the column header - When clicking on the component it will open contextual dropdown or modal - All displayed options are values available in the column - Active filters are highlighted (e.g.: colors, active indicator, checkbox...) - Multiple filters can be applied in one column or across others columns at once - Filter options in one column are dynamically updated based on filters applied in other columns. Only the values that remain valid after applying existing filters are displayed. - An indicator is showed to the user to inform that some filter are applied (e.g. badge, coloured icon): The following examples are non-exhaustive, and are intended only to inspire your future designs. In no way they represent the only truth. # Operator Filtering ## Example ### Operator filters Filtering enables users to streamline and manage visible items within extensive data sets more effectively. By applying filters, users can efficiently locate specific information, explore available options that meet particular criteria, and make well-informed decisions when dealing with a large volume of choices. This functionality not only saves time but also enhances the accuracy and relevance of the data presented to the user. #### Input | Field | Definition | Type | Required | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------- | | **Filter** | List that is the target of the search performed by the Filter function card. | Dropdown | Yes | | **Operator** | Specific comparison to be performed on a list (see Table of Relational Operators below). | Dropdown | Yes | | **Value** | When searching within a list of objects, Value is the name of the key that holds the value you want to compare. User can type it manually or choose from the dropdown. We support multiple values in there. | Multiselect Dropdown | Yes | #### List of Operators | Operator | Use case | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **is** | Will used when user wanted to filter it by specific value. | | **is not** | Will used when user wanted to filter it to exclude the specific value. | | **contains** | When value a is an string and value b is text, tests to see if the object has a value with the specified name.  | | **does not contains** | When value a is an string and value b is text, tests to see if the object does not have a key with the specified name. | | **is empty**  | Checks to see if value a is empty, ignores value b. Definition of "empty" varies by type. Note: Only works for Text and Numbers, Dates, are viewed as empty. | # Power BI ## About Power BI & Dataviz Power BI is an interactive data visualization software product developed by Microsoft to support business intelligence. Data visualization or Dataviz encompasses data and information which are displayed through smart and abstract representations in order to reinforce user’s instant understanding, big picture, data correlation and awareness. This field is crossroads between Design, Infographics and Data Sciences and plays an important role when it comes to make data meaningful, extract values from amount of data and while also speed-up dashboard analysis. Other the past few years, Dataviz became more and more ubiquitous in the Thales digital journeys for tracking among other things KPIs (ex: manufacturing efficiency, on-time delivery, forecasting, system health and monitoring…). ## What’s in the box? The Quantum Power BI distribution provides: - Dashboard templates that you can use to build your own - Recommendation and guidelines to build clean and professional dashboards - Quantum icons pack in .png - Thales and Thales Alenia Space logos # Login Page ## Overview The login page template is a preconfigured form and page layout for applications that need authentication. The login page enables a user to access an application by entering their authentication info. ## Usage When to use: - When a user wants to access his application’s personal account. - When a user logs out voluntarily or because of inactivity, they can be redirected to the login page. ## Anatomy ### Composition break down | Required elements | | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | **Main navigation** | Simplified navigation with useful links and a language switcher. | | **Login panel title** | A title that describe the form action (login) and can also provide the application name. | | **Form** | Single or paired fields that will submit the login data. The form includes the primary action and can also suggest a helper link. | | Optional elements | | | ----------------- | --------------------------------------------------------------------------------------------------------------------------- | | **Alternatives** | Secondary action suggesting an alternative login option. This action leads to another experience/page. | | **Footer** | If relevant, the footer contains a link to the sign up experience as a tertiary action. Can also contain a disclaimer text. | ## Behaviour ### Size, spacing and position The Login panel maximum width is 464px. The Login panel is included in a container with 16px, centred. ### Error message Error message should appear in a alert component at the top of the form container. Error messages should be clear and concise. They should help users understand what went wrong and give users steps to resolve the error. Do not use error message specific to an input, prefer an error banner global to the form. ### Multi-steps It’s possible to use the login page template to build a multi-steps authentication flow. Use the same Login panel by adapting the content according to your steps. ### Marketing content If you need to add some marketing or illustrated content to the login page, please contact the Quantum Core Team. ## Usage Guidelines ### Size, spacing and position - **Don’t**: change the maximum size of width, spacing, centred position. - **Do**: keep the maximum width to 464px for the Login panel and be careful to use the correct padding in desktop and mobile ### Clear and concise content - **Don’t**: write too much text in your title or in your disclaimer. - **Do**: be clear and concise in your title and use links to dedicated pages in your disclaimer for more details. ### Error message - **Don’t**: give user error message specific to a form field. This protects valid email addresses and usernames from being exposed and helps keep your product be more secured. - **Do**: use a clear and concise error messages displayed as a global banner at the top of the form container. ### Required field are obvious - **Don’t**: use the required asterisk symbol - **Do**: leave the asterisk symbol out from the Login panel. The form is short and the experience makes it obvious that both fields are required. ### Marketing content and other branding decorations - **Don’t**: add any decoration to the template. No marketing or branding decoration usage guidelines have been documented yet but we want to think about it. - **Do**: If you have needs and suggestions regarding marketing content, please comment the section so we can discuss about it. # Introduction ## Working with AI AI is changing the way we design, build, and interact with digital products. Working with AI is where we document how AI can be used effectively, responsibly, and consistently alongside our Design System. This space brings together the tools, workflows, guidelines, and shared practices that help teams use AI as part of their day-to-day work. Working with AI is not about AI for its own sake. It is about finding practical ways to augment our workflows while keeping the Design System at the center of how we design and build, in ways that remain compatible with Thales constraints, security requirements, and working environment. ## Security notice AI tools can support design and development workflows, but they must be used within the constraints of the Thales environment. Not every AI tool can be used to process our data, assets, or work context. Teams must rely on validated tools and approved environments, and avoid external dependencies that introduce known vulnerabilities or send sensitive data outside authorized boundaries. This means: - using validated tools and approved environments for work-related activities - avoiding external dependencies that introduce known vulnerabilities - ensuring that sensitive data, source code, design files, and internal project information are not sent outside authorized environments The workflows documented in Working with AI are designed with these constraints in mind, so teams can explore AI in a way that remains secure and compliant. ## What you'll find here Working with AI will evolve as we explore new tools and ways of working. For now, it is organized around a few key areas: ### AI-operability Understand how Quantum is being structured to work effectively with AI, so components, documentation, and patterns are easier for AI tools to interpret, navigate, and use correctly. → [Learn about AI-operability](/docs/working-with-ai/overview/ai-operability/) ### LLM-ready docs Access Quantum documentation through `llms.txt` indexes, task-focused documentation bundles, and Markdown URLs designed for AI tools, agents, and automation. → [Learn about LLM-ready docs](/docs/working-with-ai/overview/llm-ready-docs/) # AI-operability This page gives an overview of the progress made toward **making Quantum more AI-operable**. In this context, AI-operable means making the Design System easier for AI assistants, coding agents, and automated workflows to understand, navigate, and apply reliably. ## AI-operability resources at a glance The tables below summarize a concise set of high-level resources and assets that matter for AI-operability. They are inspired by the kinds of capabilities highlighted in the broader Design System landscape and can be used as a framework to assess Quantum's current maturity and future priorities. ### 1. Distribution & discovery | Element | Description | Status | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | MCP server | Exposes components, tokens, icons, patterns and docs as agent tools, either local (stdio) or remote (hosted). This is the most common affordance in mature AI-operable design systems. | | | `llms.txt` | A root index of docs with one-line descriptions generated from the same source as the docs site. | | | `llms-full.txt` | A full concatenated dump generated from the same source as the docs site. | | | Sliced `llms-*.txt` variants | Context-budget slices by concern (components, styling, theming, migration) so agents load only what the task needs. | | | Markdown twins of docs pages | Every docs page is available as `.md` (URL suffix, `Accept: text/markdown` negotiation, or a "Copy for LLM" button). | | | Agent-optimized markdown | A denoised markdown layer curated specifically for LLM ingestion, with reduced chrome and explicit structure. | | | Per-section markdown bundles | Combined markdown exports for the complete documentation corpus and its major sections. | | | Agent discovery layer | `.well-known/` manifests (skills index, api-catalog, MCP server card), `Link` headers and `sitemap.md` for automatic agent discovery. | | ### 2. Agent instructions | Element | Description | Status | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | Agent skills | An installable `SKILL.md` router with reference files loaded on demand, plus task-oriented skills for building, migrating and auditing. | | | Editor rules | `.github/copilot-instructions.md`, path-scoped `.github/instructions/*.instructions.md` and `.cursor/rules/*.mdc`, used to guide agents in consumer or contributor environments. | | | `AGENTS.md` | Root and per-package instruction files for contributor agents, covering conventions, commands and the definition of done. | | | `DESIGN.md` | A portable design-context manifest covering principles, tokens and key do/don’t rules. It should be treated as a complement, not as the primary agent interface. | | | AI documentation section | A dedicated documentation section covering setup, supported tools, sample prompts, workflows and usage guidance for AI-assisted work. | | ### 3. Tooling | Element | Description | Status | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | DS CLI | A deterministic action surface for agents (`setup`, `add`, `info --json`, `lint`, `migrate`) that can also generate or install agent configuration in consumer repos. | | | Lint rules | Design-system-specific lint rules that help enforce token usage, ban deprecated APIs and catch unsupported overrides, ideally with autofix support. | | | Codemods | Automated migration scripts between Design System versions, with agent-friendly output and predictable execution. | | | Registry / examples corpus | Addressable, validated code snippets, patterns and templates that serve as canonical references for generation. | | | Agent hooks | Pre- and post-edit hooks such as format, lint and typecheck that run automatically in agent sessions. | | | Design tools bridges | Bridges to design tools such as Figma or Penpot, including assets like Code Connect, design-to-code mappings and token mappings. | | ### 4. Quality | Element | Description | Status | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | Validation loop | A required validation cycle for agent output, typically based on linting, typechecking, accessibility checks and conformance verification. | | | Compliance checker | A tool that evaluates an interface or a codebase against Design System rules and assets to assess its compliance with the system. | | | Guardrails | High-level constraints that prevent unsupported output, such as verify-before-use rules, deprecated API bans, token-only styling and approved design-source allowlists. | | | AI evaluation suite | Prompt-to-expected-output evaluations run in CI on changes to skills, rules, prompts or MCP assets, with pass-rate thresholds and published results. | | ## Why this matters As AI tools become part of everyday design and development workflows, a Design System is no longer only consumed by humans. It is also increasingly consumed by: - coding assistants working inside IDEs - agents that generate or modify UI code - tools that inspect design tokens and component APIs - workflows that connect design, documentation, and implementation If Quantum is not structured for these use cases, AI-generated output becomes less reliable. It may use the wrong components, invent patterns that do not exist, or produce code that is inconsistent with the system. Improving AI-operability helps reduce that gap. The goal is not to let AI replace design and engineering judgement, but to make Quantum easier to use correctly in AI-assisted workflows. # LLM-ready docs Quantum exposes LLM-friendly documentation endpoints so AI tools, agents, and automation can discover and consume documentation content more easily in both public and private modes. These endpoints are designed to help with: - AI-assisted documentation retrieval - agent navigation across Quantum docs - downstream indexing pipelines - lightweight ingestion of documentation content ## `llms-*.txt` Use the index to discover available content, the full corpus when context limits permit, or a documentation bundle targeted to the task. ### Discovery and full corpus | File | Description | Link | | --------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | `llms.txt` | A compact index of public documentation, including canonical and Markdown links. | [`/llms.txt`](/llms.txt) | | `llms-full.txt` | Complete concatenated documentation and published blog content for tools that need the full corpus in a single request. | [`/llms-full.txt`](/llms-full.txt) | ### Documentation bundles These bundles contain documentation only, without published blog content. Choose the smallest relevant bundle to reduce context use. | File | Documentation included | Link | | ---------------------------------- | --------------------------------- | ------------------------------------------------------------------------ | | `llms-docs.txt` | All public documentation | [`/llms-docs.txt`](/llms-docs.txt) | | `llms-docs-welcome.txt` | Welcome and contribution guidance | [`/llms-docs-welcome.txt`](/llms-docs-welcome.txt) | | `llms-docs-foundations.txt` | Design foundations | [`/llms-docs-foundations.txt`](/llms-docs-foundations.txt) | | `llms-docs-components.txt` | Component documentation | [`/llms-docs-components.txt`](/llms-docs-components.txt) | | `llms-docs-extensions.txt` | Extensions | [`/llms-docs-extensions.txt`](/llms-docs-extensions.txt) | | `llms-docs-patterns-templates.txt` | Patterns and templates | [`/llms-docs-patterns-templates.txt`](/llms-docs-patterns-templates.txt) | | `llms-docs-working-with-ai.txt` | AI-assisted workflows and tools | [`/llms-docs-working-with-ai.txt`](/llms-docs-working-with-ai.txt) | ## Markdown documentation Every documentation page is also available in Markdown by adding the `.md` suffix to its URL. For example: | Example HTML page | Example Markdown URL | | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | [`/docs/welcome/introduction`](/docs/welcome/introduction) | [`/docs/welcome/introduction.md`](/docs/welcome/introduction.md) | | [`/docs/working-with-ai/overview/introduction`](/docs/working-with-ai/overview/introduction) | [`/docs/working-with-ai/overview/introduction.md`](/docs/working-with-ai/overview/introduction.md) | Use HTML pages for browsing and Markdown URLs for tools that need a simpler representation. # Design Tokens, what the heck!? _This article is a transcript of a workshop led by Edgar Lechaudel at Flupa UX Days 2024._ --- Design Tokens became such a hype topic since Figma announced their Variables feature in 2023. Since then, everyone talks about it like a revolution in our industry and many definitions of Design Tokens are popping around the internet. But still, it can be very difficult to get his head around it. Design Tokens is a broad concept that is hard to define in a single sentence. That's why I won't start with meaningless definition. No, I decided to take you on a progressive demonstration that details what pains they solve, illustrates how powerful they are and explain why they will change the way we design interfaces forever. Let's demystify Design Tokens together! ## So many and repetitive styling when creating interfaces… For the purpose of this article, we will use a Twitter-like mock-up throughout this demo. This design, recreated using the Quantum Design System (Thales Digital Design System), shows the importance of adhering to specific styling guidelines. In combination to standard design principles, this design uses many different styling values to achieve the following visual outcome. Even in a seemingly simple mock-up, numerous values, such as colors, typography, and spacing, are essential for a consistent and cohesive user experience. Twitter-like mock-up showing the design In other words, those styling values are the ones you set in your Figma inspector panel for every design layer you combine and assemble to create your designs. Figma inspector panel showing style values We might not consciously care about it, but a wide range of different values are attached to this single mock-up. Style values encompass a large number of attributes, including colors, typographies, spacings, borders and many others. Chart showing the range of style values in the mock-up And faster than we think, we find ourselves repeating the same style values over and over across the interfaces. This quickly leads to a chaotic and difficult-to-maintain Design System, especially when scaled up to multiple features, products, or even projects over an entire organization. Illustration of repetitive style values across interfaces ## Not just styling values but styling decisions In their most basic form, Design Tokens provide a solution to the repetitive nature of styling. By applying the fundamental principle of Design Tokens, we store our style values in a reusable collection. This allows changes to be propagated throughout our designs automatically, eliminating the need for manual and time-consuming interventions. Reusable collection of style values For instance, Figma's Styles feature or Penpot Assets are great examples of this basic concept in action. In fact, without realizing it, you might have already been using one of the fundamental principles of Design Tokens. Figma Styles and Penpot Assets as examples ## But Design Tokens is not just that, they push this elementary concept even more forward! While creating a collection of reusable style values is a great start, it doesn't tell the whole story. These reference style values are often not intuitive and lack the meaning and context of when, where, and why they should be applied in our interfaces. As designers, we don't just apply style values thoughtlessly or randomly; we make intentional decisions in our minds for each application. We make decisions based on the usage, the intent of a style as well as its context of application. Let's break that down in details: ### Usage First, we make decisions in terms of usage, which means where we apply styles. We have to consider the type of element we want to style when applying a style value. If we take the example of colors, a color style might be suitable for a text element but not for an icon element or a border element. The question that comes up all the time is: "what style value can I use on this design element to comply with accessibility requirements and ultimately keep my screens on brand and consistent?". Diagram showing usage decisions for style values ### Intent But it goes beyond that. We also make decisions based on intent, which means the sentiment that must convey the visual rendering. For example, we might choose and stick to a specific color for call-to-action elements and draw the user's attention. Or, we might use different font sizes to establish a visual hierarchy. These decisions, along with countless others, add to the complexity of styling our interfaces. But the question always remains the same, which styles, or even which combination of styles, should I use to achieve that visual intent? Diagram showing intent-based design decisions ### Context And that's not all. We also need to consider the context in which our designs will be experienced. For instance, we have to make decisions based on whether the user is in light or dark mode, or if they're using a large or small screen. Diagram showing context-based design decisions This adds another layer of complexity to an already challenging process. It's difficult to keep track of all the possible variations, and even with the best documentation, designers often find themselves asking the same questions repeatedly. - "What is the smallest icon size allowed?" - "What is the neutral color to make a text discrete?" - "What is the font size of a title 1?" - "What is a large spacing value on mobile?" - "What is the default neutral text color on dark?" - "What is the primary color to highlight text?" - … This leads to chronic waste of time, inconsistent styling habits, frictions and decision fatigue. Illustration of decision fatigue and inconsistency Design Tokens are here to help with that. They provide a framework for managing a global stylistic language expressed through design decisions. Design Tokens can be applied universally, regardless of the specific design context, avoiding suppositions and limiting the need for a heavy documentation-dependent design process. Design Tokens as a universal framework Rather than applying meaningless styling references on our interfaces (`blue-500`), we use our design decisions (`color-text-primary`). We don't need to think about the exact value they reference to — the design decision, on its own, becomes explicit on its usage and intent. Comparison of raw values vs. semantic token names As mentioned before, Design Tokens can be applied regardless of the specific context of a design. Whether it's a theme that affects colors, such as dark mode versus light mode, or a theme that impacts spacing and typography, like desktop versus mobile, the underlying design decisions, usage and intent, remain the same, always. Only the specific values associated with those decisions change depending on the context (theme). Below is an example with a change of spacing value between a Desktop and a Mobile screen. You can notice that the decision applied on the mock-ups remains the same across a desktop or mobile screen, a `spacing-medium` for top and bottom padding and a `spacing-xlarge` for left and right padding. Only the values applied to those decisions change depending on the responsive theme, Desktop versus Mobile. Desktop vs Mobile spacing example Furthermore, Design Tokens help to bridge the gap between design and code a little more. The language provided by Design Tokens is shared between both environments. It means that the same variable names can be used in your design tool and your programming language of choice which allow better communication and design-to-dev hand-off. Shared language between design and code Finally, Design Tokens are distributed from one single and agnostic source of truth which allows their portability between tools and languages. As a result, they ensure that updates are automatically and consistently propagated across all relevant teams involved in digital product design and development. _(Distributing Design Tokens from a single and agnostic source of truth across design tools like Figma, Sketch or Penpot is not easy and obvious as I write this article in September 2024. But it is proven and facilitated for a relevant number of programming languages thanks to Style Dictionary.)_ Design Tokens distributed from a single source of truth ## Let's sum this up Let's take some time to sum up and have a behind the scenes look at how it works. ### Primitive layer At the very beginning of the article, we talked about our collection of values of reference. This collection gathers all the style options available and that we might need in designing our interfaces. They are deliberate non-descriptive variables covering the different family of styles like color, spacing, typography, size, border, shadow, … For example `blue-500`, `spacing-1`, `fontSize-3`, `radius-2`, `shadow-1`, … In the Design Tokens world, we call them **"Primitives"**. They store the raw styling values that make up our interfaces. But as explained earlier, they are not the variables we will directly use to style our interfaces. Actually, we usually keep them invisible from the Design System users. In design and code we'll use another set of variables connected to those primitives. Primitive layer diagram ### Semantic layer (aliasing) Right after the values of reference, we shift focus to design decisions: the famous stylistic language. This collection gathers variables that unambiguously describe the usage and intent of a specific primitive value. Those are the variables that make sense to use on our interfaces — they represent the design decisions we make to craft our interfaces. In the Design Tokens world, we call them **"Semantics"**. While primitives variables store raw values, semantic variables reference other variables (primitives). This is what we call "aliasing" in the Design Tokens jargon. These variables provide meaningful context and clarity for our interfaces, revealing the underlying design intentions and guiding informed decision-making. Not all primitive variables have to be used or connected to a semantic variable. The style options available in the primitives will be useful to assign specific values to our semantic variables (design decisions) depending on the context — the themes. Semantic layer diagram showing aliasing ### Themes (permutation) Themes are the different appearances our interface can take depending on the context: dark or light mode, mobile or desktop view, color scheme "x", "y", "z", contrast high or low, density airy or compact, … Themes can be combined together to represent a specific design context. In the Design Tokens' jargon this is what we call **"Permutation"**. What makes the theming feature really possible at scale is the semantic layer — it abstracts the primitives behind design decisions. The semantic layer allows us to have persistent variables mapped and applied on our interfaces regardless of the context. A theme appears when a semantic variable can be attached to more than one reference value. For example, if I want to add a dark mode and a mobile version to my light mode desktop project, I would need to adapt some design decisions in regards to those new design contexts. In fact, a dark mode and a mobile version will undoubtedly have an impact on the styling value attached to my design decisions regarding color, typography, and spacing. **This is where the magic really happens!** Rather than having to duplicate my mock-ups and manually apply new specific design decisions on our interfaces for each new context or theme, the technology of Design Tokens allows us to assign different values of reference to any single semantic variable (design decisions). You can visualize them as mapping tables where each line represents a semantic variable, each column a theme, and each cell the corresponding primitive value of reference. Then, depending on the themes we apply to a page or a section of a page, we can switch between those different values to automatically adapt our interfaces without any intervention on the design mock-ups or the code. Themes permutation mapping table To illustrate this concept, let's examine the background color of a page. To apply the color to our main app background we have a semantic variable (design decision) called `color-background-neutral-base`. In the dark theme, we've assigned the primitive token `bluegrey-900` to that semantic variable and when switching to the light theme, the value associated with this semantic variable changes to `bluegrey-0`. What you can notice here is that the design decision applied on our mock-ups remains the same. Only the value of reference assigned to it changes depending on the chosen theme. **This demonstrates the flexibility and versatility of Design Tokens.** We can use the Design Tokens technology as a configurator to morph the style interface into almost anything we want. Dark mode vs Light mode example using tokens Further demonstration of theme switching Below is another example, illustrating how spacing can be handled through theming. On this tweet component we applied a semantic variable (design decision) called `spacing-padding-medium` to control the space within the tweet main container. In the desktop theme, this semantic variable references the `spacing-5` primitive variable while in the mobile theme it references the `spacing-3` primitive variable. Again, the same spacing design decision applied on the mock-up persists across themes — only its assigned value changes depending on the context, the chosen theme. Desktop spacing example Mobile spacing example ## Design Tokens: The strategic advantage your organization needs Design Tokens became the backbone of any robust Design System. They are a strategic advantage that elevates the way designers and developers collaborate, creating a seamless bridge between design intent and code implementation. Design Tokens provide an essential layer of abstraction that goes beyond components by focusing on the core styling variables of an interface — such as typography, size, color, spacing, assets, layout, borders, shadows, grids, animations, opacity, and breakpoints. By defining these foundational design decisions, Design Tokens empower teams to achieve greater control and flexibility, ensuring that every part of the product reflects the intended design language and decisions. In today's competitive landscape, adopting Design Tokens is not just an option — it's a critical move for any product team looking to optimize workflows, enhance collaboration, and maintain consistent libraries and documentation. Here's why Design Tokens should be at the heart of your strategy: Design Tokens as a strategic advantage ### Save time & Energy The benefits of reusability and a well-structured system are a game-changer. Design Tokens significantly reduce the time and effort required to implement styling updates, making the process of adapting, maintaining, and documenting styles both streamlined and error-free. By centralizing style values and decisions, Design Tokens allow you to update components or styling references across multiple platforms and mock-ups with just a few clicks, ensuring that changes are consistently propagated wherever the system is in use. No more tedious updates across countless screens or worrying about forgotten changes. Design Tokens transform what used to be a laborious and error-prone process into a swift, reliable action. Imagine adjusting a color or spacing value in one place and seeing that change instantly reflected across your entire application. Responsive design becomes so much more manageable as designers can effortlessly adjust Token values to accommodate different screen sizes — saving your team precious time, unlocking new capabilities at scale, and eliminating manual errors. Isn't that magical? ### Be more consistent Design Tokens create a shared language that bridges the gap between design and development, fostering better collaboration and reducing the risk of misunderstandings. When design decisions are encapsulated in tokens, everyone — designers, developers, and stakeholders — works with a shared dictionary. This not only streamlines the hand-off process but also minimizes discrepancies between the design intent and the final implementation, saving time and avoiding costly rework. I'm sure you've experienced the frustration of seeing your carefully crafted design implemented incorrectly due to miscommunication. With Design Tokens, those days are over. They ensure that the final product is not only true to the original vision but also implemented efficiently and consistently, making the entire process from design to deployment smoother and more cohesive. It's like having a translator that always gets it right! ### Embrace versatility Design Tokens empower teams to effortlessly adapt interfaces to different contexts and scenarios, from screen sizes to user preferences. This versatility is crucial in today's multi-platform world, where a single design needs to look and perform perfectly across a variety of devices and use cases. By simply adjusting token values, teams can rapidly configure and personalize the appearance of an interface without diving into complex and time-consuming redesigns. Consider scenarios like implementing dark mode or adjusting for mobile displays. With Design Tokens, such changes are as simple as creating a new preset by adapting a few values, enabling rapid iteration and testing. Imagine using this flexibility during experimentation, discovery phases, or even for A/B testing — allowing designers to explore different variations of an interface to identify the most effective approach with just a few clicks. Design Tokens are more than just a collection of design decisions — they are a strategic asset that allows for infinite customization and adaptability. By embedding these tokens within your Design System, you create a resilient framework that scales effortlessly, supports systemic approaches, and optimizes every aspect of your product development process. Adopting Design Tokens isn't just a technical upgrade; it's a new paradigm towards a more efficient, collaborative, and future-proof way of working at scale. It's time to fully embrace their power and elevate your product design to new heights now! --- Check the full Design Tokens retrospective of Quantum in [The Design Tokens book](https://frontguys.fr/the-design-tokens-book/). # Quantum Tokens Are Now Open Source Quantum's design tokens are now open source. They live in the [ThalesGroup/quantum](https://github.com/ThalesGroup/quantum) repository on GitHub under the MIT license, and you can install them from npm as [`@quantum-ds/tokens`](https://www.npmjs.com/package/@quantum-ds/tokens). It's the first public package of Quantum, the Thales Digital Design System, and it won't be the last. We've also published a public version of our documentation at [quantum.thalesdigital.io](https://quantum.thalesdigital.io), the site you're reading now. Both show the current version of Quantum, which is now a few years old. We're building its next generation, far more modern in its design system practices and in how it works with AI. Here's why we opened the current one and what you'll find inside. ## We believe in open source Quantum is built on open source. [Style Dictionary](https://styledictionary.com/) and [Terrazzo](https://terrazzo.app/) build our tokens, [Penpot](https://penpot.app/) is one of the design tools we export to, and the token format itself comes from the [Design Tokens Community Group](https://www.designtokens.org/), a W3C community group. Publishing our own work is a way to give some of that back. Working in public also makes these practices visible. A public repository needs a clear README, a changelog, a license, and a release process anyone can check. We already enforce these good practices through InnerSource, and publishing Quantum lets anyone see them in action. ## Reachable from anywhere Large organizations rarely have one place to put code. They often run several source control platforms and package registries side by side. Making a package available across them requires ongoing maintenance. People outside the organization can't reach any of them. A public package skips all of that. Most company registries already mirror npm, so `@quantum-ds/tokens` shows up in them without any extra step. A team inside Thales and a partner outside it install the same package with the same command, and get the same version. ## Open to agents More and more of us build with agents and LLMs: coding assistants in the editor, agents running in the cloud, prototypes vibe-coded from a prompt. These tools work with what they can reach. An internal registry behind a company login is out of their reach. A public npm package and a public GitHub repository aren't. With the tokens in the open, a prompt can say "use `@quantum-ds/tokens`". The agent installs the package, reads the DTCG files and the README, and picks `--button-filled-danger-background-color` instead of guessing a red. Design system folks outside Thales get the same thing: a real token set to feed to their own tools, study, or compare with theirs. ## What's in the package Version 1.10.0 is the first public one. Earlier versions were only released inside Thales. The code is under the [MIT license](https://github.com/ThalesGroup/quantum/blob/main/LICENSE) and the documentation under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). You can use, change, and share both, in commercial products too, as long as you keep the copyright notice and credit Quantum. The Quantum logo and brand images aren't covered by either license. These are the tokens of the current Quantum, created a few years back. They have two layers. Raw tokens hold the values: colors, spacing, typography, borders, shadows, icons, breakpoints, and grids. Component tokens cover 25 components, from alerts to tooltips, plus data visualization, each in a light and a dark theme. Component tokens point straight at raw values. `button.filled.danger.background.color` is `{color.red.500}`, with no semantic layer in between, no "danger background" token that every component would share. The next generation of Quantum adds that layer, and its tokens are among the next things we plan to open. From the DTCG source, the package ships: - DTCG JSON files, the source of truth, in `dist/dtcg/`. - CSS custom properties, with the dark theme under a `.dark` class. - Sass variables. - JavaScript and TypeScript modules, with one named export per token. - Android XML resources. - A Penpot token file. The build also writes files for Figma and Tokens Studio, but they aren't in the npm package yet. ```sh npm install @quantum-ds/tokens ``` ```css @import '@quantum-ds/tokens/dist/tokens.css'; @import '@quantum-ds/tokens/dist/tokens-dark.css'; .danger-button { background-color: var(--button-filled-danger-background-color); } ``` ## A new source of truth Until recently, the tokens lived in Figma. Designers defined them on artboards, we exported them to JSON, and Style Dictionary turned that JSON into CSS and JavaScript. Every change started in one design tool, and every other tool came second. We recently moved the source of truth to a set of JSON files in the repository, written in the [Design Tokens Format (DTCG)](https://www.designtokens.org/). A resolver file, `quantum.resolver.json`, tells tools how the raw, component, and theme sets fit together. Style Dictionary builds the CSS, Sass, JavaScript, and Android files. Terrazzo reads the same files and checks them against the specification. Our own scripts write the Figma, Penpot, and Tokens Studio files. Figma is now one consumer among others. You can do the same with formats we don't ship. Point [Style Dictionary](https://styledictionary.com/) or [Terrazzo](https://terrazzo.app/) at `dist/dtcg/` and generate what your platform needs. The old Figma export is still in the package so nothing breaks for current users: `dist/json/`, and `dist/tokens.js` built from it, which is also the package's main entry. Both have been deprecated since 1.8.0 and will go away in a future major version. For new work, use `dist/dtcg/` or the formats built from it. ## Thanks to the OSPO Publishing under the Thales name takes more than a `git push`. The Thales Open Source Program Office (OSPO) helped us through it, and the repository now sits in the [ThalesGroup organization](https://github.com/ThalesGroup) on GitHub next to more than 300 other Thales projects. Thank you! The OSPO sums up its approach as "Use, Contribute, Publish." Quantum has used open source from the start, and this is our first step on the publishing side. That work across the group earned Thales the [Best Open Source Strategy award](https://www.thalesgroup.com/en/news-centre/news-brief/research-innovation/thales-wins-best-open-source-strategy-prize) from the CNLL, the French open source industry council, in December 2025. If you work at Thales and want to open a project too, the OSPO is the place to start. ## What comes next Tokens are the start. We plan to open more of Quantum in the same repository: - The next-generation tokens, with their semantic layer. - Component specs. - Possibly simple themes for open source component libraries, built from Quantum tokens. If you use the tokens, inside or outside Thales, we'd like to hear how. [Open an issue](https://github.com/ThalesGroup/quantum/issues/new) on GitHub, or read the [contributing guide](https://github.com/ThalesGroup/quantum/blob/main/CONTRIBUTING.md) to send a change. And if you want to follow what we open next, [give the repository a star on GitHub](https://github.com/ThalesGroup/quantum). It helps other teams find Quantum, and it shows us there's interest in more. # Rethinking the Material 3 Color Preview for Better Legibility When our Design System team needed to create a Material 3 theme based on our specific design tokens, we naturally started with the official suite of tools provided by the Material team: - [Material Theme Builder on the Web](https://material-foundation.github.io/material-theme-builder/) - [Material Theme Builder as a Figma Plugin](https://goo.gle/material-theme-builder-figma) Official Material Theme Builder from Material team where one can select a source color or core colors, and check the rendering in different views. These official tools are excellently crafted. They allow you to select a source color or set core seeds and instantly see the rendering across different views. **However, we quickly ran into limitations regarding our specific workflow:** we wanted to explicitly define every single color token ourselves. Unless we missed a hidden feature, the official tools seemed primarily focused on generating primitive palettes from seed colors and programmatically mapping those primitives to the right semantic variables, rather than allowing granular overrides at the individual token level. Since we needed a functional theme on a tight deadline, [Edgar Lechaudel](https://www.linkedin.com/in/edgarlechaudel/) vibe-coded a custom editor that gives us full control. While the underlying code is ugly as hell, it serves its purpose perfectly as it was never meant to be a polished consumer product, just a powerful internal tool. Custom Material Theme Editor preview where one can select color tokens, check the component preview, select the color modes, reset the settings, or export the corresponding theme JSON. Our custom tool allows us to tweak individual color tokens, toggle between color modes, reset settings, and export the final theme as a JSON file. However, even with this control, we hit a snag with the standard [color preview layout used in the official Material 3 documentation](https://m3.material.io/styles/color/roles). Color system view from the official Material 3 docs where each color is used as a background color of a box: Primary, On Primary, etc. First, the Figma plugin does not seem to support rendering a custom Material 3 JSON configuration as-is. When a JSON file is uploaded, the plugin rewrites the custom definitions using its own color algorithm, regardless of the selected settings. Second, in the standard view, each color is shown as a background box (e.g., Primary, On Primary). We found the "On \{Color\}" logic particularly counter-intuitive to visualize this way. For instance, if "On Primary" is white, you have to look at the background of the "On Primary" box to see the actual color, while the text inside that box (usually the Primary color) can be misleading. This cognitive load only increases when dealing with the Surface semantic colors with several background and foreground combinations. Recognizing that we might be approaching this with "newbie" eyes, we developed an alternative color preview strategy. Instead of isolated boxes, our tool displays a comprehensive color overview where: - Each **semantic background color** is represented as a distinct colored surface. - **Compatible foreground colors**, such as text and outlines, are rendered directly onto these surfaces. - **Color token names** are positioned outside the surfaces to maintain visual clarity and independence. This layout enables instantaneous assessment of legibility and contrast in real-time. The Custom Material 3 Theme Editor displays a complete color overview. Each semantic color includes a background preview box and a list of compatible foreground options. Each foreground color is rendered directly on top of the background to visualize legibility, followed by its specific color name. This view provides a clear WYSIWYG map of the theme’s accessibility. While there might be edge cases or M3 concepts we’ve interpreted uniquely, this approach gave us the clarity we needed to finalize our theme. We believe this visualization style could be useful for other teams struggling with the abstraction of the "On" color system. **Feel free to adopt this layout in your own documentation or tools**. As for our vibe-coded custom editor, if you think this granular level of control would be helpful for your own workflow, let us know! **If there’s enough interest, we’d be happy to look into cleaning it up for an open source release**.