Skip to content

stencila/designa

Repository files navigation

πŸ“ Designa

Visual design components for executable documents

Build Status Storybook Community

πŸ‘‹ Introduction

This is the place for Stencila's visual design resources (e.g. CSS, icons, logos), styles and Web Components. The resources here are reused across a number of other repositories including our main website, the hub, and thema.

We aim to maintain browser support for popular browsers according to Browserslist, excluding IE11 and below.

πŸ“¦ Packages

This repository is a monorepo, and contains the following packages.

Name Description NPM
components Web Components built using StencilJS, styled using the style-* packages listed below. NPM
style-stencila CSS for styling semantic HTML markup in Stencila's own visual language. NPM
style-material CSS for styling semantic HTML markup in Google's Material Design visual language. NPM
brand Stencila branding elements such as fonts, logos, and illustrations. NPM

πŸ“œ Documentation

See the guide for getting started with integrating our Web Components into your site. Then, more detailed, interactive documentation for each component is available at https://stencila.github.io/designa/. For example, see the docs on the code editor and executable code chunk components.

πŸ›  Development

To get started with development, clone this repo:

git clone [email protected]:stencila/designa.git

Then install the necessary Node.js packages:

npm install

Build the styles:

npm run build:styles

Then build the components on changes,

npm run build:components:watch

πŸ‘©β€πŸ’» There are also build:styles:stencila:watch and build:styles:material:watch scripts for building styles on changes.

In a separate terminal window start Storybook:

npm run storybook

🏎 Note: To significantly reduce development build times you can disable the cssnano PostCSS plugins from the the .postcssrs.json files in packages/style-stencila and packages/style-material.

Adding Components

Create a new Storybook story and avoid using CSS classes as much as possible. Use semantic HTML tags and WAI-ARIA attributes instead. See the External Resources section below for useful references.

Once the story is written, you will need to add appropriate styles for each design system. Currently we support:

Commit Messages

Please use conventional changelog style commit messages e.g. docs(readme): fixed spelling mistake. semantic-release is enabled to automate version management: minor version releases are done if any feat(...) commits are pushed, patch version releases are done if any fix(...) commits are pushed. See the specifications for full details.

External Resources

πŸ™ Acknowledgments

We rely on many tools and services for which we are grateful ❀ to their developers and contributors for all their time and energy.

Tool Use
Testing powered by Sauce Labs Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs.