| Toggles the hint panel open or closed. |
### Slots
| Name | Description |
| --- | --- |
| default | The hint body content. |
| title | The hint panel heading. |
### Parts
| Name | Description |
| --- | --- |
| trigger | The info-circle trigger button. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --hint-trigger-color-icon-base | Color of the info-circle trigger icon. |
| --hint-trigger-color-icon-hover | Color of the trigger icon on hover. |
| --hint-trigger-color-icon-active | Color of the trigger icon while pressed. |
| --hint-trigger-radius | Border radius of the trigger icon. |
| --hint-trigger-padding | Extra space added around the trigger icon to size the trigger button. |
| --hint-trigger-size | Size of the trigger icon. |
| --hint-color-focus | Focus outline color of the trigger icon. |
| --hint-heading-font-family | Font family of the hint panel title. |
| --hint-heading-font-size | Font size of the hint panel title. |
| --hint-heading-font-weight | Font weight of the hint panel title. |
| --hint-heading-line-height | Line height of the hint panel title. |
| --hint-heading-letter-spacing | Letter spacing of the hint panel title. |
| --hint-heading-text-decoration | Text decoration of the hint panel title. |
| --hint-heading-text-transform | Text transform of the hint panel title. |
| --hint-color-heading | Text color of the hint panel title. |
| --hint-body-font-family | Font family of the hint panel body. |
| --hint-body-font-size | Font size of the hint panel body. |
| --hint-body-font-weight | Font weight of the hint panel body. |
| --hint-body-line-height | Line height of the hint panel body. |
| --hint-body-letter-spacing | Letter spacing of the hint panel body. |
| --hint-body-text-decoration | Text decoration of the hint panel body. |
| --hint-body-text-transform | Text transform of the hint panel body. |
| --hint-color-body | Text color of the hint panel body. |
| --hint-color-background | Background color of the hint panel. |
| --hint-radius | Border radius of the hint panel. |
| --hint-gap | Gap between elements inside the hint panel. |
| --hint-max-width | Maximum width of the hint popup panel on desktop. |
### Usage
## When to Use
- Provide additional context or explanation for form fields or UI elements
- Offer tips or guidance without disrupting the main workflow
- Inline help within sentences or paragraphs
- Contextual information that's optional but valuable
## When NOT to Use
- Critical instructions that users must read — use persistent text or tooltips
- Essential validation messages — place these inline with the field
- Long explanations that require scrolling — use a separate help page
- Information that should always be visible — avoid hiding behind a trigger
## Do's and Don'ts
### Clear and Concise Content
The amount you pay before insurance coverage starts.
),
description: 'Short, focused explanation that answers a single question.',
},
{
type: 'incorrect',
title: 'Incorrect: Long explanation',
contentIsLeftAligned: true,
content: (
This is a very long explanation about many different topics that should probably be broken into multiple
sections or moved to a dedicated help page because users don\'t want to read all of this when they just need
a quick answer.
),
description: 'Avoid lengthy content. Keep hints concise and scannable.',
},
]}
/>
### Contextual Placement
Your premium depends on your
Age, driving history, and vehicle type.
and coverage.
),
description: 'Place hints next to the content they explain.',
},
{
type: 'incorrect',
title: 'Incorrect: Misplaced hint',
contentIsLeftAligned: true,
content: (
Information that should be elsewhere.
Your premium depends on your profile and coverage.
),
description: 'Avoid hints that are separated from their context.',
},
]}
/>
### Variants
The basic hint using the `label` prop for the title. On desktop it opens a popup to the right; on touch viewports it opens a drawer from the bottom.
Hint content can be provided using raw HTML slots instead of the `label` prop. Use the `title` slot for the heading and the default slot for body content. This approach allows for more custom styling on the content.
Customize the accessible label on the trigger button with the `triggerLabel` prop. This is important for screen readers and provides context.
Control where the popup opens on desktop using the `placement` prop. This variant opens above the trigger.
The popup can open below the trigger. Useful when there's more space below the element.
The popup can open to the left of the trigger. Useful in right-aligned layouts or narrow columns.
On touch viewports, the drawer shows a close button. Customize its label with the `closeLabel` prop. When omitted, the label is localized based on the app language configuration.
Hints work well inline within sentences or paragraphs, providing context right where it's needed without breaking the flow.
Legacy support: Hint still works with deprecated `ds-hint-title` and `ds-hint-text` sub-components. These will be removed in v2.0. Please migrate to the `label` prop instead.
Legacy support: Hint still works with the `title` slot and `ds-hint-text` sub-component. These will be removed in v2.0. Please migrate to the `label` prop and default slot instead.
### Accessibility
## Guidelines
Set `triggerLabel` to describe what the hint contains. Default is "More information". Screen readers announce this label when focused.,
},
{
type: 'do',
title: 'Keep content scannable',
content: Use short titles and brief explanations. Users scanning hints need to quickly understand the topic and decide if they need the detail.
,
},
{
type: 'do',
title: 'Test on both mobile and desktop',
content: Hint opens a drawer on touch ({'<1024px'}) and a popup on desktop. Ensure content is appropriate for both contexts.
,
},
{
type: 'do',
title: 'Use semantic HTML in content',
content: Structure hint content with headings, lists, and paragraphs to maintain logical reading order and semantic meaning.
,
},
{
type: 'dont',
title: 'Don\'t rely on color alone',
content: The hint trigger is an icon button. Ensure it has sufficient contrast and is discoverable without relying on color differentiation.
,
},
{
type: 'dont',
title: 'Don\'t hide essential information',
content: Hints are optional. Never hide critical instructions or validation messages inside a hint. These should be visible by default.
,
},
]}
/>
## WCAG 2.2 AA Compliance
The hint component implements patterns that meet WCAG 2.2 Level AA standards:
- **Button Semantics** — The trigger is a semantic button with `aria-label` and `aria-expanded` to communicate its state and purpose.
- **Dialog Role** — The hint panel has `role="dialog"` on desktop (popup) and uses the native dialog semantics on touch (drawer).
- **Focus Management** — Focus is managed automatically: when the hint opens, focus moves into the panel; when closed, focus returns to the trigger.
- **Keyboard Navigation** — Users can open/close via click or Enter/Space. Escape closes the panel on both desktop and mobile.
- **Screen Reader Announcements** — The trigger label and panel role are announced, allowing screen reader users to understand the hint's purpose and content.
- **Icon with Label** — The info-circle icon is marked as `aria-hidden` since the button label provides sufficient context.
---
## ds-progress-bar
Docs: https://helvetia-design.vercel.app/?path=/docs/components-indicators-progress-bar-progress-bar--progress-bar
Progress bar displays a visual indicator of progress or completion for a task or operation with percentage and label.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| background | "dark" \| "light" | 'dark' | The background color |
| color | "green" \| "primary" \| "purple" \| "red" \| "yellow" | 'primary' | The progress bar color |
| value | number | 0 | The value of the bar in percentage. So min is 0 and 100 would be the max value. |
### Slots
| Name | Description |
| --- | --- |
| default | Optional label or caption text. |
### Parts
| Name | Description |
| --- | --- |
| line | The filled progress indicator element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --progress-bar-height | Height of the progress bar. |
| --progress-bar-radius | Border radius of the progress bar. |
| --progress-bar-background | Background color of the progress bar container. |
| --progress-bar-line-color | Color of the progress indicator fill. |
### Usage
## When to Use
- Display task or operation progress (0–100%)
- Show loading or completion status in workflows
- Indicate multi-step process progress
- Provide visual feedback for long-running operations
- Display file upload or download progress
- Show form completion percentage
## When NOT to Use
- For status indicators that aren't measurable progress — use badge or notification
- For simple loading without progress details — use spinner
- For very large datasets where progress is unreliable — use skeleton loading
- For circular progress animations — use spinner or circular progress component
- For boolean states (done/not done) — use checkbox or toggle
## Do's and Don'ts
### Clear Progress Values
Always provide meaningful progress information. Users need to know how much is complete.
File upload: 65%
),
description: 'Users understand progress toward completion',
},
{
type: 'incorrect',
title: 'Incorrect: No indication of progress',
content: (
),
description: 'Users unsure of progress or time remaining',
},
]}
/>
### Variants
å
### Accessibility
## Guidelines
Use role="progressbar" with aria-valuenow, aria-valuemin, and aria-valuemax for screen readers.
),
},
{
type: 'do',
title: 'Meaningful Progress Indication',
content: (
Provide descriptive labels and percentages. Screen reader users need to understand progress.
),
},
{
type: 'do',
title: 'Announce Updates',
content: (
Use aria-live="polite" to announce progress updates without interrupting other announcements.
),
},
{
type: 'do',
title: 'Color + Symbol',
content: (
Don't rely on color alone. Combine with percentage text or icons to convey progress status.
),
},
{
type: 'dont',
title: 'No ARIA Attributes',
content: (
Never omit ARIA attributes. Screen readers need semantic information about progress value and limits.
),
},
{
type: 'dont',
title: 'Animated-Only Progress',
content: (
Don't use animated bars without numeric progress indication. Users can't tell actual progress status.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The progress-bar component supports patterns that meet WCAG 2.2 Level AA standards:
- **Perceptible (1.3.1)** — ARIA role and live regions convey progress
- **Distinguishable (1.4.3)** — Sufficient contrast for progress fill and background
- **Operable (2.1)** — No keyboard traps or interaction required
- **Understandable (3.3.2)** — Percentage labels explain progress status
- **Robust (4.1.2)** — Proper ARIA roles and attributes
---
## ds-spinner
Docs: https://helvetia-design.vercel.app/?path=/docs/components-indicators-spinner-spinner--spinner
Spinner displays an animated loading indicator with customizable color, size, and variation.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| deactivated | boolean | false | If `true` the component will not add the spinner animation svg |
| inverted | boolean | false | If `true` the component can be used on dark background |
| label | string | '' | Visible label rendered next to the spinner. When omitted a translated aria-label is applied automatically. |
| label-position | "bottom" \| "right" | 'right' | Position of the visible label relative to the spinner animation. |
| size | "sm" \| undefined | | Defines the size of the spinner. If `sm` the spinner is smaller. |
| variation | "circle" \| "logo" | 'logo' | Defines the look of the spinner |
### Parts
| Name | Description |
| --- | --- |
| inner | The spinner animation container element. |
| label | The visible label rendered next to the spinner. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --spinner-logo-size | Size of the spinner logo variant. |
| --spinner-circle-size | Size of the spinner circle. |
| --spinner-circle-thickness | Border width of the spinner circle. |
| --spinner-circle-background-color | Background color of the circle border. |
| --spinner-circle-progress-color | Progress/animation color of the circle border. |
| --spinner-circle-border-style | Border style of the circle border. |
| --spinner-label-gap | Gap between the spinner animation and its label (right position). |
| --spinner-label-gap-bottom | Gap between the spinner animation and its label (bottom position). |
| --spinner-label-font-family | Font family of the visible label. |
| --spinner-label-font-size | Font size of the visible label. |
| --spinner-label-font-weight | Font weight of the visible label. |
| --spinner-label-line-height | Line height of the visible label. |
| --spinner-label-letter-spacing | Letter spacing of the visible label. |
| --spinner-label-text-decoration | Text decoration of the visible label. |
| --spinner-label-text-transform | Text transform of the visible label. |
| --spinner-label-color-text | Text color of the visible label. |
| --spinner-logo-color | Overrides the animated logo's fill color (read via JS, not CSS cascade — see spinner.tsx getColor()). |
| --spinner-animation-duration | Duration of the spinner animation. |
| --spinner-animation-easing | Easing function of the spinner animation. |
### Usage
## When to Use
- Show loading state while async operations are in progress
- Indicate data is being fetched from a server
- Display progress on long-running operations
- Replace button content while processing form submissions
- Show loading in skeleton screens or placeholder areas
## When NOT to Use
- For operations that complete instantly — don't show loading for fast operations
- As a decorative element — spinners should always indicate loading state
- When you can show actual progress — use progress bar component instead
- For page loads without context — spinners need accompanying text
- Without accessible labels or context
## Do's and Don'ts
### Spinner Context and Labels
Always provide context about what is loading. Use accompanying text to explain the operation.
Loading your profile...
),
description: 'Users understand what is loading',
},
{
type: 'incorrect',
title: 'Incorrect: Spinner without context',
content: (
),
description: "Users don't know what is being loaded",
},
]}
/>
### Spinner in Buttons
When showing loading state in buttons, disable the button and optionally replace the label with a spinner.
Saving...
\n Saving...\n'} />
>
),
description: 'Clear that action is in progress',
},
{
type: 'incorrect',
title: 'Incorrect: Spinner without disabled or label',
content: (
),
description: 'Users might click multiple times',
},
]}
/>
### Variants
Spinner variants with labels, providing additional context or information about the loading state.
Spinner variants for loading states in buttons, providing visual feedback during asynchronous operations.
Spinner variants for loading states in cards, indicating content is being loaded or refreshed.
### Accessibility
## Guidelines
Always include accompanying text explaining what is loading. This helps all users, especially those using screen readers, understand the current state.
),
},
{
type: 'do',
title: 'Use ARIA Live Regions',
content: (
Implement aria-live="polite" on parent containers to announce loading state changes to screen reader users.
),
},
{
type: 'do',
title: 'Indicate Loading State',
content: (
Use aria-busy="true" on the element containing the spinner to indicate loading status to assistive technology.
),
},
{
type: 'do',
title: 'Disable Interactivity During Loading',
content: (
Disable buttons and form controls while loading. This prevents users from triggering multiple submissions or confused actions.
),
},
{
type: 'dont',
title: 'Spinner Without Context',
content: (
Never show a spinner without explaining what is loading. Users won't understand the current operation.
),
},
{
type: 'dont',
title: 'Indefinite Loading',
content: (
Avoid showing spinners indefinitely without providing a way to cancel or escape. Users need a sense of control and progress.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The spinner component supports patterns that meet WCAG 2.2 Level AA standards:
- **Status Messages (4.1.3)** — Loading state is announced via ARIA live regions
- **Name, Role, Value (4.1.2)** — Spinner has proper ARIA attributes
- **Color Contrast (4.11.1)** — Spinner is visible against background
- **Animation Concerns (2.3.3)** — No flashing or animations that could trigger seizures
---
## ds-tag
Docs: https://helvetia-design.vercel.app/?path=/docs/components-indicators-tag-tag--tag
Tag renders a compact label element for categorizing, filtering, or marking content with optional close button.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| closable | boolean | false | The theme type of the tag. |
| color | "danger" \| "disabled" \| "green" \| "green-dark" \| "green-light" \| "info" \| "primary" \| "purple" \| "purple-dark" \| "purple-light" \| "red" \| "red-dark" \| "red-light" \| "success" \| "warning" \| "yellow" \| "yellow-dark" \| "yellow-light" \| undefined | | The theme type of the tag. |
| disabled | boolean | false | If `true`, the element is not mutable, focusable, or even submitted with the form. The user can neither edit nor focus on the control, nor its form control descendants. |
| position | "center" \| "left" \| "right" \| undefined | | Choosing left or center the tag is aligned to that side in the ds-card. |
| size | "lg" \| "md" \| "sm" \| undefined | | The size of the tag element |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsCloseClick | TagCloseClickDetail | Emitted when the input got clicked. |
### Slots
| Name | Description |
| --- | --- |
| default | The tag label text. |
### Parts
| Name | Description |
| --- | --- |
| label | The tag content element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --tag-color | Text color of the tag. |
| --tag-bg | Background color of the tag. |
| --tag-font-family | Font family of the tag text. |
| --tag-font-weight | Font weight of the tag text. |
| --tag-font-size | Font size of the tag text. |
| --tag-line-height | Line height of the tag text. |
| --tag-letter-spacing | Letter spacing of the tag text. |
| --tag-text-decoration | Text decoration of the tag text. |
| --tag-text-transform | Text transform of the tag text. |
| --tag-radius | Border radius of the tag. |
| --tag-px | Horizontal padding of the tag. |
| --tag-py | Vertical padding of the tag. |
| --tag-gap | Gap between icon and text. |
| --tag-icon-size | Size of the icon in the tag. |
### Usage
## When to Use
- Display categories or classifications for content
- Show skill tags or technology labels
- Indicate status or priority levels
- Filter or organize items by attribute
- Display removable tokens in an input field
- Show badges or labels for user-generated content
## When NOT to Use
- For standalone buttons or navigation elements — use the button component instead
- To display primary action calls-to-action — buttons are more prominent
- For important alerts or critical information — use notification or alert components
- As large block-level containers — tags are intended to be compact inline elements
## Do's and Don'ts
### Tag Content and Length
Keep tag content short and concise. Use single words or short phrases that quickly convey meaning.
JavaScript
React
Accessible
),
description: 'Quick to scan and understand at a glance',
},
{
type: 'incorrect',
title: 'Incorrect: Long, wordy tag content',
content: (
This is a very long tag that explains in detail what the thing is
),
description: 'Too verbose, defeats the purpose of tags',
},
]}
/>
### Color and Semantic Meaning
Use different tag colors to convey semantic meaning or category. Be consistent across your application.
Active
Pending
Closed
),
description: 'Colors consistently map to status meanings',
},
{
type: 'incorrect',
title: 'Incorrect: Random color usage',
content: (
Active
Pending
Closed
),
description: 'Colors don\'t match status meanings',
},
]}
/>
### Variants
Closable tags that can be removed by the user, providing a way to manage and dismiss tags as needed.
Grouping related tags together using the `TagGroup` component for better organization and visual hierarchy.
Use `color` property to apply different color variants to the tag, indicating various statuses or categories.
### Accessibility
## Guidelines
Use clear, meaningful text in tags that describes the category, status, or attribute. Avoid abbreviations or acronyms unless they're universally known.
),
},
{
type: 'do',
title: 'Color + Text Combination',
content: (
Always combine color with text to convey meaning. Users with color blindness should understand tag purpose from text alone.
),
},
{
type: 'do',
title: 'Keyboard Accessibility for Closable Tags',
content: (
When using closable tags, ensure the close button is keyboard accessible. Users should be able to focus and activate close using keyboard alone.
),
},
{
type: 'do',
title: 'Focus Indicators',
content: (
Provide clear focus indicators on closable tag close buttons. Keyboard users need visible feedback about which element has focus.
),
},
{
type: 'dont',
title: 'Color as Only Indicator',
content: (
Never rely solely on color to communicate tag meaning. Always include accompanying text so users with color vision deficiencies understand the tag purpose.
),
},
{
type: 'dont',
title: 'Icon-only Tags',
content: (
Avoid using icons alone in tags without text labels. Screen readers and color-blind users won't understand meaning.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The tag component supports patterns that meet WCAG 2.2 Level AA standards:
- **Color Contrast (4.11.1)** — Text meets minimum contrast ratios against background
- **Color Not Only Means (1.4.1)** — Color is not the only way to convey information
- **Focus Visible (2.4.7)** — Close buttons have visible focus indicators
- **Name, Role, Value (4.1.2)** — Proper semantic HTML and ARIA attributes
---
# Media
## ds-brand-icon
Docs: https://helvetia-design.vercel.app/?path=/docs/components-media-brandicon-brandicon--brandicon
Icon displays SVG icons with customizable color, size, rotation, and optional tile background.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| color | "green" \| "purple" \| "red" \| "yellow" \| undefined | | The color variant of the icon. |
| disabled | boolean | false | If `true`, the element is not mutable, focusable, or even submitted with the form. The user can neither edit nor focus on the control, nor its form control descendants. |
| invalid | boolean | false | If `true` the component gets a invalid red style. |
| size | "lg" \| "sm" \| undefined | | Defines the size of the icon. |
| src | string | '' | URL of an SVG file to fetch and display. |
| svg | string | '' | Svg content. |
| tile | boolean | false | If `true` the icon acts as a tile with a background color. |
### Parts
| Name | Description |
| --- | --- |
| inner | The SVG icon element wrapper. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --brand-icon-size | Size of the icon element. |
| --brand-icon-inner-size | Internal size of the SVG icon. |
| --brand-icon-inner-mt | Margin top of the SVG icon. |
| --brand-icon-color | Color of the icon. |
| --brand-icon-shape | Shape variant color of the icon. |
| --brand-icon-tile-radius | Border radius of the tile background. |
| --brand-icon-rotation | Rotation angle of the icon. |
### Usage
## When to Use
- Illustrate product categories or insurance lines (e.g. car, home, travel) in cards, tiles, or overviews
- Reinforce a section's topic with a large, colorful, decorative visual
- Pair with a tile background to create a compact category marker
- Show a disabled or invalid variant when the represented category is unavailable or has a data problem
## When NOT to Use
- As a functional, interactive UI icon — use `ds-icon` for actions, navigation, and status indicators
- As the only way to identify a category — always pair it with a text label
- At very small sizes where the illustration's detail is no longer legible
- To convey urgency or system status (error, warning, success) — brand icons are decorative, not semantic
## Do's and Don'ts
### Pair with a Text Label
Brand icons are decorative illustrations, not self-explanatory symbols. Always accompany them with a label that names the category.
Car Insurance
),
description: 'The label tells users what the illustration represents',
},
{
type: 'incorrect',
title: 'Incorrect: Icon alone',
content: (
),
description: 'Users must guess which product or category this represents',
},
]}
/>
### Use the Right Icon for the Job
Brand icons are large, illustrative, and decorative. For compact functional icons in buttons, links, or status messages, use `ds-icon` instead.
),
description: 'Large, colorful illustration fits a category overview',
},
{
type: 'incorrect',
title: 'Incorrect: Brand icon inside a button',
content: (
Continue
),
description: 'Use ds-icon for compact, functional icons inside interactive elements',
},
]}
/>
### Variants
The icon can be shown in an invalid or disabled state, both as a plain icon and as a tile.
Icons come in small, default, and large sizes. Choose the size that best fits the layout.
With `tile` set, the icon gets a colored background matching its `color`, at small, default, and large sizes.
### Accessibility
## Guidelines
The icon renders with aria-hidden="true" and is not announced to screen readers. Always place a
visible text label next to it so the represented category is available to everyone.
),
},
{
type: 'do',
title: 'Use Sufficient Color Contrast',
content: (
When using the tile background, verify the icon's fill colors keep enough contrast against the
tile background, especially in the disabled and invalid states.
),
},
{
type: 'do',
title: 'Keep a Legible Size',
content: (
Use a size large enough that the illustration's details remain distinguishable, particularly for users with
low vision.
),
},
{
type: 'dont',
title: 'Rely on the Icon Alone',
content: (
Do not use the icon as the only way to identify a category or product. Screen reader users and users who
don't recognize the illustration need a text alternative.
),
},
{
type: 'dont',
title: 'Use Color as the Only State Indicator',
content: (
Don't rely solely on the invalid or disabled color change to communicate state —
pair it with a text label or surrounding context.
),
},
]}
/>
## References
- [MDN: `aria-hidden`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden) - How hiding decorative content from assistive technology works
- [WCAG 2.2 — Non-text Content (1.1.1)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html) - Why decorative icons need a text alternative elsewhere on the page
- [WCAG 2.2 — Use of Color (1.4.1)](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) - Why color alone must not convey the icon's state
---
## ds-icon
Docs: https://helvetia-design.vercel.app/?path=/docs/components-media-icon-icon--icon
Icon displays SVG icons with customizable color, size, rotation, and optional tile background.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| color | "danger" \| "grey" \| "info" \| "primary" \| "success" \| "warning" \| undefined | | The theme type of the button. |
| disabled | boolean | false | If `true`, the element is not mutable, focusable, or even submitted with the form. The user can neither edit nor focus on the control, nor its form control descendants. |
| inline | boolean | false | If `true` the icon has display inline style |
| invalid | boolean | false | If `true` the component gets a invalid red style. |
| inverted | boolean | false | If `true` the icon is inverted |
| name | string | '' | Name of the baloise icon. |
| shadow | boolean | false | If `true` adds a box shadow to improve readability on image background |
| size | "lg" \| "md" \| "sm" \| "xl" \| undefined | | Defines the size of the icon. |
| src | string | '' | URL of an SVG file to fetch and display. |
| svg | string | '' | Svg content. |
| turn | boolean | false | If `true`, rotates the icon — the angle depends on `name`: 225deg for `plus` (turns it into an "×"), 180deg for `caret-down`/`caret-up`. Has no visual effect for any other icon name. |
### Parts
| Name | Description |
| --- | --- |
| icon | The SVG icon element wrapper. |
| inner | |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --icon-size | Size of the icon element. |
| --icon-inner-size | Internal size of the SVG icon. |
| --icon-inner-mt | Margin top of the SVG icon. |
| --icon-color | Color of the icon. |
| --icon-padding | Padding of the SVG icon. |
### Usage
## When to Use
- Enhance button or link labels with visual context
- Indicate file types or status in lists
- Show required field markers in forms
- Provide visual hierarchy and break up text
- Create icon-only buttons with proper ARIA labels
- Display status or state indicators
## When NOT to Use
- As the only way to convey meaning — always pair with text for critical information
- For decorative purposes at high scale — use small, subtle icons for decoration
- Without proper labels on interactive icon-only elements
- For essential information that users might not understand at a glance
- At sizes too small to be recognizable or clickable
## Do's and Don'ts
### Icon + Text Pairing
Icons should reinforce, not replace, text labels. Always provide accompanying text for meaningful content.
Download
Delete
),
description: 'Icon provides visual context for the action',
},
{
type: 'incorrect',
title: 'Incorrect: Icon replaces label without context',
content: (
),
description: 'Users must guess what these buttons do',
},
]}
/>
### Icon Accessibility
Always provide meaningful labels for icon-only interactive elements.
\n \n'} />
>
),
description: 'Screen readers announce the button purpose',
},
{
type: 'incorrect',
title: 'Incorrect: No accessible label',
content: (
),
description: 'Screen reader users won\'t know the button purpose',
},
]}
/>
### Variants
These icons are already available in the Design System. More can be added through the config or as a raw SVG via the `svg` prop.
Icons come in three sizes: small, medium, and large. Choose the size that best fits the context and layout of your application.
Use the `color` prop to apply a semantic color to the icon.
### Accessibility
## Guidelines
Always accompany icons with text labels for important content. Icons alone are not sufficient to communicate meaning to all users.
),
},
{
type: 'do',
title: 'Accessible Icon-only Buttons',
content: (
Use aria-label on buttons containing only icons. This tells screen readers what the button does.
),
},
{
type: 'do',
title: 'Decorative Icon Aria Hiding',
content: (
Mark purely decorative icons with aria-hidden="true" so screen readers skip them.
),
},
{
type: 'do',
title: 'Sufficient Size',
content: (
Use icon sizes of at least 24px for interactive elements to ensure adequate clickable area for all users, including those with motor impairments.
),
},
{
type: 'dont',
title: 'Icon as Only Meaning Carrier',
content: (
Do not rely solely on icons to convey critical information. Users may not understand the icon, or it may not render properly for some.
),
},
{
type: 'dont',
title: 'Color as Only Indicator',
content: (
Don't use color alone to differentiate icon meanings. Users with color blindness won't perceive the difference.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The icon component supports patterns that meet WCAG 2.2 Level AA standards:
- **Text Alternatives (1.1.1)** — Icons have text labels or ARIA labels
- **Color Contrast (4.11.1)** — Icons have sufficient contrast against backgrounds
- **Name, Role, Value (4.1.2)** — Proper ARIA labels on icon-only interactive elements
- **Visual Size (2.5.5)** — Icons are large enough to be easily clickable
---
## ds-logo
Docs: https://helvetia-design.vercel.app/?path=/docs/components-media-logo-logo--logo
Logo displays animated Baloise or Helvetia brand logos with customizable color, size, and responsive sizing.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| animated | boolean | false | Defines if the animation should be active |
| brand | "baloise" \| "helvetia" \| undefined | | Defines the brand of the logo. Default is 'helvetia'. |
| color | "inverted" \| "primary" | 'primary' | Defines the color of the logo. |
| size | "lg" \| "sm" \| undefined | | Size of the logo svg |
### Slots
| Name | Description |
| --- | --- |
| default | Optional label or caption text. |
### Parts
| Name | Description |
| --- | --- |
| animated | The animated logo container element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --logo-color | Color of the logo. |
| --logo-height | Height of the logo. |
| --logo-width | Width of the logo. |
| --logo-animation-duration | Duration of the logo animation. |
| --logo-animation-easing | Easing function of the logo animation. |
### Usage
## When to Use
- Display branding in application headers and footers
- Create brand identity in landing pages
- Use as a clickable link to the home page
- Show logo in authentication screens or login pages
- Include in error pages or empty states for branding
## When NOT to Use
- Multiple times on the same page — one logo per page section is sufficient
- At very small sizes where it becomes illegible
- Without proper spacing from content — maintain adequate breathing room
- As a replacement for proper page hierarchy — the logo supplements, not replaces, heading structure
## Best Practices
- Use the logo in headers and navigation areas where users expect brand identification
- Ensure the logo has sufficient space around it (minimum 24px padding)
- Keep the logo consistent in size and placement across related pages
- Consider using the animated variant on load for engaging brand presence
- Always make the logo clickable and link to the home page in navigation contexts
### Variants
> WIP coming soon
### Accessibility
## Guidelines
When used in navigation, make the logo a clickable link to the home page. This is a common navigation pattern users expect.
),
},
{
type: 'do',
title: 'Accessible Link Text',
content: (
Use an appropriate aria-label or text alternative for the logo link. Describe where the link navigates to, not just "logo".
),
},
{
type: 'do',
title: 'Sufficient Clickable Area',
content: (
Ensure the logo link has a clickable area of at least 44x44 pixels to accommodate users with motor impairments.
),
},
{
type: 'do',
title: 'Focus Indicator',
content: (
When the logo is a link, ensure there's a visible focus indicator for keyboard navigation.
),
},
{
type: 'dont',
title: 'Logo Without Link',
content: (
Don't use a non-interactive logo in header navigation areas. Users expect to click the logo to return home.
),
},
{
type: 'dont',
title: 'Decorative Logo Treatment',
content: (
If the logo is purely decorative (not a link), mark it with aria-hidden="true" to keep screen readers from announcing it.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The logo component supports patterns that meet WCAG 2.2 Level AA standards:
- **Link Purpose (2.4.4)** — Logo link destination is clear from context or label
- **Target Size (2.5.5)** — Logo link is at least 44x44 pixels
- **Focus Visible (2.4.7)** — Logo link has visible focus indicator
- **Motion (2.3.3)** — Animated logo doesn't contain problematic flashing
---
## ds-shape
Docs: https://helvetia-design.vercel.app/?path=/docs/components-media-shape-shape--shape
Shape renders decorative geometric shapes with customizable color, size, rotation, and variation.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| color | "green" \| "green-light" \| "purple" \| "purple-light" \| "red" \| "red-light" \| "yellow" \| "yellow-light" | 'purple' | The shape color |
| rotation | "0" \| "180" \| "270" \| "90" | '0' | The shape rotation |
| variation | "1" \| "2" \| "3" | '1' | The shape variation |
### Slots
| Name | Description |
| --- | --- |
| default | Optional overlay content or labels. |
### Parts
| Name | Description |
| --- | --- |
| shape | The SVG shape element container. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --shape-color | Fill color of the shape. |
| --shape-size | Size of the shape (width and height). |
| --shape-rotation | Rotation angle of the shape. |
| --shape-opacity | Opacity of the shape. |
### Usage
## When to Use
- Add decorative visual accents to layouts
- Create abstract geometric designs
- Add subtle background shapes to sections
- Enhance visual hierarchy without content
- Provide design system branded shapes
- Create visual separation between sections
## When NOT to Use
- For meaningful content — use actual content elements
- For interactive elements — shapes are purely decorative
- For SEO-critical content — shapes don't contribute to page meaning
- For functional icons — use the icon component
- For complex illustrations — use custom SVG or images
- For accessible diagrams — shapes may not convey meaning to screen readers
### Variants
> WIP - Variants for shape component are still being developed and will be added here soon.
### Accessibility
## Guidelines
Use aria-hidden="true" for purely decorative shapes. Screen readers will skip them.
),
},
{
type: 'do',
title: 'Provide Alt Text if Meaningful',
content: (
If the shape has meaning, use aria-label to describe it for screen readers.
),
},
{
type: 'do',
title: 'Sufficient Contrast',
content: (
Ensure shapes have sufficient color contrast against background (3:1 minimum for graphics).
),
},
{
type: 'do',
title: 'Don\'t Obstruct Content',
content: (
Ensure decorative shapes don't overlap or obscure meaningful content.
),
},
{
type: 'dont',
title: 'Meaningful Shapes Without Labels',
content: (
Don't use shapes to convey information without accessible descriptions or labels.
),
},
{
type: 'dont',
title: 'Low Contrast Shapes',
content: (
Don't use shapes with insufficient contrast against backgrounds. Users may not see them.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The shape component supports patterns that meet WCAG 2.2 Level AA standards:
- **Semantics (1.3.1)** — Decorative shapes use aria-hidden
- **Color Contrast (1.4.3)** — Sufficient contrast for visible shapes
- **Meaningful Content (1.4.11)** — Shapes don't obscure important content
- **Text Alternatives (1.1.1)** — Meaningful shapes have aria-label or alt text
---
# Navigation
## ds-app-navbar
Docs: https://helvetia-design.vercel.app/?path=/docs/components-navigation-appnavbar-app-navbar--app-navbar
AppNavbar provides semantic navigation with responsive sidebar menu and keyboard support.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| container | "compact" \| "default" \| "fluid" \| undefined | | Sets the inner content container width. Accepts `'default'`, `'fluid'`, or `'compact'`. Matches the `ds-container` sizing variants. |
| light | boolean | false | If `true` the navbar will use a light color scheme. |
| open | boolean | false | If `true` the navbar will open the sidebar menu. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsMenuCloseEnd | void | Emitted when the sidebar menu finishes closing |
| dsMenuCloseStart | void | Emitted when the sidebar menu starts closing |
| dsMenuOpenEnd | void | Emitted when the sidebar menu finishes opening |
| dsMenuOpenStart | void | Emitted when the sidebar menu starts opening |
### Methods
| Signature | Description |
| --- | --- |
| closeSidebar() => Promise | Closes the sidebar menu |
| openSidebar() => Promise | Opens the sidebar menu |
| toggleSidebar() => Promise | Toggles the sidebar menu open/closed state |
### Slots
| Name | Description |
| --- | --- |
| actions | Action buttons (always visible, positioned on the right) |
| brand | Logo or branding element (always visible) |
| menu-end | Right navigation links and action buttons (inline on desktop, in sidebar on mobile) |
| menu-start | Left navigation links (inline on desktop, in sidebar on mobile) |
| title | Page title or heading (visible on desktop and larger screens) |
### Parts
| Name | Description |
| --- | --- |
| hamburger | The mobile hamburger button |
| nav | The semantic navigation container |
| sidebar | The mobile menu sidebar (aside element) |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --app-navbar-background | Background color of the app-navbar |
| --app-navbar-p | Inline padding of the app-navbar container |
| --app-navbar-height | Height of the app-navbar container |
| --app-navbar-z-index | Stacking context of the app-navbar |
| --app-navbar-shadow | Shadow of the app-navbar |
| --app-navbar-max-width | Max width of the content container (default container) |
| --app-navbar-max-width-fluid | Max width of the content container in fluid container mode |
| --app-navbar-max-width-compact | Max width of the content container in compact container mode |
| --app-navbar-brand-gap | Gap between brand elements |
| --app-navbar-brand-focus-radius | Border radius for brand focus indicator |
| --app-navbar-brand-focus-p | Padding that expands the brand focus indicator around the brand |
| --app-navbar-title-color | Text color of the title |
| --app-navbar-title-font-family | Font family of the title |
| --app-navbar-title-font-size | Font size of the title |
| --app-navbar-title-font-weight | Font weight of the title |
| --app-navbar-title-line-height | Line height of the title |
| --app-navbar-title-letter-spacing | Letter spacing of the title |
| --app-navbar-title-text-decoration | Text decoration of the title |
| --app-navbar-title-text-transform | Text transform of the title |
| --app-navbar-hamburger-width | Width of the hamburger button |
| --app-navbar-hamburger-height | Height of the hamburger button |
| --app-navbar-hamburger-p | Padding inside the hamburger button |
| --app-navbar-hamburger-radius | Border radius of the hamburger button |
| --app-navbar-hamburger-transition-duration | Transition duration for hamburger hover/active states |
| --app-navbar-sidebar-max-width | Maximum width of the drawer panel |
| --app-navbar-sidebar-slide-duration | Animation duration for drawer slide-in/out |
| --app-navbar-sidebar-backdrop-color | Background color of the drawer backdrop overlay |
| --app-navbar-sidebar-backdrop-opacity | Opacity of the backdrop when drawer is open |
| --app-navbar-sidebar-panel-background | Background color of the sidebar panel |
| --app-navbar-sidebar-panel-shadow | Box shadow of the sidebar panel |
| --app-navbar-sidebar-panel-border-top | Top border of the sidebar panel |
| --app-navbar-sidebar-panel-border-width | Width of the sidebar panel top border |
| --app-navbar-sidebar-panel-border-color | Color of the sidebar panel top border |
| --app-navbar-sidebar-z-index | Stacking context of the sidebar overlay |
| --app-navbar-sidebar-content-gap | Gap between menu items in sidebar |
| --app-navbar-sidebar-px | Horizontal padding of sidebar content |
| --app-navbar-sidebar-py | Vertical padding of sidebar content |
| --app-navbar-sidebar-end-mt | Top margin of the sidebar menu-end section |
| --app-navbar-sidebar-item-min-height | Minimum height of menu items in sidebar |
| --app-navbar-sidebar-item-py | Vertical padding of menu items |
| --app-navbar-sidebar-item-px | Horizontal padding of menu items |
| --app-navbar-sidebar-item-font-size | Font size of menu items in sidebar |
| --app-navbar-sidebar-item-font-weight | Font weight of menu items in sidebar |
| --app-navbar-sidebar-item-font-family | Font family of menu items in sidebar |
| --app-navbar-sidebar-item-line-height | Line height of menu items in sidebar |
| --app-navbar-sidebar-item-letter-spacing | Letter spacing of menu items in sidebar |
| --app-navbar-sidebar-item-text-decoration | Text decoration of menu items in sidebar |
| --app-navbar-sidebar-item-text-transform | Text transform of menu items in sidebar |
| --app-navbar-sidebar-item-color | Text color of menu items in sidebar |
| --app-navbar-sidebar-item-background-active | Background of active menu items in sidebar |
| --app-navbar-sidebar-item-background-hover | Background of menu items on hover in sidebar |
| --app-navbar-sidebar-item-color-hover | Text color of menu items on hover in sidebar |
| --app-navbar-sidebar-item-color-active | Text color of active menu items in sidebar |
| --app-navbar-sidebar-item-divider-color | Color of divider below menu items |
| --app-navbar-sidebar-item-divider-color-active | Color of divider for active menu items |
| --app-navbar-sidebar-item-divider-size | Thickness of divider below menu items |
| --app-navbar-sidebar-item-divider-radius | Border radius of divider below menu items |
| --app-navbar-sidebar-item-focus-radius | Border radius of the sidebar menu item focus indicator |
| --app-navbar-sidebar-item-chevron-size | Size of the chevron indicator |
| --app-navbar-sidebar-item-chevron-color | Color of the chevron indicator |
| --app-navbar-menu-gap | Gap between menu and actions sections |
| --app-navbar-menu-start-gap | Gap between menu-start items on desktop |
| --app-navbar-menu-item-color | Text color of menu items on desktop |
| --app-navbar-menu-item-font-family | Font family of menu items on desktop |
| --app-navbar-menu-item-font-size | Font size of menu items on desktop |
| --app-navbar-menu-item-font-weight | Font weight of menu items on desktop |
| --app-navbar-menu-item-line-height | Line height of menu items on desktop |
| --app-navbar-menu-item-letter-spacing | Letter spacing of menu items on desktop |
| --app-navbar-menu-item-text-decoration | Text decoration of menu items on desktop |
| --app-navbar-menu-item-text-transform | Text transform of menu items on desktop |
| --app-navbar-menu-item-font-weight-active | Font weight of the selected/active desktop menu item — single-property part modifier. |
| --app-navbar-menu-item-py | Vertical padding of desktop menu items |
| --app-navbar-menu-item-px | Horizontal padding of desktop menu items |
| --app-navbar-menu-item-border-radius | Border radius of desktop menu items |
| --app-navbar-menu-item-color-hover | Text color of desktop menu items on hover |
| --app-navbar-menu-item-color-selected | Text color of selected desktop menu items |
| --app-navbar-menu-item-color-selected-hover | Text color of selected desktop menu items on hover |
| --app-navbar-menu-item-color-active | Text color of selected desktop menu items on click |
| --app-navbar-menu-item-underline-height | Height of the active indicator underline |
| --app-navbar-menu-item-underline-border-radius | Border radius of the underline |
| --app-navbar-menu-item-underline-offset | Distance of the underline below the menu item |
| --app-navbar-menu-item-transition-duration | Transition duration for menu items |
| --app-navbar-menu-end-gap | Gap between menu-end items |
| --app-navbar-container-gap | Gap between brand and content in nav |
| --app-navbar-content-gap | Gap between items in content area |
| --app-navbar-button-color-text | Text color of buttons |
| --app-navbar-button-color-background | Background color of buttons |
| --app-navbar-button-color-border | Border (composite: width, style, color) of buttons |
| --app-navbar-button-color-text-hover | Text color of buttons on hover |
| --app-navbar-button-color-background-hover | Background color of buttons on hover |
| --app-navbar-button-color-border-hover | Border (composite: width, style, color) of buttons on hover |
| --app-navbar-button-color-text-active | Text color of buttons on active |
| --app-navbar-button-color-background-active | Background color of buttons on active |
| --app-navbar-button-color-border-active | Border (composite: width, style, color) of buttons on active |
| --app-navbar-focus-color-start | Start color of the focus indicator gradient |
| --app-navbar-focus-color-end | End color of the focus indicator gradient |
### Usage
## When to Use
- Creating the primary navigation header for your application
- Providing site branding and logo placement
- Organizing main navigation links (menu-start, menu-end slots)
- Adding action buttons or user account controls
- Implementing responsive mobile menu with sidebar drawer
- Building accessible navigation with semantic HTML (``, ``, ``)
## When NOT to Use
- For secondary or in-page navigation — use breadcrumbs or tabs instead
- For long lists of navigation items without grouping — consider subnav or mega menu patterns
- For mobile-only navigation — navbar is responsive and works on all screen sizes
- When you need custom animations — the navbar has built-in animation handling
### Variants
Basic navbar with logo, title, navigation links, and action buttons. Automatically adapts to mobile with a sidebar drawer.
Mobile-optimized navbar with simplified branding and navigation. Resize your viewport to see the hamburger menu and sidebar drawer behavior.
Navbar with custom SVG logo in the brand slot. Shows how to structure custom branding elements while maintaining proper layout.
### Accessibility
## Guidelines
Place <a> elements in navigation slots and <button> elements for actions. The navbar renders a semantic <nav> element with role="navigation" and aria-label="Main Navigation".
),
},
{
type: 'do',
title: 'Indicate the current page',
content: (
Use aria-current="page" on the link matching the current page. This tells screen reader users which page they are on.
),
},
{
type: 'do',
title: 'Ensure hamburger menu is keyboard accessible',
content: (
The navbar automatically handles keyboard support: press Escape to close the sidebar, and Tab navigates through menu items. Focus is managed and restored properly.
),
},
{
type: 'do',
title: 'Label action buttons clearly',
content: (
Use descriptive labels for buttons in the actions slot. If using icon-only buttons, provide aria-label attributes.
),
},
{
type: 'dont',
title: 'Avoid keyboard traps in navigation',
content: (
Do not add custom focus management inside navbar slots. The navbar handles focus containment in the sidebar automatically when the menu is open.
),
},
{
type: 'dont',
title: 'Don\'t hide navigation from screen readers',
content: (
Don\'t use display: none or visibility: hidden on navigation slots. The navbar manages visibility based on responsive behavior and sidebar state.
),
},
]}
/>
## References
- [MDN: Navigation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav) - Semantic navigation element
- [MDN: aria-current](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) - Indicating the current page
- [MDN: aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) - Labeling interactive elements
- [WCAG 2.2: Navigation Mechanisms](https://www.w3.org/WAI/WCAG22/Understanding/navigation-mechanisms.html) - Best practices for navigational structures
- [ARIA: Complementary](https://www.w3.org/WAI/ARIA/apg/patterns/complementary/) - Sidebar drawer patterns
---
## ds-pagination
Docs: https://helvetia-design.vercel.app/?path=/docs/components-navigation-pagination-pagination--pagination
Pagination provides navigation controls for moving between pages of content with customizable size, alignment, and layout.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| align | "end" \| "start" \| undefined | | Align the buttons to start, center or end |
| disabled | boolean | false | Disables component |
| label | string | '' | The label for the navigation landmark |
| page-range | number | 2 | Specify the max visible pages before and after the selected page |
| size | "sm" \| undefined | | Size of the buttons |
| sticky | boolean | false | If 'true, the pagination will be sticky to the top |
| text-next | string | '' | The label for the next page button |
| text-previous | string | '' | The label for the previous page button |
| top | number | 0 | If sticky, the top position will be determined by this value |
| total-pages | number | 1 | The total amount of pages |
| value | number | 1 | Current selected page |
| variant | "dots" \| undefined | | Defines the layout of the pagination |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsChange | PaginationChangeDetail | Triggers when a page change happens |
### Methods
| Signature | Description |
| --- | --- |
| next() => Promise | Go to the next page |
| previous() => Promise | Go to the previous page |
### Slots
| Name | Description |
| --- | --- |
| default | Optional custom content or labels. |
### Parts
| Name | Description |
| --- | --- |
| ellipsis | The ellipsis item shown when pages are collapsed. |
| list | The list containing the page and ellipsis items. |
| navigation | The nav landmark wrapping all pagination controls. |
| next | The button that navigates to the next page. |
| page | Each page number button. |
| previous | The button that navigates to the previous page. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --pagination-gap | Gap between pagination items. |
| --pagination-dots-background | Background color of the ellipsis dots. |
| --pagination-dots-radius | Border radius of the ellipsis dots. |
| --pagination-dots-gap | Gap between the ellipsis dots. |
| --pagination-ellipsis-width | Width of the ellipsis item from tablet up. |
| --pagination-dots-marker-size | Width and height of a dot marker. |
| --pagination-dots-min-width | Minimum width of the "x of y" counter badge. |
| --pagination-dots-max-width | Maximum width of the "x of y" counter badge. |
| --pagination-ellipsis-font-family | Font family of the ellipsis text. |
| --pagination-ellipsis-font-size | Font size of the ellipsis text. |
| --pagination-ellipsis-font-weight | Font weight of the ellipsis text. |
| --pagination-ellipsis-line-height | Line height of the ellipsis text. |
| --pagination-ellipsis-letter-spacing | Letter spacing of the ellipsis text. |
| --pagination-ellipsis-text-decoration | Text decoration of the ellipsis text. |
| --pagination-ellipsis-text-transform | Text transform of the ellipsis text. |
| --pagination-dots-font-family | Font family of the "x of y" counter text. |
| --pagination-dots-font-size | Font size of the "x of y" counter text. |
| --pagination-dots-font-weight | Font weight of the "x of y" counter text. |
| --pagination-dots-line-height | Line height of the "x of y" counter text. |
| --pagination-dots-letter-spacing | Letter spacing of the "x of y" counter text. |
| --pagination-dots-text-decoration | Text decoration of the "x of y" counter text. |
| --pagination-dots-text-transform | Text transform of the "x of y" counter text. |
| --pagination-dots-value-font-family | Font family of the current-page value. |
| --pagination-dots-value-font-size | Font size of the current-page value. |
| --pagination-dots-value-font-weight | Font weight of the current-page value. |
| --pagination-dots-value-line-height | Line height of the current-page value. |
| --pagination-dots-value-letter-spacing | Letter spacing of the current-page value. |
| --pagination-dots-value-text-decoration | Text decoration of the current-page value. |
| --pagination-dots-value-text-transform | Text transform of the current-page value. |
### Usage
## When to Use
- Navigate large lists or search results across multiple pages
- Break content into manageable chunks for readability
- Show results count and page position to users
- Provide next/previous navigation between sequential pages
- Display paginated data in tables or galleries
## When NOT to Use
- For very small datasets (fewer than 20 items) — consider showing all items
- For infinite scroll experiences — pagination breaks the paradigm
- For sequential step-by-step workflows — use step indicators or breadcrumbs
- For single long pages — pagination not needed
- For mobile with limited space — consider infinite scroll or "Load More" button
### Variants
With `align` prop, you can align the pagination to the left, center, or right of its container.
By default, it is aligned to the center.
With `range` prop, you can control the number of pages displayed in the pagination.
The `disabled` prop can be used to disable the pagination, preventing user interaction and visually indicating that it is inactive.
With `size` prop, you can adjust the size of the pagination to fit different design needs and contexts.
### Accessibility
## Guidelines
Element',
content: (
Wrap pagination in <nav> element. Use aria-label="Pagination" to identify the navigation purpose.
),
},
{
type: 'do',
title: 'Announce Current Page',
content: (
Use aria-current="page" on the active page button. Screen readers need to know the current page.
),
},
{
type: 'do',
title: 'Keyboard Navigation',
content: (
All page buttons and nav links must be keyboard accessible. Use Tab to navigate between pages.
),
},
{
type: 'do',
title: 'Descriptive Page Information',
content: (
Display "Page X of Y" or result counts. Users need context about their position.
),
},
{
type: 'dont',
title: 'No Semantic Navigation',
content: (
Never use non-semantic divs for pagination buttons. Use actual <button> or <a> elements.
),
},
{
type: 'dont',
title: 'Missing Page Information',
content: (
Don't hide page information. Screen reader users need to know current page and total count.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The pagination component supports patterns that meet WCAG 2.2 Level AA standards:
- **Semantic Navigation (1.3.1)** — Uses nav element with aria-label
- **Keyboard Accessible (2.1.1)** — Tab navigates between page buttons
- **Focus Visible (2.4.7)** — Active page button clearly marked
- **Link Context (2.4.9)** — Page numbers provide clear context
- **Name, Role, Value (4.1.2)** — Buttons have descriptive labels
---
## ds-steps
Docs: https://helvetia-design.vercel.app/?path=/docs/components-navigation-steps-steps--steps
Steps coordinates ds-step and ds-step-panel children into an accessible stepped interface, supporting panels and navigation variants.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| color | "green" \| "purple" \| "red" \| "yellow" \| undefined | | Accent color applied to inactive circles and connector lines. |
| label | string | '' | Accessible label for the navigation landmark (navigation variant only). |
| value | null \| string \| undefined | | The `name` of the currently selected ds-step (panels variant). |
| vertical | boolean | false | If `true`, the steplist is displayed vertically. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsChange | StepsChangeDetail | Emitted when the selected step changes (panels variant only). |
### Slots
| Name | Description |
| --- | --- |
| default | ds-step-panel children (panels variant). |
| step | ds-step children; managed automatically by ds-steps. |
### Parts
| Name | Description |
| --- | --- |
| steplist | The steplist container. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --steps-connector-color | Color of the connector line between steps. |
| --steps-connector-color-filled | Color of the connector line for completed steps. |
| --steps-connector-height | Thickness of the connector line. |
| --steps-connector-radius | Corner radius of the connector line. |
| --steps-connector-gap | Space between a circle and the connector line leaving it. |
| --steps-circle-size | Diameter of the step circle. |
| --steps-circle-size-sm | Diameter of the step circle on mobile. |
| --steps-circle-radius | Corner radius of the step circle. |
| --steps-circle-opacity-disabled | Opacity of the circle (disabled state). |
| --steps-circle-color-bg | Background color of the circle (default state). |
| --steps-circle-color-bg-selected | Background color of the circle (selected state). |
| --steps-circle-color-bg-done | Background color of the circle (done state). |
| --steps-circle-color-bg-invalid | Background color of the circle (invalid state). |
| --steps-circle-color-bg-disabled | Background color of the circle (disabled state). |
| --steps-circle-color-text | Text/icon color inside the circle (default state). |
| --steps-circle-color-text-selected | Text/icon color inside the circle (selected state). |
| --steps-circle-color-text-done | Text/icon color inside the circle (done state). |
| --steps-circle-color-text-invalid | Text/icon color inside the circle (invalid state). |
| --steps-circle-color-text-disabled | Text/icon color inside the circle (disabled state). |
| --steps-step-font-family | Font family for step labels and circle numbers. |
| --steps-step-font-size | Font size for step labels and circle numbers. |
| --steps-step-font-weight | Font weight for step labels. |
| --steps-step-line-height | Line height for step labels and circle numbers. |
| --steps-step-letter-spacing | Letter spacing for step labels and circle numbers. |
| --steps-step-text-decoration | Text decoration for step labels and circle numbers. |
| --steps-step-text-transform | Text transform for step labels and circle numbers. |
| --steps-step-color | Text color for step labels (default state). |
| --steps-step-color-selected | Text color for step labels (selected state). |
| --steps-step-color-done | Text color for step labels (done state). |
| --steps-step-color-invalid | Text color for step labels (invalid state). |
| --steps-step-color-focus | Focus ring color for step buttons. |
| --steps-step-opacity-disabled | Opacity of step labels (disabled state). |
| --steps-step-gap | Space between the circle and its label (horizontal layout). |
| --steps-step-gap-vertical | Space between the circle and its label (vertical layout). |
| --steps-step-py | Vertical padding of a step in the vertical layout. |
| --steps-step-radius-focus | Corner radius of the focus ring on navigation links. |
| --steps-color-purple | Brand tint used by the purple color variant. |
| --steps-color-green | Brand tint used by the green color variant. |
| --steps-color-red | Brand tint used by the red color variant. |
| --steps-color-yellow | Brand tint used by the yellow color variant. |
### Usage
## When to Use
- Multi-step processes where the user must complete steps in order, such as checkout, onboarding, or wizards.
- When progress visibility helps the user understand how far along they are and how many steps remain.
- When navigating between major sections of a form or flow that each require distinct user input.
- As a navigation landmark (`navigation` variant) when steps represent separate pages in a linear flow.
## When NOT to Use
- For simple tabbed content with no sequential relationship — use `ds-tabs` instead.
- When there are fewer than two steps.
- When all steps are always accessible regardless of completion order — consider `ds-tabs`.
- When steps have no meaningful labels — the circle index alone is not sufficient for orientation.
## Do's and Don'ts
### Step labels
Cart content
Shipping content
Payment content
),
description: 'Short labels make the purpose of each step immediately clear.',
},
{
type: 'incorrect',
title: 'Incorrect: No labels',
content: (
Cart content
Shipping content
Payment content
),
description: 'Steps without labels force users to guess the purpose of each step from context alone.',
},
]}
/>
### Step state
Cart
Shipping
Payment
),
description: 'Mark completed steps as done so users can track their progress at a glance.',
},
{
type: 'incorrect',
title: 'Incorrect: All steps appear equal',
content: (
Cart
Shipping
Payment
),
description: 'Leaving completed steps without visual feedback removes the sense of progress.',
},
]}
/>
### Variants
The default horizontal steps with numbered circles, connector lines, and a panel for each step. The first non-disabled step is selected automatically.
Steps support four states: `done` (blue circle with checkmark), `invalid` (red circle with exclamation mark), `disabled` (muted, not selectable), and the default active state.
Setting `hidden` on a `ds-step` removes it from the layout and renumbers the remaining visible steps. The associated panel is also hidden. Useful for conditionally showing steps based on user choices.
Setting `vertical` on `ds-steps` stacks the circles in a column with labels to the right, connected by a continuous vertical line. The panel content renders below the steplist.
When `ds-step` children contain anchor links instead of panel references, the component renders a `` landmark. Pass a descriptive `label` to name the landmark for screen readers. Steps in this mode are not interactive buttons.
The navigation variant also supports `vertical` layout, placing the anchor links to the right of the circles in a column.
The `color` prop replaces the default grey on inactive circles and connector lines with a brand color tint. Use this when the steps sit within a color-coded context such as a product or status flow.
### Accessibility
## Guidelines
When using steps as page navigation, set the label prop to a meaningful name (e.g. "Checkout steps"). This labels the {''} landmark so screen reader users can identify and navigate to it.
),
},
{
type: 'dont',
title: "Don't rely on color alone to communicate state",
content: (
Step states (done, invalid, disabled) are conveyed through both color and icon/symbol changes. Do not override the icon content with CSS in a way that removes the visual distinction for users who perceive color differently.
),
},
{
type: 'do',
title: 'Use aria-current on the active navigation link',
content: (
In the navigation variant, add {'aria-current="step"'} to the {''} inside the currently active ds-step. This tells assistive technologies which step the user is currently on.
),
},
{
type: 'dont',
title: "Don't skip required step labels",
content: (
Always provide a meaningful label on each ds-step. The numbered circle alone does not give enough context for screen reader users to understand the purpose of each step.
),
},
{
type: 'do',
title: 'Keep step labels short and action-oriented',
content: (
Use concise, noun-based labels like "Cart", "Shipping", or "Confirmation". These read clearly in the context of the tablist role and are easy to distinguish when navigating by keyboard.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The steps component implements patterns that meet WCAG 2.2 Level AA standards:
- **1.3.1 Info and Relationships** — The panels variant uses `role="tablist"`, `role="tab"`, and `role="tabpanel"` with `aria-controls` and `aria-labelledby` linkage. The navigation variant uses a `` landmark with an `` list.
- **1.4.1 Use of Color** — Step states are communicated through both color changes and distinct icon/symbol content (checkmark, exclamation mark), not color alone.
- **2.1.1 Keyboard** — All steps are reachable and activatable by keyboard. Arrow keys (Left/Right or Up/Down in vertical mode), Home, and End navigate between steps in the panels variant.
- **2.4.3 Focus Order** — Focus moves to the newly selected step after keyboard activation, maintaining a logical focus sequence.
- **4.1.2 Name, Role, Value** — Each step exposes `aria-selected` and `aria-disabled` states. The active panel is visible and the inactive panels have `aria-hidden="true"`.
---
## ds-tabs
Docs: https://helvetia-design.vercel.app/?path=/docs/components-navigation-tabs-tabs--tabs
Tabs coordinates ds-tab and ds-tab-panel children into an accessible tabbed interface, supporting panels and navigation variants.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| color | "green" \| "purple" \| "red" \| "yellow" \| undefined | | Accent color applied to the bottom border track and selected indicator. |
| fullwidth | boolean | false | If `true`, tab buttons expand to fill the available width equally. |
| inverted | boolean | false | If `true`, the component adapts for use on a dark (primary) background — all labels and the indicator become white. |
| label | string | '' | Accessible label for the navigation landmark (navigation variant only). |
| value | null \| string \| undefined | | The `name` of the currently selected ds-tab (panels variant). |
| vertical | boolean | false | If `true`, the tablist is displayed vertically on the left side. |
| vertical-col-size | "full" \| "half" \| "one-quarter" \| "one-third" \| "three-quarters" \| "two-thirds" | 'one-third' | The col size of the tablist in vertical mode. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsChange | TabsChangeDetail | Emitted when the selected tab changes (panels variant only). |
### Slots
| Name | Description |
| --- | --- |
| default | ds-tab-panel children (panels variant). |
| tab | ds-tab children; managed automatically by ds-tabs. |
### Parts
| Name | Description |
| --- | --- |
| tablist | The tablist container. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --tabs-border-base | Border of the tablist border track. Set to transparent to hide it. |
| --tabs-border-width | Width of the border track and the indicator. |
| --tabs-gap | Gap between tab buttons. |
| --tabs-tab-px | Horizontal padding inside each tab button. |
| --tabs-tab-py | Vertical padding inside each tab button. |
| --tabs-tab-min-height | Minimum height of a tab button (touch target). |
| --tabs-tab-gap | Gap between a tab's label and its icon or badge. |
| --tabs-tab-unselected-font-family | Font family of an unselected tab button. |
| --tabs-tab-unselected-font-size | Font size of an unselected tab button. |
| --tabs-tab-unselected-font-weight | Font weight of an unselected tab button. |
| --tabs-tab-unselected-line-height | Line height of an unselected tab button. |
| --tabs-tab-unselected-letter-spacing | Letter spacing of an unselected tab button. |
| --tabs-tab-unselected-text-decoration | Text decoration of an unselected tab button. |
| --tabs-tab-unselected-text-transform | Text transform of an unselected tab button. |
| --tabs-tab-selected-font-family | Font family of the selected tab button. |
| --tabs-tab-selected-font-size | Font size of the selected tab button. |
| --tabs-tab-selected-font-weight | Font weight of the selected tab button. |
| --tabs-tab-selected-line-height | Line height of the selected tab button. |
| --tabs-tab-selected-letter-spacing | Letter spacing of the selected tab button. |
| --tabs-tab-selected-text-decoration | Text decoration of the selected tab button. |
| --tabs-tab-selected-text-transform | Text transform of the selected tab button. |
| --tabs-tab-unselected-color-base | Text color of an unselected tab button. |
| --tabs-tab-unselected-color-hover | Text color of a hovered, unselected tab button. |
| --tabs-tab-unselected-color-active | Text color of a pressed, unselected tab button. |
| --tabs-tab-selected-color-base | Text color of the selected tab button. |
| --tabs-tab-selected-color-hover | Text color of a hovered, selected tab button. |
| --tabs-tab-selected-color-active | Text color of a pressed, selected tab button. |
| --tabs-indicator-unselected-base | Indicator border of an idle, unselected tab. |
| --tabs-indicator-unselected-hover | Indicator border of a hovered, unselected tab. |
| --tabs-indicator-selected-base | Indicator border of the selected tab. |
| --tabs-indicator-selected-hover | Indicator border of a hovered, selected tab. |
| --tabs-indicator-radius | Corner radius of the indicator. |
| --tabs-tab-color-focus | Color of the keyboard focus ring on tab buttons. |
| --tabs-tab-radius | Corner radius of the keyboard focus ring on tab buttons. |
| --tabs-tab-badge-size | Reference size used to offset a slotted badge. |
| --tabs-panel-px | Horizontal padding inside the content panel. |
| --tabs-panel-py | Vertical padding inside the content panel. |
| --tabs-panel-vertical-py | Vertical padding inside the content panel in vertical mode. |
| --tabs-panel-min-height | Minimum height of the content panel in vertical mode. |
| --tabs-vertical-gap | Gap between the tablist and the content panel in vertical mode. |
| --tabs-vertical-gap-mobile | Gap between the tablist and the content panel in vertical mode on mobile. |
| --tabs-scroll-fade-bg | Background color for the edge-fade gradient beside the carousel buttons. |
| --tabs-scroll-btn-size | Width and height of a carousel scroll button. |
| --tabs-scroll-btn-margin | Space between a carousel scroll button and the tablist. |
| --tabs-scroll-btn-radius | Corner radius of a carousel scroll button. |
| --tabs-scroll-btn-opacity-inactive | Opacity of a scroll button that cannot scroll further. |
### Usage
## When to Use
- Organising related content into distinct sections within a single page view
- Allowing users to switch between multiple views without leaving the current context
- Reducing vertical scroll by grouping content that doesn't need to be visible simultaneously
- As a navigation aid when linking to page sections via anchor links (navigation variant)
## When NOT to Use
- When content needs to be compared side by side — use a layout instead
- When there are fewer than two tabs — just show the content directly
- When tab content is deeply nested or requires its own navigation
- When the sequence of content matters — use a stepper or accordion instead
## Do's and Don'ts
### Tab Labels
Overview
Details
History
Overview content
Details content
History content
),
description: 'Use concise labels (1–3 words) that clearly describe the panel content.',
},
{
type: 'incorrect',
title: 'Incorrect: Lengthy labels',
content: (
General Overview Information
Detailed Technical Specifications
Overview content
Details content
),
description: 'Avoid long labels that cause the tablist to overflow or wrap awkwardly.',
},
]}
/>
### Panels vs. Navigation
Tab A
Tab B
Content A
Content B
),
description: 'Use ds-tab-panel children when the content is managed in place.',
},
{
type: 'correct',
title: 'Correct: Navigation for anchor links',
content: (
Overview
Details
),
description: 'Use anchor link children (without ds-tab-panel) when tabs navigate to page sections.',
},
]}
/>
### Variants
The default tabs variant with a horizontal tablist and associated content panels.
The `color` prop replaces the default grey border track and selected indicator with a brand color. Use this when tabs sit within a color-coded context such as a product, category, or status view.
Set `inverted` when placing tabs on a dark (primary) background. All labels and the indicator turn white; non-selected tabs use the body font at regular weight to preserve the visual hierarchy.
When `fullwidth` is set, tab buttons stretch to fill the available width equally. Icons placed inside `ds-tab` complement the label and add visual context.
A `ds-badge` can be placed inside `ds-tab` to surface counts or status indicators alongside the label.
Brand icons (full-color SVG) can be passed via the `svg` property of `ds-icon` inside `ds-tab`. A subtitle can be added below the label using inline `span` elements.
Setting `vertical` places the tablist along the left side and the content panel to the right. Useful for dashboards or settings pages with many sections.
The `verticalColSize` prop controls the width of the tablist column in vertical mode. Supported values: `one-quarter`, `one-third`, `half`, `two-thirds`, `three-quarters`, `full`.
When `ds-tab` children contain anchor links instead of panel references, the component renders a `` landmark for page-section navigation. Pass a descriptive `label` to name the landmark for screen readers.
When tabs overflow the available width, scroll buttons appear automatically. The tablist scrolls smoothly to bring the active or clicked tab into view.
### Accessibility
## Guidelines
When using the navigation variant (anchor links inside ds-tab), set the label prop on ds-tabs with a descriptive name. This labels the <nav> landmark for screen reader users.
),
},
{
type: 'do',
title: 'Use short, unique tab labels',
content: (
Each tab label must be distinct and clearly describe the content of its associated panel. Screen reader users navigate tabs by their label, so duplicate or vague labels cause confusion.
),
},
{
type: 'do',
title: 'Mark the current navigation link with aria-current',
content: (
In the navigation variant, add aria-current="page" to the active anchor link so assistive technologies can identify the current location.
),
},
{
type: 'dont',
title: 'Don\'t nest interactive elements inside tab labels',
content: (
Avoid placing buttons, dropdowns, or other interactive controls inside ds-tab labels. The tab button itself is the interactive element; adding others creates confusing focus order and keyboard traps.
),
},
{
type: 'dont',
title: 'Don\'t use tabs to replace page-level navigation',
content: (
Tabs are for switching between views within a single page. For top-level site navigation use a <nav> with links, not a tab pattern, to match user expectations and ARIA landmark conventions.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The tabs component implements patterns that meet WCAG 2.2 Level AA standards:
- **1.3.1 Info and Relationships** — The tablist uses `role="tablist"`, each tab uses `role="tab"`, and each panel uses `role="tabpanel"` to communicate structure to assistive technologies.
- **2.1.1 Keyboard** — Tabs are navigable with Arrow keys within the tablist; Tab moves focus into the active panel. Carousel scroll buttons are keyboard-accessible.
- **2.4.3 Focus Order** — Focus moves logically from the active tab button into the associated panel content.
- **2.4.6 Headings and Labels** — The `label` prop exposes a visible or programmatic name for the navigation landmark in the navigation variant.
- **4.1.2 Name, Role, Value** — `aria-selected`, `aria-controls`, and `aria-labelledby` associations are managed automatically by the component.
---
# Overlays
## ds-drawer
Docs: https://helvetia-design.vercel.app/?path=/docs/components-overlays-drawer-drawer--drawer
Drawer displays a panel that slides up from the bottom of the screen.
Uses the native dialog element for accessible top-layer rendering, built-in focus management,
and Escape-key handling.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| backdrop-dismiss | boolean | true | If `true`, clicking the backdrop (outside the panel) dismisses the drawer. |
| closable | boolean | true | If `true`, the drawer can be dismissed via the Escape key and shows a close button. |
| container | "compact" \| "default" \| "fluid" | 'default' | Sets the inner content container width. Accepts `'default'`, `'fluid'`, or `'compact'`. Matches the `ds-container` sizing variants. |
| label | string | '' | Accessible label for the drawer dialog (sets aria-label on the dialog element). |
| open | boolean | false | If `true` the drawer is open. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsDidDismiss | DrawerDismissDetail | Emitted after the drawer is fully closed. |
| dsDidPresent | DrawerPresentDetail | Emitted after the drawer is fully open. |
| dsWillDismiss | DrawerDismissDetail | Emitted before the drawer closes. |
| dsWillPresent | DrawerPresentDetail | Emitted before the drawer opens. |
### Methods
| Signature | Description |
| --- | --- |
| dismiss() => Promise | Closes the drawer. |
| present() => Promise | Opens the drawer. |
### Slots
| Name | Description |
| --- | --- |
| default | The drawer content. |
### Parts
| Name | Description |
| --- | --- |
| close | The optional close button (visible when closable). |
| dialog | The native dialog element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --drawer-background | Background color of the drawer panel. |
| --drawer-radius | Border radius of the drawer top corners. |
| --drawer-max-height | Maximum height of the drawer panel. |
| --drawer-p | Padding inside the drawer panel. |
| --drawer-backdrop-background | Background color of the native backdrop. |
| --drawer-backdrop-opacity | Opacity of the native backdrop. |
| --drawer-backdrop-filter | Backdrop filter of the native backdrop. |
| --drawer-close-inset | Offset of the close button from the top and end edge of the container. |
| --drawer-width-default | Max width of the container for the `default` variant. |
| --drawer-width-fluid | Max width of the container for the `fluid` variant. |
| --drawer-width-compact | Max width of the container for the `compact` variant. |
### Usage
## When to Use
- Side panels for filters, navigation, or secondary forms that slide from the bottom
- Mobile-optimized overlays that preserve context when opened
- Collections of related actions or options grouped together
- Confirmation dialogs or multi-step workflows in a contained space
## When NOT to Use
- Critical alerts that require immediate action — use `ds-modal` instead
- Short notifications — use a toast or snackbar
- Simple inline content that fits on the page — avoid extra layers
- Actions that need permanent visibility — integrate into the main layout
### Variants
The basic drawer with default settings. Can be dismissed via Escape key, backdrop click, or the close button.
A drawer containing form controls and complex content. Useful for filtering, settings, or multi-step workflows.
Control the inner container width with the `container` prop: `'default'`, `'fluid'`, or `'compact'`. Matches `ds-container` sizing variants.
### Accessibility
## Guidelines
Set the `label` prop to describe the drawer purpose. This is announced to screen readers.,
},
{
type: 'do',
title: 'Ensure drawer is escapable',
content: Keep `closable` enabled unless the drawer is truly blocking (requires explicit action). Users should always have an Escape key exit.
,
},
{
type: 'do',
title: 'Support keyboard navigation',
content: Use focusable elements (buttons, inputs, links) as the first items in the drawer. Tab order must be logical.
,
},
{
type: 'do',
title: 'Manage focus on open/close',
content: When the drawer closes, focus returns to the trigger element. Ensure the trigger is in a predictable location.
,
},
{
type: 'dont',
title: 'Avoid trapping users',
content: Do not create drawers where users cannot escape. Disable closable and backdrop-dismiss only for critical confirmation steps.
,
},
{
type: 'dont',
title: 'Don\'t use for critical alerts',
content: Drawers slide from the bottom and may be missed. Use `ds-modal` for important notifications or confirmations.
,
},
]}
/>
## WCAG 2.2 AA Compliance
The drawer component implements patterns that meet WCAG 2.2 Level AA standards:
- **Dialog Semantics** — Uses the native `` element with `aria-label` for accessible role and naming.
- **Focus Management** — Automatically focuses the drawer content on open and returns focus to the trigger on close.
- **Keyboard Navigation** — Escape key closes the drawer (when `closable` is enabled). Tab order is trapped within the drawer during use.
- **Backdrop Dismiss** — When enabled, clicking outside the panel (on the backdrop) dismisses the drawer, providing a clear visual and tactile way to exit.
- **Contrast & Visibility** — The close button and backdrop have sufficient contrast to be easily visible and distinguished.
---
## ds-modal
Docs: https://helvetia-design.vercel.app/?path=/docs/components-overlays-modal-modal--modal
Modal displays content in a dialog overlay using the native dialog element.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| closable | boolean | true | If `true`, the modal can be dismissed via Escape key, close button, and backdrop click. |
| fullscreen | boolean | false | If `true`, the modal covers the full viewport. |
| label | string | '' | Accessible label for the modal dialog (sets aria-label on the dialog element). Required for component-overlay modals (`ModalOptions.component`), whose mounted component only fills the `body` slot — the `header` slot stays empty, so `aria-labelledby="modal-title"` alone resolves to no accessible name. |
| modal-width | number \| undefined | | Width of the modal in pixels. Overrides the `--modal-width` token (640px by default). |
| open | boolean | false | If `true` the modal is open. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsDidDismiss | ModalDismissDetail | Emitted after the modal is fully closed. |
| dsDidPresent | ModalPresentDetail | Emitted after the modal is fully open. |
| dsWillDismiss | ModalDismissDetail | Emitted before the modal closes. |
| dsWillPresent | ModalPresentDetail | Emitted before the modal opens. |
### Methods
| Signature | Description |
| --- | --- |
| dismiss(data?: unknown, role?: string) => Promise | Closes the modal, emitting `data`/`role` on `dsWillDismiss`/`dsDidDismiss`. Resolves once the close transition has finished. |
| present() => Promise | Opens the modal. |
### Slots
| Name | Description |
| --- | --- |
| actions | Action buttons rendered right-aligned at the bottom of the modal. |
| body | The modal body content. Used automatically by ds-modal-body. |
| header | The modal title content. Used automatically by ds-modal-header. |
### Parts
| Name | Description |
| --- | --- |
| actions | The div wrapping the actions slot. |
| body | The div wrapping the body slot. |
| close | The close button. |
| dialog | The native dialog element. |
| title | The h2 wrapping the header slot. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --modal-background | Background color of the modal dialog. |
| --modal-color | Text color of the modal title and body. |
| --modal-radius | Border radius of the modal dialog. |
| --modal-backdrop-opacity | Opacity of the backdrop overlay. |
| --modal-backdrop-background | Background color of the backdrop overlay. |
| --modal-backdrop-filter | Backdrop filter of the backdrop overlay. |
| --modal-heading-font-family | Font family of the modal title. |
| --modal-heading-font-weight | Font weight of the modal title. |
| --modal-heading-font-size | Font size of the modal title. |
| --modal-heading-line-height | Line height of the modal title. |
| --modal-heading-letter-spacing | Letter spacing of the modal title. |
| --modal-heading-text-decoration | Text decoration of the modal title. |
| --modal-heading-text-transform | Text transform of the modal title. |
| --modal-width | Width of the modal dialog from tablet up. Overridden by the `modal-width` property. |
| --modal-margin | Responsive inset between the modal dialog and the viewport edge. |
| --modal-p | Responsive inner padding of the modal dialog. |
| --modal-gap | Responsive vertical spacing between the modal's title, body, and actions. |
| --modal-title-padding-end | Extra end padding of the title, reserving room for the close button. |
| --modal-actions-gap | Gap between the action buttons. |
### Usage
**React**
## Imperative modal
Use `useModal()` when a modal must be presented outside of render — for example from an event handler or a promise
chain — without tracking `open` state yourself. `present()` mounts the given React content into the overlay;
`dismiss()` closes it and optionally forwards a result.
```tsx
import { DsButton, DsModalBody, DsModalHeader, useModal } from '@helvetia-design/react'
export function ImperativeModalExample() {
const [present, dismiss] = useModal()
const confirm = () =>
present(
<>
Confirm action
Do you want to continue?
dismiss('confirmed')}>Continue
>,
{ closable: true },
)
return Open modal
}
```
## Controlled modal
Use `Modal` as a controlled component. Update `open` through `onOpenChange` so React state stays synchronized when the
user closes the modal with Escape, the close button, or the backdrop.
>
Import `Modal` from `@helvetia-design/react`. The generated `DsModal` wrapper is deprecated.
```tsx
import { useState } from 'react'
import { DsButton, DsModalBody, DsModalHeader, Modal } from '@helvetia-design/react'
export function ModalExample() {
const [isOpen, setIsOpen] = useState(false)
return (
<>
setIsOpen(true)}>Open modal
Confirm action
Do you want to continue?
>
)
}
```
**HTML**
## Imperative modal
Use `dsModalController` from `@helvetia-design/core` to present a modal without adding markup to the page. `create()`
mounts a `ds-modal` into the document and opens it; append your header, body, and actions afterwards — the slots
pick them up automatically. `dismiss()` closes the currently open modal.
```html
Open modal
```
## Controlled modal
Render the modal in the document and toggle it with its `present()` and `dismiss()` methods, or by setting the
`open` property/attribute directly.
```html
Open modal
Confirm action
Do you want to continue?
Cancel
```
## Styling
Customize the modal per instance with its CSS custom properties.
```css
#modal-basic {
--modal-width: 480px;
--modal-radius: 1rem;
--modal-background: #f5f5f5;
}
```
**Angular**
## Imperative modal
WIP
## Controlled modal
WIP
## When to Use
- To interrupt the user with a decision or action that must be completed before continuing.
- To confirm a destructive or irreversible action (e.g. delete, submit).
- To display a focused form or secondary workflow without navigating away from the current page.
- To surface critical information that requires acknowledgement.
## When NOT to Use
- For non-critical or informational messages — use a notification or snackbar instead.
- When the content is too large to fit comfortably in a dialog — consider a dedicated page or side panel.
- For complex multi-step workflows — break them into separate pages instead.
- As a substitute for inline validation or contextual help.
### Variants
When `closable="false"`, the Escape key, close button, and backdrop click are all disabled. Use this only when the user must complete or explicitly acknowledge the action before proceeding.
Use `modal-width` to reduce the dialog width for compact confirmations or short messages.
Increase `modal-width` to accommodate wider content such as tables or multi-column forms.
When body content exceeds the available viewport height, the body area scrolls independently. The title and action buttons remain fixed and always visible.
Set `fullscreen` to make the modal cover the entire viewport. Useful for complex multi-step wizards, immersive forms, or when you need maximum screen real estate.
Combine `fullscreen` with `closable="false"` to create a modal that demands completion. Users cannot dismiss via Escape or backdrop click—they must interact with the action buttons.
### Accessibility
## Guidelines
Always use ds-modal-header or slot="header" with a descriptive title. The modal is labelled by this heading via aria-labelledby, which screen readers announce when the dialog opens.,
},
{
type: 'do',
title: 'Include a visible close path for closable modals',
content: When closable is true (the default), users can dismiss the modal via the close button, the Escape key, or clicking the backdrop. Ensure at least one explicit action button is also present so keyboard and screen reader users have a clear exit.
,
},
{
type: 'do',
title: 'Limit body scroll to the modal body area',
content: Place all scrollable content inside ds-modal-body or slot="body". The modal title and action buttons remain visible at all times, ensuring keyboard users can always reach the actions without scrolling.
,
},
{
type: 'dont',
title: "Don't use closable=\"false\" without a mandatory action",
content: Non-closable modals trap focus intentionally. Only use this pattern when the user genuinely must complete the action — for example, a required session expiry warning. Always provide at least one action button so users are not stuck.
,
},
{
type: 'dont',
title: "Don't nest interactive content that opens another dialog",
content: Avoid triggering a second modal from within an open modal. Stacked dialogs create confusing focus management and disorienting experiences for screen reader users.
,
},
]}
/>
## WCAG 2.2 AA Compliance
The `ds-modal` component implements patterns that meet WCAG 2.2 Level AA standards:
- **1.3.1 Info and Relationships** — The native `` element provides semantic role `dialog`, and `aria-labelledby` links the dialog to its heading.
- **2.1.1 Keyboard** — The modal is fully operable by keyboard: Tab cycles through focusable elements, Escape closes the dialog when `closable` is true.
- **2.1.2 No Keyboard Trap** — Focus is contained within the open modal (native browser focus trap via `showModal()`), and the user can always leave via Escape or an action button.
- **2.4.3 Focus Order** — Focus moves into the modal when it opens and returns to the triggering element when it closes.
- **4.1.2 Name, Role, Value** — The dialog role and accessible name are provided automatically through the native `` element and `aria-labelledby`.
---
## ds-notification
Docs: https://helvetia-design.vercel.app/?path=/docs/components-overlays-notification-notification--notification
Notification presents inline feedback messages for success, warning, error, or informational states with optional close action.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| alert | boolean | false | If `true` the notification will be displayed as an alert, otherwise as a status message. |
| closable | boolean | false | If `true` the notification can be closed by the user. |
| color | "danger" \| "default" \| "info" \| "outline-default" \| "outline-green" \| "outline-purple" \| "outline-red" \| "outline-yellow" \| "success" \| "warning" \| undefined | | Defines the color of the element Color type primary is deprecated, please use info instead. |
| heading | string | '' | Defines the heading of the notification. |
| no-icon | boolean | false | If `true` there will be no icon provided |
| size | "sm" \| undefined | | Defines the size of the notification, sm or md. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsCloseClick | NotificationCloseClickDetail | Emitted when the close button got clicked. |
| dsDidLoad | void | Emitted when the component has loaded. |
### Methods
| Signature | Description |
| --- | --- |
| close() => Promise | Closes this notification |
### Slots
| Name | Description |
| --- | --- |
| default | The notification message content. |
### Parts
| Name | Description |
| --- | --- |
| close | The close button. |
| heading | The notification heading. |
| section | The notification container element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --notification-radius | Border radius of the notification. |
| --notification-border | Composite border (width, style, color) of the notification. |
| --notification-color-background | Background color of the notification. |
| --notification-color-text | Text color of the notification. |
| --notification-color-heading | Text color of the notification heading and icon. |
| --notification-heading-font-family | Font family of the notification heading. |
| --notification-heading-font-weight | Font weight of the notification heading. |
| --notification-heading-font-size | Font size of the notification heading. |
| --notification-heading-line-height | Line height of the notification heading. |
| --notification-heading-letter-spacing | Letter spacing of the notification heading. |
| --notification-heading-text-decoration | Text decoration of the notification heading. |
| --notification-heading-text-transform | Text transform of the notification heading. |
| --notification-content-font-family | Font family of the notification content. |
| --notification-content-font-weight | Font weight of the notification content. |
| --notification-content-font-size | Font size of the notification content. |
| --notification-content-line-height | Line height of the notification content. |
| --notification-content-letter-spacing | Letter spacing of the notification content. |
| --notification-content-text-decoration | Text decoration of the notification content. |
| --notification-content-text-transform | Text transform of the notification content. |
| --notification-icon | Mask image of the icon. |
| --notification-icon-size | Width of the icon column. |
| --notification-p | Padding inside the notification. |
| --notification-gap | Gap between heading and content. |
### Usage
## When to Use
- Inform users about form submission results (success, error, warning)
- Alert users to system status changes or service updates
- Display validation errors or input issues
- Show contextual messages related to user actions
- Provide inline confirmations or acknowledgments
## When NOT to Use
- For minor or trivial information — use simple text or helper messages instead
- As a replacement for form validation error fields — combine with field-level errors
- For non-critical information that can be placed in page content — don't interrupt users unnecessarily
- For errors that require user action but offer no guidance — include clear next steps
## Do's and Don'ts
### Notification Severity and Color
Match notification color to severity level. Users should immediately understand the importance and urgency.
Your changes have been saved successfully.
Your session is about to expire.
An error occurred. Please try again.
),
description: 'Colors match severity expectations',
},
{
type: 'incorrect',
title: 'Incorrect: Mismatched severity colors',
contentIsLeftAligned: true,
content: (
Your changes have been saved successfully.
An error occurred. Please try again.
),
description: 'Colors don\'t match message urgency',
},
]}
/>
### Clear, Actionable Messages
Notification messages should be clear and actionable. Tell users what happened and what they should do next.
Your password will expire in 24 hours. Update your password now .
\n Your password will expire in 24 hours.
Update now .\n'} />
>
),
description: 'Users know what to do next',
},
{
type: 'incorrect',
title: 'Incorrect: Vague message',
contentIsLeftAligned: true,
content: (
Something might happen later.
),
description: 'Unclear what action user should take',
},
]}
/>
### Variants
With `alert` variant, the notification is styled to indicate an important message that requires user attention.
It typically uses a more prominent color scheme and may include an icon to signify urgency or importance.
With `outline` variant, the notification is styled with a border and a less prominent background,
making it suitable for less urgent messages or secondary information.
### Accessibility
## Guidelines
Implement aria-live="polite" or aria-live="assertive" to announce notifications to screen readers as they appear. Use "polite" for non-urgent messages and "assertive" for time-sensitive alerts.
),
},
{
type: 'do',
title: 'Color + Icon + Text',
content: (
Combine color, icons, and text to convey notification severity. Users with color blindness should understand the message importance from icon and text alone.
),
},
{
type: 'do',
title: 'Sufficient Color Contrast',
content: (
Ensure notification text has sufficient contrast against the background (4.5:1 for normal text). Colors alone should not convey all information.
),
},
{
type: 'do',
title: 'Clear, Plain Language',
content: (
Write notification messages in simple, clear language. Avoid jargon and technical terms that users might not understand.
),
},
{
type: 'dont',
title: 'Critical Information Hidden',
content: (
Never include critical information only in dismissible notifications that auto-hide. Users may miss the message, and screen readers might not announce it in time.
),
},
{
type: 'dont',
title: 'Relying on Color Alone',
content: (
Do not rely solely on color to convey the message severity or type. Users with color blindness cannot perceive this information.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The notification component supports patterns that meet WCAG 2.2 Level AA standards:
- **Color Contrast (4.11.1)** — Text meets minimum contrast ratios
- **Color Not Only Means (1.4.1)** — Color is not the only means of conveying information
- **Status Messages (4.1.3)** — Live region announcements for dynamic content
- **Focus Visible (2.4.7)** — Close buttons have visible focus indicators
---
## ds-popup
Docs: https://helvetia-design.vercel.app/?path=/docs/components-overlays-popup-popup--popup
Popup displays anchored overlay content positioned relative to a trigger element.
Serves as a primitive for dropdowns, hints, menus, datepickers, and autocompletes.
Trigger wiring:
Programmatic — set the `trigger` property to an HTMLElement; call `present()` / `dismiss()`.
Declarative — add `data-popup=""` to any trigger element and set matching `id` on popup.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| arrow | boolean | false | If `true`, renders a small arrow indicator pointing from the panel toward the trigger. |
| backdrop | boolean | false | If `true`, a full-screen backdrop overlay is rendered behind the popup panel. |
| backdrop-dismiss | boolean | false | If `true`, clicking outside the popup panel dismisses it. |
| closable | boolean | false | If `true`, the popup can be dismissed via the Escape key and shows a close button. |
| group | string \| undefined | undefined | Group name for mutual-exclusion. Only one popup within the same group is open at a time. |
| label | string | '' | Accessible label for the popup panel (sets aria-label on the panel element). |
| offset | number | 8 | Offset in pixels between the trigger element and the popup panel. |
| open | boolean | false | If `true` the popup is open. |
| placement | "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start" | 'bottom' | Preferred placement of the popup relative to the trigger. |
| role | "dialog" \| "grid" \| "listbox" \| "menu" \| "tree" | 'dialog' | ARIA role applied to the panel. Controls focus-trap behaviour and the aria-haspopup value set on the trigger. Use "dialog" for rich content, "listbox" or "menu" for interactive option lists. |
| trap-focus | boolean \| undefined | undefined | Override the automatic focus-trap behaviour. When undefined, trapping is enabled when `backdrop` is `true` and disabled otherwise. |
| trigger | HTMLElement \| undefined | undefined | The trigger element. Setting this wires up aria-haspopup and aria-expanded automatically. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsDidDismiss | PopupDismissDetail | Emitted after the popup is fully closed. |
| dsDidPresent | PopupPresentDetail | Emitted after the popup is fully open. |
| dsWillDismiss | PopupDismissDetail | Emitted before the popup closes. |
| dsWillPresent | PopupPresentDetail | Emitted before the popup opens. |
### Methods
| Signature | Description |
| --- | --- |
| dismiss() => Promise | Closes the popup. |
| present() => Promise | Opens the popup. |
| toggle() => Promise | Toggles the popup open or closed. |
### Slots
| Name | Description |
| --- | --- |
| default | The popup content. |
### Parts
| Name | Description |
| --- | --- |
| arrow | |
| backdrop | The optional full-screen backdrop overlay. |
| close | The optional close button (visible when closable). |
| panel | The floating panel container. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --popup-background | Background color of the popup panel. |
| --popup-radius | Border radius of the popup panel. |
| --popup-shadow | Box shadow of the popup panel. |
| --popup-p | Padding inside the popup panel. |
| --popup-min-width | Minimum width of the popup panel. |
| --popup-max-width | Maximum width of the popup panel. |
| --popup-z-index | Z-index stacking level of the popup layer. |
| --popup-backdrop-background | Background color of the optional full-screen backdrop. |
| --popup-backdrop-opacity | Opacity of the optional full-screen backdrop. |
| --popup-arrow-size | Size (width and height) of the arrow indicator. |
| --popup-close-inset | Offset of the close button from the top and end edge of the panel. |
| --popup-closable-padding-end | End padding of the panel when the close button is shown. |
### Usage
## When to Use
- Dropdowns and select menus anchored to a trigger element
- Context menus that appear near the cursor or button
- Autocomplete suggestions or search results
- Floating panels for settings, filters, or quick actions
- Tooltips with rich content or interactive elements
- Popovers that provide additional information or options
## When NOT to Use
- Modal dialogs that block interaction with the page — use `ds-modal` instead
- Drawers that slide from edges — use `ds-drawer` instead
- Simple tooltips with only text — use native title attribute or `ds-tooltip` if available
- Notifications or alerts — use toast or snackbar components
- Content that should always be visible — integrate into the main layout
## Do's and Don'ts
### Trigger Wiring
Open
),
description: 'Use declarative data-popup attribute or set trigger property programmatically. Users should understand how to interact with the component.',
},
{
type: 'incorrect',
title: 'Incorrect: Hidden trigger',
content: (
This popup has no way to be opened by users.
),
description: 'Never render a popup without a clear trigger mechanism. Users won\'t know it exists or how to open it.',
},
]}
/>
### Variants
The basic popup with a declarative trigger using the `data-popup` attribute. The popup opens when the trigger is clicked and can be closed with the close button or by pressing Escape.
Control where the popup appears relative to the trigger using the `placement` prop. This variant opens above the trigger.
The default placement opens to the right of the trigger. This works well when there's sufficient horizontal space available.
The popup can open to the left of the trigger, useful in right-to-left layouts or when right-side space is constrained.
When `backdropDismiss` is enabled, users can close the popup by clicking outside the panel. Useful for optional overlays that don't require the user to explicitly dismiss.
Render a full-screen overlay behind the popup with the `backdrop` prop. Combines visual separation and backdrop dismiss for clearer modal-like behavior without blocking page interaction.
Use `role="listbox"` when the popup contains selectable options. This provides proper ARIA semantics for screen readers and enables keyboard navigation within lists.
The `group` prop enables mutual exclusion — only one popup in the same group can be open at a time. Opening one automatically closes others in the group.
Control popups programmatically by setting the `trigger` property and calling `present()` / `dismiss()` methods. This allows fine-grained control over open/close behavior.
When the popup has `role="dialog"` (default) and contains focusable elements, focus is trapped within the popup. Tab navigates between elements and wraps at the boundaries.
### Accessibility
## Guidelines
Set `role` to match content: "dialog" for rich content, "listbox" for option lists, "menu" for navigation menus. Screen readers announce the role to provide context.,
},
{
type: 'do',
title: 'Provide a label',
content: Set the `label` prop to describe the popup. This is especially important for popups without visible titles.
,
},
{
type: 'do',
title: 'Handle keyboard navigation',
content: Users should be able to open popups with Enter/Space (if the trigger is a button) and close with Escape. Focus trap traps Tab within the popup.
,
},
{
type: 'do',
title: 'Maintain focus visibility',
content: Ensure focusable elements in the popup have clear focus indicators. Use CSS focus-visible styling for keyboard navigation.
,
},
{
type: 'dont',
title: 'Don\'t trap focus unexpectedly',
content: Focus trap only applies to `role="dialog"`. For other roles (listbox, menu), focus may move outside the popup. Clarify this behavior in your UI.
,
},
{
type: 'dont',
title: 'Don\'t hide critical information',
content: Popups are overlays. Never hide essential instructions or validation errors inside a popup that covers the main content.
,
},
]}
/>
## WCAG 2.2 AA Compliance
The popup component implements patterns that meet WCAG 2.2 Level AA standards:
- **Dialog Semantics** — The panel uses `role="dialog"` by default, with proper `aria-label` for accessible naming.
- **Focus Management** — When opening, focus moves into the popup. When closing, focus returns to the trigger (if available). Focus trap (Tab navigation) works within the panel.
- **Keyboard Navigation** — Escape key closes the popup. Tab navigates focusable elements. For role="listbox", arrow keys can be used with proper ARIA attributes.
- **Positioned Correctly** — Floating positioning uses `computePosition()` to ensure the popup doesn't get cut off by viewport boundaries.
- **Contrast** — The close button (part="close") and content have sufficient contrast for visibility.
- **Touch-friendly** — Backdrop dismiss provides a clear touch target to close the popup when backdrop-dismiss is enabled.
---
## ds-sheet
Docs: https://helvetia-design.vercel.app/?path=/docs/components-overlays-sheet-sheet--sheet
Sheet displays a fixed panel anchored to the bottom of the viewport.
Use it to surface persistent actions or contextual information without
blocking the main content.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| container-size | "compact" \| "fluid" \| undefined | | Defines the content width of the sheet. Leave unset for the default width, or use `'fluid'` for full width, or `'compact'` for a narrow layout. |
### Slots
| Name | Description |
| --- | --- |
| default | The sheet content. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --sheet-background | Background color of the sheet panel (defaults to white). |
| --sheet-radius | Border radius of the sheet panel corners (defaults to large radius). |
| --sheet-shadow | Box shadow of the sheet panel (defaults to base shadow). |
| --sheet-position-bottom | Distance from the bottom of the viewport (defaults to the sheet token value). |
| --sheet-z-index | Stacking level of the sheet (defaults to the sticky z-index). |
| --sheet-margin-inline | Inline margin between the sheet panel and the viewport edges. |
| --sheet-padding | Inner padding of the sheet panel. |
| --sheet-width-default | Max width of the sheet panel in its default size. |
| --sheet-width-fluid | Max width of the sheet panel when `container-size="fluid"`. |
| --sheet-width-compact | Max width of the sheet panel when `container-size="compact"`. |
### Usage
## When to Use
- To surface persistent actions that should always be accessible, such as a primary call-to-action at the bottom of a form or page.
- To present contextual information or a summary that complements the main content without covering it entirely.
- When the action or information relates directly to the current page context and needs to stay visible as the user scrolls.
## When NOT to Use
- Do not use a sheet for critical alerts or errors — use a notification or modal instead.
- Do not use a sheet when the user needs to focus entirely on a task — use a modal or a dedicated page.
- Do not stack multiple sheets — only one sheet should be visible at a time.
### Variants
A fixed panel anchored to the bottom of the viewport, used to surface persistent actions or contextual information alongside the main content.
### Accessibility
## Guidelines
Buttons and links placed in the sheet must be reachable via Tab and activatable with{' '}
Enter or Space. Users who navigate by keyboard must be able to reach sheet actions
without using a mouse.
),
},
{
type: 'do',
title: 'Provide meaningful labels for all actions in the sheet',
content: (
Each button or interactive element inside the sheet must have a descriptive text label or{' '}
aria-label. Avoid icon-only buttons without accessible labels, as screen reader users will not
understand the action.
),
},
{
type: 'do',
title: 'Maintain sufficient color contrast for sheet content',
content: (
All text and interactive elements inside the sheet must meet WCAG 2.2 AA contrast ratios (4.5:1 for normal
text, 3:1 for large text and UI components). This applies especially when customizing{' '}
--sheet-background.
),
},
{
type: 'dont',
title: "Don't trap keyboard focus inside the sheet",
content: (
The sheet is a persistent, non-modal panel. Do not implement a focus trap — users must be able to Tab freely
between the sheet and the rest of the page content. Focus traps are appropriate only for modal dialogs.
),
},
{
type: 'dont',
title: "Don't rely on the sheet's position alone to convey meaning",
content: (
Screen reader users are not aware that the sheet is anchored to the bottom of the viewport. Use clear,
descriptive text within the sheet rather than relying on its visual placement to communicate context or
urgency.
),
},
]}
/>
## References
- [MDN: ARIA landmark roles](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/landmark_role) — Understanding when to apply landmark roles to persistent UI regions
- [MDN: Using the button role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role) — Guidance for accessible button labels and keyboard interaction
- [WCAG 2.2 — Success Criterion 1.4.3: Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum) — Contrast requirements for text and UI components
- [WCAG 2.2 — Success Criterion 2.1.1: Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard) — All functionality must be operable via keyboard
---
## ds-snackbar
Docs: https://helvetia-design.vercel.app/?path=/docs/components-overlays-snackbar-snackbar--snackbar
Snackbar displays brief feedback messages at the bottom of the screen with optional action buttons and dismissal control.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| action | string | '' | Defines the icon of the notification, if not provided it will be derived from the color property |
| action-href | string | '' | Specifies the URL of the page the link goes to |
| action-icon | string | '' | Defines the icon of the action button. |
| action-target | "_blank" \| "_parent" \| "_self" \| "_top" | '_blank' | Specifies where to open the linked document. |
| closable | boolean | false | If `true` the notification can be closed by the user. |
| color | "danger" \| "info" \| "primary" \| "success" \| "warning" \| undefined | | Defines the color of the element Color type primary is deprecated, please use info instead. |
| heading | string | '' | Defines the heading of the notification. |
| icon | string | '' | Defines the icon of the notification. |
| message | string | '' | Defines the message of the notification as html content |
| svg | string | '' | Defines the svg content of the icon |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsActionClick | SnackbarActionClickDetail | Emitted when the action button got clicked. |
| dsCloseClick | SnackbarCloseClickDetail | Emitted when the close button got clicked. |
### Methods
| Signature | Description |
| --- | --- |
| close() => Promise | Closes this notification |
### Slots
| Name | Description |
| --- | --- |
| default | The snackbar message content. |
| action | The action button (if used). |
### Parts
| Name | Description |
| --- | --- |
| action | The action button group. |
| button | The action button element. |
| close | The close button element. |
| content | The content wrapper containing the heading and message. |
| heading | The snackbar heading. |
| icon | The icon element. |
| message | The snackbar message element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --snackbar-shadow | Box shadow of the snackbar. |
| --snackbar-radius | Border radius of the snackbar. |
| --snackbar-bg | Background color of the snackbar. |
| --snackbar-border | Border of the snackbar. |
| --snackbar-color | Text color inside the snackbar. |
| --snackbar-icon-color | Color of the snackbar icon. |
| --snackbar-heading-font-family | Font family of the snackbar heading. |
| --snackbar-heading-font-size | Font size of the snackbar heading. |
| --snackbar-heading-font-weight | Font weight of the snackbar heading. |
| --snackbar-heading-line-height | Line height of the snackbar heading. |
| --snackbar-heading-letter-spacing | Letter spacing of the snackbar heading. |
| --snackbar-heading-text-decoration | Text decoration of the snackbar heading. |
| --snackbar-heading-text-transform | Text transform of the snackbar heading. |
| --snackbar-heading-color | Text color of the snackbar heading. |
| --snackbar-content-font-family | Font family of the snackbar message. |
| --snackbar-content-font-size | Font size of the snackbar message. |
| --snackbar-content-font-weight | Font weight of the snackbar message. |
| --snackbar-content-line-height | Line height of the snackbar message. |
| --snackbar-content-letter-spacing | Letter spacing of the snackbar message. |
| --snackbar-content-text-decoration | Text decoration of the snackbar message. |
| --snackbar-content-text-transform | Text transform of the snackbar message. |
| --snackbar-content-color | Text color of the snackbar message. |
| --snackbar-p | Padding inside the snackbar. |
| --snackbar-gap | Gap between content and close button. |
### Usage
**React**
## Present and dismiss a snackbar
`useSnackbar()` returns `present` and `dismiss` functions. Use a snackbar when the message should remain available until
it is dismissed.
>
Import `useSnackbar` from `@helvetia-design/react`. The generated `DsSnackbar` wrapper is deprecated.
```tsx
import { DsButton, useSnackbar } from '@helvetia-design/react'
export function SnackbarExample() {
const [presentSnackbar, dismissSnackbar] = useSnackbar()
const showSnackbar = () =>
presentSnackbar({
heading: 'Offline',
message: 'You are currently offline.',
closable: true,
duration: 'infinite',
closeHandler: () => undefined,
actionHandler: () => undefined,
})
return (
<>
Show snackbar
dismissSnackbar()}>Dismiss snackbar
>
)
}
```
**HTML**
## Present and dismiss a snackbar
Use `dsSnackbarController` from `@helvetia-design/core` (also available as `window.DesignSystem.snackbarController`) to
create and remove snackbars. `create()` returns the snackbar's ID, which `remove()` needs to dismiss it early.
```html
Show snackbar
Dismiss snackbar
```
**Angular**
## Present and dismiss a snackbar
WIP
## When to Use
- Display persistent notifications that remain visible until the user dismisses them
- Show feedback for user actions that have completed successfully or with warnings
- Provide important information that users should be able to review at their own pace
- Display multiple notifications stacked on top of each other
## When NOT to Use
- For time-sensitive notifications that disappear automatically — use **Toast** instead
- For critical errors that require immediate user attention — use **Alert** in a modal dialog
- For inline validation feedback on form fields — use field-level error messages
### Variants
Snackbars with brand icons for enhanced visual communication.
Different color variants to represent different notification types and severity levels.
### Accessibility
## Guidelines
When a snackbar contains only an icon or minimal text, provide an aria-label to describe its purpose.,
},
{
type: 'do',
title: 'Provide clear, concise messaging',
content: Keep snackbar text brief and actionable so screen reader users can quickly understand the notification.
,
},
{
type: 'do',
title: 'Make close buttons keyboard accessible',
content: Ensure the close button can be reached via Tab navigation and activated with Enter or Space.
,
},
{
type: 'dont',
title: 'Avoid auto-dismissing important notifications',
content: If a snackbar contains critical information, do not set an auto-dismiss timeout; let users control when they close it.
,
},
{
type: 'dont',
title: 'Avoid stacking too many snackbars',
content: Multiple overlapping snackbars can confuse screen reader users and make the page difficult to navigate.
,
},
]}
/>
## References
- [`role="status"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/status_role) — MDN
- [`aria-live`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) — MDN
- [`aria-atomic`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) — MDN
---
## ds-toast
Docs: https://helvetia-design.vercel.app/?path=/docs/components-overlays-toast-toast--toast
Toast displays temporary notification messages that appear at the top of the page and auto-dismiss with optional action buttons and close control.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| action | string | '' | Defines the icon of the notification, if not provided it will be derived from the color property |
| action-href | string | '' | Specifies the URL of the page the link goes to |
| action-icon | string | '' | Defines the icon of the action button. |
| action-target | "_blank" \| "_parent" \| "_self" \| "_top" | '_blank' | Specifies where to open the linked document. |
| closable | boolean | false | If `true` the notification can be closed by the user. |
| color | "danger" \| "info" \| "primary" \| "success" \| "warning" \| undefined | | Defines the color of the element Color type primary is deprecated, please use info instead. |
| heading | string | | Defines the heading of the notification. |
| icon | string | '' | Defines the icon of the notification. |
| message | string | | Defines the message of the notification as html content |
| svg | string | '' | Defines the svg content of the icon |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsActionClick | ToastActionClickDetail | Emitted when the action button got clicked. |
| dsCloseClick | ToastCloseClickDetail | Emitted when the close button got clicked. |
### Methods
| Signature | Description |
| --- | --- |
| close() => Promise | Closes this notification |
### Slots
| Name | Description |
| --- | --- |
| default | The toast message content. |
| action | The action button (if used). |
### Parts
| Name | Description |
| --- | --- |
| button | The action button element. |
| close | The close button element. |
| content | The content wrapper containing the heading and message. |
| heading | The toast heading. |
| icon | The icon element. |
| message | The toast message element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --toast-shadow | Box shadow of the toast. |
| --toast-radius | Border radius of the toast. |
| --toast-bg | Background color of the toast. |
| --toast-border | Border of the toast. |
| --toast-color | Text color inside the toast. |
| --toast-icon-color | Color of the toast icon. |
| --toast-heading-font-family | Font family of the toast heading. |
| --toast-heading-font-size | Font size of the toast heading. |
| --toast-heading-font-weight | Font weight of the toast heading. |
| --toast-heading-line-height | Line height of the toast heading. |
| --toast-heading-letter-spacing | Letter spacing of the toast heading. |
| --toast-heading-text-decoration | Text decoration of the toast heading. |
| --toast-heading-text-transform | Text transform of the toast heading. |
| --toast-heading-color | Text color of the toast heading. |
| --toast-content-font-family | Font family of the toast message. |
| --toast-content-font-size | Font size of the toast message. |
| --toast-content-font-weight | Font weight of the toast message. |
| --toast-content-line-height | Line height of the toast message. |
| --toast-content-letter-spacing | Letter spacing of the toast message. |
| --toast-content-text-decoration | Text decoration of the toast message. |
| --toast-content-text-transform | Text transform of the toast message. |
| --toast-content-color | Text color of the toast message. |
| --toast-progress-duration | Duration of the progress bar animation. |
| --toast-progress-bar-bg | Background color of the progress bar. |
| --toast-progress-bg | Background color of the progress track. |
| --toast-progress-height | Thickness of the progress track and bar. |
| --toast-p | Padding inside the toast. |
| --toast-gap | Gap between content and close button. |
### Usage
**React**
## Present and dismiss a toast
`useToast()` returns `present` and `dismiss` functions. Pass notification content as data; toast content is not JSX.
>
Import `useToast` from `@helvetia-design/react`. The generated `DsToast` wrapper is deprecated.
```tsx
import { DsButton, useToast } from '@helvetia-design/react'
export function ToastExample() {
const [presentToast, dismissToast] = useToast()
const showToast = () =>
presentToast({
heading: 'Saved',
message: 'Your changes have been saved.',
closable: true,
duration: 5000,
closeHandler: () => undefined,
actionHandler: () => undefined,
})
return (
<>
Show toast
dismissToast()}>Dismiss toast
>
)
}
```
**HTML**
## Present and dismiss a toast
Use `dsToastController` from `@helvetia-design/core` (also available as `window.DesignSystem.toastController`) to create
and remove toasts. `create()` returns the toast's ID, which `remove()` needs to dismiss it early.
```html
Show toast
Dismiss toast
```
**Angular**
## Present and dismiss a toast
WIP
## When to Use
- Display brief, temporary notifications that auto-dismiss after a short duration
- Show confirmation messages for completed actions (e.g., "File saved successfully")
- Provide non-blocking feedback that doesn't require user action
- Inform users of background processes or updates that don't demand immediate attention
## When NOT to Use
- For notifications that need to remain visible for extended periods — use **Snackbar** instead
- For critical errors or warnings that require user interaction — use **Alert** in a modal dialog
- For large amounts of content or complex information — use a dedicated notification panel
- For form validation errors — use inline field-level feedback
## Do's and Don'ts
### Timely and Non-intrusive
Display toasts for 4-6 seconds, allowing users to read the message and then dismiss automatically.
),
description: 'Brief notifications respect user attention and screen space.',
},
{
type: 'incorrect',
title: 'Incorrect: Too Long',
content: (
Avoid displaying toasts that stay visible indefinitely or for more than 10 seconds.
),
description: 'Long-lived toasts feel intrusive and clutter the interface.',
},
]}
/>
### Single-Line Messages
Success! Your profile has been updated.
),
description: 'Short, scannable messages work best for transient notifications.',
},
{
type: 'incorrect',
title: 'Incorrect: Multi-line Content',
content: (
Operation completed. Your profile has been successfully updated with all the new information. Please check your email to verify your changes...
),
description: 'Long messages may not be read before the toast auto-dismisses.',
},
]}
/>
### Variants
Display toasts with different configurations: closable option, with action buttons, and various content arrangements.
Different color variants to convey different notification types and urgency levels.
### Accessibility
## Guidelines
Ensure screen readers announce the toast notification. Use "assertive" for urgent alerts and "polite" for informational toasts.,
},
{
type: 'do',
title: 'Write clear, concise messages',
content: Keep toast text brief and meaningful so users can quickly understand the notification before it auto-dismisses.
,
},
{
type: 'do',
title: 'Provide action buttons when necessary',
content: If a toast requires user action, include a button that allows users to act before the notification disappears.
,
},
{
type: 'dont',
title: 'Avoid auto-dismissing critical information',
content: For error messages or important warnings, consider making the toast persistent or providing a long enough timeout for users to read and understand.
,
},
{
type: 'dont',
title: 'Avoid displaying multiple toasts simultaneously',
content: Multiple overlapping toasts can confuse screen reader users and make the interface chaotic.
,
},
]}
/>
## References
- [`role="alert"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) — MDN
- [`aria-live`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-live) — MDN
- [`aria-atomic`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-atomic) — MDN
---
## ds-tooltip
Docs: https://helvetia-design.vercel.app/?path=/docs/components-overlays-tooltip-tooltip--tooltip
Tooltip displays contextual information when users hover over, focus on, or tap a trigger element.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| content-width | number \| undefined | undefined | Defines the maximum width of the tooltip content in pixels. |
| offset | number \| undefined | undefined | Offset in pixels from the trigger element to the tooltip. Defaults to the `--ds-tooltip-offset` token when not set. |
| open | boolean | false | When true, the tooltip is shown immediately on load without user interaction. |
| placement | "bottom" \| "left" \| "right" \| "top" | 'bottom' | Preferred placement of the tooltip relative to the trigger. |
| reference | string | '' | Id of the reference element. Defaults to the trigger element. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsDidAnimate | TooltipDidAnimateDetail | Emitted after the animation has finished. |
| dsWillAnimate | TooltipWillAnimateDetail | Emitted before the animation starts. |
### Methods
| Signature | Description |
| --- | --- |
| dismiss() => Promise | Hides the tooltip and cleans up the position updater. |
| present() => Promise | Shows the tooltip and positions it relative to the trigger element. |
| update() => Promise | Recomputes the tooltip position using floating-ui. |
### Slots
| Name | Description |
| --- | --- |
| default | The tooltip content text. |
### Parts
| Name | Description |
| --- | --- |
| container | The floating tooltip container element. |
| content | The inner content wrapper element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --tooltip-color-background | Background color of the tooltip container. |
| --tooltip-color-text | Text color of the tooltip content. |
| --tooltip-max-width | Maximum width of the tooltip container. |
| --tooltip-radius | Border radius of the tooltip container. |
| --tooltip-shadow | Box shadow of the tooltip container. |
| --tooltip-px | Horizontal padding of the tooltip content. |
| --tooltip-py | Vertical padding of the tooltip content. |
| --tooltip-offset | Distance between the trigger element and the tooltip container. |
| --tooltip-text-font-family | Font family of the tooltip text. |
| --tooltip-text-font-weight | Font weight of the tooltip text. |
| --tooltip-text-font-size | Font size of the tooltip text. |
| --tooltip-text-line-height | Line height of the tooltip text. |
| --tooltip-text-letter-spacing | Letter spacing of the tooltip text. |
| --tooltip-text-text-decoration | Text decoration of the tooltip text. |
| --tooltip-text-text-transform | Text transform of the tooltip text. |
| --tooltip-z-index | Z-index of the tooltip layer. |
### Usage
## When to Use
- Provide brief supplementary information about an interactive element, such as a button or icon
- Explain the purpose of an icon-only control where the action may not be self-evident
- Surface keyboard shortcuts or additional hints for experienced users
- Clarify abbreviations or technical terms inline without cluttering the layout
## When NOT to Use
- For critical information that users must read — use inline text or a notification instead
- To present long-form content, links, or interactive elements — use a popover instead
- As the sole means of conveying required instructions — content must also be available without hover/focus
- On touch-only devices where hover is unavailable — use always-visible helper text instead
## Do's and Don'ts
### Trigger Element
Always attach a tooltip to a focusable trigger so keyboard and screen reader users can access it.
Save
Saves your current progress
),
description: 'A button is keyboard-focusable, so the tooltip is reachable without a mouse.',
},
{
type: 'incorrect',
title: 'Incorrect: Non-focusable trigger',
content: (
Save
Saves your current progress
),
description: 'A plain cannot receive keyboard focus, so the tooltip is inaccessible.',
},
]}
/>
### Tooltip Content Length
Keep tooltip text short. One concise sentence is ideal.
Delete
Permanently removes this item
),
description: 'Concise and scannable at a glance.',
},
{
type: 'incorrect',
title: 'Incorrect: Overly long explanation',
content: (
Delete
Clicking this button will permanently remove this item from the system. This action cannot be undone. Please make sure you want to proceed before clicking.
),
description: 'Too verbose — consider an inline description or confirmation dialog instead.',
},
]}
/>
### Variants
Places the tooltip above the trigger element. Use when there is more visual space above the trigger than below.
Places the tooltip to the right of the trigger element. Useful in narrow vertical layouts or sidebars.
Places the tooltip below the trigger element. This is the default placement.
Places the tooltip to the left of the trigger element. Useful when there is limited space on the right side.
Set a maximum content width in pixels to constrain long tooltip text to a fixed column. Text wraps automatically.
### Accessibility
## Guidelines
Always attach the tooltip to a natively focusable element such as a button, link, or form control. This ensures keyboard users and screen reader users can trigger the tooltip without a mouse.
),
},
{
type: 'do',
title: 'Supplement, Never Replace, Visible Labels',
content: (
Use tooltips only to provide supplementary information. The trigger element must have its own accessible name — do not rely on the tooltip as the sole label for an interactive control.
),
},
{
type: 'do',
title: 'Keep Content Concise',
content: (
Limit tooltip content to a single short sentence. Screen readers announce the full tooltip text when the trigger is focused, so verbose content creates a poor listening experience.
),
},
{
type: 'dont',
title: 'Do Not Put Interactive Content Inside',
content: (
Never place links, buttons, or any interactive elements inside a tooltip. The tooltip role does not support interactive children and such content cannot be reached by keyboard or assistive technology.
),
},
{
type: 'dont',
title: 'Do Not Convey Critical Information Only via Tooltip',
content: (
Do not hide required instructions or error messages inside a tooltip. Touch users, users with motor disabilities, and users in high-contrast or reduced-motion modes may never see hover-triggered content.
),
},
{
type: 'dont',
title: 'Do Not Use on Non-Interactive Elements',
content: (
Avoid attaching tooltips to non-focusable elements like plain <div> or <span> tags. Users who rely on keyboard navigation will be unable to access the tooltip.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The tooltip component implements patterns that meet WCAG 2.2 Level AA standards:
- **1.3.1 Info and Relationships** — The trigger element receives `aria-describedby` pointing to the tooltip `id`, making the relationship machine-readable.
- **1.4.13 Content on Hover or Focus** — The tooltip persists while the pointer is over the trigger and can be dismissed with Escape; it does not disappear on hover alone.
- **2.1.1 Keyboard** — The tooltip is triggered on both `mouseenter` and `focus`, so it is accessible without a pointing device.
- **4.1.3 Status Messages** — The tooltip uses `role="tooltip"` and `aria-hidden` to correctly communicate its visibility state to assistive technology without moving focus.
---
# Structure
## ds-accordion
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-accordion-accordion--accordion
Accordion displays collapsible content sections with open/close toggle buttons and optional animations.
Perfect for organizing large amounts of content into logical, expandable groups.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| button | boolean | false | Displays the summary as a button and hides the default marker. |
| button-color | "danger" \| "primary" \| "secondary" \| "success" \| "warning" | 'primary' | The color of the button. Only applies if `button` is `true`. |
| button-icon-close | string | '' | BalIcon of the close trigger button |
| button-icon-open | string | '' | BalIcon of the open trigger button |
| button-label-close | string | '' | Label of the close trigger button |
| button-label-open | string | '' | Label of the open trigger button |
| button-size | "lg" \| "sm" \| "xl" \| undefined | | The size of the button. Only applies if `button` is `true`. |
| button-wide | boolean | false | If `true` the button is expanded to full width. Only applies if `button` is `true`. |
| group | string | '' | The name of the group the accordion belongs to. Accordions with the same group name will automatically close when another accordion in the same group is opened. |
| marker | "none" \| "plus" \| "plus-minus" \| undefined | | The marker variant. Only applies if `button` is `false`. If `''` the default marker is used, if `plus` a plus icon is used and if `plus-minus` a plus icon for closed and a minus icon for open state is used. |
| marker-position | "left" \| "right" \| undefined | | The position of the marker. Only applies if `button` is `false`. |
| open | boolean | false | If `true` the accordion is open. |
| summary-level | "h1" \| "h2" \| "h3" \| "h4" \| "h5" | 'h3' | The heading level of the summary |
| summary-title | boolean | false | If `true` the summary is styled as a title. |
| summary-visual-level | "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| undefined | | The visual heading level of the summary. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsClosed | AccordionToggleDetail | Emitted when the accordion is closed. |
| dsOpened | AccordionToggleDetail | Emitted when the accordion is opened. |
| dsToggle | AccordionToggleDetail | Emitted when the input value has changed. |
### Slots
| Name | Description |
| --- | --- |
| default | The default slot |
| content | The content slot defines the collapsible content of the accordion, which is hidden by default and becomes visible when the accordion is opened. |
| summary | The summary slot defines the summary of the accordion, which is always visible and serves as the toggle button to open or close the accordion. |
### Parts
| Name | Description |
| --- | --- |
| accordion | The accordion container element. |
| content | The content element that contains the collapsible content of the accordion. |
| header | The header element that contains the summary and marker. |
| marker | The marker element that indicates the open/close state of the accordion. |
| summary | The summary element that serves as the toggle button. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --accordion-header-min-height | Minimum height of the header row. |
| --accordion-marker-size | Height and minimum width of the expand/collapse marker icon. |
| --accordion-marker-width | Width of the expand/collapse marker box. |
| --accordion-summary-color | Text color of the summary label. |
| --accordion-summary-gap | Gap between the summary label and the marker. |
| --accordion-summary-font-family | Font family of the summary label. |
| --accordion-summary-font-weight | Font weight of the summary label. |
| --accordion-summary-font-size | Responsive font size of the summary label. |
| --accordion-summary-line-height | Line height of the summary label. |
| --accordion-summary-letter-spacing | Letter spacing of the summary label. |
| --accordion-summary-text-decoration | Text decoration of the summary label. |
| --accordion-summary-text-transform | Text transform of the summary label. |
| --accordion-summary-color-hover | Summary text color on hover. |
| --accordion-summary-color-active | Summary text color when pressed. |
| --accordion-radius | Border radius used for the focus ring outline. |
### Usage
## When to Use
- Group related content into expandable sections
- Organize FAQs or documentation with collapsible Q&A pairs
- Hide secondary or detailed information to reduce cognitive load
- Create step-by-step processes where users expand sections sequentially
- Manage form fields organized by category
## When NOT to Use
- For content that should always be visible — do not hide essential information in accordion sections
- When the content is short enough to fit on screen without scrolling — simpler layouts are clearer
- For critical user warnings or alerts — these should never be hidden
- As a replacement for proper information hierarchy — structure content logically first, then consider accordion
## Do's and Don'ts
### Accordion Headings
Accordion headers should clearly describe the content within the section. Use specific, descriptive headings.
Frequently Asked Questions
Content goes here
),
description: 'Users know exactly what content is in the section',
},
{
type: 'incorrect',
title: 'Incorrect: Vague heading',
contentIsLeftAligned: true,
content: (
More Info
Content goes here
),
description: 'Provides no indication of section content',
},
]}
/>
### Single vs. Multiple Accordion Sections
When users should only be able to open one section at a time, use the `group` prop to automatically close other sections.
What is this?
Answer goes here
How do I use it?
Answer goes here
\n \n'} />
>
),
description: 'Only one section opens at a time, improving focus',
},
{
type: 'incorrect',
title: 'Incorrect: No group binding',
contentIsLeftAligned: true,
content: (
<>
Section 1
Content 1
Section 2
Content 2
>
),
description: 'Users can open multiple sections, causing information overload',
},
]}
/>
### Variants
Customize the marker icon that indicates the open/closed state. Options include the default arrow, plus icon, or plus/minus toggle.
Position the marker on the left side of the accordion button for a different visual style and improved accessibility.
Customize the accordion summary with a stacked layout.
This is ideal for hiding complex content behind a simple header while still providing a clear visual hierarchy.
Use the `group` prop to ensure only one accordion in a group can be open at a time. This is useful for FAQs and other exclusive-choice content.
Use the `button` prop to render the accordion summary as a native button element, improving accessibility and keyboard navigation support.
### Accessibility
## Guidelines
Use clear, specific accordion headers that accurately describe the content within each section. This helps users understand what they will see before expanding.
),
},
{
type: 'do',
title: 'Keyboard Navigation',
content: (
Ensure accordion headers are keyboard accessible. Users should be able to navigate between sections and toggle them open/closed using the Tab and Enter/Space keys.
),
},
{
type: 'do',
title: 'Semantic HTML',
content: (
Use semantic heading levels (h1-h6) in accordion headers to maintain document structure. This helps screen reader users understand content hierarchy.
),
},
{
type: 'do',
title: 'State Indication',
content: (
Always provide visual indicators (arrow, icon, or color change) to show whether sections are expanded or collapsed. Screen readers need ARIA attributes to communicate state.
),
},
{
type: 'dont',
title: 'Hidden Essential Content',
content: (
Never hide critical information in accordion sections. Users with cognitive disabilities may not discover collapsed content, and some assistive technologies may skip it.
),
},
{
type: 'dont',
title: 'Icon-only Headers',
content: (
Do not rely solely on icons to indicate accordion state. Always include text labels that clearly describe the section content for all users.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The accordion component implements patterns that meet WCAG 2.2 Level AA standards:
- **Keyboard Navigation (2.1.1)** — All accordion headers are keyboard accessible
- **Focus Visible (2.4.7)** — Clear focus indicators on interactive elements
- **Name, Role, Value (4.1.2)** — Proper ARIA roles and attributes for state management
- **Heading Structure (1.3.1)** — Maintains semantic heading hierarchy within sections
---
## ds-app-footer
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-appfooter-app-footer--app-footer
AppFooter renders application level legal links, language selection, and social links.
Link content is slot first to keep links crawlable and SEO friendly.
Links and social media are shown by default unless disabled.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| container | "compact" \| "default" \| "fluid" \| undefined | | Sets the inner content container width. Accepts `'default'`, `'fluid'`, or `'compact'`. Matches the `ds-container` sizing variants. |
| disable-default-links | boolean | false | If `true` the default legal links from config will not be rendered. User must provide links via the `links` slot. |
| disable-default-social-links | boolean | false | If `true` the default social links from config will not be rendered. User must provide social links via the `social-links` slot. |
| hide-language-selection | boolean | false | If `true` the language selection will be hidden. |
| legal-text | string \| undefined | undefined | Copyright and address text below the divider. If not provided, uses the text from config based on region and language. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsLanguageChange | AppFooterLanguageChangeDetail | Emitted when the language select value changes. |
### Slots
| Name | Description |
| --- | --- |
| default | Main content area above the divider. |
| links | Optional legal or app links (shows if provided or config available). |
| logo | Optional custom logo markup. |
| social-links | Optional social link anchors (shows if provided or config available). |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --app-footer-color-background | Background color of the app-footer. |
| --app-footer-color-text | Text color of the app-footer. |
| --app-footer-font-family | Font family of the app-footer text. |
| --app-footer-font-size | Font size of the app-footer text. |
| --app-footer-font-weight | Font weight of the app-footer text. |
| --app-footer-line-height | Line height of the app-footer text. |
| --app-footer-letter-spacing | Letter spacing of the app-footer text. |
| --app-footer-text-decoration | Text decoration of the app-footer text. |
| --app-footer-text-transform | Text transform of the app-footer text. |
| --app-footer-gap | Gap between the app-footer elements. |
| --app-footer-gap-sm | Tight gap between related inline items (language picker, link list rows). |
| --app-footer-px | Horizontal padding of the app-footer. |
| --app-footer-py | Vertical padding of the app-footer. |
| --app-footer-max-width | Max width of the app-footer (default container). |
| --app-footer-max-width-fluid | Max width of the app-footer in fluid container mode. |
| --app-footer-max-width-compact | Max width of the app-footer in compact container mode. |
| --app-footer-language-font-family | Font family of the language picker. |
| --app-footer-language-font-size | Font size of the language picker. |
| --app-footer-language-font-weight | Font weight of the language picker. |
| --app-footer-language-line-height | Line height of the language picker select. |
| --app-footer-language-letter-spacing | Letter spacing of the language picker. |
| --app-footer-language-text-decoration | Text decoration of the language picker. |
| --app-footer-language-text-transform | Text transform of the language picker. |
| --app-footer-link-color | Text color of the app-footer links. |
| --app-footer-link-color-hover | Text color of the app-footer links on hover. |
| --app-footer-link-color-active | Text color of the app-footer links when active. |
| --app-footer-link-hover-text-decoration | Text decoration of a hovered/active app-footer link — single-property part modifier. |
| --app-footer-social-icon-size | Size of the social link icons in the app-footer. |
| --app-footer-social-icon-color | Color of the social link icons in the app-footer. |
### Usage
## Legal Links, Social Links & Legal Text
`legalLinks` and `socialLinks` are not props on `ds-app-footer` — they live in the global config, keyed by
`region` (and, for `legalLinks`/`legalText`, also `language`), so every footer instance on the page renders the
same defaults for the active region/language. `legalText` can additionally be overridden per instance with a prop.
**Angular**
Set the defaults once in `provideDesignSystem()`, in `app.config.ts`.
```html
```
**React**
Pass the defaults as props on `DsRootProvider`. Override `legalText` per instance with a prop on `DsAppFooter`.
${' '}${' '}${' '}
${' '}${' '}${' '}
${' '}${' '}${' '}
${' '}${' '}
${' '})
}
`} />
**HTML**
Set the defaults once with `initialize()` (or `updateDsLegalLinks` / `updateDsLegalText` / `updateDsSocialLinks` at
runtime).
```html
```
>
Need fully custom markup instead of the config-driven defaults? Set `disableDefaultLinks` /
`disableDefaultSocialLinks` and provide your own content via the `links` / `social-links` slots.
## When to Use
- Display application-level legal links, copyright information, and contact details
- Provide language selection for multilingual applications
- Include social media links and branding
- Present navigation options for privacy policies and imprints
## When NOT to Use
- For inline content that doesn't belong at the page bottom
- As a replacement for main navigation (use header components instead)
- For temporary or contextual information (use alerts or modals)
### Variants
The standard footer with default configuration, including language selection, default legal links from config, and the Baloise logo.
Footer with custom slotted links and social media icons. Use this variant when you need to provide specific legal links or social profiles different from the default config.
Footer with a custom logo and hidden language selection. The social media area is enabled to showcase social link integration. Useful for branded applications that need a custom logo instead of the default Baloise branding.
### Accessibility
## Guidelines
Wrap links in actual `<a>` elements with `href` attributes. This ensures screen readers announce links correctly and users can interact with them using keyboard navigation.
),
},
{
type: 'do',
title: 'Provide aria-labels for icon-only links',
content: (
When using social media icons without visible text, include `aria-label` attributes to describe the link destination for screen reader users.
),
},
{
type: 'do',
title: 'Mark logos as presentational when appropriate',
content: (
Use `aria-hidden="true"` on decorative logo images, or provide meaningful `aria-label` on logo links if they navigate to the homepage.
),
},
{
type: 'dont',
title: 'Use generic "Click here" link text',
content: (
Avoid vague link text. Screen reader users often navigate by headings and links alone — describe where the link goes or what it does.
),
},
{
type: 'dont',
title: 'Disable language selection without reason',
content: (
Users with language preferences need the ability to change the displayed language. Only hide the selector if your app is single-language.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The footer component implements patterns that meet WCAG 2.2 Level AA standards:
- **Link Purpose (2.4.9)** — All links have descriptive text or aria-labels
- **Language of Page (3.1.1)** — Language selection allows users to choose preferred language
- **Keyboard Navigation (2.1.1)** — All interactive elements are keyboard accessible
- **Color Contrast (1.4.3)** — Text and links meet minimum contrast ratios
- **Focus Visible (2.4.7)** — Keyboard focus indicators are clearly visible
---
## ds-card
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-card-card--card
Card groups related content together in a contained, visually distinct container with optional header and footer.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| align | "center" \| "left" \| undefined | | Defines the text alignment of the card content. |
| clickable | boolean | false | If `true` the card has a hover effect. |
| color | "dashed" \| "green" \| "green-dark" \| "grey" \| "primary" \| "purple" \| "purple-dark" \| "red" \| "red-dark" \| "yellow" \| "yellow-dark" \| undefined | | Defines the color of the card. |
| dense | boolean | false | If `true` the card gets a smaller padding. |
| flat | boolean | false | If `true` the card loses its shadow. |
| fullheight | boolean | false | If `true` the card uses 100% of the available height. |
| image-teaser | "wide-center" \| "wide-left" \| "wide-right" \| undefined | undefined | If `true` the card image is displayed as a teaser, which means it is displayed with a large image. |
| inverted | boolean | false | If `true` the card background color becomes blue. |
| selected | boolean | false | If `true` the card gets a light background to indicate a selection. |
| space | "lg" \| "sm" \| undefined | | Defines the space of the card content. |
| tile | boolean | false | If `true` the card gets a tile look, it has a brand icon on the left |
### Slots
| Name | Description |
| --- | --- |
| default | The main card content. |
| footer | Content displayed in the card footer. |
| header | Content displayed in the card header. |
| picture | |
### Parts
| Name | Description |
| --- | --- |
| card | The card container element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --card-color-background | Background color of the card. |
| --card-color-border | Border (width, style and color) of the card. |
| --card-radius | Border radius of the card. |
| --card-p | Padding inside the card. |
| --card-gap | Gap between card sections. |
| --card-shadow | Box shadow of the card. |
| --card-header-background | Background color of the card header. |
| --card-header-p | Padding inside the header section. |
| --card-footer-background | Background color of the card footer. |
| --card-footer-p | Padding inside the footer section. |
### Usage
## When to Use
- Display related content as a self-contained module
- Create product, article, or profile summary cards
- Group form fields or steps in a focused container
- Highlight featured content or promotions
- Build grids of related items (gallery, product listing)
## When NOT to Use
- For simple content that doesn't require visual separation — use plain dividers or spacing instead
- As the only layout method on a page — combine cards with other layout components
- To hide content that should be immediately visible — do not nest important information inside cards
- For very simple elements like single buttons or links — cards add unnecessary overhead
## Do's and Don'ts
> WIP
### Variants
The default card with a header, content area and action buttons.
Use the `tile` property to display a compact card with a brand icon, a tag and a toggle in the header — handy for
selectable options or coverage tiles.
Combine `align="center"` with a background `color` to center the header, content and actions inside the card.
Use the `color` property to apply a background color to the card, indicating status or visual emphasis.
Use the `space` property to adjust the inner padding of the card — `sm`, default, or `lg`.
Combine tags, buttons and a toggle inside `ds-card-title` and `ds-card-header` to build complex header layouts, with
or without an outline.
Use the `fullheight` property so cards in a grid stretch to match the height of the tallest card in the same row —
ideal for teaser cards.
Cards can display an image above the content, either as a plain `picture` or combined with `image-teaser` for a
linked teaser card.
Use the `image-teaser` property with `wide`, `wide-center` or `wide-right` to display a large image next to or
around the card content, full width on mobile.
### Accessibility
## Guidelines
Use semantic heading elements (h2-h6) for card titles, not just divs with bold text. This helps screen readers understand content hierarchy.
),
},
{
type: 'do',
title: 'Descriptive Links',
content: (
Ensure links within cards have descriptive text. Avoid generic "Click here" or "Read more" without context about what users will access.
),
},
{
type: 'do',
title: 'Keyboard Navigation',
content: (
If cards are clickable, ensure the entire card is keyboard accessible. Users should be able to activate cards using keyboard alone.
),
},
{
type: 'do',
title: 'Image Descriptions',
content: (
Always provide meaningful alt text for images within cards. Alt text should describe the image content or its relevance to the card.
),
},
{
type: 'dont',
title: 'Images Without Alt Text',
content: (
Never use images as the only way to convey important information. Screen reader users won't have access unless you provide alt text.
),
},
{
type: 'dont',
title: 'Relying on Color Alone',
content: (
Do not use color alone to distinguish card states or importance. Users with color blindness cannot perceive these differences.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The card component can support patterns that meet WCAG 2.2 Level AA standards:
- **Color Contrast (4.11.1)** — Text and interactive elements meet minimum contrast ratios
- **Keyboard Navigation (2.1.1)** — All interactive card elements are keyboard accessible
- **Focus Visible (2.4.7)** — Clear focus indicators for keyboard users
- **Image Text Alternatives (1.1.1)** — Meaningful alt text for all images
---
## ds-carousel
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-carousel-carousel--carousel
Carousel coordinates ds-carousel-item children into a scrollable, accessible slide interface. Supports an image slider and a product tile strip.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| controls | "dots" \| "large" \| "none" | 'dots' | Control style. `dots` shows dot pagination with prev/next arrows (image variant). `large` shows large side arrows (product variant). `none` hides all controls. |
| items-per-view | "auto" \| number | 'auto' | Number of items visible at once. `auto` sizes items by content. A number divides the container width equally. |
| label | string | '' | Accessible label for the carousel region. |
| steps | number | 1 | Number of items to advance per arrow click. |
| value | null \| string \| undefined | | Name of the currently selected ds-carousel-item. |
| variant | "slide" \| "tile" | 'slide' | Visual variant. `slide` uses scroll-snap and shows one slide at a time. `tile` shows multiple items with free scrolling. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsChange | CarouselChangeDetail | Emitted when the selected item changes. |
### Slots
| Name | Description |
| --- | --- |
| default | ds-carousel-item children. |
### Parts
| Name | Description |
| --- | --- |
| track | The scrollable item track. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --carousel-gap | Gap between slides / product items. |
| --carousel-control-color | Color of the scroll arrow buttons. |
| --carousel-scroll-fade-background | Background color for the edge-fade gradient in the product variant. |
| --carousel-scroll-fade-width | Width of the edge-fade gradient in the product variant. |
| --carousel-radius | Border radius of the slide track. |
| --carousel-pagination-gap | Gap between the slide track and the dot pagination. |
| --carousel-scroll-btn-size | Width and height of the scroll arrow buttons. |
| --carousel-scroll-btn-radius | Border radius of the scroll arrow buttons. |
| --carousel-scroll-btn-inset | Offset of the slide-variant arrow buttons from the image edge. |
| --carousel-scroll-btn-gap | Space between a product-variant arrow button and the track. |
| --carousel-scroll-btn-opacity-disabled | Opacity of a product-variant arrow button that cannot scroll further. |
### Usage
## When to Use
- Presenting a sequence of images or media slides with dot pagination navigation.
- Displaying a horizontal scrollable strip of product tiles or category links.
- Showcasing multiple items when vertical space is limited and a compact, interactive layout is preferred.
## When NOT to Use
- As a primary navigation pattern — important content should not be hidden behind carousel interactions.
- When all items can comfortably fit on screen without scrolling.
- To replace a data table or list where users need to compare items side by side.
### Variants
One slide visible at a time with scroll-snap. The default `controls="dots"` shows dot pagination together with the
prev/next arrows.
Use `controls="large"` to replace the dot pagination with large side-arrow scroll buttons.
Use `controls="none"` to hide all navigation controls, leaving swipe or scroll as the only way to move between
slides.
The `tile` variant shows multiple items with free scrolling, each sized automatically by its own content.
Combine the `tile` variant with `navigation` items and a fixed `--carousel-item-width` to build a strip of linked
product tiles with brand icons. Use `steps` to control how many items scroll per arrow click.
### Accessibility
## Guidelines
Set the label prop to describe the purpose of the carousel. This gives screen readers an accessible name for the scrollable region.
),
},
{
type: 'do',
title: 'Give every item a unique name',
content: (
Each ds-carousel-item requires a unique name attribute. This is used to track selection state and must be meaningful in your application context.
),
},
{
type: 'do',
title: 'Use keyboard navigation',
content: (
The slide variant supports ArrowLeft , ArrowRight , Home , and End keys to navigate between slides without using a pointer device.
),
},
{
type: 'dont',
title: 'Do not rely on auto-play',
content: (
The carousel does not auto-advance slides. Do not add auto-play behaviour — moving content that users cannot pause violates WCAG 2.2 Pause, Stop, Hide (2.2.2).
),
},
{
type: 'dont',
title: 'Do not hide critical content inside tiles',
content: (
Tiles that are scrolled out of view are still present in the DOM but may not be visible. Do not place content that every user must see inside a tile-variant carousel without an alternative.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The carousel component implements patterns that meet WCAG 2.2 Level AA standards:
- **Name, Role, Value (4.1.2)** — The track region has an accessible name via `label` and is exposed as a `region` landmark.
- **Keyboard Accessible (2.1.1)** — Slide navigation is fully operable via keyboard arrow keys, Home, and End.
- **Focus Visible (2.4.7)** — Tile items expose a focus-visible ring when navigated by keyboard.
- **Pause, Stop, Hide (2.2.2)** — No auto-advancing content; all movement is user-initiated.
---
## ds-content
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-content-content--content
Content arranges content with flexible layout, alignment, and spacing options for structural layouts.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| align | "center" \| "end" \| "start" \| undefined | | Defines the positioning like center, end or default to start. |
| direction | "column" \| "column-reverse" \| "row" \| "row-reverse" \| undefined | | Defines the direction of the child elements. Default is column. |
| layout | "horizontal" \| "horizontal-reverse" \| "vertical" \| "vertical-reverse" \| undefined | | **Deprecated:** Use direction instead. |
| space | "2xs" \| "3xs" \| "base" \| "none" \| "sm" \| "xs" | '2xs' | Defines the space between the child elements. Default is 2xs. |
| text-align | "center" \| "left" \| "right" \| undefined | | Defines the text positioning like center, right or default to left. |
### Slots
| Name | Description |
| --- | --- |
| default | The content children (text, images, other elements). |
### Parts
| Name | Description |
| --- | --- |
| content | The content container element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --content-direction | Direction of the content layout (row or column). |
| --content-gap | Spacing between content children. |
| --content-align | Alignment of items perpendicular to main axis. |
| --content-justify | Justification along the main axis. |
| --content-wrap | Whether items wrap to multiple lines. |
| --content-p | Padding around the content container. |
| --content-max-width | Maximum width of the content. |
### Usage
## When to Use
- Wrap main page content in semantic containers
- Organize content with clear sections and headers
- Provide consistent spacing and layout structure
- Create navigable content regions
- Structure complex multi-section layouts
- Implement breadcrumb or header navigation areas
## When NOT to Use
- For simple single-element layouts — basic divs may suffice
- For non-content areas (sidebars, modals) — use appropriate container components
- For content that doesn't need structural organization — use standard HTML elements
- For purely decorative grouping — unnecessary if no semantic value
- For performance-critical layouts requiring minimal markup — reduce nesting
### Variants
Content area with different text alignments: left, center, and right.
Content area with various layout options, including different spacing and
arrangement of elements to create visually appealing and organized content sections.
Content area with different spacing options to control the amount of whitespace around and between elements, enhancing readability and visual hierarchy.
### Accessibility
## Guidelines
Use proper heading levels (h1, h2, h3) within content sections. Don't skip heading levels.
),
},
{
type: 'dont',
title: 'No Semantic Landmarks',
content: (
Don't use generic divs without semantic roles. Screen readers need to understand content structure.
),
},
{
type: 'dont',
title: 'Broken Heading Hierarchy',
content: (
Don't skip heading levels or use heading styles for non-headings. Maintains structure for screen readers.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The content component supports patterns that meet WCAG 2.2 Level AA standards:
- **Semantic Structure (1.3.1)** — Uses proper roles and heading hierarchy
- **Page Structure (2.4.6)** — Clear organization with headings and sections
- **Meaningful Sequence (1.3.2)** — Reading order makes sense
---
## ds-data
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-data-data--data
Data displays a list of label-value pairs in a organized, accessible format.
Supports vertical and horizontal layouts with dividers always shown in vertical layout.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| horizontal | boolean | false | If `true` the data list is horizontal instead of vertical. |
### Slots
| Name | Description |
| --- | --- |
| default | The content of the data list (typically ds-data-item elements). |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --data-item-label-font-family | Font family of the label |
| --data-item-label-font-size | Font size of the label |
| --data-item-label-font-weight | Font weight of the label |
| --data-item-label-line-height | Line height of the label |
| --data-item-label-letter-spacing | Letter spacing of the label |
| --data-item-label-text-decoration | Text decoration of the label |
| --data-item-label-text-transform | Text transform of the label |
| --data-item-value-font-family | Font family of the value |
| --data-item-value-font-size | Font size of the value |
| --data-item-value-font-weight | Font weight of the value |
| --data-item-value-line-height | Line height of the value |
| --data-item-value-letter-spacing | Letter spacing of the value |
| --data-item-value-text-decoration | Text decoration of the value |
| --data-item-value-text-transform | Text transform of the value |
| --data-item-color-text | Text color of the value |
| --data-item-color-text-label | Text color of the label |
| --data-item-color-text-required | Color of the required indicator |
| --data-item-color-text-disabled | Text color when disabled |
| --data-item-border-bottom | Bottom border |
| --data-item-gap | Gap between label and value columns |
| --data-item-padding-block | Vertical padding of the row |
| --data-item-gap-label | Gap between label text and required indicator |
| --data-item-gap-value | Gap between value content and edit button |
| --data-item-gap-stacked | Gap between label and value in the stacked layout |
| --data-item-padding-stacked | Padding in the stacked layout |
| --data-item-min-height-horizontal | Minimum height inside a horizontal data list |
| --data-gap-horizontal | Gap between items in the horizontal layout |
### Usage
## When to Use
- Displaying read-only label-value pairs (user profile information, contact details)
- Showing structured data in a consistent, accessible format
- Creating data entry forms with custom input controls via slots
- Presenting hierarchical or nested information with clear labels
## When NOT to Use
- For simple key-value displays without visual hierarchy — use plain text or lists instead
- For complex tabular data with multiple columns and rows — use a table component instead
- For form layouts with validation and error handling — use a form component instead
- For displaying unstructured or narrative content
### Variants
Basic data list displaying label-value pairs in a vertical layout with borders.
Horizontal layout displays multiple label-value pairs as columns on larger screens. Responsive: switches to vertical on mobile.
Support for multiline values that wrap and align with labels. Handles long text and nested content like lists.
Required indicator shown on labels using the `required` attribute on ds-data-label.
Individual items can be marked as disabled using the `disabled` prop on ds-data-item. Appears with reduced opacity.
Editable items display a small edit button on the right using the `editable` prop on ds-data-item. The button is right-aligned and shows a tertiary icon button. Use the optional `editLabel` prop to customize the button's accessible label.
### Accessibility
## Guidelines
Always use ds-data-label and ds-data-value components to ensure semantic structure and proper screen reader announcements.,
},
{
type: 'do',
title: 'Associate custom inputs with labels',
content: When using native HTML form elements in the value slot, use proper for/id attributes on labels for keyboard accessibility and screen reader support.
,
},
{
type: 'do',
title: 'Mark required fields clearly',
content: Use the required attribute on ds-data-label to visually indicate required fields with color contrast compliant indicators.
,
},
{
type: 'do',
title: 'Provide sufficient color contrast',
content: All text, including labels and values, maintains WCAG 2.2 AA color contrast ratios (4.5:1 for normal text).
,
},
{
type: 'dont',
title: 'Avoid using color alone to convey meaning',
content: Do not rely solely on color (e.g., red borders) to indicate state changes. Use additional visual or textual cues.
,
},
{
type: 'dont',
title: 'Do not skip label associations',
content: When including form inputs, always associate them with labels using for/id attributes. Unlabeled inputs fail accessibility requirements.
,
},
]}
/>
## WCAG 2.2 AA Compliance
The data component implements patterns that meet WCAG 2.2 Level AA standards:
- **1.4.3 Contrast (Minimum)** — All text meets 4.5:1 contrast ratio for normal text and 3:1 for large text
- **2.4.3 Focus Order** — Focus order is logical and matches visual layout for keyboard navigation
- **3.2.4 Consistent Identification** — Components and their patterns remain consistent across pages
- **3.3.2 Labels or Instructions** — Labels clearly identify form inputs and data items
- **4.1.2 Name, Role, Value** — All interactive elements have accessible names and proper ARIA roles
---
## ds-divider
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-divider-divider--divider
Divider renders a visual separator line for grouping or distinguishing content sections.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| color | "default" \| "inverted" \| "primary" \| "secondary" | 'default' | Defines the color of the separator line. |
| dashed | boolean | false | Defines if the separator line is dashed or solid. Default is solid. |
| layout | "horizontal" \| "vertical" | 'horizontal' | Defines the position of the child elements if they are showed verticaly or horizontally. Default is verticaly. |
| space | "2xl" \| "2xs" \| "3xl" \| "base" \| "lg" \| "md" \| "none" \| "sm" \| "xl" \| "xs" | 'none' | Defines the space between the child elements. Default is none. |
### Parts
| Name | Description |
| --- | --- |
| divider | The divider line element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --divider-color | Color of the divider line. |
| --divider-size | Thickness of the divider line. |
| --divider-radius | Border radius of the divider line. |
| --divider-margin | Spacing around the divider (block axis when horizontal, inline axis when vertical). |
### Usage
## When to Use
- Separate different content sections or groups visually
- Break up long pages into manageable sections
- Distinguish between different types of content or data
- Divide layouts into columns or sections
- Provide visual breathing room between content blocks
## When NOT to Use
- Do not use dividers for purely decorative purposes without semantic meaning
- Do not use multiple dividers in close succession — it reduces their visual impact
- For structural separation that should use semantic HTML (e.g., ``, ``)
- In dense data tables where borders would be more appropriate
- As a replacement for proper whitespace and layout — use spacing instead
## Do's and Don'ts
### Placement and Spacing
Use dividers strategically to enhance content organization without cluttering the layout.
Section 1 content here
Section 2 content here
>
),
description: 'Divider with spacing clearly separates related content',
},
{
type: 'incorrect',
title: 'Incorrect: Excessive dividers',
content: (
<>
Item 1
Item 2
Item 3
>
),
description: 'Too many dividers create visual noise and reduce effectiveness',
},
]}
/>
### Color Usage
Use divider colors to reinforce meaning or hierarchy. Default grey works for most cases.
\n '} />
>
),
description: 'Color choice reinforces the semantic meaning',
},
{
type: 'incorrect',
title: 'Incorrect: Random colors',
content: (
<>
'} />
>
),
description: 'Misaligned color semantics confuse users',
},
]}
/>
### Variants
Use dashed dividers to create a more subtle separation between content sections, providing a lighter visual break compared to solid dividers.
Use vertical dividers to separate content sections in a vertical layout, providing a clear visual distinction between elements.
### Accessibility
## Guidelines
Use dividers to visually organize content into meaningful sections. Screen reader users benefit from proper semantic structure, not visual lines alone.
),
},
{
type: 'do',
title: 'Support Semantic HTML',
content: (
Pair dividers with semantic HTML elements like section or article to provide proper document structure for screen readers.
),
},
{
type: 'do',
title: 'Sufficient Color Contrast',
content: (
Ensure divider lines have sufficient contrast against their background. Light grey dividers may not be visible to users with low vision.
),
},
{
type: 'do',
title: 'Use ARIA Landmarks',
content: (
Use ARIA landmark roles (main, nav, aside) in addition to visual dividers to help screen reader users navigate page structure.
),
},
{
type: 'dont',
title: 'Rely on Dividers Alone',
content: (
Do not use dividers as the only means of communicating content separation. Screen reader users depend on semantic HTML structure, not visual lines.
),
},
{
type: 'dont',
title: 'Color Alone for Meaning',
content: (
Do not rely on divider color alone to communicate meaning. Use additional visual cues or textual labels so users with color blindness understand the distinction.
),
},
]}
/>
---
## ds-heading
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-heading-heading--heading
Heading renders semantic HTML heading elements (h1–h6) with flexible styling options for visual hierarchy independent of markup level.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| auto-level | "2xl" \| "3xl" \| "4xl" \| "5xl" \| "base" \| "display" \| "display-2" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "lg" \| "md" \| "xl" \| undefined | | The actual heading level used in the HTML markup. |
| inverted | boolean | false | If `true` the color gets inverted for dark backgrounds |
| level | "display" \| "display-2" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "p" \| "span" | 'h1' | The actual heading level used in the HTML markup. |
| no-wrap | boolean | false | When true, the text will be truncated with a text overflow ellipsis instead of wrapping. Please note that text overflow can only occur in block or inline-block level elements, as these elements require a width to overflow. |
| shadow | boolean | false | If `true` adds a text shadow to improve readability on image background |
| space | "all" \| "bottom" \| "none" \| "top" \| undefined | | Defines at which position the heading has spacing. |
| subtitle | boolean | false | If `true` the heading gets displayed slimmer. |
| visual-level | "2xl" \| "3xl" \| "4xl" \| "5xl" \| "base" \| "display" \| "display-2" \| "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "lg" \| "md" \| "xl" \| undefined | | Make the visual style mimic a specific heading level. This option allows you to make e.g. h1 visually look like h3, but still keep it h1 in the markup. |
### Slots
| Name | Description |
| --- | --- |
| default | The heading content. |
### Parts
| Name | Description |
| --- | --- |
| heading | The native HTML heading element (h1–h6). |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --heading-color | Text color of the heading. |
| --heading-font-family | Font family of the heading. |
| --heading-font-weight | Font weight of the heading. |
| --heading-font-size | Font size of the heading. |
| --heading-line-height | Line height of the heading text. |
| --heading-letter-spacing | Letter spacing of the heading text. |
| --heading-text-decoration | Text decoration of the heading text. |
| --heading-text-transform | Text transform of the heading text. |
| --heading-margin | Spacing applied to the heading. |
| --heading-shadow | Text shadow effect applied to the heading. |
| --heading-text-align | Text alignment of the heading. |
### Usage
## When to Use
- Display page titles, section headers, or any hierarchical text structure
- Provide semantic HTML heading elements for SEO and accessibility
- Create visual distinction between different heading levels in your layout
- Use shadow prop for headings displayed over images or dark backgrounds
## When NOT to Use
- Do not use headings for styling regular body text — use the Text component instead
- Do not skip heading levels (h1 to h3) — maintain semantic hierarchy
- Do not use multiple h1 elements on a single page — maintain proper document structure
- For styling only without semantic structure — consider using the Text component with visual level
## Do's and Don'ts
### Semantic Hierarchy
Maintain proper heading hierarchy in your document. Each page should have exactly one h1 element, with subsequent headings following a logical order.
Page Title
Section One
Subsection A
>
),
description: 'Clear, logical heading structure improves SEO and accessibility',
},
{
type: 'incorrect',
title: 'Incorrect: Skipped levels',
content: (
<>
Page Title
Content Section
>
),
description: 'Skipping levels confuses screen readers and breaks semantic structure',
},
]}
/>
### Visual Level vs Markup Level
Use the `visualLevel` prop when you need visual styling independent of semantic markup.
Styled as H1'} />
>
),
description: 'Allows flexible styling while maintaining semantic markup',
},
{
type: 'incorrect',
title: 'Incorrect: Wrong semantic level',
content: (
<>
Main title'} />
>
),
description: 'Using h3 as main title breaks document structure',
},
]}
/>
### Variants
Headings with different levels (H1 to H6) to establish a clear content hierarchy and improve readability.
Headings with different sizes to establish a clear content hierarchy and improve readability.
Headings render in the primary color by default. Use the `inverted` prop on dark backgrounds.
Headings can be set to not wrap, truncating overflow text with an ellipsis to maintain layout integrity.
Headings can have custom spacing to adjust the visual rhythm and layout consistency.
Headings can automatically adjust their level based on the surrounding context to maintain a consistent hierarchy.
### Accessibility
## Guidelines
Use heading levels in order (h1, then h2, then h3, etc.) without skipping levels. This ensures screen readers can construct a proper document outline and users can navigate content efficiently.
),
},
{
type: 'do',
title: 'One H1 Per Page',
content: (
Always include exactly one h1 element per page representing the main page title or heading. Multiple h1 elements confuse both screen readers and users about page structure.
),
},
{
type: 'do',
title: 'Sufficient Color Contrast',
content: (
Ensure heading text meets WCAG 2.2 AA contrast ratios (4.5:1 for normal text). Use the shadow variant on dark or image backgrounds to maintain readability.
),
},
{
type: 'do',
title: 'Use for Content Structure',
content: (
Reserve headings for actual structural sections of content. Use the Text component for decorative or styled text that is not part of the document outline.
),
},
{
type: 'dont',
title: 'Color Alone for Distinction',
content: (
Do not rely on color alone to distinguish headings from body text. Combine color changes with size, weight, and spacing to ensure all users can perceive the distinction.
),
},
{
type: 'dont',
title: 'Skip Heading Levels',
content: (
Do not jump from h1 directly to h3 or skip intermediate levels. This breaks the document structure and confuses screen reader users about content organization.
),
},
]}
/>
---
## ds-list
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-list-list--list
List renders semantic HTML list elements (ordered or unordered) for grouping related items.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| inverted | boolean | false | If `true`, the list uses an inverted color scheme for use on dark backgrounds such as the primary surface. Cascades to descendant `ds-item` elements. |
| ordered | boolean | false | If `true`, renders an ordered list (``); otherwise renders an unordered list (``). |
| size | "lg" \| undefined | | The size of the list items. If not set, the default (base) size is used. Cascades to descendant `ds-item` elements. |
### Slots
| Name | Description |
| --- | --- |
| default | The list items (li elements or content). |
### Parts
| Name | Description |
| --- | --- |
| list | The native HTML list element (ol or ul). |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --description-list-grid-term | Defines the grid column size for the term (dt) element. |
| --description-list-grid-detail | Defines the grid column size for the detail (dd) element. |
| --description-list-grid-row-gap | Defines the gap between rows in the description list. |
| --description-list-grid-column-gap | Defines the gap between columns in the description list. |
| --description-list-term-color | Defines the text color for the term (dt) element. |
| --description-list-term-font-family | Defines the font family for the term (dt) element. |
| --description-list-term-font-weight | Defines the font weight for the term (dt) element. |
| --description-list-term-font-size | Defines the font size for the term (dt) element. |
| --description-list-term-line-height | Defines the line height for the term (dt) element. |
| --description-list-term-letter-spacing | Defines the letter spacing for the term (dt) element. |
| --description-list-term-text-decoration | Defines the text decoration for the term (dt) element. |
| --description-list-term-text-transform | Defines the text transform for the term (dt) element. |
| --description-list-detail-color | Defines the text color for the detail (dd) element. |
| --description-list-detail-font-family | Defines the font family for the detail (dd) element. |
| --description-list-detail-font-weight | Defines the font weight for the detail (dd) element. |
| --description-list-detail-font-size | Defines the font size for the detail (dd) element. |
| --description-list-detail-line-height | Defines the line height for the detail (dd) element. |
| --description-list-detail-letter-spacing | Defines the letter spacing for the detail (dd) element. |
| --description-list-detail-text-decoration | Defines the text decoration for the detail (dd) element. |
| --description-list-detail-text-transform | Defines the text transform for the detail (dd) element. |
| --description-list-detail-mb | Defines the margin-bottom between stacked details on mobile. |
| --ordered-list-mb | Defines the margin-bottom for the ordered list. |
| --ordered-list-style-type | Defines the list style type for the ordered list. |
| --ordered-list-style-position | Defines the list style position for the ordered list. |
| --ordered-list-marker-color | Defines the color of the list marker for the ordered list. |
| --ordered-list-marker-font-family | Font family of the ordered list marker (counter). |
| --ordered-list-marker-font-size | Font size of the ordered list marker (counter). |
| --ordered-list-marker-font-weight | Font weight of the ordered list marker (counter). |
| --ordered-list-marker-line-height | Line height of the ordered list marker (counter). |
| --ordered-list-marker-letter-spacing | Letter spacing of the ordered list marker (counter). |
| --ordered-list-marker-text-decoration | Text decoration of the ordered list marker (counter). |
| --ordered-list-marker-text-transform | Text transform of the ordered list marker (counter). |
| --unordered-list-mb | Defines the margin-bottom for the unordered list. |
| --unordered-list-style-type | Defines the list style type for the unordered list. |
| --unordered-list-style-position | Defines the list style position for the unordered list. |
| --unordered-list-marker-color | Defines the color of the list marker for the unordered list. |
| --unordered-list-marker-radius | Defines the border radius of the list marker for the unordered list. |
| --unordered-list-marker-icon | Defines the icon for the list marker for the unordered list. |
### Usage
## When to Use
- Display a series of related items or steps
- Create navigation menus or breadcrumbs
- Show search results or filtered content
- Organize instructions or steps in sequence
- Display related links or resources
- Present hierarchical information with nesting
## When NOT to Use
- For tabular data with multiple columns — use a table component instead
- As a replacement for proper content hierarchy — lists supplement structure, not define it
- For single items or pairs of items — simple dividers are clearer
- When items don't have a logical grouping — use individual components instead
## Do's and Don'ts
### List Item Content
Keep list items concise but descriptive. Use consistent formatting across items.
Complete the form
Review your information
Submit your application
),
description: 'Clear, parallel structure',
},
{
type: 'incorrect',
title: 'Incorrect: Inconsistent list item structure',
content: (
You should fill out the form completely
Review
After reviewing the information, you can then submit your application to us
),
description: 'Inconsistent length and detail',
},
]}
/>
### Variants
List of links for navigation or reference.
Use the `inverted` prop to display a list on dark or colored backgrounds such as the primary surface. Setting it on `ds-list` cascades the inverted color scheme to every descendant `ds-item`.
List of downloadable items with associated actions.
List of items that can be expanded or collapsed to show more content.
List of nested items that can be expanded or collapsed to show more content.
List of items in a specific sequence or order.
Native bullet point list for unordered items.
Native numbered list for ordered items.
Description list for pairs of terms and descriptions.
### Accessibility
## Guidelines
Always use semantic list elements: <ul> for unordered lists, <ol> for ordered lists, and <li> for list items. Screen readers announce list structure and count.
),
},
{
type: 'do',
title: 'Proper Nesting',
content: (
Nest lists correctly to show hierarchy. Sublists should be contained within list items using proper HTML structure.
),
},
{
type: 'do',
title: 'Descriptive List Items',
content: (
Write list item content that makes sense in context. Screen reader users should understand each item without surrounding text.
),
},
{
type: 'do',
title: 'Keyboard Navigation',
content: (
Ensure interactive list items (links, buttons) are keyboard accessible. Users should navigate between items using arrow keys or Tab.
),
},
{
type: 'dont',
title: 'Divs Instead of Lists',
content: (
Never use divs or other elements to simulate lists. This removes semantic meaning and screen readers won't announce list structure.
),
},
{
type: 'dont',
title: 'No List for Navigation',
content: (
Don't skip lists for navigation. Use semantic list elements even in navigation menus so screen readers understand the menu structure.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The list component follows patterns that meet WCAG 2.2 Level AA standards:
- **Semantic HTML (1.3.1)** — Proper list element usage conveys structure
- **Keyboard Navigation (2.1.1)** — All interactive list items are keyboard accessible
- **Focus Visible (2.4.7)** — Clear focus indicators for linked list items
- **List Structure (1.3.1)** — Screen readers announce list type and number of items
---
## ds-root
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-root-root--root
Root is a root wrapper component that provides global configuration, focus management, and responsive behavior context for all design system components.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| allowed-languages | string \| undefined | | Comma separated list of languages the root allows selecting. Falls back to the global config default when unset. |
| animated | boolean | true | Disables all animation inside the ds-root. Can be used for simplify e2e testing. |
| brand | "baloise" \| "helvetia" \| undefined | | Sets the active brand for all design system components. Falls back to the global config default when unset. |
| fallback-language | "de" \| "en" \| "es" \| "fi" \| "fr" \| "it" \| "nl" \| "pl" \| "pt" \| "sv" \| undefined | | Language used when `language` is not part of `allowedLanguages`. Falls back to the global config default when unset. |
| icons | undefined \| { [key: string]: string; } | | Merges custom icons into the global config, keyed by name. Not reflected as an attribute — pass a JS object. |
| language | "de" \| "en" \| "es" \| "fi" \| "fr" \| "it" \| "nl" \| "pl" \| "pt" \| "sv" \| undefined | | Sets the active language for all design system components. Falls back to the global config default when unset. |
| legalLinks | undefined \| { CH?: { de?: AppFooterLink[] \| undefined; fr?: AppFooterLink[] \| undefined; it?: AppFooterLink[] \| undefined; en?: AppFooterLink[] \| undefined; es?: AppFooterLink[] \| undefined; pl?: AppFooterLink[] \| undefined; pt?: AppFooterLink[] \| undefined; sv?: AppFooterLink[] \| undefined; fi?: AppFooterLink[] \| undefined; nl?: AppFooterLink[] \| undefined; } \| undefined; DE?: { de?: AppFooterLink[] \| undefined; fr?: AppFooterLink[] \| undefined; it?: AppFooterLink[] \| undefined; en?: AppFooterLink[] \| undefined; es?: AppFooterLink[] \| undefined; pl?: AppFooterLink[] \| undefined; pt?: AppFooterLink[] \| undefined; sv?: AppFooterLink[] \| undefined; fi?: AppFooterLink[] \| undefined; nl?: AppFooterLink[] \| undefined; } \| undefined; BE?: { de?: AppFooterLink[] \| undefined; fr?: AppFooterLink[] \| undefined; it?: AppFooterLink[] \| undefined; en?: AppFooterLink[] \| undefined; es?: AppFooterLink[] \| undefined; pl?: AppFooterLink[] \| undefined; pt?: AppFooterLink[] \| undefined; sv?: AppFooterLink[] \| undefined; fi?: AppFooterLink[] \| undefined; nl?: AppFooterLink[] \| undefined; } \| undefined; LU?: { de?: AppFooterLink[] \| undefined; fr?: AppFooterLink[] \| undefined; it?: AppFooterLink[] \| undefined; en?: AppFooterLink[] \| undefined; es?: AppFooterLink[] \| undefined; pl?: AppFooterLink[] \| undefined; pt?: AppFooterLink[] \| undefined; sv?: AppFooterLink[] \| undefined; fi?: AppFooterLink[] \| undefined; nl?: AppFooterLink[] \| undefined; } \| undefined; AT?: { de?: AppFooterLink[] \| undefined; fr?: AppFooterLink[] \| undefined; it?: AppFooterLink[] \| undefined; en?: AppFooterLink[] \| undefined; es?: AppFooterLink[] \| undefined; pl?: AppFooterLink[] \| undefined; pt?: AppFooterLink[] \| undefined; sv?: AppFooterLink[] \| undefined; fi?: AppFooterLink[] \| undefined; nl?: AppFooterLink[] \| undefined; } \| undefined; ES?: { de?: AppFooterLink[] \| undefined; fr?: AppFooterLink[] \| undefined; it?: AppFooterLink[] \| undefined; en?: AppFooterLink[] \| undefined; es?: AppFooterLink[] \| undefined; pl?: AppFooterLink[] \| undefined; pt?: AppFooterLink[] \| undefined; sv?: AppFooterLink[] \| undefined; fi?: AppFooterLink[] \| undefined; nl?: AppFooterLink[] \| undefined; } \| undefined; IT?: { de?: AppFooterLink[] \| undefined; fr?: AppFooterLink[] \| undefined; it?: AppFooterLink[] \| undefined; en?: AppFooterLink[] \| undefined; es?: AppFooterLink[] \| undefined; pl?: AppFooterLink[] \| undefined; pt?: AppFooterLink[] \| undefined; sv?: AppFooterLink[] \| undefined; fi?: AppFooterLink[] \| undefined; nl?: AppFooterLink[] \| undefined; } \| undefined; NL?: { de?: AppFooterLink[] \| undefined; fr?: AppFooterLink[] \| undefined; it?: AppFooterLink[] \| undefined; en?: AppFooterLink[] \| undefined; es?: AppFooterLink[] \| undefined; pl?: AppFooterLink[] \| undefined; pt?: AppFooterLink[] \| undefined; sv?: AppFooterLink[] \| undefined; fi?: AppFooterLink[] \| undefined; nl?: AppFooterLink[] \| undefined; } \| undefined; FR?: { de?: AppFooterLink[] \| undefined; fr?: AppFooterLink[] \| undefined; it?: AppFooterLink[] \| undefined; en?: AppFooterLink[] \| undefined; es?: AppFooterLink[] \| undefined; pl?: AppFooterLink[] \| undefined; pt?: AppFooterLink[] \| undefined; sv?: AppFooterLink[] \| undefined; fi?: AppFooterLink[] \| undefined; nl?: AppFooterLink[] \| undefined; } \| undefined; } | | Merges per-region, per-language legal links into the global config. Not reflected as an attribute — pass a JS object. |
| legalText | undefined \| { CH?: { de?: string \| undefined; fr?: string \| undefined; it?: string \| undefined; en?: string \| undefined; es?: string \| undefined; pl?: string \| undefined; pt?: string \| undefined; sv?: string \| undefined; fi?: string \| undefined; nl?: string \| undefined; } \| undefined; DE?: { de?: string \| undefined; fr?: string \| undefined; it?: string \| undefined; en?: string \| undefined; es?: string \| undefined; pl?: string \| undefined; pt?: string \| undefined; sv?: string \| undefined; fi?: string \| undefined; nl?: string \| undefined; } \| undefined; BE?: { de?: string \| undefined; fr?: string \| undefined; it?: string \| undefined; en?: string \| undefined; es?: string \| undefined; pl?: string \| undefined; pt?: string \| undefined; sv?: string \| undefined; fi?: string \| undefined; nl?: string \| undefined; } \| undefined; LU?: { de?: string \| undefined; fr?: string \| undefined; it?: string \| undefined; en?: string \| undefined; es?: string \| undefined; pl?: string \| undefined; pt?: string \| undefined; sv?: string \| undefined; fi?: string \| undefined; nl?: string \| undefined; } \| undefined; AT?: { de?: string \| undefined; fr?: string \| undefined; it?: string \| undefined; en?: string \| undefined; es?: string \| undefined; pl?: string \| undefined; pt?: string \| undefined; sv?: string \| undefined; fi?: string \| undefined; nl?: string \| undefined; } \| undefined; ES?: { de?: string \| undefined; fr?: string \| undefined; it?: string \| undefined; en?: string \| undefined; es?: string \| undefined; pl?: string \| undefined; pt?: string \| undefined; sv?: string \| undefined; fi?: string \| undefined; nl?: string \| undefined; } \| undefined; IT?: { de?: string \| undefined; fr?: string \| undefined; it?: string \| undefined; en?: string \| undefined; es?: string \| undefined; pl?: string \| undefined; pt?: string \| undefined; sv?: string \| undefined; fi?: string \| undefined; nl?: string \| undefined; } \| undefined; NL?: { de?: string \| undefined; fr?: string \| undefined; it?: string \| undefined; en?: string \| undefined; es?: string \| undefined; pl?: string \| undefined; pt?: string \| undefined; sv?: string \| undefined; fi?: string \| undefined; nl?: string \| undefined; } \| undefined; FR?: { de?: string \| undefined; fr?: string \| undefined; it?: string \| undefined; en?: string \| undefined; es?: string \| undefined; pl?: string \| undefined; pt?: string \| undefined; sv?: string \| undefined; fi?: string \| undefined; nl?: string \| undefined; } \| undefined; } | | Merges per-region, per-language legal text into the global config. Not reflected as an attribute — pass a JS object. |
| region | "AT" \| "BE" \| "CH" \| "DE" \| "ES" \| "FR" \| "IT" \| "LU" \| "NL" \| undefined | | Sets the active region for all design system components. Falls back to the global config default when unset. |
| socialLinks | undefined \| { CH?: AppFooterSocialLink[] \| undefined; DE?: AppFooterSocialLink[] \| undefined; BE?: AppFooterSocialLink[] \| undefined; LU?: AppFooterSocialLink[] \| undefined; AT?: AppFooterSocialLink[] \| undefined; ES?: AppFooterSocialLink[] \| undefined; IT?: AppFooterSocialLink[] \| undefined; NL?: AppFooterSocialLink[] \| undefined; FR?: AppFooterSocialLink[] \| undefined; } | | Merges per-region social links into the global config. Not reflected as an attribute — pass a JS object. |
### Events
| Event | Detail | Description |
| --- | --- | --- |
| dsAllowedLanguagesChange | DsLanguage[] | Emitted when the `allowedLanguages` value changes in the global config. |
| dsAnimatedChange | boolean | Emitted when the `animated` value changes in the global config. |
| dsAppReady | void | Emitted when root is ready and painted. |
| dsBrandChange | DsBrand | Emitted when the `brand` value changes in the global config. |
| dsFallbackLanguageChange | DsLanguage | Emitted when the `fallbackLanguage` value changes in the global config. |
| dsIconsChange | DsIcons | Emitted when the `icons` value changes in the global config. |
| dsLanguageChange | DsLanguage | Emitted when the `language` value changes in the global config. |
| dsLegalLinksChange | DsLegalLinks | Emitted when the `legalLinks` value changes in the global config. |
| dsLegalTextChange | DsLegalText | Emitted when the `legalText` value changes in the global config. |
| dsRegionChange | DsRegion | Emitted when the `region` value changes in the global config. |
| dsSocialLinksChange | DsSocialLinks | Emitted when the `socialLinks` value changes in the global config. |
### Methods
| Signature | Description |
| --- | --- |
| setFocus(elements: HTMLElement[]) => Promise | Sets focus on the given elements using the root's focus-visible handling. |
### Slots
| Name | Description |
| --- | --- |
| default | All content and child elements. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --ds-root-height | Viewport height in pixels, kept in sync on window resize to work around mobile browser viewport unit inconsistencies. |
| --ds-app-height | Deprecated alias of `--ds-root-height`. |
### Usage
## When to Use
- Wrap entire application for consistent layout and theming
- Set up global root-level configuration
- Apply brand colors and design system styles globally
- Manage top-level navigation structure
- Provide consistent spacing and grid structure
- Initialize application-wide state or context
## Global Configuration
`ds-root` sets the `brand`, `region`, `language`, `allowed-languages`, `fallback-language`, and `animated` values on the shared design system config, so every component nested inside it (`ds-close`, `ds-app-footer`, form controls, …) picks them up automatically.
\n \n'} />
- `language` falls back to `fallback-language` if it isn't part of `allowed-languages`.
- Each of these props has a matching `ds*Change` event (`dsBrandChange`, `dsRegionChange`, `dsLanguageChange`, `dsAllowedLanguagesChange`, `dsFallbackLanguageChange`, `dsAnimatedChange`) emitted whenever the value changes in the shared config — whether that change came from `ds-root`'s own props or from elsewhere in the app.
- Changing a prop at runtime (e.g. `document.querySelector('ds-root').language = 'it'`) updates the config immediately, no reload needed.
## Legacy alias
`ds-app` is a deprecated compatibility alias of `ds-root`. Existing markup keeps working; new code should use `ds-root`.
## When NOT to Use
- For individual page sections — use content component
- For component-level containers — not needed for single components
- For temporary overlays or modals — use modal component
- For reusable sub-sections — create smaller layout components
- For styling only — simpler solutions may exist
## Do's and Don'ts
### Single Root Element
Use root as the root wrapper. Only one per application.
### Variants
The default root shell — header, main content, and footer.
Set `brand`, `region`, `language`, `allowed-languages`, and `fallback-language` on `ds-root` to configure every design system component nested inside it. Here `language="it"` makes the `ds-close` button render its label in Italian ("Chiudi") instead of the default.
### Accessibility
## Guidelines
Use role="banner", role="main", and role="contentinfo" for navigation and content areas. Screen readers need structure.
),
},
{
type: 'do',
title: 'Skip Links',
content: (
Include skip navigation links to jump directly to main content. Helps keyboard users bypass repeated navigation.
),
},
{
type: 'do',
title: 'Focus Management',
content: (
Manage focus appropriately on page transitions and navigation. Announce page changes to screen readers.
),
},
{
type: 'do',
title: 'Keyboard Navigation',
content: (
Ensure all app navigation is keyboard accessible. Tab through headers, nav, content, and footer.
),
},
{
type: 'dont',
title: 'No Semantic Structure',
content: (
Don't use generic divs without landmarks. Screen readers need to understand app structure.
),
},
{
type: 'dont',
title: 'Trapped Focus',
content: (
Don't trap keyboard focus. Users should be able to navigate in and out of app regions.
),
},
]}
/>
## WCAG 2.2 AA Compliance
The root component supports patterns that meet WCAG 2.2 Level AA standards:
- **Semantic Landmarks (1.3.1)** — Uses role attributes for page regions
- **Navigable Structure (2.4.1)** — Skip links and landmarks for navigation
- **Keyboard Navigation (2.1.1)** — Tab navigates chrome and content
- **Focus Management (2.4.3)** — Focus visible and managed appropriately
- **Page Structure (2.4.6)** — Clear visual hierarchy and organization
---
## ds-stack
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-stack-stack--stack
Stack arranges child elements in a vertical or horizontal layout with customizable spacing and alignment options.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| align | "bottom center" \| "bottom end" \| "bottom start" \| "center" \| "end" \| "start" \| "top center" \| "top end" \| "top start" \| undefined | | Defines the text positioning like center, right or default to start. |
| direction | "column" \| "column-reverse" \| "row" \| "row-reverse" \| undefined | | Defines the direction of the child elements. Default is column. |
| fit-content | boolean | false | Defines the width of the stack to be exactly the width of the content. |
| p | "2xl" \| "2xs" \| "base" \| "lg" \| "md" \| "none" \| "sm" \| "xl" \| "xs" \| undefined | | Defines the padding of the stack element. |
| px | "2xl" \| "2xs" \| "base" \| "lg" \| "md" \| "none" \| "sm" \| "xl" \| "xs" \| undefined | | Defines the horizontal padding left and right of the stack element. |
| py | "2xl" \| "2xs" \| "base" \| "lg" \| "md" \| "none" \| "sm" \| "xl" \| "xs" \| undefined | | Defines the vertical padding top and bottom of the stack element. |
| space | "2xl" \| "2xs" \| "auto" \| "base" \| "lg" \| "md" \| "none" \| "sm" \| "xl" \| "xs" | 'base' | Defines the space between the child elements. |
| space-column | "2xl" \| "2xs" \| "auto" \| "base" \| "lg" \| "md" \| "none" \| "sm" \| "xl" \| "xs" \| undefined | | Defines the column space between the child elements. |
| space-row | "2xl" \| "2xs" \| "auto" \| "base" \| "lg" \| "md" \| "none" \| "sm" \| "xl" \| "xs" \| undefined | | Defines the row space between the child elements. |
| use-wrap | boolean | false | Defines if the child elements will wrap to the next line if there is not enough space left. |
### Slots
| Name | Description |
| --- | --- |
| default | The stack items (child elements). |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --stack-direction | Direction of the stack layout (row or column). |
| --stack-gap | Spacing between stack items. |
| --stack-align | Alignment of items within the stack. |
| --stack-justify | Justification of items along the main axis. |
| --stack-wrap | Whether items wrap to multiple lines. |
| --stack-p | Padding around the stack container. |
### Usage
## When to Use
- Create flexible layouts with consistent spacing between elements
- Build component compositions (cards, form sections, lists)
- Manage responsive layouts without writing custom CSS
- Arrange items vertically or horizontally with automatic spacing
- Align and distribute child elements with flexbox utilities
## When NOT to Use
- For simple single-element layouts — use native HTML without wrapper
- When performance is critical and minimal DOM nesting is required
- For table-like data — use proper `` elements with semantic HTML
- As a replacement for CSS Grid for complex 2D layouts
- For content that doesn't have a linear flow pattern
## Do's and Don'ts
### Spacing and Direction
Use the stack for layouts with consistent spacing. Choose direction (row/column) based on content flow.
\n Item 1
\n Item 2
\n'}
/>
>
),
description: 'Automated consistent spacing between items improves visual harmony',
},
{
type: 'incorrect',
title: 'Incorrect: Manual margin management',
contentIsLeftAligned: true,
content: (
<>
Item 1\nItem 2
'}
/>
>
),
description: 'Manual margins are error-prone and hard to maintain',
},
]}
/>
### Accessibility
## Guidelines
Use stack for layout purposes while maintaining semantic HTML within child elements. Stack itself is a layout utility and does not affect document semantics.
),
},
{
type: 'do',
title: 'Logical Reading Order',
content: (
Arrange items in stack in a logical reading order that matches the visual flow. Screen reader users should encounter content in the same order as visually presented.
),
},
{
type: 'do',
title: 'Responsive Direction',
content: (
When using row layouts, ensure content remains readable and usable on small screens. Consider changing direction to column on mobile devices.
),
},
{
type: 'do',
title: 'Visible Focus Indicators',
content: (
If stack contains interactive elements, ensure they have clear focus indicators. Layout should not obscure or hide focus outlines.
),
},
{
type: 'dont',
title: 'Visual Order Only',
content: (
Do not rely on CSS order property to meaningfully reorder content for screen readers. Document order in HTML should match the intended reading sequence.
),
},
{
type: 'dont',
title: 'Overcomplicated Nesting',
content: (
Avoid excessive stack nesting, which can make DOM navigation difficult for screen reader users and complex for assistive technology to traverse.
),
},
]}
/>
---
## ds-text
Docs: https://helvetia-design.vercel.app/?path=/docs/components-structure-text-text--text
Text renders paragraph and article content with flexible sizing, styling, and semantic emphasis options.
### Props
| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| align | "center" \| "justify" \| "left" \| "right" \| undefined | | If `true` the component gets a invalid style. |
| bold | boolean | false | If `true` the text is bold |
| color | "danger" \| "grey" \| "info" \| "placeholder" \| "primary" \| "success" \| "warning" \| undefined | | Defines the color of the text. |
| disabled | boolean | false | If `true` the element is not mutable, focusable, or even submitted with the form. The user can neither edit nor focus on the control, nor its form control descendants. |
| heading | boolean | false | If `true` the text has heading font family |
| inline | boolean | false | If `true` the text is shown as a display inline |
| invalid | boolean | false | If `true` the component gets a invalid style. |
| inverted | boolean | false | If `true` the color gets inverted for dark backgrounds |
| no-wrap | boolean | false | When true, the text will be truncated with a text overflow ellipsis instead of wrapping. Please note that text overflow can only occur in block or inline-block level elements, as these elements require a width to overflow. |
| shadow | boolean | false | If `true` adds a text shadow to improve readability on image background |
| size | "2xl" \| "3xl" \| "4xl" \| "5xl" \| "base" \| "block" \| "lead" \| "lg" \| "md" \| "sm" \| "small" \| "xl" \| "xs" \| undefined | | Defines the size of the paragraph |
| space | "all" \| "bottom" \| "none" \| "top" \| undefined | | Defines at which position the heading has spacing. |
| subtitle | boolean | false | If `true` the text has subtitle font family |
### Slots
| Name | Description |
| --- | --- |
| default | The text content. |
### Parts
| Name | Description |
| --- | --- |
| text | The text container element. |
### CSS Custom Properties
| Property | Description |
| --- | --- |
| --text-color | Text color of the paragraph. |
| --text-align | Text alignment of the paragraph. |
| --text-font-family | Font family of the text. |
| --text-font-weight | Font weight of the text. |
| --text-font-size | Font size of the text. |
| --text-line-height | Line height of the text. |
| --text-letter-spacing | Letter spacing of the text. |
| --text-decoration | Text decoration of the text. |
| --text-transform | Text transform of the text. |
| --text-shadow | Text shadow effect applied to the text. |
| --text-margin | Spacing applied to the text element. |
### Usage
## When to Use
- Display body text, paragraphs, and article content
- Create multi-line blocks of readable content
- Apply consistent typography styling across different text sizes and weights
- Render semantic `` or `` elements based on context
- Show text with theme variations (heading font, subtitle font)
## When NOT to Use
- For main page titles or section headers — use the Heading component instead
- As a replacement for semantic HTML `` or `` elements for emphasis
- For single words or short labels without context — use plain HTML for simplicity
- When maximum performance and minimal JS are critical — consider plain HTML with CSS classes
## Do's and Don'ts
### Text Sizing
Choose text sizes based on the content hierarchy and reading experience. Balance readability with visual weight.
Article Title
This is the body text for the article.
>
),
description: 'Proper size hierarchy guides reading flow',
},
{
type: 'incorrect',
title: 'Incorrect: All text same size',
content: (
<>
Article Title
This is the body text for the article.
>
),
description: 'Equal sizing makes content structure unclear',
},
]}
/>
### Color and Contrast
Ensure sufficient contrast between text and background for readability. Use inverted variant on dark backgrounds.
Dark text on light background provides good contrast
>
),
description: 'Meets WCAG 2.2 AA contrast requirements',
},
{
type: 'incorrect',
title: 'Incorrect: Low contrast',
content: (
<>
Light grey text on white background is hard to read
>
),
description: 'Fails accessibility contrast ratios',
},
]}
/>
### Variants
Demonstrates the bold text variant for emphasizing important information.
Demonstrates the disabled text variant for indicating non-interactive or unavailable content.
Demonstrates the nested text variant for indicating hierarchical or grouped content.
Different size variants to represent different levels of emphasis and hierarchy.
Different color variants to represent different semantic meanings and emphasis levels.
Text with different spacing variants to demonstrate various layout and design options.
Text with different font family variants to demonstrate various typographic styles.
Use `no-wrap` variant to prevent text from wrapping and ensure it stays on a single line.
### Accessibility
## Guidelines
Ensure text meets WCAG 2.2 AA contrast ratios (4.5:1 for normal text, 3:1 for large text). Use the inverted prop or shadow variant on dark backgrounds to maintain readability.
),
},
{
type: 'do',
title: 'Readable Font Sizes',
content: (
Use appropriate text sizes for the content context. Avoid extremely small text; minimum body text should be at least 14px for comfortable reading on screen.
),
},
{
type: 'do',
title: 'Clear Line Height and Spacing',
content: (
Provide sufficient line height (1.5 minimum for body text) and spacing to reduce cognitive load and improve readability for users with dyslexia or vision impairments.
),
},
{
type: 'do',
title: 'Use Semantic HTML',
content: (
The text component renders p, span elements based on context. Maintain proper semantic structure in your document for screen reader users.
),
},
{
type: 'dont',
title: 'Color Alone for Meaning',
content: (
Do not rely on color alone to convey information or emphasis. Combine color with text weight, size, or other visual cues so users with color blindness can perceive the distinction.
),
},
{
type: 'dont',
title: 'All Text Caps Without Pause',
content: (
Avoid displaying large blocks of text in all capitals. Text rendered in all caps is harder to read and screen readers may pronounce it as an acronym.
),
},
]}
/>
---