@jayway/alstom-ui

alstom-ui

This is a draft for a set of reusable components for the Bombardier projects. It is meant as a configurable and extendable toolkit to follow the consistent design language om the Bombardier brand.

To extend components

All components are basing the design on the CSS custom properties definied in src/base and for each component, making it easy to change the design by adding a new css file defining a set of rules like

:root {
  --gap-width-normal: 2rem;
  --button-border-radius: 2rem;
}

To understand which components are included in the toolkit and how they can be used, start the styleguide by running yarn start.

Project setup

yarn install
yarn link
yarn start

In your project where you widh to use the components

Symlink folder to project

yarn link alstom-ui

Install dependencies

yarn add -D babel-plugin-module-resolver postcss-conditionals postcss-custom-media postcss-import postcss-load-config postcss-mixins postcss-preset-env svg-inline-loader

Create config files

babel.config.js

module.exports = {
  presets: ['@vue/cli-plugin-babel/preset'],
  plugins: [
    [
      'babel-plugin-module-resolver',
      {
        alias: {
          ui: 'alstom-ui/src'
        }
      }
    ]
  ]
}

postcss.config.js

module.exports = require('alstom-ui/postcss.config')

vue.config.js

module.exports = {
  runtimeCompiler: true,
  chainWebpack: (config) => {
    const svgRule = config.module.rule('svg')
    svgRule.uses.clear()
    svgRule.use('svg-inline-loader').loade('svg-inline-loader')
  }
}

postcss.config.js

module.exports = require('alstom-ui/postcss.config')

Contributing

This is a standalone library of components meant to be used in multiple Alstom projects. It is therefor important that any changes are backwards compatable with any current use of its content, allowing for future updates without the risk of breaking the UI.

Always keep in mind that the components in this project should be general enough to be able to use in other applications. If you have a specific component used in only one application, it might be better to have it part of that application source code.

Specific design needs can also be accomplished by extending the component in your project. FOr instance most components declare their design rules using CSS custom properties. These can easily be hijacked and changed for local variations.

For example:

.MySpecialButton {
  --button-radius: 50%;
  --button-height: 3em;
  --button-padding: 1em;
}

This way we won't break the design by overriding it's class name styling, and make sure the components will work for future versions.

Applying changes

Can the changes be accomplised using properties, additional class names and extended data, updates can probably be done without risk of breaking backwards compability. But only if the additional properties makes sense.

To change the current behaviour of a component, make sure it's previous use cases are still valid.

Test and document use cases.

Each component in this project has (should have) a markdown file with the same file name. In this file the component use cases should be documented with examples. When starting up the styleguide yarn styleguide all components will render the code expamples from these markdown files in a styleguide, where it is easy to see all props, documentation and example of how the component is meant to be used.

Make sure the component works in isolation before implementing it in any application.

Publish to npm

To publish changes to npm you need access to the Jayway npm organization.

Then login using your npm profile using.

npm login

When code changes are approved and tested you create a new version by calling

yarn bump

or npm run bump, which will version a patch, tag and push the version to github and publish your current project to npm package registery.

For major changes you can change version manually using

yarn version --minor
# or yarn version --major

git push --tags
npm publish