React components for building accessible websites and applications fast in the look and feel of Deutsche Bahn AG.
- Component documentation in the official Deutsche Bahn Marketing Portal – this requires to be logged in; afterwards click on ‘Implementierung’ and ‘React’ to view the code documentation
- Documentation for all available components with live-coding
- Getting started
- Interactive Logo and Pulse creator with code generator – the best place to get started with your first web project
- Accessibility – what you get when you use the React components
- Join our Team on MS Teams – DB internal only
- Internal GitLab Repository – if you have access, prefer GitLab over GitHub for your merge requests
On the repository for your web app or site that will include the components, add the NPM packages if this repository as
a dependency in your package.json
.
npm install @db-design/react
or
yarn add @db-design/react
- Clone this repository
- Run
yarn
to install all dependencies - Run
yarn build:react-icons
to make assets available for development
Run yarn add-component
to bootstrap a new component for the @db-design/react
package. You can optionally provide the component name right away, e.g. yarn add-component radiobutton
.
The add-component
script will
- Ask you for a component name if not already provided as argument
- Validate and possibly reformat this name to match our naming guidelines
- Give you the option to deselect some of the files which will be created
- Let you select the section in the styleguidist documentation to add the component to
Run yarn dev
to start the perpetual creation of the component documentation.
This is a multi-package repository. Each component library is a separate Node package with its own package.json
. This
is managed via Yarn workspaces. They reside in ./packages
.
react
: Core components, for general use.react-extra
: Additional components for edge use cases.react-icons
: Icon components.
Components should be placed in the appropriate package folder, in their own subfolder.
A component typically consists of:
- A
index.js
re-exporting the default export ofcomponent-name.jsx
. - A
component-name.tsx
file containing the React component as a default export. Be sure to also export the TypeScript type of your component props prop types and default props for the component. - An optional
component-name-doc.jsx
which can contain a modified version of the component for documentation (e.g. inline Modals) - A
component-name.test.jsx
file containing all unit tests for the component. - A
README.md
containing the documentation for this component in Markdown format - A
component-name.scss
file containing all styles for the components - A file containing the snapshots generated from the stories of this component. This will be taken care of automatically and placed in a separate folder, so you don't need to care about it.
(Replace component-name with the name of your component written in kebab case accordingly)
Please ensure to follow these naming conventions as all related build processes are set up to recognize files following the naming scheme. If you did successfully, a documentation page for the component will show up when you run Styleguidist.
In order to import your React component easily in other repositories, add it as named export to the
components/index.js
file. Optionally, you can also add an index.js
file in your component subfolder.
In your target application, you can then import the component like this:
import { Button } from '@db-design/react';
yarn add-component
: Starts an assistant to bootstrap a new React componentyarn build
: Transpiles component libraries to./dist/[components-package-folder]
to be published via NPMyarn build:react
: Transpiles just the@db-design/react
package to./dist/web
.yarn build:react-extra
: Transpiles just the@db-design/react-extra
package to./dist/web-extra
.yarn build:react-icons
: Generates@db-design/react-icons
from SVG sources. This must run before any other script that requires the@db-design/react-icons
package, as the javascript files do not exist before that.
yarn build:styleguidist
: Generate Styleguidist documentation to./build
yarn build:sassdoc
: Generate SCSS documentation to./build/sassdoc
yarn build:docs
: Lints and tests components and then builds Styleguidist and Sassdoc pages to./build
yarn lint
: Lint JS & SCSSyarn lint:js
: Lint JS/TS codeyarn lint:js:fix
: Auto-fix linting errorsyarn lint:styles
: Lint SCSS codeyarn lint:styles:fix
: Auto-fix linting errorsyarn test
: Run unit tests and show coverageyarn test:coverage
: Run unit tests and show coverageyarn update-snapshots
: Update jest snapshots in case you intentionally changed the markup of your componentsyarn commit
: See writing commits- release:
yarn release:styles
- Run release-it forstyles
.yarn release:react-icons
- Run release-it forreact-icons
. It compiles required files as well.yarn release:react
- Run release-it forreact
. It compiles required files as well.yarn release:react-extra
- Run release-it forreact-extra
. It compiles required files as well.
A commit message should look like:
type: [TICKET-NUMBER] Short imperative title
[Body,
possibly multi line]
[BREAKING CHANGE:
Description of breaking change]
Optional parts are set in square brackets.
Valid examples of commit messages:
-
feat: BDDP-123 Add focus ring to Button
-
fix: Make focus ring work in Firefox In Firefox the focus ring did not appear the first time the focus was set.
-
chore: Update dependencies
-
feat: BDDP-124 Implement new sizes The new sizes improve consistency between DB and Product XYZ. BREAKING CHANGE: All buttons increased by 2 pixels in height.
Rules (you can also use Commitizen which helps generate commit messages):
- Chose a type:
feat
: A new feature/visual update (build in JavaScript and/or CSS)fix
: A bug fixdocs
: Documentation only changesstyle
: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc. this is NOT about styling components with CSS)refactor
: A code change that neither fixes a bug nor adds a featureperf
: A code change that improves performancetest
: Adding missing testschore
: Changes to the build process or auxiliary tools and libraries such as documentation generationrevert
: Revert to a commit
- Separate the type with
:
(colon + space) - Optional Jira ticket number (e.g.
BDDP-123
); if set, add one space afterwards - Mandatory subject – imperative style, 50 characters max, start titlecase, no period at the end
- Optional body
- Separate with one empty line from the first line (type, ticket number and subject)
- Separate paragraphs with one empty line
- Lists starting with
-
are OK (start titlecase)
- Optional breaking change
- Separate with one empty line from the first line (type, ticket number and subject) or the body (if used)
- Start with
BREAKING CHANGE:
(all uppercase) - Provide a summary of the breaking change in the next line
Also consider adding a changelog entry.
Instead of following all commit rules, you can use Commitizen which will ask few questions to generate the commit message automatically.
yarn commit
Tip: You can add all arguments you can add to git commit
like -p
to interactively select the lines to commit:
yarn commit -p
Each package in packages/*
which is made for publishing must have its own CHANGELOG.md
.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
It is good practice, to fill the changelog with every commit in the ## [Unreleased]
section. A changelog does not need to reflect all commits. It should provide an overview.
- Prepare
git switch main
git pull
- Publish styles
- Update version number in
packages/styles/package.json
- Add version and current date number in
packages/styles/CHANGELOG.md
(keep## [Unreleased]
above) - Format
packages/styles/CHANGELOG.md
before saving cd packages/styles && npm publish && cd ../..
(do not useyarn publish
)
- Update version number in
- Publish react (and other packages)
- Update version number in
packages/react/package.json
- Optional: Upgrade to new styles package if needed
- Add version and current date number in
packages/react/CHANGELOG.md
(keep## [Unreleased]
above) - Format
packages/react/CHANGELOG.md
before saving yarn build
cd packages/react/dist && npm publish && cd ../../..
(do not useyarn publish
)
- Update version number in
- Git
git commit
withchore: Release [email protected]
,chore: Release [email protected]
orchore: Release [email protected]/react/x.x.x
(replacex.x.x
with the version numbers used above)git tag @db-design/[email protected]
git tag @db-design/[email protected]
git push
git push --tags
git push github main
git push github --tags
- Update your projects and test
- Publish post in MS Teams / TD.P BahnX DPP & Friends / React Components
When attempting to commit files in this repository, some tasks will automatically run to ensure a consistently high level of code quality:
-
JavaScript files (.js and .jsx):
- Runs
eslint
and automatically fixes auto-fixable issues (see related JS guidelines here). - Runs
prettier
and auto-formats your code (see what it does here). - Runs all unit tests concerning the committed files with
jest
.
- Runs
-
Sass files (.scss):
- Runs
stylelint
and automatically fixes auto-fixable issues (see related Sass guidelines here).
- Runs
If any of the tasks fail (which means your code does not lint or unit tests are failing), your commit will be aborted.
You can use any modern JavaScript in your components that can be automatically transpiled. The Babel configuration is
set up to recognize ES2017 and beyond. Be aware that if you use non-transpilable modern JavaScript functions like
Object.entries
or similar, you need to manually
or automatically include a polyfill in your target repository so that browsers can
understand your code.
The code is licensed under the MIT License.
The DB logo is protected by trademark law. Further, symbols/designs which can be called up under https://marketingportal.extranet.deutschebahn.com/ are partially protected by trademark law and/or copyright/design law. They may only be used in business transactions with the express prior consent of Deutsche Bahn AG. The consent is to be obtained with reasonable advance notice at [email protected].