@salesforce-ux/sds-guidelines v0.1.4

@salesforce-ux/sds-guidelines

About

All design guidelines for Salesforce.

Looking for specific design guidelines?

• @salesforce-ux/sds-guideline-iconography.

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:

1. A markdown file containing words and images
2. 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

1. Create a new folder with your guideline name under /src with the following criteria:
   • Has a unique name that is lowercase and kebab-case
2. In your new folder, create 2 new folders and 3 files
   1. /src - for your markdown and metadata file
   2. /src/images - for your image assets
   3. index.js
   4. package.json
3. 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.
   1. <guideline-name>.md
   2. <guideline-name>.meta.js
   3. <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.

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