Move away from using SCSS

[d13]

Historically, webviews have been constructed with fairly simple HTML, JavaScript, and DOM APIs. This allowed for the DOM to remain entirely open, which made it easy to use SCSS to keep styles dry and reusable.

As our webviews have become much more complex, we've moved to custom elements and shadow-DOM, to make complex UI patterns much easier to maintain and faster to build. One of the challenges with shadow-DOM is that styles in the root document no longer cascade (with very limited exceptions) to those custom elements, thus needing another mechanism to share styles between components as well with the HTML document itself.

Alternatives

Lit CSS Templates

Using Lit's CSS template functions, these will compile down to CSSStyleSheet objects which can then be shared between light and shadow DOM. The primary implementation difference is that it will require applying them to the HTML document via document.adoptedStyleSheets.

// focus.css.ts

import { css } from 'lit';

export const focusSheet = css`
  :focus {
    outline: 1px solid var(--vscode-focusBorder);
    outline-offset: -1px;
  }
`;

// app.ts

import { focusSheet } from './focus.css';

document.adoptedStyleSheets.push(focusSheet);

CSS Modules

The most ideal solution for this would be to use plain CSS files. This approach gives us the flexibility to use standard <link> tags to import in HTML files and also be able to import them as CSS Modules, which can be used in web components as well.

The problem with this approach is its only supported in Chromium-based browsers, which is fine for our currently supported version of electron in VS Code, but falls out quickly for vscode.dev which requires cross-browser support. Moving to this approach is should be highly considered in the future.

/* focus.css */

:focus {
  outline: 1px solid var(--vscode-focusBorder);
  outline-offset: -1px;
}

import resetSheet from './reset.css' assert { type: 'css' };
import focusSheet from './focus.css' assert { type: 'css' };

document.adoptedStyleSheets.push(resetSheet, focusSheet);

Recommendation

Use Lit CSS templates until CSS Modules have broader browser support. The migration from one to the other should be a fairly small effort.

We can use a plain CSS file to specify surface-specific CSS Custom properties and fonts.

References

• MDN- CSSStyleSheet
• MDN - adoptedStyleSheets property
  • Document
  • ShadowRoot
• Constructable StyleSheets
• Importing CSS as Modules
• Lit - Styles