Merge pull request #1158 from daniel-ac-martin/improve-docs

docs: Better explain how to use the components

apps/govuk-docs/src/common/pages/components.tsx

@@ -5,6 +5,7 @@ import { NavigationMenu } from '@not-govuk/components';
 import { DocsPage } from '@not-govuk/docs-components';
 import { useLocation } from '@not-govuk/router';
 import { internalComponentLinks, mainComponentLinks, nameParam, components as subpages, unofficialComponentLinks  } from '../stories';
+import Markdown from '../../../../../docs/components.md';
 import config from '../config';
 
 const siteTitle = config.title;
@@ -44,15 +45,7 @@ const Page: FC<PageProps> = () => {
             subPageName ? (
               null // should be a 404!
             ) : (
-              <Fragment>
-                <h1>{title}</h1>
-                <p>
-                  Components are reusable parts of the user interface that have been made to support a variety of applications.
-                </p>
-                <p>
-                  Individual components can be used in multiple different patterns and contexts. For example, the text input component can be used to ask for an email address, a National Insurance number or someone’s name.
-                </p>
-              </Fragment>
+              <Markdown />
             )
           )
         }

docs/components.md

@@ -0,0 +1,109 @@
+Components
+==========
+
+Components are reusable parts of the user interface that have been made to support a variety of applications.
+
+Individual components can be used in multiple different patterns and contexts. For example, the text input component can be used to ask for an email address, a National Insurance number or someone’s name.
+
+
+How to use the components
+-------------------------
+
+The components are published in NPM packages, both individually and all altogether. The best way to consume the components depends on the context in which you use them; in an application you should usually import all of the components in one go, but in your own re-usable components you should try to only consume the individual packages that your component needs.
+
+
+### Using the components in NotGovUK framework applications
+
+If you have initiated a project or prototype using the instructors in [Getting started]. You should import the components from the `@not-govuk/components` package, which you should already have installed.
+
+```jsx
+// src/common/pages/your-page.tsx
+import { FC, createElement as h } from 'react';
+import { PageProps } from '@not-govuk/app-composer';
+import { Panel } from '@not-govuk/components';
+
+export title = 'Your title'
+
+const Page: FC<PageProps> = () => {
+  return (
+    <Panel
+      classModifiers="confirmation"
+      title="Application complete"
+    >
+      Your reference number
+      <br />
+      <strong>HDJ2123F</strong>
+    </Panel>
+  );
+};
+
+export default Page;
+```
+
+Alternatively, if you are just building a prototype, you may wish to simply use the supplied HTML code, without the need to worry about importing anything from packages.
+
+
+### Using the components in re-usable components
+
+If you are publishing your own, individually packaged, re-usable components (as we facilitate in NotGovUK projects) you should import the components from their individual packages rather than the group packages.
+
+```shell
+$ npm install @not-govuk/panel
+```
+
+(Note: If you are using the framework, you should use `pnpm` in place of `npm`.)
+
+You can then import them into your component.
+
+```jsx
+import React, { createElement as h } from 'react';
+import Panel from '@not-govuk/panel';
+
+export const MyComponent = props => (
+  <Panel
+    classModifiers="confirmation"
+    title="Application complete"
+  >
+    Your reference number<br />
+    <strong>HDJ2123F</strong>
+  </Panel>
+);
+
+export default MyComponent;
+```
+
+
+### Using the components in Remix applications
+
+You should import the components from the `@not-govuk/components` package, which you should install with NPM.
+
+```shell
+$ npm install @not-govuk/components
+```
+
+You can then import the components.
+
+```jsx
+import { Panel } from '@not-govuk/components';
+```
+
+
+### Using the components in Next.js applications
+
+You should import the components from the `@not-govuk/simple-components` package, which you should install with NPM.
+
+```shell
+$ npm install @not-govuk/simple-components
+```
+
+You can then import the components.
+
+```jsx
+import { Panel } from '@not-govuk/simple-components';
+```
+
+Note that, you will not be able to make use of the [Form] framework, as this does not currently support Next.js.
+
+
+[Getting started]: https://not-gov.uk/get-started
+[Form]: https://not-gov.uk/components?name=Form

docs/get-started.md

@@ -1,15 +1,36 @@
 Getting Started
 ===============
 
-In order to consume these components you will require a system that
-utilised a bundler (such as [Webpack]) that can process imported assets
-such as images, fonts and [Sass] files. [Create React App] may be able to
-do this but does not provide Server-Side Rendering (SSR). You will also
-need to ensure that you provide an instance of [react-router].
+In order to consume these components you will require a system that utilises a
+bundler (such as [Webpack]) that can process imported assets such as images,
+fonts and [Sass] files. [Create React App] may be able to do this but does not
+provide Server-Side Rendering (SSR). You will also need to ensure that you
+provide an instance of a _router_, such as [react-router].
 
-As such, we suggest that you use our specially designed tech stack for
-this purpose. You can start a brand new project or prototype using the
-following steps.
+In most cases you will want to use these components in some sort of
+framework. The main options are as follows:
+
+- [Remix]
+- [Next.js]
+  (Isomorphic rendering, but oriented towards search engine optimisation.)
+- [Create React App] (CRA)
+  (Client-side rendering only.)
+- Our NotGovUK framework
+  (Experimental. See below.)
+
+## Using the components in another framework
+
+To just use the NotGovUK components in a 3rd party framework (such as Remix or
+CRA), please see the instructions on the [Components] page.
+
+## Using the NotGovUK framework
+
+The NotGovUK framework is still experimental and so you should not use it in
+production unless it has specific features that you require and that are not
+available in competing frameworks such as [Remix]. (In the future we may look to
+replace parts of our framework with Remix.) One such example, may be our support
+for building 'child' design systems. You can start a brand new project or
+prototype using the following steps.
 
 
 ### 1. Set up your repository
@@ -189,6 +210,9 @@ mandatory prior to merging:
 [Sass]: https://sass-lang.com/
 [Create React App]: https://create-react-app.dev/
 [react-router]: https://reactrouter.com/
+[Next.js]: https://nextjs.org/
+[Remix]: https://remix.run/
+[Components]: ./components
 [GitHub]: https://github.com/
 [GitHub Actions]: https://github.com/features/actions
 [install pnpm]: https://pnpm.io/installation

lib-govuk/components/assets/_code.scss

@@ -6,3 +6,10 @@ code {
   color: #d13118;
   background-color: #f3f2f1;
 }
+
+pre {
+  > code {
+    display: block;
+    padding: 1em;
+  }
+}