Skip to main content

Migration

This page contains migration guides for specific major changes.

v1.0.0-beta.3 → v1.0.0-rc.0#

The first release candidate contains a couple breaking changes, primarily to design token names.

Core#

@wwnds/core contains a handful of breaking changes:

React#

@wwnds/react contains one breaking change to TextField.

  • TextField can no longer be used as an uncontrolled component.
    • If you were using it as an uncontrolled component, you'll need to switch to the new TextFieldUncontrolled.
    • If you were using it as a controlled component, you don't need to change anything.

Design Tokens#

All color role tokens have had the -color suffix added to their names. This should help clarify that the token is a color token.

Note that all of the following token names are prefixed with --nds- in the corresponding CSS custom properties in @wwnds/core.

New NamePrevious NameNotes
background-colorbody-bg
text-colorbody-textRelated new token: text-color-inverse
subdued-colorsubdued
focus-ringfocus-colorThe focus-ring token now refers to a box shadow
primary-color-xprimary-xWhere x is a grade or shade*
base-color-xbase-xWhere x is a grade or shade*
disabled-color-xdisabled-xWhere x is a grade or shade*
error-color-xerror-xWhere x is a grade or shade*
success-color-xsuccess-xWhere x is a grade or shade*
warning-color-xwarning-xWhere x is a grade or shade*
focus-halo-inner-colorfocus-ring-inner
focus-halo-outer-colorfocus-ringfocus-ring still exists but is now a box shadow
focus-halofocus-shadow
focus-ringfocus-shadow-collapse

* A grade is a number like 20 and a shade is an adjective like lighter.

v0.9.x → v1.0.0-beta.0#

The first beta release contained many breaking changes, most notably a complete rewrite of @wwnds/core.

Core#

@wwnds/core now makes full use of Sass modules and CSS custom properties. If you were previously using @import statements to use the design system's Sass, it is highly recommended that you update to @forward and @use.

Entry points#

There are two main entry points:

  • @wwnds/core (index.scss) - pure abstracts for all modules and components. Using this directly will give you the most flexibility but will require the most work.
  • @wwnds/core/full (full.scss) - a fully-functional stylesheet with a reset and components declared. Using this directly will require little to no work but won't be as flexible as the default entry point.
@use '@wwnds/core' as nds with (
$font-family-base: 'Proxima Nova',
);
.my-declaration {
font-family: var(--nds-font-family-base); // 'Proxima Nova'
// font-family: nds.$font-family-base; // alternatively use the Sass variable
// (these will compile to the same thing)
}

View the @wwnds/core readme for more about this.

React#

@wwnds/react changed some elements of the TextField component.

  • The label prop has been removed in favor of children.
  • The following props have been renamed:
    • helpdescription
    • helpClassdescriptionClass
    • errorClasserrorsClass
v0.9.x
<TextField
label="My text field"
help="A longer description of the text field."
helpClass="help"
errorClass="error"
/>
v1.0.0-beta.x
<TextField
description="A longer description of the text field."
descriptionClass="desc"
errorsClass="errors"
>
My text field
</TextField>

The resulting HTML has also changed to make better use of field composition. Most notably, the text field is now a modified field component instead of a root "block" (in BEM conventions). In other words, the "block" class name is now field instead of textfield. This was done to reuse field components across form fields.

v1.0.0-beta.x
<div class="nds-field nds-field--text nds-field--invalid" id="nds-field-1">
<div class="nds-field__info">
<label
class="nds-field__label"
for="nds-field-1-input"
id="nds-field-1-label"
>
Default Text Field
</label>
<div class="nds-field__desc" id="nds-field-1-desc">
The default Text Field has a type of "text"
</div>
</div>
<div class="nds-field__group nds-field__group--text">
<input
id="nds-field-1-input"
class="nds-field__input nds-field__input--text"
aria-describedby="nds-field-1-desc"
aria-invalid="true"
type="text"
value=""
required=""
aria-errormessage="nds-field-1-err"
/>
</div>
<div class="nds-field__feedback">
<ul
class="nds-field__errors"
id="nds-field-1-err"
aria-label="Errors"
aria-live="assertive"
aria-atomic="true"
>
<li>This nds-field is required.</li>
</ul>
</div>
</div>
Last updated on by Evan Yamanishi