nwl-components 1.7.1 → 2.0.0

package/README.md

@@ -143,13 +143,108 @@ render();
 - For template strings: `renderSortIcon(direction)` (the SVG) and `ariaSort(direction)`.
 
 The headers' look is in `nwl-components/sort/style.css`, which has only the
-`th.nwl-sortable` and `.nwl-sort-*` rules (1 kB). Load that file, not `dist/style.css`, on a
+`th.nwl-sortable` and `.nwl-sort-*` rules, after the design tokens they read (`:root` custom
+properties, see "Design tokens"; 6 kB in all). Load that file, not `dist/style.css`, on a
 page not built with nwl-components: `dist/style.css` has global rules (`*` sets the font
 size and colour of every element). With a bundler, `import 'nwl-components/sort/style.css'`
 (webpack 4 included); otherwise link `node_modules/nwl-components/dist/sort/style.css`.
 `dist/style.css` keeps the same rules for `SortableTh`. Story: `Common/PlainSort`.
 Since 1.6.0.
 
+## Design tokens
+
+The library's colours, fonts, font sizes and corner radii are CSS custom properties, defined
+in `src/styles/tokens.css` (`:root` rules only) in two tiers:
+
+- the raw palette (`--nwl-grey-44`, `--nwl-white`, `--nwl-cyan`, …): the only place with hex
+  values;
+- the semantic tokens, to use in components and app CSS: backgrounds (`--nwl-bg`,
+  `--nwl-bg-surface`, `--nwl-bg-elevated`, …), borders (`--nwl-border`, …), text
+  (`--nwl-text`, `--nwl-text-2`, `--nwl-text-3`, …), accent, links and status colours
+  (`--nwl-danger`, `--nwl-success`, `--nwl-warning`), font families (`--nwl-font-body`,
+  `--nwl-font-display`, `--nwl-font-mono`), sizes (`--nwl-text-xs` … `--nwl-text-hero`;
+  body text is `--nwl-text-md`), weights, line heights, spacing (`--nwl-space-1` …
+  `--nwl-space-16`), radii (`--nwl-radius-sm`, `--nwl-radius-md`) and shadows.
+
+Their values are those the NAAT apps have today, so loading them changes nothing on screen.
+Storybook's `Library/Tokens` page lists every token with a sample.
+
+`dist/style.css` and `nwl-components/sort/style.css` each include the tokens, so a page that
+loads either needs nothing else. To use the tokens in an app's own CSS without those files:
+
+```js
+import 'nwl-components/tokens.css'; // with a bundler (webpack 4 included)
+```
+
+```html
+<!-- a page with no bundle: serve or copy node_modules/nwl-components/dist/tokens.css -->
+<link rel="stylesheet" href="/lib/nwl-components/tokens.css">
+```
+
+```css
+.my-panel {
+  background: var(--nwl-bg-surface);
+  border: 1px solid var(--nwl-border);
+  border-radius: var(--nwl-radius-sm);
+}
+```
+
+Loading the tokens twice on a page (e.g. `tokens.css` and `dist/style.css`) is harmless.
+`npm run lint` fails on a hex colour in `src/**/*.{vue,css}` outside `tokens.css`, and on a
+`var(--nwl-…)` that `tokens.css` doesn't define. Since 1.8.0.
+
+## Base styles and cascade layers
+
+Since 2.0.0 all the library's CSS is in three cascade layers, declared in this order at the
+top of each stylesheet it ships (`dist/style.css`, `nwl-components/base.css`,
+`nwl-components/sort/style.css`):
+
+```css
+@layer nwl.base, nwl.widgets, nwl.components;
+```
+
+- `nwl.base`: `src/styles/base.css` (below);
+- `nwl.widgets`: empty for now (plain-CSS widget classes, later);
+- `nwl.components`: the components' styles (scoped or not), `sortable.css`, and the CSS of
+  bundled dependencies (splitpanes).
+
+The tokens (`tokens.css`) stay outside the layers: they only define custom properties.
+**An app's own CSS, which is not in a layer, always wins over the library's**, whatever the
+load order or the selectors' specificity: `button { … }` in an app overrides `Button`'s scoped
+rules. No `!important` and no `html …` prefix are needed. (An app that puts its own CSS in
+layers must declare them after `nwl.components` to keep this.)
+
+`base.css` replaces 1.x's global `* { box-sizing: border-box; font-size: 14px; color: white }`
+rule, which is gone. Its selectors are wrapped in `:where()` (no specificity), and they apply
+inside the wrapper (`.app`, the root of `Wrapper`) only, except two:
+
+- `html`: `font-size: var(--nwl-text-md)` (1rem = 14px, as in 1.x), and `body`: `margin: 0`;
+- `.app`: font (`--nwl-font-body`, `--nwl-text-md`) and colour (`--nwl-text`), inherited by
+  everything inside; `box-sizing: border-box`, inherited by every element and pseudo-element;
+- headings, `small`, `sub`, `sup`, `code`, `pre` and form controls take their parent's font
+  size; form controls and `<dialog>` their parent's colour (the controls' font family stays
+  the browser's); links `--nwl-link`;
+- keyboard focus: `:focus-visible` gets a 2px solid `--nwl-focus` outline, 2px away
+  (`--nwl-focus` is `--nwl-text`, white). Mouse focus shows nothing on buttons; browsers
+  show it on text fields and Chromium on `<select>`, as they decide what is `:focus-visible`.
+
+`dist/style.css` includes `base.css`. A page without the Vue components (e.g. a Mustache page
+that wants the same font, colour and focus style) can load it alone, after the tokens:
+
+```js
+import 'nwl-components/tokens.css';
+import 'nwl-components/base.css'; // webpack 4 too (a copy at the package root)
+```
+
+```html
+<link rel="stylesheet" href="/lib/nwl-components/tokens.css">
+<link rel="stylesheet" href="/lib/nwl-components/base.css">
+<div class="app">…</div>
+```
+
+Outside `.app`, nothing sets font, colour or box-sizing any more: an app's own markup on a
+page that loads `dist/style.css` gets them from the app's CSS (or from being inside `.app`).
+
 ## Single File Components
 
 This project makes use of Vue SFCs: _Single File Components_, that have the `.vue` extension.

