spec-ods

SPEC Open Design System

🚧 This code is actively under development and should be considered unstable.

This repository contains the code for SPEC's Open Design System (ODS). The goal of ODS is to coherently organize design patterns and best practices to support development of user interfaces that are accessible, inclusive, and ergonomic. ODS should provide pattern libraries, design languages, style guides, coded components, brand languages, and supporting documentation. Our hope is that ODS will serve as a reference and source of truth that helps SPEC and other organizations design and build digital products.

Currently, ODS is being used in React-based projects at SPEC as an npm package. There are plans in the future to include setup instructions for Vue, Angular, and other JavaScript frameworks. If you are interested in using ODS in your project feel free to create an issue, open a pull request or reach out to us at [e-mail].

Quick Start for Create React App

• Install the npm package

npm install spec-ods

• Add the set up code to the index.js file

import { applyPolyfills, defineCustomElements } from 'spec-ods/loader'
import 'spec-ods'

applyPolyfills().then(() => {
  defineCustomElements(window)
})

• Use custom element in your code

function ExampleButton () {
  return (
    <plain-button>Click me!</plain-button>
  )
}

Detailed instructions

About

• Module published at spec-ods

Use instructions

• Run npm install spec-ods --save from the root of your project directory

2. Framework use

React

1. Import Middleware into index.js

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';

import { applyPolyfills, defineCustomElements } from 'spec-ods/loader'

// ... //

reportWebVitals();

applyPolyfills().then(() => {
  defineCustomElements(window)
})

2. Import the component into your React component

import React from 'react';
import './App.css';
import 'spec-ods';


function App() {

  const array = [
    {
      label: 'Accordion 1',
      description: 'Lorem ipsum',
      color: '#439ECA',
      width: '300px'
    },
    {
      label: 'Accordion 2',
      description: 'Lorem ipsum',
      color: '#7EC74A',
      width: '300px'
    },
    {
      label: 'Accordion 3',
      description: 'Lorem ipsum',
      color: '#F8CD41',
      width: '300px'
    }
  ]
  return (
    <div className="App">
      {
        array.map((array) => {
          return (
            <accordion-button 
            label={array.label}
            description={array.description}
            color={array.color}
            width={array.width}>
            </accordion-button>
          )})
      }
    </div>
  );
}

export default App;

Steps

Steps taken to create the component(s)

1. Create a project directory

1.1- mkdir spec-ods
1.2- cd spec-ods

2. Initialize the stencil

2.1- Run npm init stencil
2.2- Choose the component option
2.3- Name your project
2.4- Run npm install

3. Create a component.

3.1- Create component directory

mkdir src/components/my-button

3.2- Create and fill out file component.tsx

3.2.1- Create component.tsx

touch src/components/my-button/my-button.tsx

3.2.2- my-button.tsx

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

@Component({
  tag: 'my-accordion',
  styleUrl: 'my-accordion.scss',
  shadow: true
})

export class MyComponent {

  @State() toggle: boolean = false;

  @Event() onToggle: EventEmitter;

  @Prop() label: string;

  @Prop() description: string;

  @Prop() width: string;

  @Prop() color: string;

  toggleComponent() {
    this.toggle = !this.toggle;
    this.onToggle.emit({ visible: this.toggle });
  }

  render() {

    return (
      <div>
      <button class="accordion"
      style={{
        width: this.width,
        backgroundColor: this.color,
      }}
      onClick={() => this.toggleComponent()}>
      {this.label}
      {this.toggle ? <span>&#9650;</span> : <span>&#9660;</span>}
      </button>
      <div class={`content-box ${this.toggle ? 'open' : 'close'}`}
      style={{width: this.width}}>
      <p>{this.description}</p>
      </div>
      </div>
    )
  }
}

3.3- Create a component.scss file

3.3.1- Create component.scss

touch src/components/my-accordion/my-accordion.scss

3.3.2- Fill out component.scss file

* {
    font-family: 'Lato', sans-serif;
}

.container {
    display: flex;
    flex-direction: column;
    justify-content: center;
    align-items: center
}

.accordion {
    cursor: pointer;
    padding: 18px;
    text-align: left;
    border-radius: 20px;
    font-size: 1.2rem;
    font-weight: bold;
    outline: 0;
    span {
        float: right;
    }
}
 
 .open {
    display: block;
    height: auto;
    border-radius: 20px;
    border: 0.5px solid rgb(199, 197, 197);
    width: 200px;
 }

 p {
    padding: 18px;
 }

 .close {
    display: none;
 }

3.4- Insert the component into the body index.html

<body>
  <my-accordion width='100%' 
                label='Bacon Ipsum'
                color='pink'
                description="Bacon ipsum dolor amet pork chop sausage turkey spare ribs ham hock cupim pork loin capicola bacon ham filet mignon prosciutto boudin turducken. Shank corned beef burgdoggen jowl ribeye. Ham pork pastrami rump meatball buffalo venison andouille picanha fatback pork loin. Venison doner porchetta, chicken leberkas fatback burgdoggen ham andouille landjaeger alcatra. Pork belly pork jerky prosciutto leberkas tail salami tongue frankfurter turducken short loin flank."></my-accordion>
  <my-accordion width='100%'
                label='Cat Ipsum'
                color='aquamarine'
                description="Human give me attention meow i want to go outside let me go outside nevermind inside is better but cats are cute flex claws on the human's belly and purr like a lawnmower find something else more interesting, yet lick sellotape lick butt and make a weird face. The cat was chasing the mouse lick the plastic bag for furrier and even more furrier hairball but scratch at door to be let outside, get let out then scratch at door immmediately after to be let back in. "></my-accordion>
  <my-accordion width='100%'
                color='#eee'
                description="I feel empty."></my-accordion>
</body>

3.5- Run npm start

npm start

3.6- Publish your package

3.6.1- Build your component

npm run build

3.6.2- Publish your compnent

npm publish