Skip to content

Commit ec7da1f

Browse files
Copilotmfranzkenmerget
authored
Add comprehensive DB-UI to DB-UX-DSv3 component migration guide (#4867)
* Initial plan * Add comprehensive DB-UI to DB-UX-DSv3 component migration guide Co-authored-by: mfranzke <787658+mfranzke@users.noreply.github.com> * chore: update db-ui-to-db-ux-dsv3.md --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mfranzke <787658+mfranzke@users.noreply.github.com> Co-authored-by: Nicolas Merget <nicolas.merget@deutschebahn.com> Co-authored-by: Nicolas Merget <104347736+nmerget@users.noreply.github.com>
1 parent 6b8bac9 commit ec7da1f

File tree

3 files changed

+169
-0
lines changed

3 files changed

+169
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,8 @@ As [DB UX Design System](https://marketingportal.extranet.deutschebahn.com/marke
104104
We're providing a detailed migration for each component next to the documentation of each component, like e.g.
105105
<https://design-system.deutschebahn.com/core-web/review/main/components/action/button/migration>
106106

107+
For a comprehensive overview of all DB-UI components and their migration status, including components that don't have direct equivalents in DB-UX Design System v3, see our [DB-UI to DB-UX Design System v3 Component Migration Guide](https://github.com/db-ux-design-system/core-web/blob/main/docs/migration/db-ui-to-db-ux-dsv3.md).
108+
107109
### In between DB UX Design System Core versions
108110

109111
Check our migration docs for breaking changes:

‎docs/migration/db-ui-to-db-ux-dsv3.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# DB-UI to DB-UX Design System v3 Component Migration Guide
2+
3+
> **Note**
4+
> This document provides migration guidance for DB-UI components that don't have direct equivalents in DB-UX Design System v3. For package name changes and general migration information, see [v0.7.x-to-v1.0.0.md](./v0.7.x-to-v1.0.0.md).
5+
6+
## Overview
7+
8+
DB-UX Design System v3 represents a complete rethinking of the component architecture with a focus on atomic design principles, accessibility, and modern web standards. Some DB-UI components have been redesigned, consolidated, or are planned for future releases.
9+
10+
## Components without Direct Equivalents
11+
12+
| Component | Status | Recommendation | Description |
13+
| --------------------------- | :----: | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14+
| `rea-main` | ❌ | Use `db-page` with custom layout | The `db-page` component provides basic page structure. It already includes `<main>` |
15+
| `rea-grid` | ❌ | Use CSS Grid or `db-stack` component | Replace with modern CSS Grid for complex layouts, or use `db-stack` for simple spacing. See [CSS Grid examples](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout) |
16+
| `rea-footer` | 🔄 | Under research - build custom for now ,Planned for Q4/2025 | Footer component is being researched. Use semantic `<footer>` element with `db-link` components and custom styling. [Research document](../research/footer.md) |
17+
| `elm-headline` | 🔁 | Use heading elements with `db-infotext`, Planned for Q4/2025 | Replace with semantic heading tags (`<h1>`, `<h2>`, etc.) styled with CSS. For subtitle functionality, combine with `db-infotext` |
18+
| `elm-headline` (with pulse) | ❌ | Use heading + CSS animation, Planned for Q4/2025 | Implement pulse animation using CSS animations or transitions on heading elements. Pulse animations should be used sparingly for accessibility |
19+
| `elm-loadingindicator` | 🔄 | Planned for Q4/2025 | Loading indicator component is planned. Use CSS spinners or skeleton screens temporarily. Consider accessibility with `aria-live` regions |
20+
| `elm-progress` | 🔄 | Planned for Q4/2025 | Progress component in development. Use HTML5 `<progress>` element with custom styling or build custom solution |
21+
| `elm-chip` | 🔁 | Use `db-tag` with interactive elements | Replace with `db-tag` containing `db-button`, `db-checkbox`, or `db-radio` for interactive functionality. See [tag migration guide](../../packages/components/src/components/tag/docs/Migration.md) |
22+
| `cmp-breadcrumb` | 🔄 | Planned for Q4/2025 | Breadcrumb component planned for future release. Use `db-link` components with `aria-label="Breadcrumb"` navigation wrapper |
23+
| `cmp-pagination` | 🔄 | Planned for Q4/2025 | Pagination component in development. Build custom solution with `db-button` components and proper ARIA labels |
24+
| `cmp-table` | 🔄 | Under active research | Table component being researched with comprehensive roadmap. Use semantic HTML tables with custom styling. [Research document](../research/table.md) |
25+
| `cmp-sidenavi` | 🔁 | Use `db-navigation` in `db-drawer` | Combine `db-navigation` component within `db-drawer` for side navigation functionality. Configure drawer with appropriate width and positioning |
26+
| `cmp-dialog` | 🔁 | Use `db-drawer` or custom modal, Planned for Q4/2025 | Use `db-drawer` for side panels, or build custom modal dialog with proper focus management and ARIA attributes |
27+
28+
## Legend
29+
30+
| Symbol | Meaning |
31+
| :----: | --------------------------------------------------------------------- |
32+
| 🔁 | **Available replacement** - Use suggested alternative component(s) |
33+
| 🔄 | **Planned for future** - Component in roadmap, use temporary solution |
34+
| ❌ | **Not planned** - Use alternative approach or build custom solution |
35+
| 🆕 | **New in DB-UX-DSv3** - Enhanced or new functionality available |
36+
37+
## Migration Strategies
38+
39+
### 1. Layout Components Migration
40+
41+
#### From `rea-main` to `db-page` + Custom Layout
42+
43+
```html
44+
<!-- DB-UI -->
45+
<div class="rea-main">
46+
<main>Content</main>
47+
</div>
48+
49+
<!-- DB-UX-DSv3 -->
50+
<db-page> Content </db-page>
51+
```
52+
53+
#### From `rea-grid` to CSS Grid
54+
55+
```css
56+
/* DB-UI grid replacement */
57+
.custom-grid {
58+
display: grid;
59+
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
60+
gap: var(--db-spacing-fixed-md);
61+
}
62+
```
63+
64+
### 2. Interactive Elements Migration
65+
66+
#### From `elm-chip` to `db-tag`
67+
68+
```html
69+
<!-- DB-UI -->
70+
<div class="elm-chip" data-variant="primary">Chip Text</div>
71+
72+
<!-- DB-UX-DSv3 -->
73+
<db-tag>
74+
<db-button variant="ghost">Chip Text</db-button>
75+
</db-tag>
76+
```
77+
78+
#### From `elm-headline` to Semantic Headings
79+
80+
```html
81+
<!-- DB-UI -->
82+
<div class="elm-headline" data-size="h1">Main Title</div>
83+
84+
<!-- DB-UX-DSv3 -->
85+
<h1 class="custom-headline">Main Title</h1>
86+
<!-- Optional subtitle -->
87+
<db-infotext>Subtitle text</db-infotext>
88+
```
89+
90+
### 3. Navigation Migration
91+
92+
#### From `cmp-sidenavi` to `db-navigation` + `db-drawer`
93+
94+
```html
95+
<!-- DB-UX-DSv3 -->
96+
<db-drawer>
97+
<db-navigation>
98+
<db-navigation-item>
99+
<db-link href="/page1">Navigation Item 1</db-link>
100+
</db-navigation-item>
101+
<db-navigation-item>
102+
<db-link href="/page2">Navigation Item 2</db-link>
103+
</db-navigation-item>
104+
</db-navigation>
105+
</db-drawer>
106+
```
107+
108+
## Accessibility Considerations
109+
110+
When building custom solutions for missing components:
111+
112+
1. **Use semantic HTML** - Always start with appropriate HTML elements
113+
2. **ARIA attributes** - Add proper ARIA labels, roles, and states
114+
3. **Keyboard navigation** - Ensure all interactive elements are keyboard accessible
115+
4. **Focus management** - Handle focus properly in dynamic content
116+
5. **Screen reader support** - Test with screen readers and provide meaningful announcements
117+
118+
## Temporary Solutions & Best Practices
119+
120+
### Loading States
121+
122+
```html
123+
<!-- Temporary loading indicator -->
124+
<div class="custom-loading" aria-live="polite" aria-label="Loading content">
125+
<div class="spinner"></div>
126+
<span class="visually-hidden">Loading...</span>
127+
</div>
128+
```
129+
130+
### Progress Indicators
131+
132+
```html
133+
<!-- HTML5 progress element -->
134+
<progress value="70" max="100" aria-label="Upload progress: 70%">70%</progress>
135+
```
136+
137+
### Breadcrumb Navigation
138+
139+
```html
140+
<!-- Semantic breadcrumb structure -->
141+
<nav aria-label="Breadcrumb">
142+
<ol class="breadcrumb-list">
143+
<li><db-link href="/">Home</db-link></li>
144+
<li><db-link href="/category">Category</db-link></li>
145+
<li aria-current="page">Current Page</li>
146+
</ol>
147+
</nav>
148+
```
149+
150+
## Getting Help
151+
152+
- **Documentation**: [Component documentation](https://www.npmjs.com/package/@db-ux/core-components)
153+
- **Migration CLI**: Use `npx @db-ux/core-migration --type=v007_v100 --src=./src` for automated migration
154+
- **Research Updates**: Check [research documents](../research/) for component development status
155+
- **Community**: Join discussions about missing components in GitHub issues
156+
157+
## Future Roadmap
158+
159+
Check the [project board](https://github.com/orgs/db-ux-design-system/projects/4/views/1) for current status and release planning.
160+
161+
---
162+
163+
_This migration guide is maintained by the DB-UX Design System team. For specific component requests or migration assistance, please open an issue on GitHub._

‎docs/migration/v0.7.x-to-v1.0.0.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,7 @@ npx @db-ux/core-migration --type=v007_v100 --src=./src
6262
```
6363

6464
Please check the changes made in your codebase afterwards, as this is mainly a simple search & replace and there might be unexpected changes of similar wordings to our properties for any other methods, or further code occurrences that don't even refer to properties.
65+
66+
## Complete DB-UI Component Migration Guide
67+
68+
For a comprehensive overview of all DB-UI components and their migration status in DB-UX Design System v3, including components that don't have direct equivalents, see the [DB-UI to DB-UX Design System v3 Component Migration Guide](./db-ui-to-db-ux-dsv3.md).

0 commit comments

Comments
 (0)