📐 Designa

Visual design components for executable documents

👋 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.
style-stencila	CSS for styling semantic HTML markup in Stencila's own visual language.
style-material	CSS for styling semantic HTML markup in Google's Material Design visual language.
brand	Stencila branding elements such as fonts, logos, and illustrations.

📜 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 git@github.com:stencila/designa.git

Then install the necessary Node packages:

npm install

Build packages and watch for changes:

components: npm run build:components:watch
Styles:
- style-stencila: npm run build:styles:stencila:watch
- style-material npm run build:styles:stencila:watch
- 🏎 Note: To significantly reduce development build times you can disable the cssnano PostCSS plugins from the respective project’s .postcssrs.json file

In a separate terminal window start Storybook:

npm run storybook

An issue to improve the development experience when using Storybook can be seen here

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.

Package builds and Storybook generation are done on Travis CI. Releases are made to the sub-packages found inside the packages directory.