JavaScript CSS Ruby
Clone or download
Permalink
Failed to load latest commit information.
.github fix(stale-bot): change to 120 days and include exempt labels (#3375) Jul 5, 2018
.scss-linters Add custom linter to prevent breaking the scoped build Mar 4, 2016
__fixtures__/ui chore(documentation): add back s1 badges Sep 19, 2017
__tests__ chore(build): remove unused dependencies Mar 12, 2018
assets feat(welcome-mat): new image asset, center alignment of content in sa… Feb 15, 2018
design-tokens chore(tokens): Add new token for brand primary at 40% opacity (#3161) Mar 22, 2018
docs chore(documentation): update contributing.md Aug 31, 2017
scripts fix(webpack): fix IE 11 docblock bug (#3255) May 4, 2018
shared chore(build): remove unused dependencies Mar 12, 2018
ui chore(release): release 2.6.2 (#3368) Jun 29, 2018
.babelrc chore(previewer): upgrade Mar 8, 2018
.editorconfig Merge pull request #1404 from salesforce-ux/summer-16 Aug 18, 2016
.eslintignore Ignore the design-tokens directory Sep 2, 2016
.eslintrc.yml Format jsx? files with prettier Aug 29, 2017
.esmrc chore(build): consolidate gulp tasks Mar 5, 2018
.gitattributes Initial commit Sep 4, 2015
.gitignore feat(issues): add stale bot (#3366) Jun 29, 2018
.hound.yml Enable ESLint in HoundCI Jun 13, 2016
.scss-lint.yml Adjust sass linter to accept annotations, disable mergeable selector … Jan 27, 2017
.stylelintrc.yml chore(lint): break build on lint errors Oct 17, 2017
.stylestatsrc Compare local CSS stats with the public version Mar 3, 2016
.travis.yml chore(build): tests Mar 5, 2018
CONTRIBUTING.md update file path Aug 31, 2017
ISSUE_TEMPLATE.md chore(github): Add issue template (#2346) Apr 17, 2017
LICENSE-font.txt Add license files at the root of the project Feb 16, 2017
LICENSE-icons-images.txt Add license files at the root of the project Feb 16, 2017
LICENSE.txt Add license files at the root of the project Feb 16, 2017
MAINTAINERS.md chore(docs): adds release checklist to the maintainers docs (#2873) Oct 31, 2017
PULL_REQUEST_TEMPLATE.md Merge Spring 18 into Summer 18 (#3001) Jan 9, 2018
Procfile Remove Heroku Babel compilation Dec 14, 2015
README-dist.md Update readme to BSD 3 Feb 16, 2017
README.md Update README.md Mar 5, 2018
RELEASENOTES.md chore(release): release 2.6.2 (#3368) Jun 29, 2018
Salesforce_CLA.pdf Initial commit Sep 4, 2015
browserslist Link to the browser support page Jul 21, 2016
gulpfile.js chore(gulp) update gulp commands in the comments Apr 16, 2018
jest.helpers.js fix(build): correctly update snapshots Mar 5, 2018
jest.setup.global.js fix(build): correctly update snapshots Mar 5, 2018
jest.setup.js chore(build): tests Mar 5, 2018
jest.teardown.global.js chore(build): refactor getMarkupAndStyle Mar 5, 2018
package.json chore(release): release 2.6.2 (#3368) Jun 29, 2018

README.md

Salesforce Lightning Design System Build Status

Welcome to the Salesforce Lightning Design System brought to you by Salesforce UX.

  • Tailored for building Salesforce apps: Using the Lightning Design System markup and CSS framework results in UIs that reflect the Salesforce Lightning look and feel.
  • Continuously updated: As long as you’re using the latest version of the Lightning Design System, your pages are always up to date with Salesforce UI changes.

Quick start

  1. Clone the project with git clone https://github.com/salesforce-ux/design-system.git
  2. Run npm install in the root design-system folder.
  3. Run npm start to launch the Previewer.
  4. Visit http://localhost:3003/local/preview

Having trouble getting these steps to work on your machine? Follow the troubleshooting guide below.

Previewer

previewer component/variant/modifier selection

The previewer is an interactive tool for creating components.

It runs at the designated url on startup and is the primary means of viewing your work - it will live update as you make changes.

You can choose the component, variant, and modifiers to preview as well as background color and screen size. It also previews the sass docs.

Everything in the design system is driven by annotations and the previewer is no different. To see any work in the previewer, you must add annotations to your code.

Annotations

Annotations are the metadata that describe the entire system.

The most intriguing part is the @selector/@restrict pair. Each CSS selector should have a corresponding selector describing where it can be applied. Both are normal CSS selectors that will behave like a DOM query.

For example:

/**
 * @selector .slds-button
 * @restrict button, a, span
 */
.slds-button {
  ...
}

/**
 * @selector .slds-button_brand
 * @restrict .slds-button
 */
.slds-button_brand {
  ...
}

In this example we can see that .slds-button_brand must be applied to a .slds-button, which, in turn, must be applied to a button, a, span.

It's important to know that slds-button_brand will only be associated to the button component via this @restrict chain. Each rule uses its @restrict to declare its place in the hierarchy - it is not the the file that tells us to which component a selector belongs

For a more complex example, see: https://github.com/salesforce-ux/design-system-internal/blob/summer-17/ui/components/combobox/base/_index.scss

While there is a handful of annotations used throughout the codebase, you'll only need to know a few to get started:

  • @base: creates a new component
  • @variant: a component implementation with corresponding markup
  • @modifier: a class that alters appearance when applied to existing markup

The markup for a @variant will be required from the /ui/:component/:variant/example.jsx.

For example:

/**
 * @name advanced
 * @selector .slds-table_fixed-layout
 * @restrict .slds-table
 * @variant
 */

Folder Structure:

ui/
└── components/
    └── data-tables/
        ├── _doc.scss
        ├── _doc.mdx
        └── advanced/
            └── example.jsx
            └── _index.scss

All other selectors which are not @base/@variant/@modifier are considered child elements of a component.

For more information see the Full annotation docs

Tasks

npm start

Start the Lightning Design System preview app.

npm run gulp -- lint

Lint the code base for syntax and stylistic errors.

# Lint indentation, Sass, JavaScript files
npm run gulp -- lint

# Lint languagesindependently
npm run gulp -- lint:sass
npm run gulp -- lint:javascript
npm run gulp -- lint:javascript:test
npm run gulp -- lint:spaces
npm run gulp -- lint:html

# HTML5 validation
npm run gulp -- lint:vnu
# HTML5 validation on comma separated component names
npm run gulp -- lint:vnu --components button, path, trees

# a11y validation
npm run gulp -- lint:a11y
# a11y validation on comma separated component names
npm run gulp -- lint:a11y --components button, path, trees

# Lint examples using vnu, aXe, slds validation, and HTML5 validation
npm run gulp -- lint:examples

Compilation

npm run build && npm run dist

Generate the Lightning Design System into the .dist directory.

npm run gulp -- styles

Compile Sass to CSS into .assets/styles.

npm run gulp -- clean

Delete temporary build and local files.

Stats

npm run gulp -- styles:stats: Useful stats about the project's deliverables.

Tests

npm test: run all tests

Troubleshooting

npm and Node.js

The Salesforce Lightning Design System uses npm to manage dependencies. Please install Node.js, and try running npm install again.

If Node.js is already installed, make sure you’re running v8 or up.

JavaScript and compilation issues

JavaScript dependencies sometimes get out of sync and inexplicable bugs start to happen. Follow these steps to give a fresh start to your development environment:

  1. The installed npm version must be at least v3.10. You can update your npm with: npm install npm -g (sudo may be required).
  2. Re-install dependencies: rm -Rf node_modules && npm install
  3. npm start

If this did not work, try running npm cache clean and repeat the above steps.

Contributing to the code base

See CONTRIBUTING.md.

Licenses

Got feedback?

Please open a new GitHub Issue.