diff --git a/apps/govuk-docs/src/common/pages/components.tsx b/apps/govuk-docs/src/common/pages/components.tsx index 1f1a237fd..68f47acd5 100644 --- a/apps/govuk-docs/src/common/pages/components.tsx +++ b/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 = () => { subPageName ? ( null // should be a 404! ) : ( - -

{title}

-

- 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. -

-
+ ) ) } diff --git a/docs/components.md b/docs/components.md new file mode 100644 index 000000000..b5d17435b --- /dev/null +++ b/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 = () => { + return ( + + Your reference number +
+ HDJ2123F +
+ ); +}; + +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 => ( + + Your reference number
+ HDJ2123F +
+); + +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 diff --git a/docs/get-started.md b/docs/get-started.md index 7aac46795..084bbd6c4 100644 --- a/docs/get-started.md +++ b/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 diff --git a/lib-govuk/components/assets/_code.scss b/lib-govuk/components/assets/_code.scss index a457abbb4..1d5575b7b 100644 --- a/lib-govuk/components/assets/_code.scss +++ b/lib-govuk/components/assets/_code.scss @@ -6,3 +6,10 @@ code { color: #d13118; background-color: #f3f2f1; } + +pre { + > code { + display: block; + padding: 1em; + } +}