chore: sync content to repo (#10326)

Co-authored-by: nilbuild <4921183+nilbuild@users.noreply.github.com>
2026-09-14 14:21:03 +02:00
1 parent f78ceb44e6
commit 0505268b44
@@ -1,3 +1,3 @@
 # A/B Tests and Experiments

-Understand how the team implements A/B tests and experiments on different screens and if the new design system should accommodate any necessary requirements.
+A/B tests and experiments compare two or more versions of a design to measure which performs better against a specific metric, such as click-through rate or conversion. When building a design system from an existing product, past experiment results help identify which design variations actually improved outcomes and are worth standardizing. Reviewing this history avoids locking in a component variant that experimentation already showed was weaker.
@@ -1,3 +1,3 @@
 # Accessibility Testing
-
-Design systems should cover accessibility as much as possible. Making this automatic reduces the risk of inaccessible components or user flows in the product.
+ 
+Accessibility testing checks that components meet standards like WCAG, covering things like sufficient color contrast, proper keyboard navigation, and correct screen reader labeling. It combines automated tools, like axe or Lighthouse, with manual testing using assistive technology to catch issues automated tools miss. Testing accessibility at the component level ensures every product built from the design system inherits accessible behavior by default.
@@ -1,3 +1,3 @@
 # Accessibility

-For icons that convey a meaning or serve a function, add the necessary support for screen readers. You can skip this for decorative icons.
+For icons that convey a meaning or serve a function, add the necessary support for screen readers. You can skip this for decorative icons.
@@ -1,6 +1,6 @@
 # Accessibility

-Guidelines for how you approach accessibility and how you leverage colour, hierarchy and assistive technologies to help your users.
+In the context of design tokens, accessibility refers to ensuring that color and other visual choices meet contrast and legibility standards, such as WCAG guidelines, for users with visual impairments. It means checking that text colors have sufficient contrast against their backgrounds and that icon sizes remain legible at small scales. Accessibility considerations get baked into the tokens themselves so every component built from them meets the same baseline.

 Visit the following resources to learn more:

@@ -9,4 +9,4 @@ Visit the following resources to learn more:
 - [@article@Accessibility Principles](https://www.w3.org/WAI/fundamentals/accessibility-principles/)
 - [@article@WebAIMs Website (Web Accessibility In Mind)](https://webaim.org/)
 - [@article@WAVE Web Accessibility Evaluation Tool](https://wave.webaim.org/)
- [@feed@Explore top posts about Accessibility](https://app.daily.dev/tags/accessibility?ref=roadmapsh)
+- [@feed@Explore top posts about Accessibility](https://app.daily.dev/tags/accessibility?ref=roadmapsh)
@@ -1,3 +1,3 @@
 # Accessibility

-Make sure to have accessible pairings between the main colours in your palette. More importantly, make sure that your background and text colours have at least an AA standard contrast ratio between them.
+Make sure to have accessible pairings between the main colours in your palette. More importantly, make sure that your background and text colours have at least an AA standard contrast ratio between them.
@@ -1,10 +1,3 @@
 # Avatar

-Avatars are used to show a thumbnail of a user photo or a visual representation of any other type of content.
-
- **Image:** Avatars should mask an image into their shape and work with any image size since they may get this image from unknown data sources.
- **Image Fallback:** There should be fallbacks when there’s no image available. This can be done with placeholder images or initials.
- **Accessibility:** Always provide a description for screen readers describing what’s displayed on the avatar image instead of just naming its role.
- **Sizes:** There are many contexts to use avatars and they all require different sizes for the component. For average projects use at least 2-3 different sizes and make sure there’s at least a small size available.
- **Icon:** Avatars can be used with an icon instead of an image to emphasize areas that don’t necessarily have (or need) an image associated with it.
- **Background Colors:** When used with icons or text, there has to be a background colour from the design system colour tokens applied to the avatar shape. Make sure that icons and text have enough contrast ratio with the background according to the WCAG AA standard.
+An avatar is a graphical representation of a user or entity, typically displayed as a circular or square image, an icon, or a set of initials. It serves as a visual identifier within an interface to provide context about a person, group, or account status. These components often include fallback mechanisms to display placeholder content when a profile image is unavailable, ensuring consistent presentation across different parts of an application.
@@ -1,6 +1,3 @@
 # Badge

-Badges are elements that represent the status of an object or user input value.
-
- **Appearance:** Badges may play various roles in your product and having a predefined colour for each role should help users understand their meaning. When changing colours, make sure the text has enough contrast ratio with the background according to the WCAG AA standard.
- **Dismissible Action:** Badges can be used as a dynamic way to display selected values and there should be a way to dismiss them.
+A badge is a small UI element used to display status indicators, notifications, or counts associated with a specific item. It typically appears as a compact label containing text or a number, often positioned near an icon, button, or navigation link to provide quick, at-a-glance information to the user. Design systems use badges to highlight states such as "New," "Active," or "Offline" while maintaining a clean and consistent visual hierarchy.
@@ -1,10 +1,3 @@
 # Banner

-Banners display an actionable message used as a prominent way of communicating with your users.
-
- **Appearance:** Banners are used to display different types of messages and it’s important to differentiate their visual appearance based on the role they’re playing. If you’re using background colours for role differentiation, make sure there’s enough contrast ratio with the content according to the WCAG AA standard.
- **Area for icons or images:** Banners can supplement their message using a supporting icon or image. They shouldn’t be used instead of text content.
- **Actions:** Actions in banners should relate to its text and provide a way to react to the message sent to the user.
- **Dismissible Action:** Don’t overwhelm the user with banners on the page and include a dismissable action. That may be either a separate close button or one of the actions provided.
- **Accessibility:** If a banner dynamically appears on the page, it should be announced to the user by their assistive technology.
- **Responsiveness:** Banners should adapt to the viewport size. This usually means that they become full-width for mobile to save some space.
+A banner is a UI element used to display prominent, time-sensitive messages, alerts, or announcements to users. It typically appears at the top of a page or section to ensure immediate visibility without blocking the user's interaction with the rest of the interface. These components often include a short text message and optional actions, such as buttons or links, to help users navigate or respond to the information provided.
@@ -1,3 +1,3 @@
 # Breakpoints

-Predefine the screen sizes and orientations your grid will adapt to.
+Breakpoints are the specific screen width values at which a layout changes to adapt to different device sizes, such as switching from a single column on mobile to multiple columns on desktop. Design systems define a standard set of breakpoints so that every component and page responds consistently at the same screen widths. Common breakpoint categories include mobile, tablet, and desktop.
@@ -1,13 +1,3 @@
 # Button

-Buttons are interactive elements used for single-step actions.
-
- **Hover State:** Clearly show that the button is interactive when it gets hovered with a mouse cursor.
- **Active State:** Used when a button gets pressed. The same state can be used to represent the button responsible for toggling another element on the page while that element is visibly opened.
- **Focused State:** Used when a button gets selected through keyboard navigation.
- **Icon Support:** Icons easily communicate the purpose of the button when used next to its label or can be used without text when there’s not enough space. Make sure that the accessibility label is provided when used with an icon only.
- **Disabled:** Visually shows that a button is not interactive and restricts it from being pressed.
- **Loading:** Used when users have to wait for the result of their action after they press a button. If a spinner is used to display this state make sure that it’s not changing the original button width or height.
- **Full Width:** By default buttons take the width of their content, but they should also come with a full width variant that works well in mobile devices.
- **Variants:** When using multiple buttons, there should be a way to differentiate between primary and secondary actions. Buttons may play different roles for the user or be used on different types of surfaces and they have to change the way they look.
- **Sizes:** Buttons can be used in different areas of the website and may have multiple predefined sizes. On mobile, tappable areas have to be a minimum of 48px to be accessible according to iOS and Android accessibility guidelines.
+A button is an interactive element that triggers an action or event when a user clicks or taps on it. It serves as a primary navigation or functional trigger within a user interface, often featuring distinct styles to represent different states such as hover, active, or disabled. By defining a set of consistent properties like shape, typography, and color, buttons ensure predictable user interactions across an entire application.
@@ -1,9 +1,3 @@
 # Card

-Cards are used to group information about subjects and their related actions.
-
- **Supports any type of content:** Cards are one of the most used components in the product, so they have to be flexible enough to support any other components placed in them.
- **Information structure:** No matter how flexible cards are, it’s important for cards to have a specific structure for its elements for product consistency.
- **Supports media sections:** One of the most popular scenarios for using cards is mixing them with media content. The most popular options are having a full-width area on top of the content or full-height area at one of the card’s sides.
- **Supplementary actions:** Cards can be used with actions usually placed at the bottom of the card, or the card itself can be tappable and represent an action.
- **Responsiveness:** On mobile viewports cards are usually full-width in order to save space for the content.
+A card is a versatile UI container that groups related content, such as text, images, and actions, into a single, cohesive visual unit. It acts as a flexible interface element that helps organize information into manageable blocks, making it easier for users to scan and interact with specific data points. By using a consistent layout and style, cards provide a clear hierarchy and structure across different screens and views within an application.
@@ -1,10 +1,3 @@
 # Carousel

-Carousels stack the same type of items and allows scrolling through them horizontally.
-
- **Navigation Controls:** Carousels should have easy-to-find navigation controls for scrolling through content.
- **Supports any content:** Carousels can be used in different contexts and shouldn’t be limited to a specific child component. In some scenarios you might want items within the same carousel to differ from each other.
- **Items width customisation:** For simple products, it might be fine to use multiple predefined sizes for carousel items. For more flexibility, it’s good to provide a way to define a custom width.
- **Touch events support:** Carousels should be scrollable on touch devices. Some of the best practices are to use native scrolling and to make sure you’re supporting the same behaviour for all touch devices, not just mobile phones.
- **Keyboard navigation:** It should be possible to scroll through content with keyboard arrows when focused on navigation controls.
- **Responsiveness:** It’s good practice to hide or reduce the size of navigation controls for mobile viewports to improve the visibility of the content.
+A carousel is a UI component that displays a series of visual items or content blocks in a rotating, horizontal, or vertical sequence. It allows users to browse through multiple pieces of media or information within a confined space by interacting with navigation controls like arrows, dots, or swipe gestures. This component helps optimize screen real estate by cycling through content, such as image galleries, feature highlights, or promotional banners, while maintaining a clean and organized layout.
@@ -1,3 +1,3 @@
 # Code Style
-
-Having a defined code style helps align the way code’s written in the system and increases development velocity. It should be automated with the tools provided for each platform.
+ 
+Code style refers to the formatting and structural conventions followed when writing a design system's component code, such as naming conventions, file structure, and formatting rules enforced by tools like ESLint or Prettier. Consistent code style makes the codebase easier to read and maintain as multiple contributors add or update components. It's usually enforced automatically through linting tools rather than left to manual review.
@@ -1,3 +1,3 @@
 # Commit Guidelines
-
-Automate the generation of your changelog by adopting a commit message guidelines that categorise and define the changes being made.
+ 
+Commit guidelines define a consistent format for writing commit messages when contributing code to a design system, such as the Conventional Commits format that prefixes messages with types like "feat" or "fix." Consistent commit messages make it easier to generate changelogs automatically and to understand a project's history at a glance. They're often enforced through automated checks that reject commits not following the required format.
@@ -1,3 +1,3 @@
 # Communication Channel
-
-Most product development work happens digitally, so create a digital channel where people can reach out and ask questions.
+ 
+A communication channel is the primary medium a design system team uses for day-to-day questions and announcements, such as a dedicated Slack channel or Microsoft Teams space. It gives consuming teams a fast way to ask questions or report issues without going through formal ticketing for every small query. Having a clearly designated channel prevents design system discussions from getting scattered across multiple informal threads.
@@ -1,3 +1,3 @@
 # Community Meetings
-
-Arrange community meetings with everyone who uses the design system. Share your knowledge and make proposals to improve the sense of community.
+ 
+Community meetings are regularly scheduled sessions where design system maintainers and the teams that consume the system come together to discuss updates, gather feedback, and address concerns. They give consuming teams a direct channel to raise issues or request new components rather than relying solely on written tickets. These meetings also help build a sense of shared ownership over the design system across the organization.
@@ -1,3 +1,3 @@
 # Component Analytics

-Track the usage of your components. For development you can use built-in tools like Figma’s Design System Analytics. For the end product you can have a separate way of tracking per platform depending on the technology.
+Track the usage of your components. For development you can use built-in tools like Figma’s Design System Analytics. For the end product you can have a separate way of tracking per platform depending on the technology.
@@ -1,3 +1,3 @@
 # Component Catalog
-
-Isolate your UI components’ environment outside of your product codebase to make sure they’re not dependent on any global dependencies and can be easily reused.
+ 
+A component catalog is a searchable, browsable reference of every component in a design system's code library, usually generated automatically from the component code itself. Tools like Storybook are commonly used to build a catalog that shows each component's variants, props, and usage examples in an interactive interface. It gives developers a live reference to check component behavior without reading the underlying source code.
@@ -6,4 +6,4 @@ Visit the following resources to learn more:

 - [@article@Pattern Lab](https://patternlab.io/)
 - [@article@Fractal](https://fractal.build/)
- [@article@Storybook](https://storybook.js.org/)
+- [@article@Storybook](https://storybook.js.org/)
@@ -1,3 +1,3 @@
 # Component

-Components are the reusable building blocks of a design system. Each component meets a specific interaction or UI needs, and is specifically created to work together to create patterns and intuitive user experiences.
+A component is a reusable, self-contained UI element, such as a button, input field, or card, built once and used across multiple screens or products. It usually has defined states, like default, hover, and disabled, and accepts configurable properties to adapt to different contexts. Components are the building blocks that a design system's component library is made of.
@@ -1,3 +1,3 @@
 # Contribution Guidelines
-
-Define the process of contributing to the UI and UX of the design system and document it in a discoverable place to make it easier for everyone to contribute.
+ 
+Contribution guidelines document the process for proposing, reviewing, and approving changes to a design system, whether on the design side or the development side. They typically cover how to submit a new component, who reviews proposed changes, and what criteria a contribution needs to meet before acceptance. Clear contribution guidelines make it possible for people outside the core design system team to safely add or update components.
@@ -1,3 +1,3 @@
 # Contribution Guidelines

-Define the process of contributing to the code of the design system. Document everything in a discoverable place to make it easier for everyone to contribute.
+Contribution guidelines are a set of rules and best practices that define how team members can submit updates, bug fixes, or new components to a shared codebase. They outline the expected workflow, such as how to set up the local environment, follow branching strategies, run automated tests, and format pull requests.
@@ -1,3 +1,3 @@
 # Core Components

-Components are the main building blocks for user interfaces. Building a reusable component library enhances your product development workflow by reducing design and tech debt and speeding up the process. Core components can’t be broken down into granular pieces without losing their meaning.
+Components are the main building blocks for user interfaces. Building a reusable component library enhances your product development workflow by reducing design and tech debt and speeding up the process. Core components can’t be broken down into granular pieces without losing their meaning.
@@ -7,4 +7,4 @@ Visit the following resources to learn more:
 - [@article@What is a Design Language.. really?](https://medium.com/thinking-design/what-is-a-design-language-really-cd1ef87be793)
 - [@article@How to Develop a Design Language](https://xd.adobe.com/ideas/principles/web-design/how-to-develop-design-language/)
 - [@article@What Actually Constitutes Design Language?](https://www.uxpin.com/studio/blog/design-language/)
- [@article@Visual Design Language: The Building Blocks Of Design](https://www.smashingmagazine.com/2020/03/visual-design-language-building-blocks/)
+- [@article@Visual Design Language: The Building Blocks Of Design](https://www.smashingmagazine.com/2020/03/visual-design-language-building-blocks/)
@@ -1,3 +1,3 @@
 # Dark Mode

-Preparing a dark mode version of your colour palette will allow your design system to adapt to dark mode and respect what your user wants to see.
+Dark mode is an alternate color scheme that uses dark backgrounds and light text instead of the default light theme, often to reduce eye strain in low-light environments. Supporting it as a design token concern means defining a parallel set of color values that map to the same semantic roles as the light theme, such as background, text, and border colors. Components then reference these semantic tokens so they adapt automatically when a user switches themes.
@@ -1,7 +1,7 @@
 # Design Tokens

-Variables that store values for the base layer of your design system, like colour and typography. They’re used in components, so changes on this level will resonate throughout the whole system.
+Defining design tokens means translating the visual decisions from a brand's design language into named, reusable values for colors, spacing, typography, and iconography. This step turns abstract design language into concrete variables that both design tools and code can reference directly. Once tokens are defined, components get built by referencing them rather than hardcoding values.

 Visit the following resources to learn more:

- [@article@What Are Design Tokens?](https://xd.adobe.com/ideas/principles/design-systems/what-are-design-tokens/)
+- [@article@What Are Design Tokens?](https://xd.adobe.com/ideas/principles/design-systems/what-are-design-tokens/)
@@ -1,3 +1,3 @@
 # Design Editor

-There are many design editors available in the market today with the most popular names being Sketch, Figma and Adobe XD. If you're unsure which route to go down it's often best to speak with your team.
+There are many design editors available in the market today with the most popular names being Sketch, Figma and Adobe XD. If you're unsure which route to go down it's often best to speak with your team.
@@ -1,10 +1,10 @@
 # Design Language

-A design language or design vocabulary is an overarching scheme or style that guides the design of a complement of products or architectural settings, creating a coherent design system for styling.
+Design language is the overall visual and interaction style that defines how a product looks and feels, including color, typography, spacing, iconography, and motion. It expresses a brand's personality through consistent visual decisions rather than a specific set of components. A design system implements a design language through tokens, components, and guidelines.

 Visit the following resources to learn more:

 - [@article@What is a Design Language.. really?](https://medium.com/thinking-design/what-is-a-design-language-really-cd1ef87be793)
 - [@article@How to Develop a Design Language](https://xd.adobe.com/ideas/principles/web-design/how-to-develop-design-language/)
 - [@article@What Actually Constitutes Design Language?](https://www.uxpin.com/studio/blog/design-language/)
- [@article@Visual Design Language: The Building Blocks Of Design](https://www.smashingmagazine.com/2020/03/visual-design-language-building-blocks/)
+- [@article@Visual Design Language: The Building Blocks Of Design](https://www.smashingmagazine.com/2020/03/visual-design-language-building-blocks/)
@@ -1,3 +1,3 @@
 # Design Principles

-The considerations that guide the basis of your practice. They outline how you approach design from a philosophical perspective and help with everyday decisions.
+Design principles are a short set of guiding statements that describe the values a team follows when making design decisions, such as prioritizing clarity over cleverness or consistency over novelty. They act as a reference for resolving disagreements or evaluating whether a new component fits the system's intent. Unlike specific guidelines, design principles are broad enough to apply across every part of the design system.
@@ -1,10 +1,12 @@
 # Design System Examples

+Design system examples are live implementations of design patterns, component libraries, and style guides used by organizations to maintain consistency across their digital products. These examples showcase how visual elements like typography, color palettes, and interactive components are organized into a cohesive framework. By examining platforms like Google’s Material Design, Shopify’s Polaris, or IBM’s Carbon, teams can observe how documentation and code integrate to streamline the development process and ensure a unified user experience.
+
 Visit the following resources to learn more:

+- [@opensource@Collection of Open Source Design Systems](https://github.com/alexpate/awesome-design-systems)
 - [@article@Material Design (Google)](https://material.io/)
 - [@article@Carbon Design System (IBM)](https://carbondesignsystem.com/)
 - [@article@Atlassian Design System](https://atlassian.design/)
 - [@article@Polaris Design System (Shopify)](https://polaris.shopify.com/)
- [@article@Gov.uk Design System](https://design-system.service.gov.uk/)
- [@opensource@Collection of Open Source Design Systems](https://github.com/alexpate/awesome-design-systems)
+- [@article@Gov.uk Design System](https://design-system.service.gov.uk/)
@@ -6,4 +6,4 @@ Visit the following resources to learn more:

 - [@article@A Design System: So Much More Than A Component Library](https://www.architech.ca/a-design-system-so-much-more-than-a-component-library)
 - [@article@Design System vs UI Component Library vs Brand Style Guide](https://prototype.net/blog/design-system-component-library-style-guide)
- [@article@Design Systems vs Pattern Libraries vs Style Guides vs Component Libraries](https://www.uxpin.com/studio/blog/design-systems-vs-pattern-libraries-vs-style-guides-whats-difference/)
+- [@article@Design Systems vs Pattern Libraries vs Style Guides vs Component Libraries](https://www.uxpin.com/studio/blog/design-systems-vs-pattern-libraries-vs-style-guides-whats-difference/)
@@ -1,3 +1,3 @@
 # Documentation

-Organize and document the results of visual audit, design elements, components with variations, states, patterns found, any existing documentation, current design process, and considerations. This documentation will be shared across the team and act as a guide when building the new design system.
+Organize and document the results of visual audit, design elements, components with variations, states, patterns found, any existing documentation, current design process, and considerations. This documentation will be shared across the team and act as a guide when building the new design system.
@@ -1,3 +1,3 @@
 # Documentation

-Having your code documented is key to driving adoption and reducing the load on the contributors.
+Documentation serves as the central hub for capturing guidelines, component usage, and design principles, allowing teams to understand how to effectively implement and maintain the system. It bridges the gap between design and development by providing interactive examples, code snippets, and clear instructions for consuming the shared assets.
@@ -1,11 +1,3 @@
 # Dropdown

-Dropdowns are used to display a contextual subview with a list of actions or content related to the area where the dropdown is.
-
- **Supports any type of content:** Dropdowns may be used in a lot of contexts like date pickers, language selection or other product features.
- **Action Menu:** One of the most used scenarios for dropdowns is providing an action menu for the user, so it’s useful to have this layout defined.
- **Focus Trapping:** Once the dropdown’s opened, the focus should work only for elements inside the dropdown. When it’s closed, the focus should move to the dropdown trigger.
- **Close Action:** Either some actions inside the dropdown should close it or there should be a separate close button. Also, it’s good practice to close the dropdown when a user clicks outside.
- **Keyboard Navigation:** It should be possible to navigate through dropdown children elements with the keyboard and close it with an Esc key.
- **Dynamic Position:** Dropdown content should be displayed based on the current position of the trigger element on the screen and always visible to the user.
- **Responsiveness:** Dropdown content should be adapted for mobile viewpoints as it may take a lot of space on desktops.
+A dropdown is a navigation or selection component that presents a list of options when a user interacts with a toggle element, such as a button or an icon. It serves as an efficient way to save screen space by hiding secondary choices until they are explicitly needed. When activated, the component typically displays a menu overlay containing actionable items, filters, or navigational links that close once a selection is made or the user clicks outside the menu area.
@@ -1,11 +1,3 @@
 # Existing Design Analysis

-First step in creating a design system from an existing design is performing a design analysis and understanding what you will be working with to identify the requirements and prepare a plan. Performing the analysis may consist of:
-
- Understanding the Existing Design Process
- Performing Visual Audit
- Identifying Design Elements
- Identify Common Components
- Understanding the A/B Testing and Experimentation Needs
- Understanding any Locale or regional requirements (such as LTR/RTL).
- Documenting your findings
+Existing design analysis is the process of auditing and evaluating an established product’s visual elements, components, and patterns to identify inconsistencies and redundancies. This practice involves gathering current UI assets, documenting usage across the application, and mapping them against modern requirements to determine what should be kept, refactored, or discarded. Through this systematic review, teams gain a clear understanding of the current state of their product to inform the foundation of a scalable design system.
@@ -1,3 +1,3 @@
 # FAQs
-
-To save everyone time, define which questions are asked frequently by your audience and document them in a discoverable place.
+ 
+FAQs are a curated list of frequently asked questions and their answers, covering the most common issues or points of confusion that consuming teams run into when using the design system. Maintaining an FAQ reduces repetitive support requests by pointing people to existing answers before they need to ask directly. It's usually kept alongside the main documentation and updated as new common questions emerge.
@@ -1,5 +1,7 @@
-# Different File Formats
+# Logo File Formats

-Providing a variety of formats for the vector version of your logo will make it easier for others to work and prevent anyone from redrawing it.
+Logo file formats determine how a brand mark is encoded, stored, and rendered across different digital and print environments. Vector formats, such as SVG, EPS, and AI, use mathematical paths to ensure the logo remains crisp and scalable at any size without losing quality. Raster formats, including PNG, JPG, and WebP, use a grid of pixels, making them suitable for specific web displays where fixed resolution is preferred. Choosing the correct format ensures that a logo maintains its visual integrity and performance efficiency when implemented throughout a design system.
+
+Visit the following resources to learn more:

 - [@article@What is a Vector Logo and Why You Need It](https://www.renderforest.com/blog/vector-logo)
@@ -1,3 +1,3 @@
 # Functional Colors

-Besides your brand colours, make sure to have colours defined and made into variables for functions like disabled states, backgrounds, actions and high contrast text.
+Functional colors are tokens that communicate a specific meaning or state, such as red for error, green for success, yellow for warning, and blue for informational messages. They are distinct from a brand's primary palette because their purpose is to convey status consistently rather than express brand identity. Design systems document functional colors separately so every component uses the same color for the same type of feedback.
@@ -7,4 +7,4 @@ Visit the following resources to learn more:
 - [@article@Governance is a design system’s friend](https://zeroheight.com/blog/governance-is-a-design-systems-friend)
 - [@article@Design System Governance – Scale Your Design](https://www.uxpin.com/studio/blog/design-system-governance/)
 - [@article@Governance by design: Building successful design systems](https://rangle.io/blog/governance-by-design-building-successful-design-systems/)
- [@article@Team Models for Scaling a Design System](https://medium.com/eightshapes-llc/team-models-for-scaling-a-design-system-2cf9d03be6a0)
+- [@article@Team Models for Scaling a Design System](https://medium.com/eightshapes-llc/team-models-for-scaling-a-design-system-2cf9d03be6a0)
@@ -1,3 +1,3 @@
 # Grid Relation

-Draw your icons in a bounding box that plays well with your grid. This makes for a better pairing with other UI elements. A good example of this would be icons with bounding boxes paired with text.
+Draw your icons in a bounding box that plays well with your grid. This makes for a better pairing with other UI elements. A good example of this would be icons with bounding boxes paired with text.
@@ -1,3 +1,3 @@
 # Grid Relation

-Font sizes and leading should match your grid to allow better pairing between text and other UI elements. A good example of this is text paired with icons with bounding boxes.
+Grid relation describes how typography or iconography sizes align to the underlying layout grid, ensuring that line heights and icon dimensions land on consistent grid units. Keeping these elements aligned to the grid avoids visual misalignment when text or icons sit next to other grid-based components. This relationship is usually checked when defining the base sizes for type scales and icon sets.
@@ -1,3 +1,3 @@
 # Grid

-Every layout should sit on a grid that brings order and hierarchy to the interface. Define a grid separately for mobile, tablet and desktop devices with columns, gutters, and margins so your interface can adapt to any platform easily.
+Every layout should sit on a grid that brings order and hierarchy to the interface. Define a grid separately for mobile, tablet and desktop devices with columns, gutters, and margins so your interface can adapt to any platform easily.
@@ -1,3 +1,3 @@
 # Guidelines

-Provide guidelines on how and when to use the pairings in your typography scale, what to keep in mind when working with them and how not to use them.
+Provide guidelines on how and when to use the pairings in your typography scale, what to keep in mind when working with them and how not to use them.
@@ -1,3 +1,3 @@
-# Guidelines
+# Color Guidelines

-Provide guidelines on how and when to use the colours in your palette, what to keep in mind when working with them and how not to use them.
+Color guidelines provide a standardized framework for how colors are applied across an interface to ensure visual consistency and accessibility. These rules define the specific usage for primary, secondary, functional, and neutral color palettes, detailing which shades should be used for elements like backgrounds, text, borders, and interactive states.
@@ -1,3 +1,3 @@
 # Guidelines

-Provide guidelines on how and when to use icons, what to keep in mind when working with them and how not to use them.
+Provide guidelines on how and when to use icons, what to keep in mind when working with them and how not to use them.
@@ -4,4 +4,4 @@ Design guidelines are sets of recommendations on how to apply design principles

 Visit the following resources to learn more:

- [@article@Design Guidelines](https://www.interaction-design.org/literature/topics/design-guidelines)
+- [@article@Design Guidelines](https://www.interaction-design.org/literature/topics/design-guidelines)
@@ -1,6 +1,3 @@
 # Icon

-The icon component is a way to align the way iconography static assets are displayed in the product.
-
- **Sizes:** Icons should have a number of predefined sizes to provide a holistic experience across the product. Typography pairings may be used for these size values to ensure that they are aligned with the text sizes.
- **Colors:** Icons should be using values from the design system colour palette. Using parent element text colour for icon fill colour can make this automatic.
+An icon is a small graphical symbol used to represent actions, objects, or concepts within a user interface. These visual elements provide immediate visual context and help users navigate applications more efficiently by replacing or supplementing text labels. In a design system, icons are standardized in terms of size, weight, and style to maintain a consistent visual language across all digital products.
@@ -1,8 +1,3 @@
-# Existing Design Process
+# Identify Existing Design Process

-To better understand the kind of design system you would like to implement, you need to start by reviewing and analyzing the current approach for design at your company. Find the answers to the following questions:
-
- What is the design process that your company follows?
- What are the existing tools that your company uses?
-
-It’s also recommended to evaluate the level of design maturity of the product teams. This knowledge will help you estimate the time required to introduce the system to your organization.
+Identifying the existing design process involves mapping out how a team currently creates, communicates, and implements design decisions. This phase requires gathering insights into how designers and developers collaborate, documenting the current workflow, and pinpointing the specific tools or manual tasks used to hand off assets. By clarifying these steps, teams can uncover inefficiencies, understand how UI patterns are currently maintained, and determine how to integrate new design system standards into established habits.
@@ -1,11 +1,3 @@
 # Input Checkbox
-
-An input checkbox is a form element used for selecting one or multiple options.
-
- **Checked State:** Used when the checkbox is selected and will use its value for the form submission.
- **Disabled State:** Prevents checkbox interactions and removes its value from the form submission.
- **Intermediate State:** Used when the checkbox has children selectable elements and only some of them are selected.
- **Label:** There should be a text label linked with the checkbox field. Clicking the label should also trigger the checkbox selection.
- **Error State:** The error state is used for form validation errors when the error is related to the checkbox field only. Always use a text error along with changing the colour of the field.
- **Keyboard State:** Checkbox selections should be triggered with the Space key. Using native elements for this should provide this kind of interaction out of the box.
- **Checkbox Group:** Checkboxes can be grouped to work with multiple values at the same time.
+ 
+An input checkbox component lets users select one or more options from a set of choices, toggling between a checked and unchecked state. It usually supports an indeterminate state as well, used when a checkbox represents a partially selected group of sub-options. Checkboxes are built with clear focus and disabled states to remain accessible via keyboard navigation.
@@ -1,10 +1,3 @@
 # Input Radio
-
-An input radio is a form element used for selecting one option from a list.
-
- **Checked State:** Used when the radio is selected and will use its value for the form submission. A radio input can’t be unselected by pressing it again.
- **Disabled State:** Prevents radio interactions and removes its value from the form submission.
- **Label:** There should be a text label linked with the radio field. Clicking the label should also trigger the radio selection.
- **Error State:** The error state is used for form validation errors when the error is related to the radio field only. Always use a text error along with changing the colour of the field.
- **Keyboard State:** A radio selection should be triggered when the Space key is pressed. Using native elements for this should provide this kind of interaction out of the box.
- **Radio Group:** Radio inputs should always be used in a group. If one of them is selected, it can be deselected only by choosing another radio.
+ 
+An input radio component lets users select exactly one option from a group of mutually exclusive choices. Radio buttons in a group share a common name so that selecting one automatically deselects the others. They are used instead of a dropdown when all options should be visible at once for easier comparison.
@@ -1,8 +1,3 @@
 # Input Switch
-
-Input switches toggle the state of a single item. Compared to the input checkbox, their changes usually apply without any additional submission.
-
- **Checked State:** Used when an input switch is turned on. It’s better to provide an additional way to indicate the checked state besides changing its colour when applicable.
- **Disabled State:** Prevents interacting with an input switch.
- **Label:** There should be a text label linked with the switch field. Clicking the label should also trigger the input selection.
- **Keyboard State:** A switch selection should be triggered when the Space key is pressed.
+ 
+An input switch, also called a toggle, lets users turn a single setting on or off, typically represented as a sliding control rather than a checkbox. It's commonly used for binary settings, like enabling notifications, where the on and off states have a clear, immediate effect. Switches usually include a visual and sometimes textual indicator of the current state.
@@ -1,11 +1,3 @@
 # Input Text

-Input text lets users enter and edit text.
-
- **Disabled State:** Prevents input interactions and removes its value from the form submission.
- **Placeholder:** When there’s no value entered, show a placeholder with a potential value example. Don’t use placeholders as labels for the inputs.
- **Label:** There should be a text label linked with the text field. Clicking the label should move the focus to the field.
- **Error State:** The error state is used for form validation errors when the error is related to the text field only. Always use a text error along with changing the colour of the field.
- **Focused State:** The focused state should highlight the text field when users start to interact with it. There is always only one focused field in the form.
- **Autocomplete:** When applicable, adding support for the HTML autocomplete attribute will allow users to easily enter different data types.
- **Icon Support:** Icons are used to describe input methods, express a text field state or provide additional functionality.
+An input checkbox component lets users select one or more options from a set of choices, toggling between a checked and unchecked state. It usually supports an indeterminate state as well, used when a checkbox represents a partially selected group of sub-options. Checkboxes are built with clear focus and disabled states to remain accessible via keyboard navigation.
@@ -1,3 +1,3 @@
 # Keywords

-Adding keywords will improve the discoverability of each icon and provide a better user experience for anyone using your system.
+Keywords are the searchable terms associated with each icon, used to help designers and developers find the right icon in a large icon library. An icon representing a trash can might include keywords like "delete," "remove," and "bin" so it surfaces under multiple search terms. Well-chosen keywords reduce duplicate icon requests when someone can't find an existing icon that already covers their need.
@@ -1,8 +1,3 @@
 # List
-
-Lists define the layout of the page content or groups of elements stacking them vertically or horizontally.
-
- **Support any type of content:** Lists can be used in any context from page-level layout to managing offsets between granular components. hey should work with any component used inside.
- **Horizontal Stacking:** Lists can be used for inline elements and they have to manage how they’re stacked horizontally, including handling offsets between multiple rows of elements.
- **Divided Variant:** Lists with dividers are the best practice advised by many platform guidelines (especially on mobile).
- **Supports Actionable Content:** Sometimes lists are used for grouping tappable components, where the whole area of the list item should be clickable.
+ 
+A list component displays a vertical sequence of items, each following the same layout, such as a list of contacts or notifications. It often supports variants like showing an icon, avatar, or action button alongside each item's text. Lists are commonly built to handle large datasets efficiently through virtualization when the number of items is high.
@@ -1,8 +1,3 @@
 # Loading Indicator
-
-The loading indicator shows that an operation’s being performed and how long the process will take.
-
- **Linear and non-linear Variants:** Depending on the context and the component it’s used for, the loading indicator can be represented either with linear or with a non-linear (e.g. circular) variant.
- **Determinate or indeterminate wait time:** In some cases, the wait time can’t be determined. The loading indicator should be shown until the loading finishes or an error happens. In other cases, it’s better to indicate how much time’s left until the loading is done.
- **Light Variant:** The loading indicator should respect its parent element background and provide a variant to be used on darker background colours.
- **Reduced Motion:** The loading indicator should be synced with the system motion settings and reduce its animation speed when reduced motion settings are turned on.
+ 
+A loading indicator communicates to the user that content is being fetched or processed, typically shown as a spinner, progress bar, or skeleton screen. It prevents the interface from appearing frozen or broken during delays caused by network requests or heavy computation. Design systems usually offer a few variants, such as a small inline spinner and a full-page loading state.
@@ -1,3 +1,3 @@
-# Error Logging
-
-Implement a way to track and pinpoint component-related outages in your product.
+# Logging
+ 
+Logging, in the context of a design system, means recording events and errors that occur when components are used in production, such as a component failing to render or receiving invalid props. Reviewing these logs helps the design system team catch bugs that only surface in real-world usage across different consuming products. It complements testing done before release by revealing issues that appear once components run at scale.
@@ -1,11 +1,11 @@
 # Making a Design System

-First step in building a design system is identifying [if you even need a design system](https://sparkbox.com/foundry/when_not_to_use_a_design_system).
+Making a design system is the process of creating a centralized collection of reusable components, standards, and documentation that guide the development of digital products. It involves establishing a shared language through design tokens, UI patterns, and accessibility guidelines to ensure visual and functional consistency across different interfaces. This workflow typically requires collaboration between designers and developers to build a scalable

 Visit the following resources to learn more:

- [@video@Introducing Design Systems Into Chaos - Diana Mounter, GitHub](https://www.youtube.com/watch?v=FZSi1bK-BRM)
- [@video@Design Systems, when and how much?](https://www.youtube.com/watch?v=Hx02SaL_IH0)
 - [@article@Design Systems: Step-by-Step Guide to Creating Your Own](https://www.uxpin.com/create-design-system-guide/)
 - [@article@Does My Organization Need a Design System?](https://www.method.com/insights/does-my-organization-need-a-design-system/)
- [@video@Create a Design System with Figma - Full Course](https://www.youtube.com/watch?v=RYDiDpW2VkM)
+- [@video@Introducing Design Systems Into Chaos - Diana Mounter, GitHub](https://www.youtube.com/watch?v=FZSi1bK-BRM)
+- [@video@Design Systems, when and how much?](https://www.youtube.com/watch?v=Hx02SaL_IH0)
+- [@video@Create a Design System with Figma - Full Course](https://www.youtube.com/watch?v=RYDiDpW2VkM)
@@ -1,7 +1,7 @@
 # From Existing Design

-If you are creating a Design System from pre-existing product design, there is an additional step to perform the existing design analysis, understand the existing design process, perform a visual audit, identify design elements and components and so on.
+Building from existing design means creating a design system by auditing and standardizing the UI of a product that already exists. This path starts with analyzing current screens, identifying inconsistencies, and extracting reusable patterns before formalizing them into tokens and components. It takes longer upfront than starting from scratch, since the team must reconcile years of inconsistent decisions first.

 Visit the following resources to learn more:

- [@video@Create a Design System with Figma - Full Course](https://www.youtube.com/watch?v=RYDiDpW2VkM)
+- [@video@Create a Design System with Figma - Full Course](https://www.youtube.com/watch?v=RYDiDpW2VkM)
@@ -1,7 +1,7 @@
 # From Scratch

-If you are building a Design System from Scratch, you may skip the "Existing Design Analysis" node of the roadmap and start with "Creating Design Language".
+There are two general paths for building a design system: creating one from scratch with a blank slate, or building one by analyzing and consolidating an existing product's design. The right approach depends on whether a product already exists and how much design debt has accumulated. Both paths eventually converge on the same outputs: design tokens, documented components, and guidelines.

 Visit the following resources to learn more:

- [@video@Create a Design System with Figma - Full Course](https://www.youtube.com/watch?v=RYDiDpW2VkM)
+- [@video@Create a Design System with Figma - Full Course](https://www.youtube.com/watch?v=RYDiDpW2VkM)
@@ -1,3 +1,3 @@
 # Microcopy Guidelines

-The standard way to write for the components in your design system. These take platform conventions and best practices for writing all into consideration.
+Microcopy guidelines provide a standardized framework for writing the small snippets of text that appear throughout an interface, such as button labels, error messages, and tooltips. These instructions outline the preferred voice, tone, vocabulary, and formatting standards to ensure that all user-facing text is clear, concise, and helpful.
@@ -1,3 +1,3 @@
 # Milestones
-
-Define milestones that act as bigger epics in your project management with the help of your roadmap. These will help you understand your progress.
+ 
+Milestones are specific checkpoints within a design system's roadmap that mark the completion of a significant piece of work, such as shipping a new component library version or completing an accessibility audit. They break a larger roadmap into measurable stages, making it easier to track progress over time. Milestones are often tied to specific dates or releases to create accountability.
@@ -1,10 +1,3 @@
 # Modal
-
-Modals are containers appearing in front of the main content to provide critical information or an actionable piece of content.
-
- **Supports any type of Content:** Like any other container, modals can be used in different scenarios and you should be able to use it with any other component inside.
- **Supplementary Actions:** Since content in the modal may be actionable, it’s important to have an area for action elements. This area is usually located at the bottom of the modal container.
- **Close Action:** Modals should provide a clear way to be closed as they’re blocking content when open. This may be either a separate close button or one of the supplementary actions.
- **Information Structure:** Even though modals can be used as an empty container for the content, they need a defined information structure to provide a holistic experience. It may include defining how titles and subtitles look by default or where an action element’s area is.
- **Keyboard Navigation Support:** It should be possible to close a modal by pressing the Esc key and all the focusable elements inside the modal container should be accessible with keyboard navigation.
- **Focus Trapping:** Once a modal is opened, the focus should be moved to the first element inside the modal and should be looped within the modal container. Closing the modal should return the focus to the last focused element on the page.
+ 
+A modal component displays content in a layer above the main page, requiring user interaction before returning to the underlying content, commonly used for confirmations or focused tasks. It typically includes a backdrop that dims the rest of the page and traps keyboard focus within the modal while it's open. Modals need careful accessibility handling to ensure focus returns to the triggering element once closed.
@@ -1,3 +1,3 @@
 # Monochrome Version

-A monochrome version of your logo that looks good on top of photography or when it’s printed with a poor quality printer.
+A monochrome version of a logo is a single-color variant used in contexts where the full-color logo doesn't work, such as on colored backgrounds, in print, or in low-contrast situations. It typically comes in both black and white variants to cover light and dark backgrounds. Design systems document exact usage rules for when to use the monochrome version instead of the primary logo.
@@ -1,3 +1,3 @@
 # Naming

-Name your icons based on what they are, not what they represent. For instance, a trash icon should be named trash, not delete. You can still add related keywords to improve discoverability.
+Naming conventions for icons define how each icon file or component is labeled, typically based on what it represents or the action it performs, such as "icon-search" or "icon-trash." Consistent naming makes icons easier to find and reference in code, especially as an icon set grows to hundreds of entries. Design systems usually document a naming pattern to avoid duplicate or ambiguous icon names.
@@ -4,6 +4,6 @@ Having a solid design system speeds up your work by making the product team more

 Visit the following resources to learn more:

- [@video@Design Systems, when and how much?](https://www.youtube.com/watch?v=Hx02SaL_IH0)
 - [@article@Why You Need a Strong Design System (and How to Build One)](https://www.drawbackwards.com/blog/why-you-need-a-strong-design-system-and-how-to-build-one)
 - [@article@On Design Systems: Sell The Output, Not The Workflow](https://www.smashingmagazine.com/2016/05/design-systems-responsive-design-sell-output-not-workflow/)
+- [@video@Design Systems, when and how much?](https://www.youtube.com/watch?v=Hx02SaL_IH0)
@@ -1,3 +1,3 @@
 # Open Hours
-
-Create open hours in which you can engage your audience in a more private setting where you can discuss things in more detail. You can also use these as peer coding or peer design opportunities.
+ 
+Open hours are scheduled time blocks during which the design system team is available for live questions, pairing sessions, or troubleshooting help from consuming teams. They give teams a predictable way to get direct support without waiting for a response in a ticket or chat channel. Open hours work especially well for onboarding teams that are new to using the design system.
@@ -1,3 +1,3 @@
 # Pattern

-Patterns are best practice design solutions for specific user-focused tasks and page types. Patterns often use one or more components and explain how to adapt them to the context. Some sample patterns could be user signing in to the application or performing the checkout operation.
+Patterns are best practice design solutions for specific user-focused tasks and page types. Patterns often use one or more components and explain how to adapt them to the context. Some sample patterns could be user signing in to the application or performing the checkout operation.
@@ -1,3 +1,3 @@
 # Performance

-Custom fonts need to be downloaded before they can be displayed, especially on the web. Make sure that you have sensible fallbacks and fast loading time for your typography assets. Using system fonts solves this performance problem.
+Custom fonts need to be downloaded before they can be displayed, especially on the web. Make sure that you have sensible fallbacks and fast loading time for your typography assets. Using system fonts solves this performance problem.
@@ -1,5 +1,3 @@
-# Visual Audit
+# Performing a Visual Audit

-Take screenshots of your current product with the help of your team. You can use any presentation software like Google Slides or print and pin them on foam-core boards. Group the screenshots into categories like buttons, navigation, forms, tables, charts, lists etc.
-
-Now, review each category to find inconsistencies and note areas for improvement with your team. Use a tool like [CSS Stats](https://cssstats.com/) to see how many unique colors, typefaces you have in your style sheets.
+A visual audit is the process of collecting and examining all existing user interface elements across a product to identify inconsistencies in styles, components, and patterns. This practice involves capturing screenshots of current screens and grouping similar items to reveal discrepancies in typography, color usage, spacing, and iconography. By documenting these variations, teams can establish a clear baseline of the current design state and prioritize the necessary cleanup or standardization required for the new design system.
@@ -5,4 +5,4 @@ Pilots are one of the best ways to put your design system through its paces, esp
 Visit the following resources to learn more:

 - [@official@Design Systems: Pilots & Scorecards](https://danmall.com/posts/design-systems-pilots-scorecards/)
- [@article@How to run a design system pilot](https://university.obvious.in/product-design/design-system/how-to-run-a-design-system-pilot)
+- [@article@How to run a design system pilot](https://university.obvious.in/product-design/design-system/how-to-run-a-design-system-pilot)
@@ -1,3 +1,3 @@
 # Plugins
-
-Most popular Design Editors (Sketch and Figma, especially) come with third-party plugin support. Whilst it's best to use the editors in-built tools for laying out your components, plugins can bring in a range of useful data to populate them.
+ 
+Plugins are add-on tools that extend a design editor's functionality, such as automating token synchronization, checking accessibility contrast, or generating code snippets from design components. They reduce manual work by connecting the design tool directly to other parts of the design system workflow, like a token repository or a documentation site. Teams often build custom plugins tailored to their specific design system setup.
@@ -1,3 +1,3 @@
-# Pull Request Templates
-
-Create pull request templates that outline the change being proposed to facilitate productive discussions.
+# PR Templates
+ 
+A PR template is a predefined structure that appears when someone opens a pull request, prompting contributors to fill in information like a description of the change, screenshots, and a checklist of required steps. It ensures every contribution includes the context a reviewer needs, rather than relying on contributors to remember what to include. Design systems use PR templates to keep the review process consistent as the number of contributors grows.
@@ -1,3 +1,3 @@
 # Project Management

-Design systems are no different than any other project your team might take on. In order to successfully build and maintain one, you need a clear strategy that’s well executed daily, and you‘ll need to create opportunities for your colleagues to give feedback to help share your design system together.
+Design systems are no different than any other project your team might take on. In order to successfully build and maintain one, you need a clear strategy that’s well executed daily, and you‘ll need to create opportunities for your colleagues to give feedback to help share your design system together.
@@ -1,3 +1,3 @@
 # Readability

-Optimising the letter spacing (tracking), line height (leading) and line length for your typography scale will help with the readability of text.
+Readability in typography covers the factors that make text easy to read, including font size, line height, line length, and contrast against the background. Design systems set minimum readability standards, such as a maximum number of characters per line or a minimum line height ratio, to prevent overly dense or cramped text. These standards apply across all typography tokens and components that display text.
@@ -1,3 +1,3 @@
 # Regional Requirements

-Understand any regional requirements such as LTR or any other UX variations that your design system should accommodate.
+Regional requirements are design and content constraints that differ by market, such as right-to-left text direction, date and currency formats, legal disclaimers, or color meanings that vary by culture. A design system built for a global product needs to account for these variations in its tokens and components rather than assuming one region's conventions apply everywhere. Ignoring regional requirements usually surfaces as bugs or complaints once a product expands to new markets.
@@ -1,3 +1,3 @@
 # Release Strategy
-
-Design system releases should be automated and ideally use scripts ran locally or in remote CI pipelines to prevent broken releases.
+ 
+A release strategy defines how and how often new versions of a design system get published, including whether releases happen on a fixed schedule or whenever changes are ready. It also covers how breaking changes get communicated and how long older versions remain supported. A clear release strategy helps consuming teams plan when to upgrade without being caught off guard by unexpected changes.
@@ -1,3 +1,3 @@
 # Reserved Icons

-Reserving icons that represent common actions will prevent their use in any other context. System icons for navigation or adding and deleting are a good example. This leads to a more intuitive user experience.
+Reserving icons that represent common actions will prevent their use in any other context. System icons for navigation or adding and deleting are a good example. This leads to a more intuitive user experience.
@@ -1,3 +1,3 @@
 # Responsiveness

-Desktop devices can usually afford to have bigger font sizes compared to mobile devices. Creating a typography scale that adapts to the viewport size will help with a more meaningful hierarchy and layout.
+Desktop devices can usually afford to have bigger font sizes compared to mobile devices. Creating a typography scale that adapts to the viewport size will help with a more meaningful hierarchy and layout.
@@ -1,3 +1,3 @@
 # Roadmap
-
-Setting your short and long term vision and mapping things out helps you decide the steps to take, understand your place in the bigger picture and prioritise day-to-day tasks.
+ 
+A roadmap, in project management terms, is a high-level plan that outlines what a design system team intends to build or improve over a given period, such as new components or major token changes. It helps set expectations with consuming teams about what's coming and in what order. Roadmaps are typically reviewed and adjusted regularly as priorities shift based on feedback and adoption needs.
@@ -1,11 +1,3 @@
 # Select

-Select lets user select a value from a list of values in a form context:
-
- **Disabled State:** Prevents input interactions and removes its value from the form submission.
- **Placeholder:** When there’s no value entered, show a placeholder with a potential value example. Don’t use placeholders as labels for the inputs.
- **Label:** There should be a text label linked with the text field. Clicking the label should move the focus to the field.
- **Error State:** The error state is used for form validation errors when the error is related to the text field only. Always use a text error along with changing the colour of the field.
- **Focused State:** The focused state should highlight the text field when users start to interact with it. There is always only one focused field in the form.
- **Autocomplete:** When applicable, adding support for the HTML autocomplete attribute will allow users to easily enter different data types.
- **Icon Support:** Icons are used to describe input methods, express a text field state or provide additional functionality.
+A select component is an interface element that allows users to choose one or more options from a predefined list. It typically appears as a dropdown menu that remains collapsed to save screen space until the user clicks or taps on it. Once activated, the component expands to display the available choices, making it an efficient way to handle long lists of data while maintaining a clean and organized layout.
@@ -1,3 +1,3 @@
 # Semantic Versioning
-
-Version your code with semantic versioning that dictates how version numbers are assigned and incremented.
+ 
+Semantic versioning is a version numbering convention, formatted as major.minor.patch, used to communicate the type of change made in each release of a design system's code. A major version bump signals a breaking change, a minor version adds new functionality without breaking existing usage, and a patch fixes bugs. Following this convention lets teams consuming the design system understand the risk of upgrading to a new version at a glance.
@@ -1,3 +1,3 @@
 # Service and Health Metrics
-
-Define service and health metrics for your design system to set a benchmark on how well you’re doing. Common examples can be the number of tickets closed, improvements made or bugs fixed.
+ 
+Service and health metrics track the overall reliability and performance of a design system as a product in its own right, such as build times, uptime of documentation or component hosting, and how quickly reported bugs get resolved. These metrics give the team an objective view of how well the design system is being maintained, beyond just component-level usage. They're often reported to stakeholders as evidence of the system's ongoing value.
@@ -1,3 +1,3 @@
 # Sizes

-Provide different sizes for icons that correlate to your grid. Provide a minimum size and remove unnecessary detail for your icons for smaller sizes.
+Icon sizes define the standard dimensions an icon set supports, such as 16px, 24px, and 32px, so icons remain crisp and consistent wherever they appear. Design systems typically build icons on a fixed grid at each supported size to keep stroke widths and proportions consistent across the set. Components reference these standard sizes rather than scaling icons arbitrarily.
@@ -1,5 +1,7 @@
 # Small Use Guidance

-Your logo must perform well and be recognisable at all sizes. Tips for using your logo in these cases will minimise the risk of it being misused.
+Small use guidance provides specific instructions and design adjustments for rendering a logo at minimal sizes, such as in favicons, mobile headers, or social media avatars. This involves simplifying complex shapes, removing intricate text, or increasing the contrast of visual elements to ensure the brand remains recognizable and legible at very low resolutions. By establishing these constraints, you ensure that the logo maintains its visual integrity and professional appearance across all digital touchpoints.

- [@article@Everything You Need to Know About Logo Usage Guidelines](https://www.tailorbrands.com/blog/logo-usage-guidelines)
+Visit the following resources to learn more:
+
+- [@article@Everything You Need to Know About Logo Usage Guidelines](https://www.tailorbrands.com/blog/logo-usage-guidelines)
@@ -1,3 +1,3 @@
 # Spacing

-Horizontal and vertical rhythm plays a big role in a layout. You should provide easy methods for adding space between interface elements independent of your grid.
+Spacing tokens define the standard set of gap and padding values used between and within components, usually built as a scale of multiples of a base unit. Having a fixed spacing scale prevents designers and developers from picking arbitrary pixel values, which keeps layouts visually consistent. Components reference spacing tokens for their internal padding and the gaps between elements.
@@ -1,16 +1,7 @@
-# Stakeholders
+# Stakeholders Involved in Building

-Building an effective design system is not an individual responsibility, you need more than just designers. Here’s a quick list of the disciplines that can be represented in your team to create an effective design system:
-
- **Designers:** to define the visual elements of the system
- **Frontend Developers:** To create modular efficient code
- **Accessibility Experts:** Accessibility experts to ensure your system conforms to standards like WCAG
- **Performance Experts:** who can ensure your system loads quickly on all devices
- **Content Strategists:** who can help the team nail the voice and tone of the system
- **Researchers:** who can help you understand customer needs
- **Product Managers:** to ensure the system is aligning to customer needs
- **Leaders:** (VPs and directors) to champion and align the vision throughout the company including up to executive leadership
+Building a design system requires input from several roles, not just designers. Product designers define visual language and interaction patterns, frontend developers implement and maintain components in code, product managers align the system with business priorities, and accessibility specialists ensure components meet usability standards. Leadership buy-in and cross-team communication are also needed, since a design system only works if multiple product teams agree to adopt it.

 Visit the following resources to learn more:

- [@article@Designing the Design System](https://www.designbetter.co/design-systems-handbook/designing-design-system)
+- [@article@Designing the Design System](https://www.designbetter.co/design-systems-handbook/designing-design-system)
@@ -1,3 +1,3 @@
 # Style

-Make sure that your icon family makes visual sense as a whole. Picking an outlined or filled style and sticking with it will lead to better visual consistency and predictability.
+In iconography, style refers to the consistent visual approach used across a set of icons, such as outlined, filled, or duotone, along with consistent stroke width and corner treatment. Keeping a single style across all icons prevents a product from feeling visually disjointed when icons from different sources get mixed together. Style guidelines usually specify exact stroke widths and corner radii to keep new icons consistent with existing ones.
@@ -1,9 +1,3 @@
 # Tabs
-
-Tabs organise navigation between multiple pages or content sections.
-
- **Active Button State:** There should be a clear differentiation between selected and unselected tab buttons.
- **Button Icon Support:** Icons help show the purpose of the tab buttons when used next to its label.
- **Equally-sized tab buttons:** Tabs can be used in a relatively small-sized container where you need to switch between a definite number of sections. For such scenarios, it’s better to support a variant where the button’s area is divided equally.
- **Keyboard Navigation:** All tab buttons should be focusable and navigation between the tab’s component should be accessible from the keyboard.
- **Responsiveness:** If all tabs on mobile don’t fit into the viewport, users should still have access to all tab buttons. Ways to solve this can be making the button area scrollable for mobile or showing a More button containing a dropdown with the rest of the buttons.
+ 
+A tabs component lets users switch between different views or sections of content within the same page area, without navigating to a new page. Each tab typically shows a label and, when selected, displays its associated content while hiding the others. Tabs need keyboard support so users can navigate between them using arrow keys.
@@ -1,3 +1,3 @@
 # Terminology

-Create the standard terms and phrases that need to be kept the same throughout the user experience, speeding up the design process and unifying your voice.
+Create the standard terms and phrases that need to be kept the same throughout the user experience, speeding up the design process and unifying your voice.
@@ -4,4 +4,4 @@ Design systems can be tricky if you don’t know what certain words mean. Have a

 Visit the following resources to learn more:

- [@article@Design Systems Glossary](https://web.archive.org/web/20220620075140/https://superfriendly.com/design-systems/glossary/)
+- [@article@Design Systems Glossary](https://web.archive.org/web/20220620075140/https://superfriendly.com/design-systems/glossary/)
@@ -1,9 +1,3 @@
 # Textarea

-Text area lets users enter and edit text.
-
- **Disabled State:** Prevents input interactions and removes its value from the form submission.
- **Placeholder:** When there’s no value entered, show a placeholder with a potential value example. Don’t use placeholders as labels for the inputs.
- **Label:** There should be a text label linked with the text field. Clicking the label should move the focus to the field.
- **Error State:** The error state is used for form validation errors when the error is related to the text field only. Always use a text error along with changing the colour of the field.
- **Focused State:** The focused state should highlight the text field when users start to interact with it. There is always only one focused field in the form.
+A textarea component is a multi-line text input used for longer form entries, such as comments or descriptions, as opposed to a single-line text input. It usually supports resizing, character count limits, and validation states like error or success. Textareas share styling conventions with other input components to keep form fields visually consistent.
@@ -1,3 +1,3 @@
 # Ticketing
-
-Make it easier to track your day-to-day progress by using ticketing software like Jira, Trello or GitHub. This’ll make it easier for others to submit feature proposals or bug reports.
+ 
+Ticketing refers to the system used to track individual tasks, bugs, and feature requests related to a design system, typically using tools like Jira or Linear. Each ticket captures a specific piece of work, such as adding a new component variant or fixing an accessibility issue, along with its status and assignee. A well-maintained ticketing system gives the team and stakeholders visibility into what's currently being worked on.
@@ -1,9 +1,3 @@
 # Toast
-
-Toasts provide short meaningful feedback messages about the action results.
-
- **Dismissed Automatically:** Toast messages shouldn’t interrupt the user flow, block the screen for a long time or require additional action from the user.
- **Action Support:** Besides displaying the message, toasts may also provide an action related to the message like undoing an action.
- **Handles Multiple Instances:** Even though it doesn’t happen often, toasts can be called from multiple sources at the same time and all resulting toasts should be queued. It’s good practice not to show all the messages at the same time.
- **Accessibility:** Toast messages should be announced by the voice assistive technology and their action should be easily accessible from the keyboard.
- **Responsivenss:** Toasts should be aligned with the mobile viewport and their action should be easily reachable for tapping.
+ 
+A toast component displays a brief, temporary message that appears and disappears automatically, typically used for confirmations like "Changes saved" or lightweight error notices. Unlike a banner, a toast floats above the page content and doesn't require the user to dismiss it manually. Toasts are commonly positioned in a corner of the screen and stack when multiple messages appear at once.
@@ -4,4 +4,4 @@ Design system tokens are the style values of UI elements such as color, typograp

 Visit the following resources to learn more:

- [@article@What Are Design Tokens?](https://xd.adobe.com/ideas/principles/design-systems/what-are-design-tokens/)
+- [@article@What Are Design Tokens?](https://xd.adobe.com/ideas/principles/design-systems/what-are-design-tokens/)
@@ -1,3 +1,3 @@
 # Tone of Voice

-A clear tone of voice defines how you speak to your audience at every moment in their journey, helping them get wherever they want to go.
+Tone of voice describes the personality and style a brand uses when communicating with users through text, such as being friendly, formal, or playful. It shapes word choice, sentence length, and how messages are framed, especially in things like onboarding copy, error messages, and notifications. A defined tone of voice keeps a product's writing consistent even as multiple people contribute copy over time.
@@ -1,3 +1,3 @@
 # Tooling Analytics
-
-Track what tools are being used for your design system. Find out which ones are used the most and which features are the most popular.
+ 
+Tooling analytics measure how the design system's own supporting tools get used, such as how often a Figma plugin runs, how frequently the documentation site is visited, or how often the component catalog is searched. This data helps the team understand which tools deliver value and which ones go unused. It informs decisions about where to invest further tooling effort.
@@ -1,9 +1,3 @@
 # Tooltip
-
-Tooltips are desktop-only components that display additional information when hovering over or focusing on an element.
-
- **Keyboard Hover Support:** Tooltips should be accessible when an element is focused using the keyboard.
- **Dynamic Positioning:** Tooltip content should be displayed based on the current position of the trigger element on the screen and always visible to the user.
- **Hover Timeout:** Having a small timeout before triggering a tooltip will help to prevent occasionally showing tooltips while users move their mouse cursor.
- **Light Variant:** The tooltip should respect its parent element background and provide a variant to be used on darker background colours.
- **Instant Transition for Element Groups:** If there’s a group of elements using tooltips, hovering over another element while a tooltip’s already active shouldn’t trigger the animation.
+ 
+A tooltip component displays a small piece of contextual information when a user hovers over or focuses on an element, typically used to explain an icon-only button or provide extra detail. It appears near the triggering element and disappears once the user moves away or shifts focus elsewhere. Tooltips need to be accessible via keyboard focus, not just mouse hover, to work for all users.
@@ -5,4 +5,4 @@ As it relates to a design system, a UI Kit is a representation of coded componen
 Visit the following resources to learn more:

 - [@article@Design System vs UI Kit](https://uigstudio.com/insights/design-system-vs-ui-kit)
- [@article@Your sketch library is not a design system](http://bradfrost.com/blog/post/your-sketch-library-is-not-a-design-system/)
+- [@article@Your sketch library is not a design system](http://bradfrost.com/blog/post/your-sketch-library-is-not-a-design-system/)
@@ -1,10 +1,10 @@
 # Design System Basics

-A design system is a set of standards to manage design at scale by reducing redundancy while creating a shared language and visual consistency across different pages and channels.
+This covers the foundational concepts a team needs before building or adopting a design system. It includes what a design system actually is, why it matters, how it differs from a plain component library, and who needs to be involved to make it work. Getting these basics right sets the direction for every decision that follows.

 Visit the following resources to learn more:

 - [@article@Design Systems 101](https://www.nngroup.com/articles/design-systems-101/)
- [@video@What is a Design System? Design Systems 101 for Designers](https://www.youtube.com/watch?v=wc5krC28ynQ)
 - [@article@How to build your design system](https://www.figma.com/blog/design-systems-102-how-to-build-your-design-system/)
 - [@article@Everything you need to know about Design Systems](https://uxdesign.cc/everything-you-need-to-know-about-design-systems-54b109851969)
+- [@video@What is a Design System? Design Systems 101 for Designers](https://www.youtube.com/watch?v=wc5krC28ynQ)
@@ -1,3 +1,3 @@
 # Unit Testing
-
-Every part of the design system should be covered with unit tests. Once your system’s adopted, any change in the isolated environment may affect how the product works.
+ 
+Unit testing means writing automated tests that verify individual components behave correctly in isolation, such as checking that a button calls its click handler or that a checkbox toggles its state correctly. These tests catch regressions early when a component's code changes, before the change reaches production. Design systems rely heavily on unit tests since a bug in a shared component can affect every product that uses it.