Psammead is a GEL-compliant React component library for the BBC, built on styled-components.
Psammead packages are split into:
- Components - GEL-compliant presentational React components, ready for use out of the box, regardless of data source.
- Utilities - Commonly shared Psammead dependencies, and fundamentals to aid building additional GEL-compliant components.
git clone git@github.com:bbc/psammead.git
cd psammead && npm run install:packages
N.B. When merging branches, the npm run install:packages command should be favoured over npm install. More details available here.
Install dependencies locked to package-lock.json:
npm run ci:packages
(NB: You can't reliably run the jest tests when the packages are linked locally, as they may have been linked across breaking changes. Running npm run ci:packages resets all links. To update snapshots within unit tests, run npm run updateSnapshots.)
Run the component tests:
npm test
This runs Jest across any packages matching this glob pattern: packages/components/**/*.test.jsx. It also runs each package's npm test command if it is defined.
npm run storybook
NB, we've defined global styles (normalize, box-sizing, Reith font) in the Storybook config so that components render as expected.
npm run build
When making changes to a package locally if you want to pull those changes into another psammead package then the following command will create the required symlinks for you.
Run the following command to link all psammead packages up regardless of dependency version:
npm run install:packages:link
These components have been tested in an environment which uses normalize and box-sizing: border-box for consistent behaviour across browsers. Additionally, many components depend on the BBC Reith font having been defined.
You can do this in pure CSS:
<link
rel="stylesheet"
href="https://necolas.github.io/normalize.css/8.0.0/normalize.css"
/>
<style>
/* Box Sizing https://bit.ly/1A91I0J */
html {
box-sizing: border-box;
font-size: 100%;
}
*,
*:before,
*:after {
box-sizing: inherit;
}
@font-face {
font-display: optional;
font-family: "ReithSans";
font-style: normal;
font-weight: 400;
src: url('https://gel.files.bbci.co.uk/r2.302/BBCReithSans_W_Rg.woff2')
format('woff2'), url('https://gel.files.bbci.co.uk/r2.302/BBCReithSans_W_Rg.woff')
format('woff');
}
@font-face {
font-display: optional;
font-family: "ReithSerif";
font-style: normal;
font-weight: 600;
src: url('https://gel.files.bbci.co.uk/r2.302/BBCReithSerif_W_Md.woff2')
format('woff2'), url('https://gel.files.bbci.co.uk/r2.302/BBCReithSerif_W_Md.woff')
format('woff');
}
</style>Or if you're using styled-components, you can use styled-normalize (npm install styled-normalize) and createGlobalStyle to manage global styles as has been done in Simorgh.
Psammead components use styled-components.
We recommend when you use these in your application, to add the following setup:
npm install --save-dev babel-plugin-styled-components
This plugin adds support for server-side rendering, minification of styles, and a nicer debugging experience by giving meaningful names to the style classes.
Our recommended .babelrc config for this is here:
{
"plugins": [
[
"babel-plugin-styled-components",
{
"ssr": true,
"fileName": false
}
]
]
}
"ssr": true ensures that when you have server-side rendering, there won't be a checksum mismatch between the StyledComponent class on the server render and client render.
"filename": false This is to prevent the filename from appearing in the generated class name, which would generally be a duplication of the component name.
See documentation on the Styled Components site
NOTE: if you run into issues with CSS not being applied to your components, it is likely that there is a duplicate styled-components dependency somewhere in your packages. You can try running npm dedupe in most cases, or lerna bootstrap --hoist in monorepo setups such as Psammead's. Failing that, make sure your application's styled-components dependency is the same version as that in Psammead.
We strive for components to conform to the following minimum levels of support, but please check each component's individual README.
| Browser | Lowest version |
|---|---|
| Safari | 7 |
| Facebook for iPhone | 187 |
| Chrome for iOS | 68 |
| Chrome | 25 |
| Edge | 14 |
| Firefox | 48 |
| IE | 9 |
| Amazon Silk | 69 |
| Opera Mini | 4 |
| Android Browser | 4 |
| Nokia | 6280 |
| Firefox for iOS | 13 |
| Facebook for Android | 190 |
Note that these browser support levels have been defined by usage statistics for BBC News and BBC Persian.
| Software | Version | Type | Browser |
|---|---|---|---|
| ZoomText | Latest | screen magnifier | Internet Explorer 11 |
| Dragon NaturallySpeaking | 13 | speech recognition | Internet Explorer 11 |
| JAWS | 17 | screen reader | Internet Explorer 11 |
| Read&Write | Latest | screen reader | Internet Explorer 11 |
| VoiceOver | Latest | screen reader | Safari on iOS |
| NVDA | Latest | screen reader | Firefox on Windows |
Testing instructions for each assistive technology, including priority categories.
- Create an npm account with your bbc email address. https://www.npmjs.com
- In your npm profile settings, set up Two Factor Authentication. Enable it for authorization and publishing
- Back up your recovery codes for your account
- Join the BBC npm org by following the process here: https://github.com/bbc/npm When you're added to the org and signed in, you should be able to see all public and private
@bbcpackages here: https://www.npmjs.com/settings/bbc/packages
Packages are published on merge into the latest branch via our CI process. The process defaults to publishing with public access and a tag of latest, however this can be overridden using configuration on your package json.
To stop your package from publishing to NPM add the following value to your package.json
"private": true,
The access and tag of the release can be overridden from the default values by adding the following values to your package.json
"publishConfig": {
"access": "restricted",
"tag": "alpha",
}
The access value is restricted by NPM and can only be the values public and restricted.
The Psammead Storybook is hosted on GitHub pages at http://bbc.github.io/psammead. It is currently deployed via a local script that builds Storybook to the gh-pages git branch which is used by GitHub pages.
npm run deploy-storybook
NB, this automatically pushes to the 'gh-pages' branch, which deploys to the live GitHub pages site. Please only run this script on the latest branch.
Psammead is currently maintained by developers in the BBC Articles and Reach + Languages teams. If you want to open an issue, please add it to our issues page.
Contact us by email on PsammeadMaintainers@bbc.co.uk, or find us on Slack at #psammead in the bbcnews workspace.
Pronounced as sam-me-ad 'sΓ¦miΛ|Γ¦d
"The Psammead, also known as Sand Fairy, is a sapient magical creature once encountered by five children in a gravel pit".
It MIGHT stand for:
Perfectly sharable atomically modular magically engineered abstract doodads
Or it might be named Psammead to follow the mythical creature theme of related repos.
We'll let you decide!