package/base.css

@@ -0,0 +1,58 @@
+@layer nwl.base, nwl.widgets, nwl.components;
+@layer nwl.base {
+/* nwl-components base styles: `import 'nwl-components/base.css'` (after `nwl-components/tokens.css`,
+   whose tokens it reads). dist/style.css includes it.
+
+   The build puts this file in `@layer nwl.base`, the lowest of the library's layers
+   (`@layer nwl.base, nwl.widgets, nwl.components`), so any app rule wins over it. Selectors are
+   wrapped in :where(), so they add no specificity.
+
+   Font and colour are set once, on the wrapper (`.app`, the root of `Wrapper`), and inherited:
+   there is no `*` rule setting them on every element. */
+
+/* 1rem = 14px, as in 1.x (where the `*` rule set it on <html>): the components' rem sizes */
+:where(html) {
+  font-size: var(--nwl-text-md);
+}
+
+:where(body) {
+  margin: 0;
+}
+
+:where(.app) {
+  box-sizing: border-box;
+  font-family: var(--nwl-font-body);
+  font-size: var(--nwl-text-md);
+  color: var(--nwl-text);
+}
+
+:where(.app) *,
+:where(.app) *::before,
+:where(.app) *::after {
+  box-sizing: inherit;
+}
+
+/* Elements the browser gives a size of their own (headings, small print, code, form controls)
+   take their parent's, as 1.x's `*` rule made them do. */
+:where(.app) :where(h1, h2, h3, h4, h5, h6, small, sub, sup, big, code, kbd, samp, pre, tt, button, input, select, textarea) {
+  font-size: inherit;
+}
+
+/* Form controls and dialogs don't inherit the colour by default either. The controls' font
+   family stays the browser's, as it was in 1.x. */
+:where(.app) :where(button, input, select, textarea, dialog) {
+  color: inherit;
+}
+
+/* links: the link colour, not the browser's blue */
+:where(.app a) {
+  color: var(--nwl-link);
+}
+
+/* Keyboard focus: a 2px outline in --nwl-focus. Mouse focus shows nothing (browsers match
+   :focus-visible on a mouse click only for text fields). */
+:where(.app :focus-visible) {
+  outline: 2px solid var(--nwl-focus);
+  outline-offset: 2px;
+}
+}

package/dist/base.css

@@ -0,0 +1,58 @@
+@layer nwl.base, nwl.widgets, nwl.components;
+@layer nwl.base {
+/* nwl-components base styles: `import 'nwl-components/base.css'` (after `nwl-components/tokens.css`,
+   whose tokens it reads). dist/style.css includes it.
+
+   The build puts this file in `@layer nwl.base`, the lowest of the library's layers
+   (`@layer nwl.base, nwl.widgets, nwl.components`), so any app rule wins over it. Selectors are
+   wrapped in :where(), so they add no specificity.
+
+   Font and colour are set once, on the wrapper (`.app`, the root of `Wrapper`), and inherited:
+   there is no `*` rule setting them on every element. */
+
+/* 1rem = 14px, as in 1.x (where the `*` rule set it on <html>): the components' rem sizes */
+:where(html) {
+  font-size: var(--nwl-text-md);
+}
+
+:where(body) {
+  margin: 0;
+}
+
+:where(.app) {
+  box-sizing: border-box;
+  font-family: var(--nwl-font-body);
+  font-size: var(--nwl-text-md);
+  color: var(--nwl-text);
+}
+
+:where(.app) *,
+:where(.app) *::before,
+:where(.app) *::after {
+  box-sizing: inherit;
+}
+
+/* Elements the browser gives a size of their own (headings, small print, code, form controls)
+   take their parent's, as 1.x's `*` rule made them do. */
+:where(.app) :where(h1, h2, h3, h4, h5, h6, small, sub, sup, big, code, kbd, samp, pre, tt, button, input, select, textarea) {
+  font-size: inherit;
+}
+
+/* Form controls and dialogs don't inherit the colour by default either. The controls' font
+   family stays the browser's, as it was in 1.x. */
+:where(.app) :where(button, input, select, textarea, dialog) {
+  color: inherit;
+}
+
+/* links: the link colour, not the browser's blue */
+:where(.app a) {
+  color: var(--nwl-link);
+}
+
+/* Keyboard focus: a 2px outline in --nwl-focus. Mouse focus shows nothing (browsers match
+   :focus-visible on a mouse click only for text fields). */
+:where(.app :focus-visible) {
+  outline: 2px solid var(--nwl-focus);
+  outline-offset: 2px;
+}
+}