Migration Checklist
Track your migration step by step. Your progress is saved automatically in your browser's local storage and stays there until you reset it. This checklist follows the same structure as the migration guide. Open the guide in another tab if you need context for any item.
Prefer something you can drop into your repo? Download the markdown version.
1. Install Web Awesome
@shoelace-style/shoelace from
package.json@awesome.me/webawesome to
package.json@awesome.me/webawesome/dist/styles/webawesome.css@awesome.me/webawesome/dist/webawesome.loader.jsearly.webawesome.com/webawesome@3/...setBasePath import to
@awesome.me/webawesome/dist/webawesome.jswa-theme-shoelace for
soft landing, or default / awesome2. Global Find-and-Replace
Run these in order. Commit between passes.
@shoelace-style/shoelace with
@awesome.me/webawesome in imports<sl- with <wa- in
templates and HTML</sl- with </wa- in
templates and HTML--sl- with --wa- in CSS files,
inline styles, CSS-in-JSsl-theme- with wa-theme-
class names'sl- with 'wa- in event
listener strings"sl- with "wa- in event
listener stringsSl with Wa in TypeScript
event class imports (e.g. SlChangeEvent → WaChangeEvent)variant="primary" with
variant="brand" on all componentsclass="sl-theme-light" with
class="wa-light"class="sl-theme-dark" with
class="wa-dark"slot="prefix" with
slot="start"slot="suffix" with
slot="end"help-text= with hint= on
form controlsslot="help-text" with
slot="hint" on form controlsFinal Sweep: Confirm Zero Matches
grep -r 'sl-' src/ matches nothing
meaningfulgrep -r '\-\-sl\-' src/ matches nothinggrep -r '@shoelace-style/shoelace' . matches
nothinggrep -rE "['\"]sl-[a-z]+['\"]" src/ matches
nothing (catches event listener strings)3. Components
Renamed Elements
<sl-alert> → <wa-callout>
(inline use; toast UX is now Pro <wa-toast>)<sl-image-comparer> →
<wa-comparison><sl-range> →
<wa-slider><sl-menu> + <sl-menu-item> →
<wa-dropdown> + <wa-dropdown-item><sl-menu-label> →
<wa-divider> + heading, or restructureRemoved Elements
<sl-icon-button> →
<wa-button> with single <wa-icon> child<sl-radio-button> →
<wa-button-group> of <wa-radio> controls<sl-visually-hidden> →
class="wa-visually-hidden" utility on any elementButtons
outline boolean with
appearance="outlined"circle boolean (auto-detected when button has a
single <wa-icon> child)variant="text" with
appearance="plain"caret with with-caretslot="prefix"/"suffix" to
slot="start"/"end"sl-blur/sl-focus listeners
to native blur/focussl-invalid to
wa-invalidForm Controls
help-text attribute to
hinthelp-text slot to
hintprefix/suffix slots to
start/endclearable to with-clear (input,
select)filled boolean with
appearance="filled"sl-change/sl-input/sl-blur/sl-focus to native events (no
prefix)sl-clear listeners (event removed; listen for
input after clear)sl-invalid to
wa-invalidformdata-event-based form
serialization shims (form association is native)name attribute
(required for native FormData)Slider (from <sl-range>)
<wa-slider>tooltip attribute with
with-tooltip + tooltip-placement + tooltip-distancerange attribute for two-thumb
selectionInline Callout (from <sl-alert>)
<sl-alert> static usage with
<wa-callout>open, closable,
duration (callouts always render)show()/hide() calls (use
conditional rendering).toast() calls to Web Awesome Pro
<wa-toast> (or built your own)Dialog and Drawer
sl-show/sl-hide/sl-after-show/sl-after-hide to wa-
prefixsl-initial-focus to
wa-initial-focussl-request-close listeners to
cancellable wa-hidenoHeader attribute to
without-headerDropdown and Menu
<sl-dropdown> +
<sl-menu> into <wa-dropdown> (menu is gone)<sl-menu-item> to
<wa-dropdown-item>caret on trigger button to
with-caretsl-select to
wa-select<sl-menu-label> separators (use
<wa-divider> + heading)Tabs
sl-tab-show to
wa-tab-showsl-tab-hide to
wa-tab-hidesl-close (closable tab) to
use new pattern (see docs for details)Tree
sl-selection-change to
wa-selection-changesl-expand/sl-collapse/sl-after-expand/sl-after-collapse to
wa- prefixsl-lazy-load/sl-lazy-change to
wa-lazy-load/wa-lazy-changeTag
removable to
with-removesl-remove to
wa-removeOther Components (Event Names Only)
sl-* events to wa-* (or native
where applicable)Icons
exclamation-triangle → triangle-exclamation)setKitCode() or
data-fa-kit-code4. Theme Tokens
--sl-color-primary-* with
--wa-color-brand-*--sl-spacing-* with
--wa-space-{2xs,xs,s,m,l,xl,2xl,...}--sl-font-size-{x-small,small,medium,large,x-large,...} with
--wa-font-size-{xs,s,m,l,xl,...}--sl-font-mono with
--wa-font-family-code--sl-font-sans with
--wa-font-family-body (or --wa-font-family-heading)--sl-font-serif with
--wa-font-family-longform--sl-line-height-dense with
--wa-line-height-condensed--sl-line-height-loose with
--wa-line-height-expanded--sl-border-radius-{small,medium,large} with
--wa-border-radius-{s,m,l}--sl-shadow-x-small/-small →
--wa-shadow-s--sl-shadow-large/-x-large →
--wa-shadow-l--sl-transition-x-fast/-fast → --wa-transition-fast--sl-transition-medium to
--wa-transition-normal--sl-input-* with
--wa-form-control-*--sl-color-neutral-0 with
--wa-color-surface-default--sl-color-neutral-1000 with
--wa-color-text-normal--sl-z-index-* references (use cascade
layers and stacking contexts)var(--sl-*, fallback) calls so the
fallback isn't silently masking missed migrations5. Forms and Validation
formdata event listeners that
extracted Shoelace control valuesnew FormData(form) returns expected
fieldsform.checkValidity() and
form.reportValidity() include all controlsform.reset() resets all
<wa-*> controlssetCustomValidity() calls (still works)
or moved to customError attributesl-invalid listeners to
wa-invalid:invalid,
:valid, :required) apply as expected6. Silent Breakage Risks
addEventListener('sl-...') strings
remainslot="prefix" or
slot="suffix" lefthelp-text= attributes leftvariant="primary"
left::part() selectors still target valid
parts after renamewa-dark class, not
sl-theme-dark)7. Testing
8. Optional Follow-Ups
wa-theme-shoelace initially? Consider
switching to default or awesomewa-cluster,
wa-stack, wa-grid, etc.) to replace custom layout CSS<wa-page> for app shell layout<wa-popover> where you previously used a
tooltip with rich content<wa-number-input> instead of
<wa-input type="number"><wa-toast>,
<wa-combobox>, <wa-file-input>, charts, sparklines, additional
themes