@cruk/cruk-react-components 7.0.0 → 7.1.1

package/README.md

@@ -1,28 +1,35 @@
 # cruk-react-components
 
-React implementation of the CRUK design system.
+React implementation of the CRUK design system using only React HTML and CSS.
+Contains the following themes for all components
 
-## View the docs
+- CRUK
+- RFL
+- SU2C
+- Bowelbabe
 
-cruk-react-component docs site: https://master.d28a8la187lo73.amplifyapp.com/
+## View storybook
 
-## Usage
+cruk-react-component storybook site demoing all the components with their different variants and themes:
+https://master.d28a8la187lo73.amplifyapp.com/
 
----
+## Getting Started
 
 Add cruk-react-components and its peer dependencies react, react-dom and styled-components to your package.json file.
 
 ```sh
 "dependencies": {
   "react": "^19",
-  "react-dom": "^19",
-  "styled-components": "^6"
+  "react-dom": "^19"
 }
 ```
 
 After an `npm i @cruk/cruk-react-components --save`, you can start importing components from the library:
 
 ```js
+// Ideally you would import the css on the top level entry point on you app
+// because you only need to import this once
+import "@cruk/cruk-react-components/lib/index.css";
 import { Button } from "cruk-react-components";
 
 const MyComponent = () => (
@@ -32,12 +39,134 @@ const MyComponent = () => (
 );
 ```
 
+## Extending your components with custom styles
+
+### Using the style prop
+
+```js
+import { Button } from "cruk-react-components";
+
+const MyComponent = () => (
+  <div>
+    <Button style={{ color: "#ff0000" }} />
+  </div>
+);
+```
+
+### Using your own css class
+
+Lets say we want to preseve and use the API that exists on the component, we want to add our own CSS class but we don't want to overwrite the CSS class that already styles the component The solution is simple because each components CSS already exposed when you import the index css
+
+```js
+import "@cruk/cruk-react-components/lib/index.css";
+```
+
+The always follow the same naming convetion of
+
+`.component-{componentName}`
+
+For example
+
+- `.component-button`
+- `.component-link`
+- `.component-text-field`
+- `.component-textarea-field`
+
+So we need to include the component class as well as our new CSS classes
+
+```js
+import { Button } from "cruk-react-components";
+
+const MyComponent = () => (
+  <div>
+    <Button
+      appearance="primary"
+      className={["component-button", "my-other-class-name"].join(" ")}
+    />
+  </div>
+);
+```
+
+### Utility classes
+
+There are currently three utility CCS classes
+
+- `color-props`
+- `spacing-props`
+- `text-props`
+
+This utility CSS classes can be used like this
+
+```js
+const MyComponent = () => (
+  <div className="color-props" data-bg-color="primary">
+    <Button
+      appearance="primary"
+      className={["component-button", "spacing-props"].join(" ")}
+      data-margin-bottom="s"
+    />
+  </div>
+);
+```
+
+##### color-props
+
+This CSS class will take names colours within the themes and applies them to the following data attributes
+
+- `data-color`: the text and svg colour
+- `data-bg-color`: the background colour
+- `data-border-color`: the border colour
+
+##### text-props
+
+This CSS class will take theme values like named font weights (vlight, light, medum, normal, heavy), named font families (base, buttons, links, headings, labels) and named font sizes (xs, s, m, l, xl, xxl, xxxl ) specified in each theme, as well as word wrap, overflow wrap, text align etc following data attributes
+
+- `data-word-break`: word-break
+- `data-overflow-wrap`: overflow-wrßap
+- `data-text-font-family`: sets font family using named font categories
+- `data-text-weight`: sets font weight using names weight categories, matches HTML convention
+- `data-text-size`: sets font size using named font sizes from themes
+
+##### spacing-props
+
+This CSS class will set the following named spacing values to different spacing CSS attributes.
+The names spacing values are:
+
+- `none`: 0;
+- `auto`: auto;
+- `xxxs`: 0.25rem; /_ 4px _/
+- `xxs`: 0.5rem; /_ 8px _/
+- `xs`: 1rem; /_ 16px _/
+- `s`: 1.5rem; /_ 24px _/
+- `m`: 2rem; /_ 32px _/
+- `l`: 2.5rem; /_ 40px _/
+- `xl`: 3rem; /_ 48px _/
+- `xxl`: 3.5rem; /_ 56px _/
+- `full`: 100%;
+
+The attribute available are:
+
+- `data-margin`: all margins
+- `data-margin-vertical`: top and bottom margin
+- `data-margin-horizontal`: left and right margin
+- `data-margin-top`: top margin
+- `data-margin-bottom`: bottom margin
+- `data-margin-left`: left margin
+- `data-margin-right`: right margin
+- `data-padding`: all padding
+- `data-padding-vertical`: top and bottom padding
+- `data-padding-horizontal`: left and right padding
+- `data-padding-top`: top padding
+- `data-padding-bottom`: bottom padding
+- `data-padding-left`: left padding
+- `data-padding-right`: right padding
+
 ## Migration from V5 and V6 to V7
 
 Styled Components has entered maintenance mode.
 
-- The first phase is to uses CSS variables and data attributes on HTML elements for theming, instead of using Styled Components themes and ThemeProvider.
-- The second phase is to convert components written in Styled Components into html and css modules and remove Styled Components.
+- The first phase was to uses CSS variables and data attributes on HTML elements for theming, instead of using Styled Components themes and ThemeProvider.
+- The second phase was to convert components written in Styled Components into html and css modules and remove Styled Components.
 
 ### Themeing