Merge pull request #6111 from Sage/update-roadmap

docs: update carbon public roadmap

cypress/components/carbon-provider/carbon-provider.cy.js

@@ -1,5 +1,9 @@
 import React from "react";
-import * as stories from "../../../src/components/carbon-provider/carbon-provider.stories";
+import {
+ SageTheme as SageThemeStory,
+ MintTheme as MintThemeStory,
+} from "../../../src/components/carbon-provider/carbon-provider.stories";
+import { AllThemes as AllThemesStory } from "../../../src/components/carbon-provider/carbon-provider-test.stories";
 import Button from "../../../src/components/button";
 import Link from "../../../src/components/link";
 import Loader from "../../../src/components/loader";
@@ -272,20 +276,20 @@ context("Testing Carbon Provider component", () => {
  );
 
  describe("Accessibility tests for Carbon Provider", () => {
- it("should pass accessibility tests for Carbon Provider", () => {
- CypressMountWithProviders(<stories.Default />);
+ it("should pass accessibility tests for Carbon Provider sage theme story", () => {
+ CypressMountWithProviders(<SageThemeStory />);
 
  cy.checkAccessibility();
  });
 
- it("should pass accessibility tests for Carbon Provider mixing story", () => {
- CypressMountWithProviders(<stories.Mixing />);
+ it("should pass accessibility tests for Carbon Provider mint theme story", () => {
+ CypressMountWithProviders(<MintThemeStory />);
 
  cy.checkAccessibility();
  });
 
- it("should pass accessibility tests for Carbon Provider theming story", () => {
- CypressMountWithProviders(<stories.Theming />);
+ it("should pass accessibility tests for Carbon Provider all themes story", () => {
+ CypressMountWithProviders(<AllThemesStory />);
 
  cy.checkAccessibility();
  });

docs/installation.stories.mdx

@@ -0,0 +1,57 @@
+import LinkTo from "@storybook/addon-links/react";
+
+<Meta title="Getting Started/Installation" />
+
+# Installation
+
+## Contents
+
+- [Main installation](#main-installation)
+- [Peer dependencies](#peer-dependencies)
+- [Fonts and icons](#fonts-and-icons)
+
+## Main installation
+
+Carbon is available as an [npm package](https://www.npmjs.com/package/carbon-react). To install it into your project run the following command:
+
+```shell
+npm install carbon-react
+```
+
+## Peer dependencies
+
+You will need to install the following dependencies in your project, these are peer-dependencies of Carbon and are required.
+
+```shell
+npm install @sage/design-tokens@^4.0 react@^17.0 react-dom@^17.0 styled-components@^4.4.1
+```
+
+Carbon uses [draft-js](https://draftjs.org/) for the `TextEditor` or `Note` components. If you plan on using these components in your project, run the following to install the package:
+
+```shell
+npm install draft-js
+```
+
+## Fonts and icons
+
+Carbon requires the `Sage UI` and `CarbonIcons` fonts to display correctly. The CSS font face definitions are included in Carbon and can be imported directly in either your entry-point CSS:
+
+```css
+/* Import Sage UI and CarbonIcons fonts */
+@import "~carbon-react/lib/style/fonts.css";
+```
+
+or your entry-point JavaScript:
+
+```js
+// Import Sage UI and CarbonIcons fonts
+import "carbon-react/lib/style/fonts.css";
+```
+
+### Assets
+
+The font and icon assets themselves will **not** be automatically handled by Carbon, so you will be required to load these into your application yourself through your build system.
+
+Your build system must support CSS and file loading for this to work, e.g. `webpack` with `css-loader` and `file-loader`. This is pre-configured if you are using `create-react-app`, but it is possible to use other bundling solutions such as [Vite](https://vitejs.dev/) or [Parcel](https://parceljs.org/) if you wish.
+
+Note the `Sage UI` font assets themselves are provided by the [@sage/design-tokens](https://www.npmjs.com/package/@sage/design-tokens) library. If this has not been installed in your project beforehand, text will be rendered in the browser's default sans-serif font.

docs/roadmap.stories.mdx

@@ -0,0 +1,28 @@
+<Meta title="Contributing/Roadmap" />
+
+# Roadmap
+
+> **Disclaimer**: We operate in a dynamic commercial environment, and things are subject to change. The information provided is intended to outline the general direction of the library. It's intended for informational purposes only. We may decide to add/remove new items at any time depending on our capability to deliver while meeting our quality standards. The development, releases, and timing of any features or functionality of Carbon remain at the sole discretion of Sage. The roadmap does not represent a commitment, obligation, or promise to deliver at any time.
+
+Alongside regular support, we currently have the below activities on our backlog:
+
+## Support for React 18
+
+To enable the community to utilise the latest React features, we are currently replacing Enzyme in our internal tests in favour of React Testing Library. You can see a detailed plan in [the official React Testing Library RFC](https://github.com/Sage/carbon/tree/master/rfcs/text/enzyme-to-rtl.md).
+
+## Accessibility
+
+We are actively working with the community and Sage Accessibility auditors to ensure all Carbon components are accessible to at least [level AA standard of the WCAG 2.1 guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/).
+
+## Replacing `styled-components`
+
+We will eventually retire support for `styled-components` and `styled-system` and investigate alternative tooling such as CSS Modules, with the intention of removing technical debt and improving performance.
+
+## Responsiveness
+
+We will be updating Carbon to ensure all our components natively support mobile devices down to 320px screen width. This will be a large, multi-disciplinary effort with other developers, designers and accessibility auditors to ensure the best solution is offered to Carbon consumers.
+
+## Documentation
+
+We will increase our documentation efforts to ensure that our consumers have a good development experience.
+We will consider the langauge that we use, the examples that we provide and the tooling that we use.

docs/usage.stories.mdx

@@ -0,0 +1,77 @@
+import LinkTo from "@storybook/addon-links/react";
+
+<Meta title="Getting Started/Usage" />
+
+# Usage
+
+## Contents
+
+- [Quickstart](#quickstart)
+- [Globals](#globals)
+ - [Global styles](#global-styles)
+ - [Theming](#theming)
+ - [Localisation](#localisation)
+
+## Quickstart
+
+A basic project `index.js` file would resemble this example:
+
+```jsx
+import React from "react";
+import ReactDOM from "react-dom";
+import CarbonProvider from "carbon-react/lib/components/carbon-provider";
+import GlobalStyle from "carbon-react/lib/style/global-style";
+import sageTheme from "carbon-react/lib/style/themes/sage";
+import "carbon-react/lib/style/fonts.css";
+import Typography from "carbon-react/lib/components/typography";
+
+const App = (props) => {
+ return (
+ <CarbonProvider theme={sageTheme}>
+ <GlobalStyle />
+ <Typography>Hello Carbon</Typography>
+ </CarbonProvider>
+ );
+};
+
+ReactDOM.render(<App />, document.getElementById("app"));
+```
+
+This can also be found in our Codesandbox templates:
+
+- [JavaScript quickstart](https://codesandbox.io/s/carbon-quickstart-j5pb2).
+- [TypeScript quickstart](https://codesandbox.io/s/carbon-quickstart-typescript-6sjfuz)
+
+## Globals
+
+### Global styles
+
+We recommend using our global stylesheet, which can be used by including the global `GlobalStyle` component within your app like so:
+
+```ts
+import React from "react";
+import ReactDOM from "react-dom";
+import GlobalStyle from 'carbon-react/lib/style/global-style';
+
+ReactDOM.render(
+ <CarbonProvider>
+ <GlobalStyle/>
+ ...
+ </CarbonProvider>
+, ...);
+```
+
+### Theming
+
+Carbon supports two theming systems - the latest which uses Design Tokens in form of CSS custom properties maintained by designers, and legacy themes which use old theme properties from the ThemeProvider from the [styled-components library](https://styled-components.com/docs/advanced#theming). Currently both systems are being supported to aid projects using older versions of Carbon with upgrading.
+
+The themes available in Carbon include:
+
+- **sage** - the latest theme which uses Design Tokens in form of CSS custom properties. _Note this theme requires installation of `@sage/design-tokens` library, otherwise styles fallback to the old mint theme for compatability._
+- **mint**, **aegean** and **none** - legacy themes that use old theme properties consumed by [ThemeProvider from the styled-components library](https://styled-components.com/docs/advanced#theming).
+
+To supply the theme styles to your components, you can pass them via the <a href="../?path=/docs/carbon-provider--sage-theme" target="_self">Carbon Provider</a>.
+
+### Localisation
+
+We also provide a `i18nProvider` global for handling different locales. For more information on how to use this in your app, <a href="../?path=/docs/documentation-i18n--page#i18n">see our i18n docs</a>.