orange-design-system

Orange design system

Local installation

• Install node >= 6.9.0
• Clone this repository
• Install project with npm install
• Build project with npm run build (postinstall hook should run npm run build automatically after installation)

Components library

This project can be used as npm dependency which includes all components with styles and other static assets.

Prerequisites

• npm > 6.x.x
• Add SSH key of your machine to your profile at Bitbucket (https://bitbucket.org/account/user/[userName]/ssh-keys/).

Installation

npm install npm install bitbucket:lightingbeetle/orange-design-system --save

Above install master branch of this repository. For more granular control you can specify version specified as git tag via (recommended):

npm install bitbucket:lightingbeetle/orange-design-system#semver:~1.0.0 --save

This outputs:

...
"dependencies": {
  ...
  "orange-design-system": "bitbucket:lightingbeetle/orange-design-system#semver:1.0.0",
  ...
}
...

Manual installation from local filesystem

link this repository

npm link orange-design-system

or install this repository via relative path in your project

{
  ...
  dependencies: {
    "orange-design-system": "./relative/path/to/this/repository/styleguide"
  },
  ...
}

Library output

Components

Entry point of npm dependency is build/components/index.js which contains UMD build of all React components specified in src/components/index.js. You can import components directly from this package:

import { Button } from 'orange-design-system';

Styles

CSS is outputted into build/components/ folder. In most cases, two CSS files files are important:

• style.css which includes global CSS rules and also components rules
• fonts.css which includes font definitions

Other

Other static assets such as SVG icon sprite or fonts are also in the build/ folder.

Browser support

Supported browsers

Icons

Icons are using SVG sprite with reference on external file named sprite.svg. You need to store this file from build/sprite.svg somewhere in your project (or web-server) and fix-up path to the sprite file like on example below.

import { Icon } from '@orange/orange-design-system'

export const MyIcon = props => (
  <Icon spritePath="/my/public/path" {...props} />
);

Library contents and polyfills

React.js is excluded from components library and it's expected that is available in upper scope.

Runtime polyfills are not included inside bundle and library expects that polyfills listed below are available in upper scope.

Project

Folder Structure

After creation, your project should look like this:

my-app/
  README.md
  node_modules/
  package.json
  public/
    index.html
    favicon.ico
  src/
    assets/
    components/
    docs/
    layouts/
    pages/
    scripts/
    styleguide/
    styles/
    utils/
    pollyfils.js
    index.js

For the project to build, these files must exist with exact filenames:

• public/index.html is the styleguide template;
• src/index.js is the App JavaScript entry point.
• src/styleguide/index.js is the Styleguide JavaScript entry point.

You can delete or rename the other files.

• src/assets is for static assets: icons, etc..
• src/components is for components definition.
• src/docs is for global docs.
• src/layouts is for page layouts.
• src/pages is for templates of pages.
• src/scripts is for global scripts.
• src/styles is for global styles.
• src/utils is for global JS utils.
• src/styleguide is where styleguide lives.

You may create subdirectories inside src. For faster rebuilds, only files inside src are processed by Webpack.
You need to put any JS and CSS files inside src, otherwise Webpack won’t see them.

Available Scripts

In the project directory, you can run:

npm start

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

npm run build

Runs build:app and build:lib

npm run build:app

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information

npm run build:lib

Runs production build of all components from src/components. Outputs ES5 compatible bundle as UMD package.

Supported Language Features and Polyfills

This project supports a superset of the latest JavaScript standard.
In addition to ES6 syntax features, it also supports:

• Exponentiation Operator (ES2016).
• Async/await (ES2017).
• Object Rest/Spread Properties (stage 3 proposal).
• Dynamic import() (stage 3 proposal)
• Class Fields and Static Properties (stage 2 proposal).
• JSX and Flow syntax.

Learn more about different proposal stages.

Runtime supported pollyfils:

• Object.assign - used polyfill (ES2015).
• Array.from - used polyfill (ES2015).

If you use any other ES6+ features that need runtime support (such as Symbol or Promises), make sure you are including the appropriate polyfills manually, or that the browsers you are targeting already support them.

Deployment

npm run build creates a build directory with a production build of your app. Set up your favourite HTTP server so that a visitor to your site is served index.html, and requests to static paths like /static/js/main.<hash>.js are served with the contents of the /static/js/main.<hash>.js file.

Updating to New Releases

Lighter consists of @lighting-beetle/lighter-react-scripts which is a development dependency in the projects (including this one).

To update an existing project to a new version of @lighting-beetle/lighter-react-scripts, open the changelog, find the version you’re currently on (check package.json in this folder if you’re not sure), and apply the migration instructions for the newer versions.

In most cases bumping the lighter-react-scripts version in package.json and running npm install in this folder should be enough, but it’s good to consult the changelog for potential breaking changes.

Something Missing?

We are always open to your feedback.

This project was build with Lighter - Lighting Beetle's living styleguide.