@engie-group/fluid-design-system
Version:
The Fluid Design System is ENGIE’s open-source library to create, build and deliver ENGIE digital services in a more efficient way.
222 lines (163 loc) • 7.5 kB
Markdown
# Fluid Vanilla Library v5.18.2 → v6.0.0 Migration Guide
This migration guide helps you upgrade from v5.18.2 to v6.0.0, covering all breaking changes, new features, and necessary steps for a smooth transition. Please follow each step carefully, testing your application after each migration phase.
---
## 1. **Global and Core**
### 1.1. **Class Name Changes for Icons**
- **What changed:** All icons now use `.nj-icon-material` instead of `.material-icons`.
- **Action:** Replace all occurrences of `.material-icons` with `.nj-icon-material` across your HTML and CSS files.
```html
<!-- Before -->
<span aria-hidden="true" class="material-icons nj-icon-material">home</span>
<!-- After -->
<span aria-hidden="true" class="nj-icon-material">home</span>
```
---
### 1.2. **Fonts Embedded in CSS**
- **What changed:** Component fonts (Lato, Material Icons, Roboto Mono) are now embedded in CSS and no longer require external imports.
- **Action:** Remove any external font imports for these from your project.
---
## 2. **Component-by-Component Migration Steps**
### 2.1. **Avatar**
- **Background:** Picture avatar background is removed.
- **Size Modifiers:**
- `.nj-avatar--md`: now `40px` (was 48px)
- `.nj-avatar--lg`: now `48px` (was 64px)
- `.nj-avatar--xl`: now `56px` (was 96px)
- New: `.nj-avatar--2xl` → `64px`; `.nj-avatar--3xl` → `96px`
- **Action:**
- Remove background customizations for avatars displaying images.
- Update size modifiers and verify layout.
### 2.2. **Badge**
- **Icon Sizing:** Badge no longer controls custom icon size; use `--nj-material-icon-size` in CSS.
- **Contrast Improvement:** `warning` + `minimal` badge now uses `--nj-semantic-color-icon-status-warning-contrast-default` for better visibility.
- **Vertical Spacing Adjusted:**
- `md`: 4px (was 6px)
- `lg`: 6px (was 9px)
- **Fixes:** Border radius for better pill shape.
- **Action:**
- Adjust spacing/CSS overrides accordingly.
- Define icon size on custom icon via CSS:
```css
width: var(--nj-material-icon-size); /* example */
height: var(--nj-material-icon-size); /* example */
```
### 2.3. **List & List Item**
- **List Item Structure:**
- Now a part of `.nj-list` as element, not as standalone block.
- All `.nj-list-item` and related class names are replaced with corresponding `.nj-list__item` structure.
- **Element Changes:**
- `.nj-list-item__icon` removed, use `.nj-list-item__leading`.
- Added support for secondary content: `.nj-list__item-secondary` inside `.nj-list__item-content`.
- **List Tokens:**
- Font size token updated: `--nj-semantic-font-size-text-md` replaces `--nj-semantic-font-size-text-sm`.
- **Action:**
- Refactor list templates to match new HTML and class structure.
- Update tokens if customized.
### 2.4. **Modal**
- **Change:**
- `.nj-modal` class is deprecated.
- Use `<nj-modal>` Web Component, or rename `.nj-modal*` and sub-classes to `.nj-modal-deprecated*` to continue using legacy styles.
- **Action:**
- Update template and class names accordingly.
- Recommended: migrate to new web component for future compatibility.
### 2.5. **Tag**
- **Actionable Elements:**
- `.nj-tag__link` and `.nj-tag__button` replaced with `.nj-tag__action`.
- **Action:**
- Replace relevant classes for buttons/links inside tags.
### 2.6. **Sidebar & SidePanelLayout**
- **Sidebar:**
- Old `.nj-sidebar*` classes deprecated; use `.nj-sidebar-deprecated*` to avoid visual breaks, but migrate to updated sidebar soon.
- **SidePanelLayout:**
- `.nj-sidepanel-layout` class removed. Use standard CSS flex layouts.
### 2.7. **Menu Group**
- **Structure Change:**
- All menu groups must have a container with `.nj-menu-group` and headers must use `.nj-menu-group__header`.
- **Action:**
- Refactor HTML structure for menu groups.
### 2.8. **Spinner**
- **Change:**
- Use `.nj-spinner--2xs` (was `xxs`).
- **Action:**
- Update all usages:
```html
<!-- Before -->
<div class="nj-spinner nj-spinner--xxs"></div>
<!-- After -->
<div class="nj-spinner nj-spinner--2xs"></div>
```
### 2.9. **Heading & Display Component**
- **Heading:**
- Font sizes for `lg` and `xl` reduced.
- `2xl` removed—use `Display` component instead.
- New `ai` gradient variant added.
- **Action:**
- For previous `2xl`, use `.nj-display--xl`.
- For previous `xl`, use `.nj-display--md`.
- For previous `lg`, use `.nj-heading--xl`.
- **Display:**
- Add `Display` component where big headings are needed.
### 2.10. **Footer & Header**
- **Footer:**
- Deprecated, update accordingly.
- **Header:**
- Rename `.nj-header*` classes to `.nj-header-deprecated*`.
### 2.11. **Icon Button, Skeleton, Inline Message, etc.**
- **Icon-Button:**
- Default size is now `sm` (was `xs`).
- **Skeleton:**
- New circle scales: `2xl`, `3xl`
- Previous defaults updated (see. Avatar changes).
- **Inline Message:**
- Main content: change `<p>` to `<div>` for `.nj-inline-message__body`.
- Remove inline-message title; use external heading/text components as needed.
- Add action slot as needed.
---
## 3. **CSS Token Changes**
- **Use New Responsive Tokens:**
- Replace legacy desktop/mobile text/heading/line-height tokens with:
- `--nj-semantic-font-size-text-<size>`
- `--nj-semantic-font-size-heading-<size>`
- `--nj-semantic-line-height-text-<size>`
- `--nj-semantic-line-height-heading-<size>`
---
## 4. **Deprecated & Removed Components**
- Navbar is now deprecated, please use Header Web Component
- Deprecated list: Replace by new version of the same component. The deprecated have now `-deprecated` suffix.
- Footer
- Sidebar
- Header
- List
- Progress
- Removed list
- Alert
- Bullet
- Dropdown
- Fluid Icon
- Forms (`.nj-form-group`)
- Switch
---
## 5. **Recommended Migration Steps**
1. **Update all dependencies**, especially `@engie-group/fluid-design-tokens`.
2. **Refactor icon class names** everywhere.
3. **Refactor modal, sidebar, tag, list, avatar** components as described.
4. **Update all deprecated components** by renaming with `-deprecated` suffix to preserve appearance during migration.
5. **Adjust for all token changes** in custom and extended stylesheets.
6. **Remove any external font imports** that are now embedded.
7. **Test visually and functionally at each stage** - most breaking changes are CSS - and template-level.
8. **Consult Fluid’s documentation** for new component APIs when migrating behavior.
---
## 6. **New Features to Leverage**
- Display component for large headings.
- New Badge, Button, Icon, Spinner, Status-indicator `ai` variant.
- Responsive tokens for better scaling.
---
## 7. **Testing & QA**
- Regression-test visually across all major components (Avatar, Badge, Modal, Tag, List, Sidebar, Spinner, Heading, etc.).
- Test interaction for Segmented Control, Menu, Sidebar.
- Review Icon usage everywhere (both static HTML and dynamically rendered templates).
---
## 8. **For Further Help**
- Some component refactors recommend checking the [documentation](https://fluid.design.digital.engie.com/fluid-design-system/storybook/vanilla/index.html?path=/docs/docs-getting-started--documentation) for full usage examples.
---
**If you have custom Fluid-based themes or re-exports in your codebase, review all relevant overrides for token/class/HTML changes above. If you need clarification on any migration aspect, let us know!**