Adoption

Overview

This page is not intended to provide stringent rules for Skylab SDK adoption. Rather, the guidance below has been collected from various engineering teams that have been through this process. The most important part of the process below is that CSS is adopted prior to components. The rest of the process can be customized as needed.

If you identify improvements to this process or have feedback, please submit a Merge Request to the skylab-sdk repository or reach out on the #skylab Slack channel.

Process

1. Preparation

Some teams have found it helpful to do the following preparation prior to migration-related development:

1. Take screenshots of each major page to compare with migration work
2. Create a feature branch to limit the number of major visual changes for users and enable ongoing development unrelated to adoption.

Your UX designer should have a strong knowledge of Skylab design at this point. Work closely with them throughout this process to validate that the implementation matches Skylab design standards. For any questions, reach out on the #skylab Slack channel.

2. Install

Install Skylab SDK per instructions on the home page of this site.

3. CSS

When adopting Skylab SDK in an existing web application, the most significant challenges are typically related to these Skylab SDK styles clashing with existing app styles. There will be significant styling breakages when the Skylab CSS is first brought into the app.

Skylab SDK's CSS impacts high-level app styling (normalization) as well as various native HTML elements. Review the docsite pages linked to below to identify Skylab SDK standards for native HTML elements:

• Headings
• Link
• Lists
• Button
• Form
• Checkbox
• Input
• Radio
• Textarea
• Table

Note that the native HTML <select> should always be replaced in your code with the <s-select> component in order to maintain consistency between apps. See the s-select documentation for more information.

Some general best practices:

• It is always ideal to remove styles from within the app's stylesheets rather than layering styles on top of one another.
• The engineer(s) resolving these CSS conflicts should have a strong knowledge of CSS properties and specificity to work through this step efficiently.
• Leveraging Skylab SDK's CSS Utils wherever possible as they greatly reduce the need for app-specific CSS and are aligned with Skylab Design principles (e.g. base-6px margin/padding).
• For all components linked above, use the implementation as described, such as providing all <button> elements one of the identified classes and applying the <label> in the manner described on the forms page (e.g. preceding <input type="text">, not enclosed by it).

A note on rem

Skylab SDK's CSS sets the font-size to the root element (1rem) to 16px. As a result, any existing styles in your app that utilize rem units will be measured in units of 16px.

4. Layout and unified navigation

Due to the importance of providing a unified navigation with other Avalara web applications, we recommend adopting the standard layout and unified navigation directly after CSS - see:

• Standard layout
• <aui-header>
• <aui-supernav>
• <aui-footer>

Note: implementation of <s-row> and <s-col> can be delayed until the next step.

5. Grid

Update your app's layout with the <s-row> and <s-col> elements in each view. Their usage is documented on the Grid page. This gives an opportunity to clean up cruft and past poor practices, as well as setting up a solid layout for the Skylab SDK components to land in.

6. Other Components

While adopting components, ensure that you are following Best practices and adhering to the guidelines - particularly with regard to accessibility - on each component page. We recommend never manipulating the internals (CSS or JS) of a Skylab SDK component. Doing so will likely result in breakages. Rather, if there is an issue or missing feature, surface it on the #skylab Slack channel and if approved, we recommend contributing it to the skylab-sdk repository.

There is no prescribed order for the adoption of other components, but in many cases, they can be adopted in batches (e.g. convert all existing icons to Skylab SDK icons). If you have existing components that can be replaced directly with a Skylab SDK component, those may be a good place to start.

You will most likely need to listen for Skylab SDK components' custom events in order for the components to function correctly in your app. See the events page for information on handling custom events in our supported frameworks.

References

If you have never used Skylab SDK before, we recommend finding other apps using your framework/implementation using the Platform Adoption Dashboard and review their implementation using Gitlab. We are in the process of opening access to these repositories, but if you receive a 404 when you try to click on one of the Gitlab links, request access from the associated Dev contact.