📐 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.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:

• Stencila's own design system
• Material Design system

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

• WAI-ARIA
• Inclusive Components
• TailwindCSS

🙏 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
	Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs.