You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: MIGRATION.md
+200-5Lines changed: 200 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,12 +2,207 @@
2
2
3
3
## 🤖 Automated migration
4
4
5
-
Some of the changes in this guide can be automated using [`@sumup/eslint-plugin-circuit-ui`](https://circuit.sumup.com/?path=/docs/packages-eslint-plugin-circuit-ui--docs). Changes that can be automated are marked with a robot emoji (🤖) and the name of the ESLint rule (e.g. _no-deprecated-props_)
5
+
Some of the changes in this guide can be automated using the [ESLint](https://circuit.sumup.com/?path=/docs/packages-eslint-plugin-circuit-ui--docs) and [Stylelint](https://circuit.sumup.com/?path=/docs/packages-stylelint-plugin-circuit-ui--docs) plugins. Changes that can be automated are marked with a robot emoji (🤖) and the name of the rule (e.g. _no-deprecated-props_)
6
6
7
7
We encourage you to enable and apply the rules incrementally and review the changes before continuing. The rules don't cover all edge cases, so further manual changes might be necessary. For example, the ESLint rules only analyze one file at a time, so if a Circuit UI component is wrapped in a styled component in one file and used in another, ESLint won't be able to update its props.
8
8
9
9
Prior to v5, codemods were implemented using [jscodeshift](#-codemods-jscodeshift).
10
10
11
+
## From v8.x to v9
12
+
13
+
Circuit UI v9 introduces a [new typeface](#new-typeface), more flexible [typography APIs](#typography-apis), and [stable input components](#stable-components) for colors, dates, and phone numbers. For a complete list of changes, refer to the [changelog](https://github.com/sumup-oss/circuit-ui/blob/main/packages/circuit-ui/CHANGELOG.md).
14
+
15
+
### Prerequisites
16
+
17
+
Circuit UI now requires at minimum Node.js v20. Note that [Node 18](https://nodejs.org/en/about/previous-releases) reached its end-of-life in October 2024.
18
+
19
+
We strongly recommend upgrading to [Foundry v8.3+](https://github.com/sumup-oss/foundry/blob/main/CHANGELOG.md#830) which adds support for the Circuit UI ESLint plugin's [new package scope](#renamed-package-scope) and prevents dependency conflicts in the shared [`@typescript-eslint/*`](https://github.com/typescript-eslint/typescript-eslint) dependencies. If you're unable to upgrade, manually add the Circuit UI ESLint plugin to your ESLint config and enable the relevant rules.
20
+
21
+
### Renamed package scope
22
+
23
+
The packages have moved from the `@sumup` to the `@sumup-oss` scope to avoid conflicts with private packages. To get started, remove the old design system packages, then install the new ones:
Note that [`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill) is a new required peer dependency and that the [`@sumup-oss/intl`](https://www.npmjs.com/package/@sumup-oss/intl) peer dependency has been upgraded to v3. If your app also depends on `@sumup-oss/intl` (previously called `@sumup/intl`), you need to upgrade it as well. Refer to its [changelog](https://github.com/sumup-oss/intl-js/blob/main/CHANGELOG.md) for migration instructions.
31
+
32
+
Follow the same process to upgrade any linter plugins your app is using:
Update any static and dynamic imports to the new package scope (🤖 `renamed-package-scope`). The ESLint rule might not catch all occurrences of the old package names, so manually search for and fix any left-overs after applying the ESLint rule. For example:
44
+
45
+
```diff
46
+
-import { Button, type ButtonProps } from '@sumup/circuit-ui';
47
+
+import { Button, type ButtonProps } from '@sumup-oss/circuit-ui';
The default typeface has changed from [Aktiv Grotesk](https://www.daltonmaag.com/font-library/aktiv-grotesk.html) to [Inter](https://rsms.me/inter/), a variable font. Variable fonts combine a continuous range of weights and other "axes" into a single file. This speeds up page load times and enables more creative freedom. Inter is a close match to Aktiv Grotesk, so the change should be seamless.
64
+
65
+
Circuit UI no longer loads the fonts by default. Instead, import the stylesheet that contains the font face declarations globally in your application, such as in a global layout file:
66
+
67
+
```ts
68
+
import'@sumup-oss/design-tokens/fonts.css';
69
+
```
70
+
71
+
To speed up the loading of the fonts, add preload links to the global `<head>` element of your application. Choose which subsets to preload based on the languages your app supports. The available subsets are `latin`, `latin-ext`, `cyrillic`, `cyrillic-ext`, `greek`, `greek-ext`, and `vietnamese`.
The typography components have been redesigned to improve visual hierarchy, ensure consistency across platforms and provide more flexible APIs for developers. The changes are fully backward compatible and can be adopted gradually.
86
+
87
+
#### Consistent names
88
+
89
+
The Title component has been renamed to Display for consistency with other platforms. The SubHeadline component has been deprecated in favor of the Headline component in size `s`. The BodyLarge component has been deprecated in favor of the Body component in size `l` (🤖 `no-deprecated-components`).
90
+
91
+
#### Flexible props
92
+
93
+
The Body component's `variant` prop has been split into individual `color`, `weight` and `decoration` props. Use the `color` prop instead of the `alert`, `confirm` and `subtle` variants, use the `weight` prop instead of the `highlight` variant, and use custom CSS to replicate the `quote` variant (🤖 `no-renamed-props`). The new `decoration` prop makes it easier to apply `italic` and `strikethrough` styles.
94
+
95
+
The sizes of the Display (formerly Title), Headline, and Body components have been consolidated and renamed to enforce greater visual hierarchy. Here's how the old size names map to the new ones (🤖 `no-renamed-props`):
96
+
97
+
**Display**
98
+
99
+
| Old | New |
100
+
| ----- | --- |
101
+
| one | l |
102
+
| two | m |
103
+
| three | m |
104
+
| four | s |
105
+
106
+
**Headline**
107
+
108
+
| Old | New |
109
+
| ----- | --- |
110
+
| one | l |
111
+
| two | m |
112
+
| three | s |
113
+
| four | s |
114
+
115
+
**Body**
116
+
117
+
| Old | New |
118
+
| --- | --- |
119
+
| one | m |
120
+
| two | s |
121
+
122
+
The typography design tokens have been updated accordingly (🤖 `no-deprecated-custom-properties` (ESLint & Stylelint)):
The new Compact component should be used to label information in space-constraint contexts.
154
+
155
+
The new Numeral component should be used to give emphasis to numerical content such as currency values.
156
+
157
+
### Stable components
158
+
159
+
All experimental components are now stable.
160
+
161
+
- The Calendar and DateInput components have been rebuilt from scratch for better performance and accessibility. They replace the legacy RangePicker, RangePickerController, SingleDayPicker, CalendarTag, and CalendarTagTwoStep components, which have been removed. The DateInput component now requires additional localized label props.
162
+
- The ColorInput and PhoneNumberInput components enable users to enter hex colors and phone numbers respectively.
163
+
- The Tooltip and Toggletip components have been rebuilt from scratch for improved accessibility. They replace the legacy Tooltip component.
164
+
165
+
Update the related imports (🤖 `component-lifecycle-imports`). For example:
166
+
167
+
```diff
168
+
- import { Calendar, type CalendarProps, type PlainDateRange } from '@sumup-oss/circuit-ui/experimental';
169
+
+ import { Calendar, type CalendarProps, type PlainDateRange } from '@sumup-oss/circuit-ui';
170
+
```
171
+
172
+
### Other changes
173
+
174
+
- Changed the `PlainDateRange` type from an array to an object with start and end properties. This affects the Calendar component's `selection` prop. Use the new `updatePlainDateRange` helper function to update a date range when a user selects a date:
175
+
176
+
```tsx
177
+
import { useState } from'react';
178
+
import { Calendar, updatePlainDateRange } from'@sumup-oss/circuit-ui';
179
+
180
+
function Component() {
181
+
const [selection, setSelection] =useState({});
182
+
return (
183
+
<Calendar
184
+
onSelect={setSelection((prevSelection) =>
185
+
updatePlainDateRange(prevSelection, date)
186
+
)}
187
+
/>
188
+
);
189
+
}
190
+
```
191
+
192
+
- Deprecated the `InputElement` interface and narrowed the Input component's element type to `HTMLInputElement` and the TextArea component's element type to `HTMLTextAreaElement`. This affects `ref`s and event handlers.
193
+
194
+
```diff
195
+
-import { InputElement } from '@sumup-oss/circuit-ui';
196
+
197
+
-ChangeHandler<InputElement>
198
+
+ChangeHandler<HTMLInputElement>
199
+
200
+
-useRef<InputElement>()
201
+
+useRef<HTMLInputElement>()
202
+
```
203
+
204
+
- Removed the Table component's deprecated `initialSortedRow` prop. Use the `initialSortedColumn` prop instead (🤖 `no-renamed-props`).
205
+
11
206
## From v7.x to v8
12
207
13
208
Circuit UI v8 introduces a redesigned Button component and switches the brand color from blue to black.
@@ -71,7 +266,7 @@ expect.extend({
71
266
this.utils.matcherHint(
72
267
`${this.isNot?'.not':''}.toBeDisabled`,
73
268
'element',
74
-
'',
269
+
''
75
270
),
76
271
'',
77
272
`Received element ${is} disabled:`,
@@ -92,7 +287,7 @@ expect.extend({
92
287
this.utils.matcherHint(
93
288
`${this.isNot?'.not':''}.toBeEnabled`,
94
289
'element',
95
-
'',
290
+
''
96
291
),
97
292
'',
98
293
`Received element ${is} enabled:`,
@@ -724,7 +919,7 @@ import styled from 'util/styled';
724
919
const RedCard = styled(Card)(
725
920
({ theme }) => css`
726
921
background-color: red;
727
-
`,
922
+
`
728
923
);
729
924
```
730
925
@@ -750,7 +945,7 @@ import styled from '@emotion/styled';
Copy file name to clipboardExpand all lines: packages/design-tokens/README.md
+1-29Lines changed: 1 addition & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,8 +40,6 @@ Refer to the [theme documentation](https://circuit.sumup.com/?path=/docs/feature
40
40
41
41
### Fonts
42
42
43
-
#### Default
44
-
45
43
Import the stylesheet that contains the font face declarations globally in your application, such as in a global layout file:
46
44
47
45
```ts
@@ -60,33 +58,7 @@ To speed up the loading of the fonts, add preload links to the global `<head>` e
60
58
/>
61
59
```
62
60
63
-
#### Next.js
64
-
65
-
If you're using Next.js 13+, use the built-in [font optimization](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) feature with this recommended configuration instead:
66
-
67
-
```tsx
68
-
// app/layout.tsx
69
-
import { Inter } from'next/font/google';
70
-
71
-
const inter =Inter({
72
-
// Choose which subsets to preload based on the languages your app supports
73
-
subsets: ['latin'],
74
-
// Note that Next.js <14.2.6 contains outdated Google Fonts data which prevents
75
-
// usage of the `ital` axis (see https://github.com/vercel/next.js/issues/68395)
76
-
axes: ['ital'],
77
-
variable: '--cui-font-stack-default',
78
-
display: 'swap',
79
-
preload: true,
80
-
});
81
-
82
-
exportdefaultfunction RootLayout({ children }) {
83
-
return (
84
-
<htmllang="en">
85
-
<bodyclassName={inter.variable}>{children}</body>
86
-
</html>
87
-
);
88
-
}
89
-
```
61
+
Do not use Next.js' built-in font optimization as it doesn't support Inter's italic axis.
0 commit comments