@salesforce-ux/sds-guidelines
About
All design guidelines for Salesforce.
Looking for specific design guidelines?
Installation
Use npm to install the SDS Design Guidelines:
npm install --save-dev @salesforce-ux/sds-guidelines
Usage
A design guideline is made up of two things:
- A markdown file containing words and images
- A metadata file containing usage guidelines
{
html: '<h2 id="overview">Overview</h2>\n' +
'\n' +
'<p>Five types of icons are used to communicate information within Salesforce, each with variations based on use case and representation. From most to least used, they are:</p>\n' +
...,
meta: [{
name: 'iconography',
category: 'brand',
file: 'iconography.md',
status: 'DRAFTED',
created_at: 'YYYY-MM-DD',
updated_at: 'YYYY-MM-DD',
platforms: ['Web', 'iOS', 'Android', 'Aura'],
systems: ['slds'],
}]
}
Other File Formats
Additionally, these other formats are available for use:
markdown
html
commonjs
These file formats are located under /dist
and do not have metadata.
Adding a new guideline
If you plan to add a new guideline, please ensure the following requirements are met:
- Has been approved by the SDS governing body
- Solves universal design problems at Salesforce
Good to go?
Instructions
- Create a new folder with your guideline name under
/src
with the following criteria:- Has a unique name that is lowercase and kebab-case
- In your new folder, create 2 new folders and 3 files
-
/src
- for your markdown and metadata file -
/src/images
- for your image assets index.js
package.json
-
- In
/src
, add 3 new files. 1 for your markdown file to author your guideline, 1 for your metadata, and 1 to tell storybook to render your newly written design guideline.<guideline-name>.md
<guideline-name>.meta.js
<guideline-name>.stories.js
What goes in each file
src/<guideline-name>.md
The main file to author your design guideline. This file is authored using markdown.
src/<guideline-name>.meta.js
The main metadata file.
Example
module.exports = [
{
name: 'iconography',
category: 'brand',
file: 'iconography.md',
status: 'DRAFTED',
created_at: 'YYYY-MM-DD',
updated_at: 'YYYY-MM-DD',
platforms: ['Web', 'iOS', 'Android', 'Aura'],
systems: ['slds'],
},
];
Data Structure:
-
name
- type:string
- Name of your design guideline -
category
- type:string
- Category your design guideline resides in -
file
- type:string
- Name of your markdown file -
status
- type:string
- Status of your design guideline. -
created_at
- type:string
- Date created (YYYY-MM-DD) -
update_at
- type:string
- Date updated (YYYY-MM-DD) -
platforms
- type:array
- Platform the design guideline applies to -
systems
- type:array
- Subsystem the design guideline applies to
src/<guideline-name>.stories.js
The file to display your design guideline in Storybook.
Example
import IconographyMarkdown from './iconography.md';
export default {
title: 'SDS Guidelines/Brand',
};
export const Iconography = () => IconographyMarkdown;
index.js
The main module for your design guideline.
Example
'use strict';
const content = require('./dist/iconography');
const meta = require('./dist/iconography.meta');
module.exports = {
content: content.html,
meta: meta[0]
};
package.json
The main file that describes the package.
Example
{
"name": "@salesforce-ux/sds-guideline-iconography",
"version": "0.0.0",
"description": "Salesforce brand guideline for Iconography",
"author": "Salesforce UX",
"license": "SEE LICENSE IN README.md",
"scripts": {
"dist": "lerna run dist --scope @salesforce-ux/sds-guidelines",
"dist:assets": "lerna run dist:assets --scope @salesforce-ux/sds-guidelines"
}
}
Building out your Guideline
We provide a few web components to help with building your guideline layout.
Implementation Detail
If you are using SDS Design Guidelines in your own Storybook environment then you need to import the Web Component definitions into your project. This file is available at
@salesforce-ux/sds-guidelines/lib/components/define
Components
<sds-guideline-wrapper>
Provides default styling in Storybook (should be the first thing in markdown file). Accepts slotted content.
Usage
<sds-guideline-wrapper>
<!-- Your html/markdown goes here -->
</sds-guideline-wrapper>
<sds-guideline-figure>
Display images with optional captions.
Attribute | Type | Value | Description |
---|---|---|---|
caption |
string |
Sets caption below the image. | |
position |
string |
start /end
|
Floats image to the left or right of content. |
width |
string |
50 |
Sets width of image to 50%. Useful when used with position . |
guidance |
string |
do /dont
|
Provides visuals for do and don't guidance. |
Usage
<sds-guideline-figure>
<img src="path/to/image" alt="Useful alt text for screenreaders" />
</sds-guideline-figure>
<sds-guideline-layout>
Display content in a 2 column grid. Accepts slotted content. Content will break to next line every 2 images.
Usage
<sds-guideline-layout>
<sds-guideline-figure>
<img src="path/to/image" alt="Useful alt text for screenreaders" />
</sds-guideline-figure>
<sds-guideline-figure>
<img src="path/to/image" alt="Useful alt text for screenreaders" />
</sds-guideline-figure>
</sds-guideline-layout>
Bundling the design guideline
Once you have all the files setup and updated with information pertaining to your design guideline. We need to build the assets to be used for exporting your module and displaying it in Storybook.
To build your design guideline, run the following:
lerna run dist --scope @salesforce-ux/sds-guidelines
Publishing the design guideline
TBD