chughes87 / dsa-ui

Design system and web component library for DSA built with Stencil, Tailwind, and Storybook. Currently a work-in-progress.

📖 dsausa.github.io/dsa-ui

@dsa-ui

This is a design system built with Stencil, Tailwind, and Storybook for Democratic Socialists of America sites and applications by the DSA National Tech Committee.

It will incorporate branding from design.dsausa.org and the mydsa figma.

DISCLAIMER: This is an exploratory respository and not yet officially endorsed by the DSA nor the National Tech Committee. While it is public for now, that is subject to change.

Getting Started

Quick Tour

This repo currently has a root package and two sibling packages, ./react and ./wc.

Each corresponds to a published package: @dsa-ui/react for native React components and @dsa-ui/wc for web components that can be used in any other framework (or no framework).

.

The root! You can run the node scripts listed below from this directory. This allows us to keep our two packages synced.

./.vs-code

Contains some settings and extension suggestions helpful for working with this toolset. Feel free to add other tweaks or disregard them if they do not suit your needs.

./react

This is a generated native React library. You should not work in this package or change any files unless you are making adjustments to the package.json or other non-generated file for publishing purposes. Any changes to the components should be made in ./wc.

./wc

This is where the magic happens. Development, testing, stories, and publishing are controlled from this directory.

/src

Generated types and a static site for development. These can be ignored.

/components

Each component has its own directory. Each contains a .tsx file that contains the component itself as well as tests and stylesheets (which can be ignored in favor of tailwind).

/stories

Story files, which can be simple like my-component.stories.tsx (which takes advantage of auto-generation) or complex. Each file can hold multiple stories with different arguments and arrangements to test and doc different states.

Start Development

yarn install
yarn start

• Installs dependencies in all three packages: root, wc, and react.
• Starts a dev build of web components and watches for changes
• Builds a custom elements manifest that helps Storybook generate helpful docs
• Starts a Storybook server on http://localhost:6006

Build For Production

yarn build:prod

Builds optimized web components and syncs the React library.

Run Tests

yarn test

Update the Version

Use patch for internal changes, minor for new features, and major for breaking changes. If you're not sure, make it minor. For more information, see semver.

yarn bump --patch

This will ensure tests pass and, bump versions on all three package.jsons, and create a version bump pull request. Once merged, the main branch will be tagged with the new version, the packages will be published to npm, and the Storybook site will be deployed.

NOTE: In order to use this command, you must have:

• No git changes compared to main
• The GitHub CLI installed active
• All tests in ./wc passing

Creating New Components

Navigate to ./wc/src/components and create a new directory for your component. The directory name should be the same as the component name. Use the prefix dsa; i.e., dsa-button or dsa-card.

Inside the directory, create a .tsx file with the same name as the directory. You can use the demo file, my-component.tsx, as a template. Additionally, create a .spec.ts file for unit tests, a .e2e.ts file for end-to-end tests, and a .css file if you need styles beyond what Tailwind provides. Please ensure near-complete test coverage.

Component Structure

import { Component, Prop, h } from '@stencil/core';

@Component({
  tag: 'dsa-component', // HTML tag
  styleUrl: 'dsa-component.css', // styles, if needed
  shadow: true, // set to `true`-- encapsulated DOM and styles
})
export class MyComponent {

  @Prop() name: string; // indicate a public prop (attribute) on the component-- establishes a public API

  private message = "My name is "; // mark an internal prop as private; use `@State()` if you need to trigger a re-render when it changes

  render() { // return JSX, just like React
    return (
      <p>
        {this.message + this.name}
      </p>
    );
  }
}

For more information on writing Stencil components, see the Stencil docs.

Adding a Story

You will also need to create a .stories.tsx file for Storybook in the ./wc/stories directory. This file will be used to generate documentation and test the component in different states.

// full, working example of a generated story
import { formatArgs } from './utils/utils';

export default {
  title: 'Example/MyComponent',
  component: 'my-component',
};

const Template = (args) => `<my-component ${formatArgs(args)}></my-component>`;

export const Default = Template.bind({});

In many cases, you will only need to change the title and component variables, and the tag name in the Template() function. If your need is more complex, consult the Storybook documentation.