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
Jump to heading
@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
Jump to heading
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
Jump to heading
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
Jump to heading
Renamed Elements
Jump to heading
<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
Jump to heading
<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
Jump to heading
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
Jump to heading
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>)
Jump to heading
<wa-slider>tooltip attribute with
with-tooltip + tooltip-placement + tooltip-distancerange attribute for two-thumb
selectionInline Callout (from <sl-alert>)
Jump to heading
<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
Jump to heading
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
Jump to heading
<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
Jump to heading
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
Jump to heading
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
Jump to heading
removable to
with-removesl-remove to
wa-removeOther Components (Event Names Only)
Jump to heading
sl-* events to wa-* (or native
where applicable)Icons
Jump to heading
exclamation-triangle → triangle-exclamation)setKitCode() or
data-fa-kit-code4. Theme Tokens
Jump to heading
--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
Jump to heading
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
Jump to heading
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
Jump to heading
8. Optional Follow-Ups
Jump to heading
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