when applicable (e.g., address fields, multi-step forms).
- Provide clear and descriptive error messages, ensuring they appear close to the relevant input fields.
- Use appropriate input types (email, tel, date, etc.) to optimize accessibility and improve validation.
**Validation & Error Handling**
- Ensure errors are clearly visible and have clear instructions on how to correct mistakes.
- Forms should prevent accidental data loss by prompting users before navigating away if unsaved changes exist.
- A reset function should allow users to clear the form efficiently when needed.
- Indicate a successful form submission with confirmation messages or redirect to a relevant success page or success state.
Design Rationale
- Consistency: The form component standardizes data input across the platform, ensuring a uniform experience.
- Accessibility First: By enforcing label association and validation messages, the form supports inclusive design principles.
- Flexibility: Supports both native and custom elements, allowing adaptation to complex use cases such as multi-step forms and dynamic field updates.
- Error Prevention: Provides feedback mechanisms to guide users toward accurate data entry and reduce submission errors.
---
## Horizontal
### Horizontal Usage
The `Horizontal` component arranges child elements horizontally with configurable spacing. It provides a standardized way to arrange child elements horizontally with consistent spacing between them.
#### Horizontal Typical usage pattern
- Use for arranging form elements, buttons, or other UI components side by side
- Place within sections or other layout components to group related elements
- Use different spacing variants (xxs, xs, s, m, l, xl) to control gaps between items
- Combine with `m-vertical` for complex nested layouts
---
## IconList
### IconList Examples
#### IconList Default Example
```html
Simple feature
Feature with bold text
```
### IconList Usage
**Use the Icon List to:**
- Visually represent steps in a process (e.g., onboarding, approval workflows).
- Display key features of a product or service.
- Communicate statuses (e.g., success, warning, error messages).
- Organize categorical information (e.g., permissions, user roles, benefits).
- Improve scannability in data-heavy interfaces.
**Do not use the Icon List to:**
- Replace tables or grids when structured data is needed.
- Overload the UI with excessive icons that do not add meaning.
- Use complex or highly detailed illustrations (stick to simple, recognizable icons).
### IconList Other Considerations
- Ensure each icon has text context—icons alone should not convey critical information.
- Icons should be uniform in size within the list to maintain alignment.
### IconList Design Rationale
- **Enhances Readability:** Icons act as visual cues, making information easier to process.
- **Supports Quick Decision-Making:** Users can scan lists faster with recognizable symbols.
---
## Icon
### Icon Examples
#### Icon Default Example
```html
```
#### InputMonth WithDescription Example
```html
```
#### InputMonth InForm Example
```html
Submit
```
#### InputMonth MultipleInputs Example
```html
```
#### InputMonth WithLongLabels Example
```html
```
#### InputText FullWidth Example
```html
```
#### InputText WithButton Example
```html
📋 Button Slot Guidelines:
✅ Use only m-button components with variant="default"
✅ Keep buttons simple and focused on immediate actions
❌ Avoid complex interactive components or popovers
❌ For date pickers, use m-datepicker component instead
Simple Action Buttons
Search
Icon-Only Buttons
Error State
Send
```
### InputText Usage
**Use an Input to:**
- Allow users to enter freeform text (e.g., names, job titles, email addresses).
- Collect structured data such as numbers, dates, or passwords.
- Provide search functionality where users can input keywords.
**Do not use an Input to:**
- Select from predefined options (use radio buttons, checkboxes, or dropdowns instead).
- Display non-editable information (use a text display component instead).
- Input complex formatted data without validation (ensure proper input masks or formatting helpers are used).
### InputText Button Slot Guidelines
The `button` slot is designed for simple action buttons that provide immediate functionality. **Only use default buttons in the button slot** - avoid complex components like popovers, dropdowns, or other interactive elements.
**✅ Recommended:**
- Simple action buttons (copy, send, search)
- Toggle buttons (show/hide password)
- Icon-only buttons
- Reset or clear buttons
**❌ Not Recommended:**
- Popover-wrapped buttons
- Dropdown menus
- Complex interactive components
- Date pickers (use m-datepicker component)
For complex button interactions, use specialized components like m-datepicker or create custom implementations.
### InputText Other Considerations
- Ensure every input field has a descriptive label.
- Use placeholder text sparingly — it should not replace labels as it disappears when users type.
- Include error messages and validation hints for incorrect or missing input.
- Labels should be short, clear, and aligned with the user’s expectations (e.g., "First Name", "Phone Number").
- Provide help text when input expectations may be unclear (e.g., password rules).
- Restrict input types appropriately (e.g., type="email" for email fields, type="number" for numeric input).
### InputText Design Rationale
Alignment with standards ensures all users, including those with disabilities, can interact with input fields effectively.
---
## Link
### Link Examples
#### Link SimpleText Example
```html
The link component (
You can configure your preferences in the
```
#### Link Size Example
```html
```
### Link Usage
**Use Link to:**
- Navigate users to another page within the same platform (e.g., from a notification to the employee profile).
- Link to external content, such as HR policies, legal terms, or help center articles.
- Provide downloadable file links (e.g., “Download salary statement PDF”).
- Link to email or phone contacts using mailto: or tel: links.
**Do not use Link to:**
- Trigger UI actions like opening modals or submitting forms (use a button instead).
- Simulate navigation without a valid href (this breaks accessibility and keyboard support).
- Create links with generic or ambiguous text (e.g., “Click here” or “More”).
### Link Other Considerations
- Always include a meaningful href — empty or missing values make links unusable for assistive tech.
- Use descriptive link text that clearly communicates the destination or purpose.
### Link Design Rationale
- A well-understood, accessible pattern for navigation across the web.
- Aligning with WCAG and usability best practices ensures a more inclusive, intuitive experience.
---
## List
### List Examples
#### List UnorderedList Example
```html
First item
Second item
Third item
Fourth item
```
#### List OrderedList Example
```html
First step
Second step
Third step
Fourth step
```
#### List WithLabel Example
```html
Read the manual
Prepare the materials
Follow the steps
```
#### List WithLongContent Example
```html
This is a significantly longer list item that contains substantially more text to thoroughly demonstrate how the component handles wrapping content across multiple lines. The text should wrap naturally and maintain proper spacing and alignment throughout the entire content area.
Another item with extensively expanded content that comprehensively shows the styling behavior when text wraps to multiple lines, ensuring that all visual elements remain properly aligned and the overall design maintains its integrity regardless of content length.
Short item
Yet another considerably longer item that demonstrates the consistent spacing and formatting across different content lengths, providing a comprehensive example of how the component adapts to varying amounts of textual information while preserving readability and visual appeal.
First step in a much longer process that requires multiple lines of text to fully explain all the necessary details, context, and background information that users need to understand before proceeding with the subsequent steps in this comprehensive workflow.
Second step with additional extensive details and context that may span multiple lines, providing users with all the information they need to successfully complete this particular phase of the process while maintaining clarity and avoiding any potential confusion.
Third step
Final step with comprehensive instructions that include all necessary information, detailed explanations, important considerations, and any additional context that might be relevant for users to successfully complete the entire process from start to finish.
```
#### List WithLinks Example
```html
First link Second link Third link
```
#### List Default Example
```html
First item
Second item
Third item
```
---
## MainNav
### MainNav Examples
#### MainNav Default Example
```html
```
#### MainNav WithActiveItem Example
```html
```
#### MainNav WithDisabledItems Example
```html
```
#### MainNav MobileView Example
```html
{
const navigationData = {
mainNav: [
{ label: "Dashboard", href: "/dashboard" },
{ label: "Settings", href: "/settings", active: true },
{ label: "Profile", href: "/profile" }
],
subNav: [
{ label: "Account", href: "/settings/account" },
{ label: "Security", href: "/settings/security", active: true },
{ label: "Preferences", href: "/settings/preferences" }
],
currentPage: "Security",
currentLevel: 2
};
return html`
Mobile View (≤768px)
Resize your browser to ≤768px width to see mobile navigation
`;
}
```
#### MainNav WithSlots Example
```html
```
---
## MenuGroup
### MenuGroup Examples
#### MenuGroup Default Example
```html
```
#### MenuGroup WithoutTitle Example
```html
```
#### MenuGroup WithMenuComponent Example
```html
Open Menu
```
#### MenuGroup MixedContent Example
```html
Open Menu
```
#### MenuGroup UserMenuExample Example
```html
```
---
## Menu
### Menu Examples
#### Menu Default Example
```html
Open Menu
```
#### Menu WithSlottedMenuItems Example
```html
Open Menu
```
#### Menu WithComplexSlottedContent Example
```html
Open Menu
Project Settings
Configure your project preferences
Last modified: 2 hours ago
View Project History
```
#### Menu WithMenuGroups Example
```html
Open Menu
```
#### Menu WithCustomTrigger Example
```html
Custom Trigger
```
#### Menu WithDisabledItems Example
```html
Open Menu
```
#### Menu WithOverlay Example
```html
Open Menu
```
#### Menu SingleGroup Example
```html
Open Menu
```
#### Menu WithCustomContent Example
```html
Open Menu
John Doe
john.doe@example.com
Custom content can be added using the content slot
Custom Button
```
#### Menu PlacementExamples Example
```html
Top Left
Top Right
Bottom Left
Bottom Right
```
#### Menu WithClickEvents Example
```html
console.log('Menu item clicked:', e.detail.item.label)}
>
Click Me
```
#### Menu WithLinks Example
```html
Open Menu
```
#### Menu WithHeader Example
```html
Open Menu
John Doe
john.doe@example.com
```
#### Menu SimpleItems Example
```html
Open Menu
```
#### Menu BottomSheet Example
```html
Open Bottom Sheet Menu
```
---
## NavGroupApp
---
## NavGroup
### NavGroup Examples
#### NavGroup Default Example
```html
```
#### NavGroup WithoutHeading Example
```html
```
---
## Nav
### Nav Examples
#### Nav Default Example
```html
```
---
## Password
### Password Examples
#### Password Default Example
```html
```
### Password Usage
**Use a Password Input to:**
- Collect secure user credentials for logging in or creating an account.
- Allow users to set or update passwords in profile settings.
- Ensure password confidentiality by masking input characters.
**Do not use a Password Input to:**
- Collect non-sensitive information (use a standard input field instead).
- Display static passwords (use a readonly text field with obfuscation if needed).
- Auto-fill passwords without user consent (browser-managed password storage should be leveraged instead).
### Password Other Considerations
- Provide a clear label (e.g., "Enter Password") and do not rely solely on placeholders.
- Add password policies as a hint text (e.g., minimum length, special characters, case sensitivity).
- Use error messages for invalid passwords (e.g., "Password must be at least 8 characters").
### Password Design Rationale
- Enhances security by masking password.
- Balances accessibility and security by giving users control over password visibility.
- Improves usability with visibility toggle.
---
## Popover
### Popover Examples
#### Popover Default Example
```html
Toggle Popover
Popover Content
Placement: ${args.placement}
```
#### Popover HeaderDemo Example
```html
Open Header Popover
This popover demonstrates the basic header functionality:
Title in the header
Close button
Standard placement
```
#### Popover HeaderVariations Example
```html
Basic Header
Basic Header
Standard header with default styling.
Long Title
Long Title
Header with a long title to test truncation.
With Overlay
With Overlay
Header with overlay background.
No Header
No Header
Popover with header explicitly disabled.
```
#### Popover BottomSheetWithHeader Example
```html
Open Bottom Sheet
This demonstrates header behavior in bottom sheet mode:
Full width on mobile
Header stays fixed at top
Content scrolls underneath
Close button for easy dismissal
Option 1
Option 2
Option 3
Action Button
```
#### Popover OverlayDemo Example
```html
Open Overlay Popover
Overlay Demo
This popover has an overlay that dims the background content.
Click outside or on the overlay to close the popover.
Button Inside
```
#### Popover PlacementDemo Example
```html
Top Start
Top Start Popover
Top
Top Popover
Top End
Top End Popover
Left
Left Popover
Center
Bottom (default)
Bottom Popover
Right
Right Popover
Bottom Start
Bottom Start Popover
Bottom
Bottom Popover
Bottom End
Bottom End Popover
```
#### Popover ViewportEdgeDemo Example
```html
Top Edge
This popover should flip to bottom when near the top edge.
Right Edge
This popover should flip to left when near the right edge.
Bottom Edge
This popover should flip to top when near the bottom edge.
Left Edge
This popover should flip to right when near the left edge.
```
#### Popover LargeContent Example
```html
Show Large Content
Large Content Popover
This demonstrates how the popover handles large content:
Content is scrollable if it exceeds viewport
Maintains max-width and max-height constraints
Preserves placement when possible
Flips placement when needed
Try resizing the window to see how it adapts!
```
#### Popover FocusTrapDemo Example
```html
```
### Popover Usage
A Popover is a floating panel that appears on user interaction, providing additional information or controls without navigating away from the main interface. Unlike traditional tooltips, which provide simple text hints, popovers can contain rich content like buttons, links, forms, and images.
The Popover API allows for native, accessible, and efficient rendering of popovers in modern web applications, reducing reliance on JavaScript-heavy solutions.
**Use the Popover to:**
- Display contextual information on demand, such as additional details about a user, job listing, or setting.
- Provide lightweight interactions, such as quick actions or filtering options, without navigating away.
- Show explanations or descriptions, reducing cognitive load.
- Replace traditional dropdowns for richer, interactive content.
- Display non-blocking alerts or notifications.
**Do not use the Popover to:**
- Display critical alerts or confirmation dialogs. Use dialog instead.
- Replace full-screen navigation or complex multi-step workflows.
- Hide essential information that should always be visible.
### Popover Other Considerations
- Provide a close button or mechanism to dismiss the popover when needed.
- Position the popover near the triggering element while avoiding screen edges.
- Use auto-placement where possible to avoid popovers going off-screen.
- Dismiss popovers when clicking outside or pressing the Escape key.
- Ensure content inside the popover does not cause layout shifts when opening.
- Improved Native Support: The Popover API is a modern web standard that eliminates the need for custom JavaScript-heavy implementations.
- Better Performance: Unlike traditional JS-based popovers, native popovers do not require complex event handling and reduce memory usage.
- Accessibility-First Approach: The popover API ensures compliance with WCAG and ARIA guidelines, making the interface more inclusive.
- Seamless User Experience: Popovers provide additional content when necessary without disrupting the main workflow.
---
## ProductLeadForm
### ProductLeadForm Examples
```html
Are you interested?
Information about why user should contact us. Fill and send the form and
we will tell you more.
```
---
## ProgressBar
### ProgressBar Examples
#### ProgressBar Default Example
```html
In progress
```
#### ProgressBar WithTextOnly Example
```html
Uploading files...
```
#### ProgressBar CircleOnly Example
```html
Progress: 50%
```
---
## PromotionDialog
### PromotionDialog Examples
#### PromotionDialog Default Example
```html
Open dialog
Category information
Accessible header for dialog
Visual header
Short description of the promotion.
Key benefits and features (optional)
Simple feature description
Feature with **markdown** support
Cancel
Learn more
```
#### PromotionDialog WithAppMenu Example
```html
Additional service!
Learn about our additional service
Effortless onboarding with Intro
Welcome new employees with ease using Intro’s smart and engaging
onboarding solution. Automate repetitive tasks, ensure a consistent
experience, and help new hires feel at home from day one. Say goodbye to
manual processes—Intro does the heavy lifting for you.
Key features
Tailored onboarding flows – Create personalized
journeys that reflect your company culture.Automated task management – Keep new hires on track
with structured guidance.Seamless integrations – Connect effortlessly with
your existing HR tools.
Ready to elevate your onboarding?
Discover how Intro can transform your onboarding experience. Fill out
the form below, and our team will be in touch!
Cancel
```
### PromotionDialog Usage
The Promotion Dialog component is designed to enable seamless promotion of product-led features and services. It helps guide users towards exploring and activating new offerings by leveraging a structured and user-friendly dialog.
#### PromotionDialog Key Use Cases
- Feature Promotion: Highlight new or underutilized features within the product.
- Service Upgrades: Offer upgraded plans or add-on services directly to users.
- Beta Invitations: Enable admins or users to join beta programs or trials.
#### PromotionDialog Example Scenarios
- Introducing AI-powered recommendations in a recruitment application.
- Inviting users to activate a free beta for a feature set within their organization.
- Promoting an upgrade to premium services during feature exploration.
#### PromotionDialog Placement
- Trigger the dialog using action buttons, inline promotions, or notifications.
- Avoid using persistent triggers for promotions to prevent user fatigue.
- Ensure the promotion dialog aligns with the overall application’s visual hierarchy.
### PromotionDialog Design Rationale
- Focused Engagement: The modal dialog ensures user attention is directed to the promotion without distractions.
- Guided Actions: Clear CTAs and error handling guide users seamlessly through the process.
- Accessibility: Ensures compliance with accessibility standards (e.g., ARIA roles, focus trapping).
---
## RadioGroup
### RadioGroup Examples
#### RadioGroup Default Example
```html
This is a helpful hint text
This is a helpful description text
Mixed content example
This group uses both slots and items property
```
#### RadioGroup WithError Example
```html
Custom error message
```
#### RadioGroup Horizontal Example
```html
```
#### RadioGroup HorizontalWithItems Example
```html
```
#### RadioGroup States Example
```html
```
---
## Radio
### Radio Examples
#### Radio Default Example
```html
```
#### Radio States Example
```html
```
#### Radio WithHint Example
```html
This field is required
```
#### Radio WithCustomContent Example
```html
Custom formatted label
Custom formatted hint
Custom formatted error
```
### Radio Usage
**Use a Radio Button to:**
- Allow users to select one option from a list when multiple choices exist.
- Present mutually exclusive options, where selecting one automatically deselects others.
- Indicate a required selection, ensuring that users make a decision before proceeding.
**Do not use a Radio Button to:**
- Allow multiple selections (use checkboxes instead).
- Toggle a single setting on or off (use a checkbox or toggle switch instead).
- Display a long list of options (consider a dropdown for better space management).
### Radio Other Considerations
- Ensure each radio button descriptive labels that clearly communicate the choice (e.g., “Full-time”, “Part-time”).
- Avoid using vague options like “Yes” and “No” unless the context is clear.
- Default to the most common or recommended option when appropriate.
- Visually group related options under a heading or a question to provide context.
- Ensure that all radio buttons in a group are logically ordered for a smooth user experience.
### Radio Design Rationale
- Mutual exclusivity ensures users can only select one option, preventing conflicting choices.
- Immediate feedback provides clarity, as selecting one option automatically deselects the others.
- Ease of use makes radio buttons a familiar and effective choice for form inputs.
- Consistency with accessibility guidelines ensures that all users, including those using assistive technologies, can easily interact with radio buttons.
---
## Section
### Section Examples
#### Section WithLongTitleAndAction Example
```html
This is a Very Long Section Title That Demonstrates How the Layout Handles Extended Text Content
Active
This section demonstrates how the actions slot behaves when the title is quite long and takes up significant space.
Content Item 1
Content Item 2
Content Item 3
```
### Section Usage
The `Section` component provides a semantic container with header and content areas. It creates a standardized section layout with optional title and description areas, followed by the main content. It provides consistent spacing and typography for section headers and content, with support for different heading levels and description text.
#### Section Accessibility Features
The component includes built-in accessibility features:
- **Default role**: The section has a default `role="region"` which helps screen readers identify it as a landmark region
- **Custom role**: You can override the role attribute to use other semantic roles like `complementary`, `contentinfo`, etc.
- **aria-label**: Use the `aria-label` attribute to provide a descriptive label for the section when the title slot content isn't sufficient for screen readers
#### Section Typical usage pattern
- Use within the default slot of `m-view` for organizing page content
- Place section titles (h1-h6) in the title slot
- Place descriptive text in the description slot
- Place main section content (forms, lists, cards) in the default slot
- Use the box variant for sections that need visual separation
- Add `aria-label` for sections that need additional context for assistive technologies
- Override the `role` attribute when the default "region" role isn't semantically appropriate
---
## Select
### Select Examples
#### Select Default Example
```html
Option 1
Option 2
Option 3
```
#### Select States Example
```html
Default
With icon
Disabled
Read only option
Another option
Required
Error
```
#### Select Horizontal Example
```html
Option 1
Option 2
Option 3
```
#### Select FullWidth Example
```html
Option 1
Option 2
Option 3
```
#### Select WithLongContent Example
```html
Option 1
Option 2
Option 3
```
#### Select WithLongContentHorizontal Example
```html
Option 1
Option 2
Option 3
```
#### Select DescriptionState Example
```html
Description
```
#### Select HintState Example
```html
Hint
```
### Select Usage
The Select component is commonly used in forms and settings where users must make a selection from a limited set of choices. Unlike text inputs, a select component restricts user input to predefined options, ensuring data consistency and reducing errors.
**Use Select when:**
- Users need to choose one option from a fixed set of choices.
- The number of options is manageable (e.g., 5–15 options).
- The choices do not require complex descriptions (if descriptions are necessary, consider a radio buttons).
- A consistent, compact UI is required, and a radio button group would take too much space.
- Users should not enter free text but instead select from a valid list.
- Users should be able to refine results or content (e.g., selecting a category).
**Do not use Select when:**
- The number of options is very small (2–4); use radio buttons instead.
- Users need to make multiple selections; use a checkboxes instead.
- Options require additional descriptions or explanations; use a group of radio buttons with descriptions.
- The selection should be immediately visible without clicking.
### Select Other Considerations
- Use clear and concise label.
- Use placeholder text like “Select a department” instead of a default selection unless a default is meaningful.
- Keep option labels short and scannable.
- Group related options for better readability (either alphabetically, by importance or by group).
- Provide clear error messages when a selection is required but not made.
- Preselect a default option when appropriate (e.g., "Select a department").
- Do not use vague labels like “Choose One” without context.
- Avoid long option lists that require excessive scrolling.
### Select Design Rationale
The Select component is designed to improve efficiency and clarity in forms while maintaining accessibility. A dropdown conserves space and simplifies decision-making for users, particularly when dealing with long lists.
---
## Spinner
### Spinner Examples
#### Spinner Default Example
```html
```
#### Spinner InButton Example
```html
Loading
```
### Spinner Usage
**Use the Loading Spinner to:**
- Indicate asynchronous actions, such as fetching data from an API.
- Show progress when a process takes more than a second.
- Prevent users from interacting with UI elements while waiting for a response.
- Provide feedback when loading components dynamically in a lazy-loading scenario.
**Do not use the Loading Spinner to:**
- Indicate progress for long-running actions (use a progress bar if the duration is predictable).
- Replace skeleton screens where content placeholders would be more appropriate.
- Block the entire page unless necessary—prefer inline spinners for non-critical loading states.
### Spinner Use case examples
- Submitting a job application, approving a request.
- Updating a salary breakdown, filtering a job listing.
- Loading a user dashboard after login.
- Saving user settings in a modal.
### Spinner Other Considerations
- Avoid unnecessary loading indicators—if a process is fast, the spinner can feel disruptive.
- If possible, use progressive loading (e.g., show part of the UI while the rest loads).
- Avoid excessive animations that may feel distracting.
### Spinner Design Rationale
- Instant Feedback: Prevents users from wondering if an action was registered.
- Guides User Expectations: Helps manage perception of system performance.
- Consistent Interaction Model: Standardized loading behavior across different UI elements.
- Enhances Usability: Ensures users don’t take unintended actions while waiting.
- Lightweight and optimized for performance (CSS-based preferred).
- Match the UI theme (size, color, and speed).
---
## Stack
### Stack Usage
**Use the Stack Component to:**
- Stack elements vertically with controlled spacing.
- Group related content while preserving visual hierarchy.
- Ensure uniform spacing in layouts.
- Enable flexible wrapping for grouping elements like tags, buttons, or metadata.
**Do not use the Stack Component to:**
- Replace Grid layouts when a structured, column-based layout is required.
- Introduce arbitrary whitespace—Stack should be used purposefully to maintain consistency.
- Handle complex nested layouts—consider combining with a Grid or Flexbox layout for intricate designs.
### Stack Other Considerations
- Ensure semantic structure when stacking headings, paragraphs, and form fields.
- Avoid applying excessive nesting of Stack components, as it may impact maintainability.
### Stack Design Rationale
- Solves Margin Collapsing Issues: Instead of manually setting margins on individual elements, Stack ensures uniform spacing.
- Encourages Consistent Spacing: Helps maintain a predictable layout across the UI.
- Reduces Layout Complexity: Provides a straightforward approach to structuring content without introducing unnecessary styles.
---
## StatusPage
### StatusPage Examples
#### StatusPage Header Example
```html
{{lang_selector}}
```
#### StatusPage Footer Example
```html
Grade.com
{{subscribe_button}}
© 2025 Grade
```
---
## SubNav
### SubNav Examples
#### SubNav Default Example
```html
```
#### SubNav WithActiveItem Example
```html
```
#### SubNav WithDisabledItems Example
```html
```
#### SubNav MultiLevel Example
```html
Name Email Role
John Doe john@example.com Admin Jane Roe jane@example.com Editor
Total: 2
```
#### Table WithHeaderAndActions Example
```html
Name Email Role Actions
John Doe john@example.com Admin
Jane Roe jane@example.com Editor
```
#### Table WithCheckboxes Example
```html
Name Email Role Actions
John Doe john@example.com Admin Edit | Delete Jane Roe jane@example.com Editor Edit | Delete
```
#### Table CellAlignments Example
```html
Left Aligned
Center Aligned
Right Aligned
Default (Left)
Left aligned text
Centered text
Right aligned text
Default alignment
Another left
Another center
Another right
Another default
Numbers: 123
Numbers: 456
Numbers: 789
Numbers: 000
```
#### Table MixedAlignments Example
```html
Product
Status
Price
Quantity
Total
Premium Widget
In Stock $29.99
5
$149.95
Basic Widget
Low Stock $19.99
2
$39.98
Deluxe Widget
Out of Stock $49.99
0
$0.00
Grand Total: 7 $189.93
```
#### Table Sortable Example
```html
Name
Email
Role
Join Date
Alice Johnson alice@example.com User 2023-01-15 Bob Smith bob@example.com User 2023-02-20 John Doe john@example.com Admin 2022-12-01 Jane Roe jane@example.com Editor 2023-03-10
```
#### Table SortableWithMixedColumns Example
```html
ID
Name
Email
Status
Score
1 Alice Johnson alice@example.com Active 95 2 Bob Smith bob@example.com Pending 87 3 John Doe john@example.com Active 92 4 Jane Roe jane@example.com Inactive 78
```
#### Table SortableWithEventListener Example
```html
{
const handleSort = (event: CustomEvent) => {
console.log('Sort event received:', event.detail);
// Here you would implement your actual sorting logic
// The component only dispatches the event - you need to sort your data
};
return html`
Name
Email
Role
Alice Johnson alice@example.com User Bob Smith bob@example.com User John Doe john@example.com Admin Jane Roe jane@example.com Editor
`;
}
```
#### Table SortableWithAccessibility Example
```html
Accessibility Features:
Keyboard navigation: Tab to headers, Enter/Space to sort
Screen reader support: ARIA labels and sort states
Visual indicators: Sort icons and hover states
Focus management: Clear focus indicators
Product Name
Price
Stock
Category
Premium Widget $29.99 15 Electronics Basic Widget $19.99 8 Electronics Deluxe Widget $49.99 3 Premium Standard Widget $24.99 12 Standard
```
#### Table WithCaption Example
```html
User Management
Name Email Role
John Doe john@example.com Admin Jane Roe jane@example.com Editor
```
#### Table WithCaptionAndButton Example
```html
User Management
Add User
Name Email Role Actions
John Doe john@example.com Admin
Jane Roe jane@example.com Editor
```
---
## Tag
### Tag Examples
#### Tag Default Example
```html
Category
```
#### Tag WithIcon Example
```html
Featured
```
#### Tag Variants Example
```html
${Object.values(TagVariant).map(
(variant) =>
html`
${variant}
${variant}
`
)}
```
#### Tag LargeVariants Example
```html
${Object.values(TagVariant).map(
(variant) =>
html`
${variant}
${variant}
`
)}
```
#### Tag WithSection Example
```html
```
### Tag Usage
Use the Tag component to:
- Indicate status or progress (e.g., "Pending," "Approved")
- Highlight categories or types (e.g., "Admin," "User")
- Draw attention to new or updated content (e.g., "New")
- Help users filter or identify items by type in lists, cards, or other grouped components
### Tag Other Considerations
- **Concise Wording:** Use one or two words for clear communication (e.g., "New," "Alert").
- **Consistent Use:** Apply tags only where necessary and avoid overuse to prevent visual clutter.
- **Positioning:** Place tags in consistent positions, such as at the top-right corner of cards or lists, so users can easily scan for information.
---
## Textarea
### Textarea Examples
#### Textarea Default Example
```html
```
#### Toggle WithError Example
```html
Error message
Error message
```
#### Toggle WithHint Example
```html
```
#### Toggle LongLabel Example
```html
```
#### Toggle LongTexts Example
```html
```
### Toggle Usage
**Use the Toggle to:**
- Enable or disable a setting with an immediate effect.
- Represent a binary choice (e.g., on/off, show/hide, enable/disable).
- Improve clarity when changes apply instantly without additional confirmation.
- Make a setting’s status clearly visible at a glance.
**Do not use the Toggle to:**
- Submit forms or trigger complex actions (use buttons instead).
- Choose between more than two options (use radio buttons or dropdowns instead).
- Require explicit confirmation before applying changes (use checkboxes or modals).
- Replace checkboxes for settings that require additional information or context.
### Toggle Other Considerations
- **Labeling:** Ensure toggles have clear, descriptive labels. Labels should explain what the toggle controls (e.g., "Enable Dark Mode").
- **Default State:** Default states should be based on user expectations. If a feature is optional, it should be off by default.
- **Grouping:** If multiple toggles are related, visually group them together to maintain clarity.
### Toggle Design Rationale
- **Immediate Feedback:** Unlike checkboxes, toggles indicate that changes take effect immediately, making them ideal for system or UI settings.
- **Recognition Over Recall:** A toggle’s visual representation (switching between states) helps users understand its purpose at a glance.
- **Consistency:** Standardizing toggles across the application ensures a familiar and predictable user experience.
---
## UserMenu
### UserMenu Examples
#### UserMenu Default Example
```html
```
#### UserMenu WithSlottedMenuItems Example
```html
```
#### UserMenu WithComplexSlottedContent Example
```html
John Doe
john.doe@example.com
Premium Member
Storage used
75%
Upgrade Plan
```
#### UserMenu InitialsExamples Example
```html
No initials → (shows icon)
```
#### UserMenu WithIcon Example
```html
```
#### UserMenu WithDisabledItems Example
```html
```
#### UserMenu WithClickEvents Example
```html
console.log('Menu item clicked:', e.detail.item.label)}
>
```
#### UserMenu PlacementExamples Example
```html
```
#### UserMenu WithSlottedHeader Example
```html
John Doe
john.doe@example.com
Premium Member
```
---
## Vertical
### Vertical Usage
The `Vertical` component arranges child elements vertically with configurable spacing. It provides a standardized way to arrange child elements vertically with consistent spacing between them.
#### Vertical Typical usage pattern
- Use for stacking form fields, content blocks, or other UI components vertically
- Place within sections, views, or other layout components to organize content
- Use different spacing variants (xxs, xs, s, m, l, xl) to control gaps between items
- Combine with `m-horizontal` for complex nested layouts
#### Vertical Example
```html
```
---
## View
### View Examples
#### View Default Example
```html
This is main content in a view container with size ${args.size} and margin
${args.margin}
The view component manages content width, spacing between elements, and vertical margins
```
#### View WithAside Example
```html
This is the aside content
Main content area
Another content block in main area with spacing controlled by the view's spacing property
```
#### View SizeVariations Example
```html
Size: xxs (440px)
Size: xs (720px)
Size: s (960px)
Size: m (1200px)
Size: full (100%)
```
#### View MarginVariations Example
```html
Margin: s (small vertical margin)
Margin: m (medium vertical margin)
Margin: l (large vertical margin)
```
### View Usage
The `View` component provides a responsive layout for application views with optional aside and main content slots. It creates a responsive grid layout that can include an optional sidebar (aside) and main content area. The component automatically handles responsive behavior, switching from a two-column layout on desktop to a single-column layout on mobile devices.
#### View Typical usage pattern
- Use as the main content wrapper within the default slot of `m-app-layout`
- Place page content (sections, forms, lists) in the default slot
- Place navigation, filters, or secondary content in the aside slot
- Use different size variants (xxs, xs, s, m, full) to control content width
- Use margin variants (s, m, l) to control vertical spacing
```html
Add main elements into default slot
```
---
## Overview
Version {version}
## Overview Components
> Components are the reusable building blocks of our design system. Each component meets a specific interaction or UI need, and has been specifically created to work together to create patterns and intuitive user experiences.
{modules
.flatMap((module) => module.declarations)
.filter(
(declaration) => declaration.kind === "class" && declaration.customElement && !exclude.includes(declaration.name)
)
.sort((a, b) => a.name.localeCompare(b.name))
.map((component) => (
Version {version}
## Overview Layout components
> Layout components provide the structural foundation for applications by defining the HTML document outline. These components use semantic HTML elements and readable naming conventions to create accessible, well-structured layouts that developers can easily understand and implement.
{modules
.flatMap((module) => module.declarations)
.filter(
(declaration) =>
declaration.kind === "class" &&
declaration.customElement &&
include.includes(declaration.name) &&
!exclude.includes(declaration.name)
)
.sort((a, b) => a.name.localeCompare(b.name))
.map((component) => (
In progress
## Overview Patterns
> Design patterns help create consistent, intuitive experiences across our products. They provide proven solutions to common UX challenges, reduce cognitive load for users, and speed up both design and development by offering ready-to-use combinations of our components.
## Overview Templates
> Templates are complex examples of how to use the components to create the structure of a page or view. They are used to define the HTML document outline and are used to create accessible, well-structured layouts that are easy to implement.
### Overview Static html templates
{templateItems.map((component, index) => (
{component.name}
{component.description}
))}
### Overview Vue demo applications
{demoItems.map((component, index) => (
{component.name}
{component.description}
))}
Version {version}
## Overview Design Tokens
> Design tokens are the foundational elements of our design system. They are used to create consistent and scalable UI components.
{tokenGroups.map((component) => (
---
## Typography
Under construction
## Typography Typography
> This page is under construction. We are working on a more comprehensive guide for typography.
Below you can see the typography styles that are currently in testing phase.
### Typography Loose style
Heading 1
Mieleni minun tekevi, aivoni ajattelevi lähteäni laulamahan, saa'ani sanelemahan, sukuvirttä suoltamahan, lajivirttä laulamahan. Sanat suussani sulavat, puhe'et putoelevat, kielelleni kerkiävät, hampahilleni hajoovat.
Veli kulta, veikkoseni, kaunis kasvinkumppalini! Lähe nyt kanssa laulamahan, saa kera sanelemahan yhtehen yhyttyämme, kahta'alta käytyämme! Harvoin yhtehen yhymme, saamme toinen toisihimme näillä raukoilla rajoilla, poloisilla Pohjan mailla.
Heading 2
Veli kulta, veikkoseni, kaunis kasvinkumppalini! Lähe nyt kanssa laulamahan, saa kera sanelemahan yhtehen yhyttyämme, kahta'alta käytyämme! Harvoin yhtehen yhymme, saamme toinen toisihimme näillä raukoilla rajoilla, poloisilla Pohjan mailla.
Veli kulta, veikkoseni, kaunis kasvinkumppalini! Lähe nyt kanssa laulamahan, saa kera sanelemahan yhtehen yhyttyämme, kahta'alta käytyämme! Harvoin yhtehen yhymme, saamme toinen toisihimme näillä raukoilla rajoilla, poloisilla Pohjan mailla.
Heading 3
Veli kulta, veikkoseni, kaunis kasvinkumppalini! Lähe nyt kanssa laulamahan, saa kera sanelemahan yhtehen yhyttyämme, kahta'alta käytyämme! Harvoin yhtehen yhymme, saamme toinen toisihimme näillä raukoilla rajoilla, poloisilla Pohjan mailla.
Lyökämme käsi kätehen, sormet sormien lomahan, lauloaksemme hyviä, parahia pannaksemme, kuulla noien kultaisien, tietä mielitehtoisien, nuorisossa nousevassa, kansassa kasuavassa: noita saamia sanoja, virsiä virittämiä vyöltä vanhan Väinämöisen, alta ahjon Ilmarisen, päästä kalvan Kaukomielen, Joukahaisen jousen tiestä, Pohjan peltojen periltä, Kalevalan kankahilta.
---
## ErrorMessages
## ErrorMessages Error Message Guidelines
Clear, empathetic, and actionable error messages help users recover quickly, reduce frustration, and build trust. Use these principles and examples to craft messages that guide users effectively.
---
### ErrorMessages 1. Be Clear and Concise
- Use plain, everyday language.
- Avoid error codes, system terminology, and technical jargon.
- Be short but specific—no more than one or two short sentences.
**Good**: *We couldn’t find this page.*
**Poor**: *Error 404: Page not found.*
---
### ErrorMessages 2. Be Explicit About What Went Wrong
- Clearly state the exact issue—don’t be vague.
- Include necessary context without overwhelming the user.
**Good**: *Please enter a valid phone number.*
**Poor**: *Submission failed.*
---
### ErrorMessages 3. Offer a Solution
- Guide users on what to do next.
- Be specific about the required fix or input.
**Good**: *Check your username and try again.*
**Poor**: *Invalid input.*
---
### ErrorMessages 4. Be Empathetic and Encouraging
- Write in a tone that feels helpful and human—not cold or blaming.
- Assume the user had good intentions.
**Good**: *Having trouble signing in? Let’s reset your password.*
**Poor**: *Login failed.*
---
### ErrorMessages 5. Use Positive Framing
- Avoid phrasing that blames the user.
- Focus on the action that will lead to success.
**Good**: *Fill out all required fields to continue.*
**Poor**: *You missed required fields.*
---
### ErrorMessages 6. Place Messages in the Right Context
- Show the error next to or inside the field it relates to.
- Avoid generic banners or popups unless the error applies globally.
---
### ErrorMessages 7. Prevent Errors Through Instruction
- Use inline helper text to reduce user errors.
- Validate inputs in real time where possible.
**Good**: *Password must include at least one number and a special character.*
---
### ErrorMessages 8. Be Conversational
- Sound like a real person speaking to another person.
- Use a friendly, familiar tone aligned with your brand voice.
**Good**: *We need your email to keep you updated.*
**Poor**: *Field is mandatory.*
---
### ErrorMessages 9. Test and Improve Regularly
- Run usability testing on key forms and flows.
- A/B test message variants to find the most effective versions.
- Monitor analytics and support tickets to spot confusing errors.
---
### ErrorMessages 10. Avoid Triggers and Negative Emotion
- Don’t embarrass or alarm the user.
- Be cautious with humor—it must fit the context and brand.
- Keep the tone calm, even when something goes wrong.
**Good**: *Oops, something went wrong. Let’s try again.*
---
### ErrorMessages 11. Design for Accessibility
- Use sufficient color contrast for error messages.
- Follow the WCAG minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text. This helps users with low vision or color vision deficiency.
- Don’t rely on color alone—use icons, labels, and ARIA roles.
- For example, instead of only using red text to indicate an error, combine it with a clear error message, an icon (like ❌), and accessible labels. This ensures that colorblind users or those using screen readers understand the issue.
- Write error messages that are screen-reader friendly.
- The message is real text (not an image of text).
- The error message is programmatically associated with the relevant field using aria-describedby, aria-invalid, or aria-live.
- The message is concise, polite, and clearly indicates how to fix the issue.
---
### ErrorMessages 12. Stay Consistent
- Use standardized language for recurring patterns.
- Match tone and terminology across buttons, labels, and messages.
---
### ErrorMessages Reusable Patterns and Examples
#### ErrorMessages Login
*Incorrect username or password. Need help signing in?*
#### ErrorMessages Job Posting
*This position already exists. Review your entry and try again.*
#### ErrorMessages Candidate Submission
*Unable to submit candidate profile. Check the required fields and resubmit.*
#### ErrorMessages Search
*We couldn't find any matches. Adjust your filters and try again.*
---
## Punctuation
## Punctuation Punctuation marks
Punctuation is essential for clear writing. It guides the reader, creates pauses, and adds emphasis.
Punctuation follows grammar rules, not spoken language. Correct usage helps structure the text and makes it easier to read.
### Punctuation Multiplication Sign
Use the multiplication sign ( × ) to indicate multiplication or to express dimensions. The space can be omitted if there are only numbers on both sides.
**Win:** ```alt``` + ```0 2 1 5```
**Example (good):** 1024 × 768 pixels
**Example (poor):** 1024 X 768 pixels
---
### Punctuation En dash
An en dash ( – ) should be used in all time period expressions.
**Mac:** ```option``` + ```-``` **Win:** ```alt``` + ```0 1 5 0```
---
**Example (good):** 28.1. – 12.3.
**Example (poor):** 28.1.-12.3.
---
**Example (good):** 7.30 – 8.15
**Example (poor):** 7.30-8.15
---
### Punctuation Ellipsis
Use ellipsis ( … ) to express a continuation in lists or sequences. Ellipsis is an alternative for situations where an en dash would be insufficient.
**Mac:** ```option``` + ```;``` **Win:** ```alt``` + ```0 1 3 3```
**Example (good):** -2…+2 °C
**Example (poor):** -2–+2 °C
---
### Punctuation Time format
Use a period ( . ) to separate minutes from hours.
**Example (good):** 12.45
**Example (poor):** 12:45
---
## UxWriting
## UxWriting Writing Guidelines
Clear, consistent, and user-friendly UX writing improves usability, accessibility, and user trust. These guidelines help you create purposeful content that supports users in every interaction.
---
### UxWriting 1. Voice and Tone
Our voice reflects who we are: **direct, empathetic, and supportive**. We adapt our tone based on context and user emotion.
- Always write with **clarity, respect, and encouragement**.
- Use **natural, conversational** language without being overly casual.
- Speak **to** users, not **about** them.
- Avoid robotic or bureaucratic expressions.
**Example (poor)**: "The user must complete the process immediately."
**Example (better)**: "Please finish the process to continue."
---
### UxWriting 2. Clear and User-Focused Language
Write from the **user's perspective**. Think about their goals, not your system’s logic.
- Avoid jargon, internal terms, or developer-speak.
- Be concise—eliminate unnecessary words.
- Use **verbs and action-oriented phrases** that help users understand what to do.
- Have a colleague read the text and ask whether they understood it as intended
**Example (poor)**: "Enter the process implementation data into the system."
**Example (better)**: "Add recruitment details to the system."
---
### UxWriting 3. Scannable and Structured Content
Help users **scan and act** with ease.
- Use **clear headings and subheadings** to guide users.
- Use **lists** to highlight key actions or steps.
- Break long text into **short paragraphs** or bullets.
**Example (poor)**: A dense paragraph with no emphasis.
**Example (better)**:
**Open Positions**
View and manage current job openings.
---
### UxWriting 4. Accessibility and Inclusivity
Make content usable for **everyone**.
- Use plain language that meets accessibility guidelines.
- Ensure sufficient **color contrast** and avoid using color as the only signal.
- Avoid idioms, cultural references, or gendered phrases.
- Use **person-first language** (e.g., “people with disabilities”).
**Example (poor)**: "He should check the dashboard."
**Example (better)**: "They should check the dashboard."
---
### UxWriting 5. Support Decision-Making
Guide users with **clear, outcome-based choices**.
- State what will happen when they take an action.
- Avoid vague CTAs like “Click here”.
- Align wording with user intent and task.
**Example (poor)**: "Click here."
**Example (better)**: "Submit your application now."
---
### UxWriting 6. Ensure Comprehension
- Use familiar terms users already know.
- Provide **examples or explanations** for abstract terms.
- Keep error-prone or critical flows extra clear.
- Provide an expanded form of an abbreviation the first time that specific abbreviation is written in the text
**Example (poor)**: "Contact the relevant person."
**Example (better)**: "Contact the recruitment manager."
---
### UxWriting 7. Logical Text Structure
Help users follow a **logical flow**.
- Present steps in the order they happen.
- Connect related information clearly.
- Use **numbered or bulleted lists** for instructions.
**Example (better)**:
1. Fill out the form
2. Attach your CV
3. Submit your application
---
### UxWriting 8. Friendly and Respectful Tone
Be encouraging—users are often under pressure or unsure.
- Use polite and positive framing.
- Avoid passive-aggressive or imperative phrasing.
- Don’t blame users for mistakes.
**Example (poor)**: "You failed to complete the form."
**Example (better)**: "Please complete all fields before submitting."
---
### UxWriting Writing for Error Messages
Help users recover gracefully and confidently.
#### UxWriting Clear and Concise
Say what happened in plain language.
- **Poor**: "An error occurred."
- **Better**: "We couldn’t find the page you’re looking for."
#### UxWriting Avoid Codes or Technical Jargon
- **Poor**: "Error 404."
- **Better**: "Page not found."
#### UxWriting Offer Next Steps
- **Poor**: "Invalid input."
- **Better**: "Check your email address and try again."
#### UxWriting Use Empathy and Encouragement
- **Poor**: "You entered incorrect data."
- **Better**: "Having trouble logging in? Reset your password."
#### UxWriting Place Messages in Context
Place the message next to the field or component that needs fixing.
---
### UxWriting Reusable Words with Context
The following words are acceptable when **context is clear**. Avoid using them alone in ambiguous situations.
Use modifiers like:
- “Save application”
- “Edit applicant details”
- “Download report”
#### UxWriting List of generic terms:
- Save
- Download
- Open
- Close
- Edit
- Copy
- Delete
- Add
- Create
- Log in
- Log out
- Update
- Print
- Settings
- Search
- Filter
---
## AllIcons
Version {version}
## AllIcons Icons
> This gallery showcases our complete icon set. Browse our comprehensive collection, quickly search for specific icons, and easily copy the component code for any selected icon. Use this tool to find and implement the perfect icons for your application's user interface.
>
>
---
## About
## About About Mark Design System
> Mark is our unified design system, crafted to empower developers and designers to create consistent, accessible, and high-quality user interfaces across all our products and platforms. As a **Modular Accessible Reusable Kit**, Mark sets the standard for precision and simplicity in design.
Mark is more than a set of components — it’s a comprehensive toolkit that ensures quality, consistency, and a streamlined development process.
### About Key components
#### About Unified Component Library
The `@mark/ui` package offers a cohesive library of pre-built, customizable components, each crafted to meet Grade’s standards for accessibility, usability, and visual harmony. These components provide a seamless experience that users will recognize and trust across platforms.
#### About Design Tokens for Consistency
Through `@mark/tokens`, all core design decisions—from colors to typography to spacing—are centralized and standardized, creating a consistent visual identity across every Grade product. Design tokens simplify updates and ensure our brand’s look and feel is applied universally and reliably.
#### About Clear, Accessible Icon System
Our `@mark/icons` package includes a curated selection of icons that integrate smoothly into projects, making information more intuitive and visually consistent. Each icon reflects Grade’s visual identity, reinforcing clarity in communication.
#### About Refined Typography
Typography plays a key role in conveying clarity and professionalism. With `@mark/fonts`, our system includes a selection of font families and styles that enhance readability and align with Grade’s design language, providing a polished, cohesive look across all interfaces.
#### About Accessibility as a Core Principle
Built with accessibility at its foundation, Mark ensures every component aligns with WCAG standards. By integrating accessible design from the beginning, Mark helps create inclusive experiences for all users, demonstrating our commitment to usability and inclusivity.
### About Learn more about the principles
Mark is built on a set of principles that guide our design and development practices.
[Learn more about the principles →](?path=/docs/info-principles--docs)
#### About Getting Started
To begin using Mark in your project, install the core packages.
[Get started with Mark →](?path=/docs/info-get-started--docs)
#### About Contribution and Support
We value all input and welcome contributions to the Mark Design System. If you're interested in contributing or need support:
- Check our [contribution guidelines](https://gradegroup.ghe.com/mark/mark/blob/main/CONTRIBUTING.md) for details on how to get involved.
- For questions or support, reach out to the design team via [Teams]().
- [Report issues](https://gradegroup.atlassian.net/jira/software/projects/MDS/form/5) or submit [feature requests](https://gradegroup.atlassian.net/jira/software/projects/MDS/form/6).
---
## Cdn
## Cdn CDN usage
> Mark Design System components can be used directly via CDN without setting up a build system. Here's how to include the necessary files.
You can also experiment with Mark Design System components directly in CodePen. Look for `Edit in CodePen` button in our component examples to try them out instantly with the correct CDN configuration.
### Cdn Required Files
Add these files to your HTML:
First release
## GenAiSupport Mark DS Gen AI Documentation Support
You can use the official Mark Design System documentation as a custom documentation source in Cursor IDE. This enables enhanced code search, context-aware suggestions, and instant access to component usage and API details directly within your development environment.
### GenAiSupport How to Add Mark DS Documentation in Cursor Settings
1. **Open Cursor IDE.**
2. Go to **Settings** → **Features**.
3. Scroll to the **Docs** section.
4. Click **+ Add new doc**.
5. Enter the following URL as the documentation source:
First draft
## Principles Mark DS Principles
> Our design philosophy is centered around creating inclusive, efficient, and user-friendly products that meet real-world needs with simplicity and clarity.
We believe that effective design is a balance of innovation, accessibility, and a human touch. Each design decision reflects our commitment to providing modern, trusted solutions that enhance the experiences of HR professionals and decision-makers in the public and private sectors.
### Principles Simplicity and Clarity
-> Our design principle of "less is more" guides us to create interfaces that are clean, intuitive, and easy to navigate.
By focusing on essential elements and removing unnecessary complexity, we ensure that users can engage with our products confidently, without distractions. Clarity is at the heart of our design language, making sure information is presented in a way that feels direct, straightforward, and supportive of user goals.
### Principles User-Centered and Inclusive Design
-> We prioritize an inclusive approach to design that speaks in the language of the user, for the user.
Our team actively involves diverse groups throughout the design process to ensure our products serve a wide range of abilities, preferences, and backgrounds. This commitment to inclusivity means our designs are adaptable, accessible, and aim to eliminate barriers that could limit user experience.
### Principles Consistency and Reusability
-> Our design system provides a unified structure and set of components that drive consistency across all Grade products.
This reusability not only speeds up the development process but also ensures that users encounter a familiar experience, regardless of which Grade product they are using. We build with scalability in mind, enabling our system to adapt as our product suite grows and evolves.
### Principles Accessibility for All
-> Accessibility is at the foundation of everything we design.
Following the Web Content Accessibility Guidelines (WCAG), we ensure our products are usable for everyone, including those with disabilities. Our accessibility standards guarantee that our solutions are equitable and support all users in achieving their objectives without unnecessary hurdles.
### Principles Data and Research-Driven Design
-> In-depth research and data guide our design decisions, ensuring that every feature we develop addresses genuine user needs.
We leverage user insights, feedback, and testing to refine our products continually, grounding each iteration in a solid understanding of our users’ behaviors and preferences. This research-driven approach allows us to evolve our products with confidence, backed by real-world evidence and experience.
### Principles Innovation with a Human Touch
-> Our designs are modern and technically sophisticated, yet always centered around the human experience.
We aim to create an environment that is professional yet approachable, innovative yet warm. This philosophy is especially crucial as we serve HR professionals and decision-makers, for whom trust, reliability, and efficiency are paramount. Through thoughtful design, we bring warmth and clarity to our digital solutions, making them feel both cutting-edge and inviting.
---
## StartHere
## StartHere Welcome to Mark Design System
> Mark is [Grade Group's](https://grade.com/en/) unified design system, providing modular, reusable components and tools to streamline UI/UX development across all products.
>
>
---
## UsingWebComponents
## UsingWebComponents Using Mark Web Components
This guide covers how to use Mark web components in your application, including properties, events, methods, and slots.
### UsingWebComponents Properties
Properties (or attributes) can be set on the component to configure its behavior. For example:
```html
Click me
```
#### UsingWebComponents Boolean Attributes
When using Mark web components (or any web components) in HTML or frameworks like Vue, it is important to understand how boolean attributes (such as `disabled`, `selected`, etc.) are handled:
- In HTML, the **presence** of a boolean attribute (e.g., ``) means `true`, regardless of its value. For example, `` will still be disabled.
- To **enable** a component, either omit the attribute or, in Vue, use a binding: `:disabled="false"`.
- To **disable** a component, use `disabled`, `disabled="true"`, or `:disabled="true"`.
- **Do not use** `disabled="false"` or `selected="false"` in your markup, as these will still be interpreted as `true` by the browser and most frameworks.
- Mark components use a property converter to handle string values like `"true"` and `""` (empty string) as `true`, but this cannot override the browser's native behavior.
**Summary Table:**
{`
| Markup | Result |
| ---------------------------- | --------------------- |
| | Disabled |
| | Disabled |
| | Disabled (do not use) |
| | Disabled |
| | Enabled |
| | Enabled |
`}
**Accessibility:**
This approach ensures the correct disabled state is reflected in the DOM and to assistive technologies, meeting WCAG 2.2 AA requirements.
**Best Practice:**
- Use `:disabled` or `:selected` bindings in Vue for dynamic state.
- Omit the attribute for the default (enabled/unselected) state.
- Use the attribute (or set to `true`) for the active (disabled/selected) state.
### UsingWebComponents Events
Web components emit events that you can listen to. For example:
```html
Click me
```
This listens for the `click` event on the button and calls the `handleClick` function when it occurs.
### UsingWebComponents Methods
Some components expose methods that you can call. You can access these methods by getting a reference to the element. For example:
```javascript
const dialogElement = document.querySelector("#my-dialog");
dialogElement.showModal();
```
This calls the `showModal` method on a dialog component.
### UsingWebComponents Slots
Slots allow you to insert content into specific places in a component. For example:
```html
Modal title
Modal content goes here
Cancel
Save
```
### UsingWebComponents Using Icons
Icons can be used either as standalone elements or within components:
```html
Click me
```
### UsingWebComponents Vue Integration
#### UsingWebComponents Configuring Vue for Web Components
##### UsingWebComponents Vite Configuration
If you're using Vite, add the following configuration to your `vite.config.ts`:
```typescript
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
export default defineConfig({
plugins: [
vue({
template: {
compilerOptions: {
isCustomElement: (tag) => tag.includes("m-"),
},
},
}),
],
});
```
##### UsingWebComponents Vue Application Configuration
Add the following configuration to your main Vue file (usually `main.js` or `main.ts`):
```javascript
import { createApp } from "vue";
import App from "./App.vue";
// Import all Mark components
import "@mark/ui";
import "@mark/icons";
import "@mark/fonts";
import "@mark/tokens/css";
const app = createApp(App);
app.mount("#app");
```
#### UsingWebComponents Using Mark Components in Vue
After the global configuration, you can use Mark components in your Vue templates:
```typescript
Click me
Hello
```
---
## AiAssistedJobDescriptions
## AiAssistedJobDescriptions Universal Pattern for AI-Assisted Job Descriptions
> This guide standardizes the user experience for implementing and using the AI job description generation feature within the ATS, accommodating product-specific components. The pattern is tailored for two main user groups: Admin Users and Recruiters (regular ATS users).
### AiAssistedJobDescriptions Flow overview
**Admin Flow**: Guide Admins from the promotion banner to feature settings.
**Recruiter Flow**: Guide Recruiters from generating a job ad for the first time to providing AI consent. Ensure AI consent settings are always accessible in user profile settings.
### AiAssistedJobDescriptions 1. Feature Promotion for Admins
#### AiAssistedJobDescriptions Banner Display
- **Purpose**: Use the AI feature banner to promote the job description generation tool to eligible Admin users.
- **Visibility**: Display only to Admin Users on the **Main Home View** if the AI feature is not yet enabled.
- **Banner Action**: Link the banner to the **AI Feature Section** on the **Settings Page**, where the Admin can enable the AI feature for the entire organization.
#### AiAssistedJobDescriptions Post-Enablement Behavior
- Remove the promotion banner from the **Main Home View** once the feature is enabled to avoid redundant prompts.
#### AiAssistedJobDescriptions Additional Considerations
- **User Experience**: Ensure Admin users clearly understand the feature trial and its functions.
- **Placement**: Position the promotion prominently within the application, ideally on the dashboard or settings page.
- **Promotion Design**:
- Use the **AppPromotion** component for consistent styling and behavior.
- Display an appealing message about the feature and the trial.
- Include a clear CTA directing Admin users to the settings page to activate the feature.
### AiAssistedJobDescriptions 2. Enabling AI Access for Recruiters
#### AiAssistedJobDescriptions Admin's Role in Feature Enablement
- Limit AI feature enablement to Admin Users only.
- Place controls for activating the AI tool in the **AI Feature Section** on the **Settings Page**.
#### AiAssistedJobDescriptions Result of Enabling AI Feature
- Provide Recruiters access to the AI feature in the **Job Post Settings** section within their regular job posting workflow.
#### AiAssistedJobDescriptions Additional Considerations
- **Settings Messaging**: Provide clear information regarding the feature, trial duration, and limitations.
- **Trial Expiry**: Explain what happens when the trial expires and how users can continue using the feature.
- **Activation Control**:
- Set the activation control (e.g., toggle, checkbox, button) to "off" by default.
- Ensure the control remains "off" when the feature is inactive.
- Hide the promotion banner once the feature is active.
### AiAssistedJobDescriptions 3. Access and consent flow for recruiters
#### AiAssistedJobDescriptions Recruiter Access
- **Feature Location**: Place the AI feature within the **Job Post View** under **Job Post Settings** once enabled.
#### AiAssistedJobDescriptions Consent Requirement
- **First-Time Consent**:
- Prompt Recruiters to provide AI consent the first time they use the feature.
- **Consent Modal**: Trigger a modal with consent information and options when the Recruiter clicks the AI feature button.
- Require Recruiters to agree to AI use before generating any job description text.
#### AiAssistedJobDescriptions Persistent Consent Setting
- Make the **AI Consent Setting** accessible in **Profile Settings** once consent is provided.
- Allow each recruiter to review or revoke consent at any time, as this is a **personal setting**.
### AiAssistedJobDescriptions Design and Component Guidelines
#### AiAssistedJobDescriptions Universal Flow and Product-Specific Components
- **Feature Banner Component**: Use the **Grade Product Design System** for consistent styling and behavior.
- **Product-Specific Views**: Ensure that other components and UI views integrate seamlessly with this universal AI feature pattern, even if they vary by product.
#### AiAssistedJobDescriptions Supported Features
- Adapt the universal flow to various product implementations, allowing teams to integrate the AI feature into existing workflows while ensuring a consistent user experience.
### AiAssistedJobDescriptions User Interface Summary
{`
| **User Type** | **Initial Access Location** | **Post-Enablement Access Location** | **Consent Requirement** | **Consent Setting Access** |
|-----------------|------------------------------|--------------------------------------|-------------------------------------------|---------------------------------------|
| **Admin User** | Main Home View (Banner) | Settings Page (AI Feature Section) | None (Admin enables feature for all) | N/A |
| **Recruiter** | N/A | Job Post View (Job Post Settings) | First use only (per user, via modal) | Accessible in User Profile Settings |
`}
---
## AiButton
## AiButton AI button
> This guide standardizes the creation of the AI button within each ATS, accommodating product-specific look and feel.
### AiButton AI button design overview
**Core design**: The AI button component is a simple button that triggers the AI generation process. Each ATS needs to skin their own button with the following core elements:
- **Gradient border**
- **Icon**
#### AiButton Gradient border
The gradient border is a key visual element. It contians the following two colors:
- **#159EFD** (blue)
- **#A834FF** (purple)
The gradient should be a linear gradient that transitions from the top left to the bottom right.
#### AiButton Icons
The second key visual element is the AI icon, which can be downloaded here . When the AI is processing, display a loading icon alongside the text "Generating...". Please use your ATS's existing loading icon to maintain consistency. If your ATS doesn't have a loading icon, you can download an alternative here .
#### AiButton Animation
To provide visual feedback when the AI is processing, consider animating the gradient border when the user clicks the AI button to generate content. This animation helps indicate that the AI is actively working. For inspiration, view an example of how this animation can be implemented:
---
## DiscoveryAndEngagement
## DiscoveryAndEngagement Service Discovery & Engagement Guide
> Effective service discovery and promotion are crucial for user engagement and business growth. This pattern combines seamless navigation with strategic feature promotion to create value for both users and organizations.
### DiscoveryAndEngagement Benefits
The combination of seamless navigation and strategic feature promotion creates significant value for both users and organizations. When implemented properly, this pattern delivers clear advantages:
**For Users**
1. **Discovery Through Context**: Find relevant tools exactly when needed
2. **Seamless Experience**: Move between applications while maintaining workflow
3. **Clear Value Proposition**: Understand benefits before commitment
4. **Guided Growth**: See natural progression path for their needs
**For Organizations**
1. **Increased Adoption**: Higher discovery and conversion of complementary services
2. **Reduced Friction**: Seamless transitions reduce abandonment
3. **Strategic Promotion**: Right message at the right time
### DiscoveryAndEngagement Implementation Strategy
#### DiscoveryAndEngagement 1. Navigation & Discovery
Navigation and discovery is handled by the `m-app-menu` component. It is used to display the main navigation and the additional services.
[AppMenu Documentation →](?path=/docs/components-appmenu--docs)
{" "}
---
## Changelog
## Changelog Changelog
> Track all notable changes to Mark Design System packages.
> You can find the individual changelogs of the packages from the tabs below.
{processedUI}
{processedIcons}
{processedTokens}
{processedFonts}
{processedEditor}
---
## Testing
## Testing E2E Test Report
> We test every component in the design system using [Cypress](https://docs.cypress.io/guides/overview/why-cypress).
> Below you can see the latest E2E test results.
End-to-End (E2E) testing is a methodology used to test the flow of an component from start to finish inside a real browser. It aims to replicate real user scenarios and validate the components for integration and data integrity.
{" "}
---
## TokensBorder
## TokensBorder Border Tokens
> This is a list of all the border tokens in the Mark design system.
---
## TokensColor
## TokensColor Color Tokens
> This is a list of all the color tokens in the Mark design system.
---
## TokensFontFamily
## TokensFontFamily Font Family Tokens
> This is a list of all the font family tokens in the Mark design system.
---
## TokensFontSize
## TokensFontSize Font Size Tokens
> This is a list of all the font size tokens in the Mark design system.
---
## TokensFontWeight
## TokensFontWeight Font Weight Tokens
> This is a list of all the font weight tokens in the Mark design system.
---
## TokensLineHeight
## TokensLineHeight Line Height Tokens
> This is a list of all the line height tokens in the Mark design system.
---
## TokensSize
## TokensSize Size Tokens
> This is a list of all the size tokens in the Mark design system.
---
## TokensSpace
## TokensSpace Space Tokens
> This is a list of all the space tokens in the Mark design system.
## Template Examples
This section contains complete HTML template examples demonstrating Mark Design System components in real-world scenarios.
### Candidates
```html
Linda Hill - Candidate Profile | Grade
Account
Logout
Linda Hill
Complete
My candidate
linda.hill@example.com
Report
Manage
Delete
Process started
Invited references (1/3)
Finished
Recruiter
Marcus Wedin
Invited on
Monday 19 Oct 2025, 11:40
Project
Stockholm Stad T1
Language
Swedish
Dejan Holmstrand
Manage
Delete
Added by:
Recruiter
E-mail:
dejan.holmstrand@example.com
Language:
Swedish
Telephone:
+46 8 44 55 66
Status:
Completed
Invited on:
Wednesday 21 Oct 2025, 15:00
Company:
Telia
Work relation:
Colleague
Worked together:
2022-08 – 2025-03
```
### Index
```html
Mark Design System - Templates
Mark Design System Templates
Static HTML templates demonstrating Mark Design System components and patterns.
Candidate information
Example of a candidate listing interface for employers
Reference Check - Welcome
Landing page for reference check process for candidates
Reference Check - Add References
Form for adding reference information for candidates
Reference Check - Status Overview
Overview page showing reference submission status for candidates
Mark Design System
Copyright © 2024 Grade. All rights reserved.
```
### Refensa Reference 1
```html
Add References | Grade
Add references
To move forward, please provide information for the requested references.
1
Add reference
0/3 invited
2
Response status
0/3 received
3
Done
All good
Required references 1 / 3
Manager
Reference contact information
English
Svenska
Norsk
Dansk
Where and when did you work together?
Employment information
Cancel
Send invitation
Manager
Reference contact information
Any reference
Reference contact information
Send all invitations
Cookies
Data Privacy
Accessibility
Copyright © 2024 Grade. All rights reserved.
```
### Refensa Reference 2
```html
References Complete | Grade
Add required references
To move forward, please provide information for the requested references.
Add reference
3/3 invited
Response status
3/3 received
All done
You're references are completed
Required references 3 / 3
Manager
Done
Name
John Doe
Email
john.doe@example.com
Phone
+1 (234) 567-890
Delivery status
Invitation send via email on January 1, 2025
Edit reference
Manager
Email not delivered
Name
John Doe
Email
john.doe@example.com
Phone
+1 (234) 567-890
Delivery status
Invitation send via email on January 1, 2025
The e-mail invitation failed to deliver. Check if the reference's e-mail address is correct or
invite a new reference.
Invite new reference
Edit reference
Manager
Invitation sent
Name
John Doe
Email
john.doe@example.com
Phone
+1 (234) 567-890
Delivery status
Invitation send via email on January 1, 2025
Channels status
Email not delivered
SMS delivered
Edit reference
Invite another reference
To invite another reference, please follow this link:
Invite another reference
Cookies
Data Privacy
Accessibility
Copyright © 2024 Grade. All rights reserved.
```
### Refensa Reference
```html
Welcome - Reference Check | Grade
Welcome Username
Stockholm Stad has invited you to complete a digital reference check for the position of
Junior Art Director . Adding your references only takes a couple of minutes.
To move forward, please provide the requested references. Here’s how it works:
Add references: Select the people requested, such as a former manager.Provide contact details: Enter their email and/or phone number.We’ll handle the rest: Your references will be contacted, and you’ll be notified once
everything is complete.
Once all references have responded, the process is complete.
You can track the progress here on this page. All responses are confidential and used solely for the
recruitment process.
Get started
Cookies
Data Privacy
Accessibility
Copyright © 2024 Grade. All rights reserved.
```
Talentrekry
