Getting started with Elements

Consuming this SDK

We recommend that you install Elements in your project using npm:

npm install --save pearson-elements

The installation provides both the dist version with CSS, and the original source SCSS, with required assets. This allows the option for the consuming app to include the SDK as a static asset or as part of a build process.

To comment out any SCSS file so it's not added to your rendered elements.css, open /scss/elements.scss and use JavaScript-style commenting. Example:

    // base variables
    @import 'base/variables';

    // base HTML tags
    //@import 'base/html-tags';

    // typography
    @import 'elements/typography/font-face';

The above would prevent the _html-tags.scss styles from being transpiled into the elements.css file.

NOTE: if desired, Elements SDK ships with a version that does not include any styling on plain HTML tags. Simply include the dist/css/elementsNoPlain.css or dist/css/elementsNoPlain.min.css files or add the /scss/elementsNoPlain.scss file to the project.

Important: Fonts and Icons

The Elements SDK looks for the /fonts and /icons folders at the root of your served application. Copy the npm-installed /fonts and /icons to the correct location in your web server, and ensure your application is set up to allow the font files to download correctly and not filter out the response header Content Type (i.e. 'application/x-font-ttf') so the fonts may be rendered in the browser.

Internet Explorer

Some caching headers will prevent Internet Explorer from showing font files after a refresh. The culprits are Cache-control: no-store and on https Pragma: no-cache.

Icons

This version of Elements uses an SVG sprite for icons (the Pearson logos are two separate SVGs, not part of the sprite). The sprite file is found in /dist/icons/ in Elements, and should be copied to the appropriate place, as mentioned above, in your web server. In additional, to support Internet Explorer and some versions of Android where the default-Chrome browser is actually webkit, that SVG sprite must be present on your application's page. See the icons page under "Two methods of including icons" for examples of getting this sprite on your application page. Additionally, there are instructions on that page for how to add new icons.

Contributions

Please review the guidelines for contributing before getting started.

You must have Node.js v5 installed.

Clone the project and install the dependencies:

git clone https://github.com/Pearson-Higher-Ed/elements.git
cd elements
npm install

Adding Icons

See the icons documentation under "Adding new icons" for the process of adding a new icon.

Build the Documentation

Contibutors adding wholly new components to Elements (which have been already approved by UX design), in addition to writing CSS for the component, will also need to add a new component page to the docs.

We use Metalsmith to generate the documentation. To add a new component to the docs:

update /docs/_data/nav.yaml file with the new component name (this adds it to the menu)
add a new .md file to /docs/elements/ (use any of the other files in that directory as an example)

The new component's document page should:

have some explanation of what the purpose of the element or component is
have some example HTML (wrapped in demo tags, you can show both the rendered in-browser version as well as the actual HTML code in one go) for other developers to see where to best add Elements classes
have any special use notes if needed, such as accessibility or browser support gotchas

To view your changes or some branch in action:

npm start

This will give you a browser-sync served copy of the docs on http://localhost:3000, and build the latest version of elements.min.css to /dist.

Fork repo

Forked repo will not trigger the 'ux-test-platform' tests. In the logs, you would see this error: {"error":"Travis encountered an error, sorry :("} which may cause the elements build to fail.

To handle this, follow below steps to have successful build runs:

cd elements
travis login --org *Provide your github login and password
travis token --org *Copy the access token
travis encrypt AUTH_TOKEN=access_token *Copy this token and replace it with env: global: secure: <<access_token>> in .travis.yml file

Push this change and the ux-test-platform build would be triggered successfully.

Element Design Document Version

List of Elements with their current respective design version:

( Design Document Site )

Element	Current Design Version
Typography	v2.0.0
Color	v2.1.0
Icons	v2.1.0
Buttons	v2.1.2
Inputs	v2.0.1
Grid	v1.0.0
Presentation Strategies	v1.0.0
Templates	v2.0.0-beta.2
Responsive Utilities (Breakpoints)	v1.0.0
Forms	v1.0.0-beta.3

** Developers should update table as they implement new versions...

Acknowledgements

This project was inspired by other popular front-end frameworks published under the MIT license: