Merge pull request #1063 from Financial-Times/base-styles-rethink

integrate ex-n-ui-foundations styles into dotcom-ui-base-styles

Author: apaleslimghost

examples/ft-ui/client/main.scss

@@ -1,6 +1,4 @@
-// The base styles will be output in the shared css bundle, so
-// only include the required mixins and variables.
-@import 'n-ui-foundations/mixins';
+@import '@financial-times/o-typography/main';
 
 p {
   @include oTypographySans($scale: 7);

examples/ft-ui/package.json

@@ -16,6 +16,7 @@
     "@financial-times/dotcom-middleware-navigation": "file:../../packages/dotcom-middleware-navigation",
     "@financial-times/dotcom-ui-layout": "file:../../packages/dotcom-ui-layout",
     "@financial-times/dotcom-ui-shell": "file:../../packages/dotcom-ui-shell",
+    "@financial-times/o-typography": "^7.6.2",
     "express": "^4.21.2",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
@@ -25,7 +26,6 @@
     "@financial-times/dotcom-build-base": "file:../../packages/dotcom-build-base",
     "@financial-times/dotcom-build-js": "file:../../packages/dotcom-build-js",
     "@financial-times/dotcom-build-sass": "file:../../packages/dotcom-build-sass",
-    "n-ui-foundations": "^9.0.0",
     "nodemon": "^1.18.9",
     "ready-state": "^2.0.5",
     "webpack": "^5.88.2",

examples/kitchen-sink/__test__/build.test.js

@@ -24,6 +24,7 @@ describe('examples/kitchen-sink/build', () => {
         "shared.stable.bundle.js",
         "styles.css",
         "vendors.bundle.js",
+        "vendors.css",
         "webpack-runtime.bundle.js",
       ]
     `)

examples/kitchen-sink/client/main.scss

@@ -1,6 +1,4 @@
-// The base styles will be output in the shared css bundle, so
-// only include the required mixins and variables.
-@import 'n-ui-foundations/mixins';
+@import '@financial-times/o-typography/main';
 
 .hello {
   @include oTypographySans($scale: 7);

examples/kitchen-sink/package.json

@@ -22,6 +22,7 @@
     "@financial-times/dotcom-ui-layout": "file:../../packages/dotcom-ui-layout",
     "@financial-times/dotcom-ui-shell": "file:../../packages/dotcom-ui-shell",
     "@financial-times/n-tracking": "7.2.1",
+    "@financial-times/o-typography": "^7.6.2",
     "express": "^4.21.2",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
@@ -32,9 +33,7 @@
     "@financial-times/dotcom-build-code-splitting": "file:../../packages/dotcom-build-code-splitting",
     "@financial-times/dotcom-build-js": "file:../../packages/dotcom-build-js",
     "@financial-times/dotcom-build-sass": "file:../../packages/dotcom-build-sass",
-    "@financial-times/o-header": "^11.1.0",
     "@sucrase/jest-plugin": "^2.0.0",
-    "n-ui-foundations": "^9.0.0",
     "nodemon": "^1.18.9",
     "ready-state": "^2.0.5",
     "webpack": "^5.88.2",

package-lock.json

@@ -63,7 +63,6 @@
     "jest-puppeteer": "^11.0.0",
     "lint-staged": "^10.0.0",
     "morphdom": "^2.7.0",
-    "n-ui-foundations": "9.0.0",
     "prettier": "^2.0.2",
     "puppeteer": "^24.1.0",
     "react": "^17.0.2",

package.json

@@ -75,7 +75,6 @@ export class PageKitCodeSplittingPlugin {
         'ftdomdelegate',
         'morphdom',
         'n-topic-search',
-        'n-ui-foundations',
         'ready-state'
       ],
       usedInUnknownWay: true

packages/dotcom-build-code-splitting/src/index.ts

@@ -34,8 +34,6 @@ export class PageKitSassPlugin {
       // Prefer `dart-sass`.
       implementation: require(this.implementation),
       // Prepends SCSS code before the actual entry file.
-      // Introduced to maintain snappy grid after n-ui-foundations removed it as the default.
-      // Once user-facing apps and components move away from using snappy grid then this can be removed.
       additionalData: this.additionalData,
       sassOptions: {
         // Disable formatting so that we don't spend time pretty printing

packages/dotcom-build-sass/src/index.ts

@@ -1,23 +1,30 @@
 # @financial-times/dotcom-ui-base-styles
 
-This new package provides the global document styles for FT.com, including normalisation styles, basic typography, focus states, and `o-grid`.
-
-_Please note_ the initial goal of this package is to centralise all of the required pieces for the progressive font loading technique provided by [`o-typography`](https://github.com/Financial-Times/o-typography/#progressive-loading-web-fonts) and create a placeholder for the future inclusion of global styles from `n-ui-foundations`.
-
+This package provides the global document styles for FT.com, including normalisation styles, basic typography, and grid styles, provided by [Origami](https://github.com/financial-times/origami) components.
 
 ## Getting started
 
-This package is compatible with Node 12+ and is distributed on npm.
-
 ```bash
 npm install --save @financial-times/dotcom-ui-base-styles
 ```
 
 After installing the package you can use it to embed the progressive font loading hooks and document styles into your pages on the server-side and initialise the font loading on client-side.
 
-### Server-side
+## Usage in apps
+
+### Styles
 
-If you are using React to render your app you should use the `LoadFontsEmbed` component along with the `loadCustomFontsClassNames` and `documentStyles` variables to integrate font loading and document styles with your pages:
+`dotcom-ui-base-styles` provides styles which should be imported into your application's main stylesheet:
+
+```scss
+@import '@financial-times/dotcom-ui-base-styles/styles';
+```
+
+### Critical styles and font preloading
+
+`dotcom-ui-base-styles` allows apps to HTTP-preload Origami's fonts, and provides baseline styles to be rendered as a `style` attribute on the `<html>` tag, to reduce [flash of unstyled content (FOUC)](https://en.wikipedia.org/wiki/Flash_of_unstyled_content).
+
+If you are using React to render your app, render the `LoadFontsEmbed` component along with the `loadCustomFontsClassNames` and `documentStyles` variables to integrate font loading and document styles with your pages:
 
 ```jsx
 import {
@@ -40,7 +47,7 @@ export default (props) => (
 )
 ```
 
-Otherwise you can insert the code snippet into a `<script>` element:
+Otherwise, you can insert the code snippet into a `<script>` element:
 
 ```js
 const {
@@ -64,20 +71,17 @@ function page() {
 }
 ```
 
-### Client-side
-
-Once you are rendering the styles, class names, and code snippets in your page you will need to initialise the client-side code.
+### Client-side Javascript
 
-To initialise the client-side JavaScript import the package and call the `.init()` method:
+`dotcom-ui-base-styles`'s font loader requires client-side Javascript to work. Import the package in your client-side entry point, and call the `.init()` method:
 
 ```js
 import * as baseStyles from '@financial-times/dotcom-ui-base-styles'
 
 baseStyles.init()
 ```
 
-This component also provides styles written in Sass which should be imported into your application's main Sass stylesheet:
+### Components
 
-```scss
-@import '@financial-times/dotcom-ui-base-styles/styles';
-```
+> [!WARNING]
+> `n-ui-foundations`, the predecessor of `dotcom-ui-base-styles`, provided common Origami dependencies for apps and components. `dotcom-ui-base-styles` only supports apps. For components, you should directly depend on and use the Origami components you require.