Update utility package READMEs

packages/utilities/gel-foundations/CHANGELOG.md

@@ -2,5 +2,6 @@
 
 | Version | Description |
 |---------|-------------|
+| 0.1.1   | [PR#212](https://github.com/BBC-News/psammead/pull/212) Update package description and README. |
 | 0.1.0   | [PR#221](https://github.com/BBC-News/psammead/pull/221) Create initial package, pulled in from gel-constants and gel-foundations-styled-components packages. |
 

packages/utilities/gel-foundations/README.md

@@ -1,8 +1,12 @@
 # gel-foundations · [![GitHub license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/BBC-News/psammead/blob/latest/LICENSE) [![npm version](https://img.shields.io/npm/v/@bbc/gel-foundations.svg)](https://www.npmjs.com/package/@bbc/gel-foundations) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BBC-News/psammead/blob/latest/CONTRIBUTING.md)
 
-This package is a collection of constants which can be imported into your application.
+This package provides a range of string constants for use in CSS, intended to help implement [BBC GEL-compliant](https://www.bbc.co.uk/gel/articles/what-is-gel) webpages and components.
 
-[More details on the type sizes defined in this package are available here.](./typography_sizes_web.md)
+## Exports
+
+`/breakpoints` - GEL breakpoints, as well as typography breakpoints. These use the GEL grid sizes which can be found in the [GEL Grid guidelines](https://www.bbc.co.uk/gel/guidelines/grid#grid-sizes).  
+`/spacings` - GEL spacings and GEL Grid margins and gutters. These use the GEL grid spacing sizes which can be found in the [GEL Grid guidelines](https://www.bbc.co.uk/gel/guidelines/grid#spacing-layout).  
+`/typography` - GEL typography. These are based on the gel typography standard which can be found in the [GEL guidelines](https://www.bbc.co.uk/gel/guidelines/typography). [More details on how these sizes were implemented for this package are available here.](./typography_sizes_web.md)
 
 ## Installation
 
@@ -15,21 +19,27 @@ npm install @bbc/gel-foundations --save
 ```jsx
 import { GEL_GROUP_3_SCREEN_WIDTH_MIN } from '@bbc/gel-foundations/breakpoints';
 
-import { GEL_GUTTER_BELOW_600PX } from '@bbc/gel-foundations/spacings';
+import { GEL_GUTTER_ABOVE_600PX } from '@bbc/gel-foundations/spacings';
 
 import { GEL_BREVIER } from '@bbc/gel-foundations-styled-components/typography';
 ```
 
+These values can then be used directly within CSS declarations in code:
+```jsx
+import { css } from 'styled-components';
+
+const SomeStyledComponent = css`
+   @media  (min-width: ${GEL_GROUP_3_SCREEN_WIDTH_MIN}) {
+      grid-gap: ${GEL_GUTTER_ABOVE_600PX };
+      ${GEL_BREVIER};
+   }
+`;
+```
+
 To allow the typography to be fully accessible and responsive, please note that you should apply a default font-size to the document root (e.g. `html { font-size: 100% }`).
 
 Our typography uses `em` for font-size and `rem` for line-height. `em` allows modularity of components: you can change the component font-size by changing the font-size of its container. `rem` is relative to the document root, so we use that for line-height and spacing for a consistent look-and-feel across the document. You can read our [detailed analysis of "REMs vs EMs for spacing"](https://github.com/BBC-News/simorgh/blob/latest/docs/Spacing-Units.md) for more information.
 
-## Exports
-
-`/breakpoints` - GEL breakpoints, as well as typography breakpoints. These use the GEL grid sizes which can be found in the [GEL Grid guidelines](https://www.bbc.co.uk/gel/guidelines/grid#grid-sizes).  
-`/spacings` - GEL spacings and GEL Grid margins and gutters. These use the GEL grid spacing sizes which can be found in the [GEL Grid guidelines](https://www.bbc.co.uk/gel/guidelines/grid#spacing-layout).  
-`/typography` - GEL typography. These are based on the gel typography standard which can be found in the [GEL guidelines](https://www.bbc.co.uk/gel/guidelines/typography).
-
 ## Contributing
 
 Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at [the root of the Psammead respository](https://github.com/BBC-News/psammead/blob/latest/CONTRIBUTING.md).

packages/utilities/gel-foundations/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bbc/gel-foundations",
-  "version": "0.1.2",
-  "description": "A collection of gel constants",
+  "version": "0.1.3",
+  "description": "A range of string constants for use in CSS, intended to help implement BBC GEL-compliant webpages and components.",
   "repository": {
     "type": "git",
     "url": "https://github.com/BBC-News/psammead/tree/latest/packages/utilities/gel-foundations"

packages/utilities/psammead-assets/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 | Version | Description |
 |---------|-------------|
+| 0.1.3   | [PR#212](https://github.com/BBC-News/psammead/pull/212) Update package description and README. |
 | 0.1.2   | [PR#173](https://github.com/BBC-News/psammead/pull/173) Update PRs welcome link |
 | 0.1.1   | [PR#74](https://github.com/BBC-News/psammead/pull/74) Move file contents into a src directory and babel transpile prepublish. |
 | 0.1.0   | [PR#49](https://github.com/BBC-News/psammead/pull/49) Create initial package, pulled in from [simorgh](https://github.com/BBC-News/psammead/blob/latest/CONTRIBUTING.md). |

packages/utilities/psammead-assets/README.md

@@ -1,6 +1,11 @@
 # psammead-assets · [![GitHub license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/BBC-News/psammead/blob/latest/LICENSE) [![npm version](https://img.shields.io/npm/v/@bbc/psammead-assets.svg)](https://www.npmjs.com/package/@bbc/psammead-assets) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BBC-News/psammead/blob/latest/CONTRIBUTING.md)
 
-This package is a collection of variable constants which can be imported into your application.
+This package provides a collection of common assets that are likely to be required by many Psammead components or users, such as SVGs or small scripts.
+
+## Exports
+
+`/amp-boilerplate` - A helper, allowing projects using Psammead to easily pull in a versioned copy of [AMP's required boilerplate scripts](https://github.com/ampproject/amphtml/blob/master/spec/amp-boilerplate.md).
+`/svgs` - SVG icons commonly required by projects using Psammead.
 
 ## Installation
 

packages/utilities/psammead-assets/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bbc/psammead-assets",
-  "version": "0.1.2",
-  "description": "A collection of BBC assets including svgs",
+  "version": "0.1.3",
+  "description": "A collection of common assets that are likely to be required by many Psammead components or users, such as SVGs or small scripts.",
   "repository": {
     "type": "git",
     "url": "https://github.com/BBC-News/psammead/tree/latest/packages/utilities/psammead-assets"

packages/utilities/psammead-styles/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 | Version | Description |
 |---------|-------------|
+| 0.1.5   | [PR#212](https://github.com/BBC-News/psammead/pull/212) Update package description and README. |
 | 0.1.4   | [PR#173](https://github.com/BBC-News/psammead/pull/173) Update PRs welcome link |
 | 0.1.3 | [PR#74](https://github.com/BBC-News/psammead/pull/74) Move file contents into a src directory and babel transpile prepublish. |
 | 0.1.2 | [PR#72](https://github.com/BBC-News/psammead/pull/72) Update Readme's usage examples |

packages/utilities/psammead-styles/README.md

@@ -1,6 +1,11 @@
 # psammead-styles · [![GitHub license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/BBC-News/psammead/blob/latest/LICENSE) [![npm version](https://img.shields.io/npm/v/@bbc/psammead-styles.svg)](https://www.npmjs.com/package/@bbc/psammead-styles) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BBC-News/psammead/blob/latest/CONTRIBUTING.md)
 
-This package is a collection of variable constants which can be imported into your application.
+This package provides a collection of string constants for use in CSS, containing non-GEL styling details that are bespoke to specific BBC services and products
+
+## Exports
+
+`/colours` - Project-defined colours that will be required by multiple Psammead components or themes. These colours are not defined by GEL.
+`/fonts` - Project-defined font families. These fallbacks are not defined by GEL.
 
 ## Installation
 
@@ -16,6 +21,16 @@ import { C_POSTBOX } from '@bbc/psammead-styles/colours';
 import { FF_NEWS_SANS_REG } from '@bbc/psammead-styles/fonts';
 ```
 
+These values can then be used directly within CSS declarations in code:
+```jsx
+import { css } from 'styled-components';
+
+const SomeStyledComponent = css`
+    background-color: ${C_POSTBOX};
+    font-family: ${FF_NEWS_SANS_REG};
+`;
+```
+
 ## Contributing
 
 Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at [the root of the Psammead respository](https://github.com/BBC-News/psammead/blob/latest/CONTRIBUTING.md).

packages/utilities/psammead-styles/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bbc/psammead-styles",
-  "version": "0.1.4",
-  "description": "A collection of BBC colours and fonts.",
+  "version": "0.1.5",
+  "description": "A collection of string constants for use in CSS, containing non-GEL styling details that are bespoke to specific BBC services and products.",
   "repository": {
     "type": "git",
     "url": "https://github.com/BBC-News/psammead/tree/latest/packages/utilities/psammead-styles"

packages/utilities/psammead-test-helpers/CHANGELOG.md

@@ -2,5 +2,6 @@
 
 | Version | Description |
 |---------|-------------|
+| 0.1.2   | [PR#212](https://github.com/BBC-News/psammead/pull/212) Update package description and README. |
 | 0.1.1   | [PR#173](https://github.com/BBC-News/psammead/pull/173) Update PRs welcome link |
 | 0.1.0   | [PR#80](https://github.com/BBC-News/psammead/pull/80) Create initial package, pulled in from [simorgh](https://github.com/BBC-News/simorgh). |

packages/utilities/psammead-test-helpers/README.md

@@ -1,6 +1,15 @@
 # psammead-test-helpers · [![GitHub license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/BBC-News/psammead/blob/latest/LICENSE) [![npm version](https://img.shields.io/npm/v/@bbc/psammead-test-helpers.svg)](https://www.npmjs.com/package/@bbc/psammead-test-helpers) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BBC-News/psammead/blob/latest/CONTRIBUTING.md)
 
-This package is a collection helper methods used for snapshot testing, with support for styled components.
+This package provides a collection of helper methods for implementing Jest snapshot tests for styled-components, required by many Psammead components.
+
+## Exported Functions
+
+| Name                       | Arguments        | Description  |
+|:---------------------------|:-----------------|:-------------|
+| shouldMatchSnapshot        | title, component | Renders the component using react-test-renderer, converts it to JSON and asserts that it matches the given snapshot, which will be saved in the `__snapshots__` directory. The first argument `title` is the title for the test. |
+| shallowRender              | component        |  Shallow renders the component using react-test-renderer and returns the render output |
+| shouldShallowMatchSnapshot | title, component | Shallow renders the component using react-test-renderer and asserts that it matches the given snapshot, which will be saved in the `__snapshots__` directory. The first argument `title` is the title for the test. |
+| isNull                     | title, component    | Renders the component using react-test-renderer, converts it to JSON and asserts that it is null. The first argument `title` is the title for the test. |
 
 ## Installation
 
@@ -19,15 +28,6 @@ shouldMatchSnapshot(
 );
 ```
 
-## Functions
-
-| Name                       | Arguments        | Description  |
-|:---------------------------|:-----------------|:-------------|
-| shouldMatchSnapshot        | title, component | Renders the component using react-test-renderer, converts it to JSON and asserts that it matches the given snapshot, which will be saved in the `__snapshots__` directory. The first argument `title` is the title for the test. |
-| shallowRender              | component        |  Shallow renders the component using react-test-renderer and returns the render output |
-| shouldShallowMatchSnapshot | title, component | Shallow renders the component using react-test-renderer and asserts that it matches the given snapshot, which will be saved in the `__snapshots__` directory. The first argument `title` is the title for the test. |
-| isNull                     | title, component    | Renders the component using react-test-renderer, converts it to JSON and asserts that it is null. The first argument `title` is the title for the test. |
-
 ## Roadmap
 
 There is currently a plan to migrate from `react-test-renderer` to `enzyme` as it provides a nicer higher-level API over the same functionality, as well as having support for more granular unit tests.

packages/utilities/psammead-test-helpers/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bbc/psammead-test-helpers",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "main": "dist/index.js",
-  "description": "A collection of helper methods for react snapshot testing with support for styled components",
+  "description": "A collection of helper methods for implementing Jest snapshot tests for styled-components, required by many Psammead components.",
   "repository": {
     "type": "git",
     "url": "https://github.com/BBC-News/psammead/tree/latest/packages/utilities/psammead-test-helpers"