Sparkgeo Design System Components and Tokens

This is a work in progress. Dont use this for anything but playing around and critiquing development.

Purpose

• Create reusable design components, themes and a token system to be used for easy theme creation.

Goals

• keep basic UX components easily consistent across projects.
• save developers time when they want to use Sparkgeo-looking components.
• allow for branding and basic look-and-feel overriding on a project-level/client level.
• ensure it is possible to create officially supported themes in addition to the default theme provided.

Out of Scope:

• Advanced theme overriding or all css properties and every possible edge case. If a project requires a look-and-feel that is very different from the official themes or adds unreasonable complexity to the code base that makes it hard to maintain, that project has the option of creating their own components. The purpose of these components is consistency while allowing basic 'reasonable' flexibility for project-level branding. That said, currently it is possible to override most things with styled components, so if its not a lot of extra effort, keep advanced overrides as a stretch goal, but dont let it distract.
• Developer helper functionality. If there is a desire to expand upon these components beyond what is in-scope here, a separate repo can be created that wraps these DS components. For example, if we would like to add helper props or methods to make life easier for developers, that goes in another library. This repo is for design-scope only. A layout component might be in scope, but a simpleEasyMap creator component likely isnt. Reusable cartographic theming or map control components might live here or at least be linked from the readme. Mapbox, Leaflet, D3, etc. helpers are worthy projects, but need to live in a different repo with a different scope.

Consuming Components (WIP)

Notes:

• keep a close eye on this repo's peer dependencies. When composing a component in another project, you will need to add some or all of the peer dependencies listed here.
• to avoid name collision with other themes a project may use, these components use the designToken namespace for their styling
• this guide assumes you are familiar with React and Styled-Components

Currently Available Components

| Name | Non-native Paramaters | Desctiption | | - | - | -| | ButtonPrimary | errorMessage: string: optional error styling and message | | ButtonSecondary | errorMessage: string: optional error styling and message | | ButtonTertiary | errorMessage: string: optional error styling and message | | ButtonCaution | errorMessage: string: optional error styling and message | | ButtonCallToAction | errorMessage: string: optional error styling and message | | H1-H6 | | Headers | | TextTiny | | | InputText | id: string: requirederrorMessage: string: optional error styling and messagehelperText: string: optional description text to replace placeholderlabel: string: optional aria-compliant label | Aria-compliant text input that disallows the placeholder attribute| | InputPassword |id: string: requirederrorMessage: string: optional error styling and messagehelperText: string: optional description text to replace placeholderlabel: string: optional aria-compliant label | Aria-compliant password input that disallows the placeholder attribute|

Basic Use with Default Theme:

1. Import the component library yarn add test-mmnoo-shared-components (temporary pre-release package location)
2. Install the listed peer dependencies in your project repo

• yarn add styled-components

1. At the root of your application, supply a ThemeProvider component with the theme you want to use

2. A SparkgeoTopLevelStyling component is available (rem units will not take this into account)

3. 1. Use the component like you normally would

   Example:

   import {
     ButtonPrimary,
     sparkgeoDefaultTheme,
     SparkgeoTopLevelStyling,
   } from "test-mmnoo-shared-components";
   import { ThemeProvider } from "styled-components";
   import styled from "styled-components/macro";
    
   function App() {
     return (
       <ThemeProvider theme={sparkgeoDefaultTheme}>
         <SparkgeoTopLevelStyling>
           Inherits font-family and font-size from the SparkgeoTopLevelStyling component
           <ButtonPrimary>A DS button</ButtonPrimary>
         </SparkgeoTopLevelStyling>
       </ThemeProvider>
     );
   }
   
   ...

Overriding tokens

1. import and use the overrideTheme function ensure proper merging.

     import {
       overrideTheme,
       sparkgeoDefaultTheme,
     } from "test-mmnoo-shared-components";
        
     // Overrides need to have a 'ds' property
     const newTokens = {
       ds: {
         color: {
           brand: 'magenta',
           error: 'pink',
           textLight: 'yellow',
           link: 'brown',
         },
         button: {
           colorTextSecondary: sparkgeoDefaultTheme.ds.color.text,
         },
       },
     }
     const overridenTheme = overrideTheme(sparkgeoDefaultTheme, newTokens)
   

2. Use your new theme in a ThemeProvider

   <ThemeProvider theme={overridenTheme}></ThemeProvider>

Overriding DS Components in your project or theme

1. Use Styled Components to override a DS component

     const CustomizedButtonPrimary = styled(ButtonPrimary)`
       box-shadow: 10px 5px 5px red;
       & :hover {
         transition: transform 1s ease all;
         transform: rotate(360deg);
       }
     `;

Developing Components

Engineering Goals

• use minimal dependencies

• maintain an api as close as possible to the native elements

• aim for good developer experience. This means keeping the readme up-to-date, ensuring design tokens are simple and their names are intuitive and discoverable

Out of Scope

• being framework agnostic
• being useful outside of Sparkgeo

Current Proposed Development Steps:

1. Clone the repo locally

2. yarn install

3. yarn test to run tests

4. A component generator exists to scaffold component files. Run plop [componentname].

5. For visual inspection and documentation we currently have two options:

   • Storybook. To use it run yarn storybook. This will compile and visualize all compoents with a <component name>.stories.js file name type. Please include these files within the component folder.
   • A demo create-react-app app. To use it, run yarn start, and modify the files inside the Demo folder as you work. We're keeping it around for now for scenarios where storybook might not suffice. This is expected to be removed later.

6. Please commit changes to separate branch and create a PR. Because of the technical debt potential of this library, this repo has mandatory code reviews by the following developers [@mmnoo, @alanjleonard, x, y, z]}. @mmnoo will sign off on engineering-related things, @alanleonard will check the look-and-feel

7. After your review, let the #xxxxxxxx channel on slack know about the availability of your component (?)

Dev Guidelines

1. If you remove or rename a token, you must make sure to update everthing that consumes it in the library, including tests.
2. If new tokens are created, tests must be written for them
3. Only create tokens that are consumed in an existing component. Avoid hypothetical tokens (they become orphans pretty quickly)
4. Token naming convention is for easy autocomplete browsing and token sorting. Instead of .button.PrimaryBackgroundColor, button.colorBackgroundPrimary is used. For autocomplete, you can just type 'color' and see whats available (if we set up types)
5. Component naming is . Eg 'ButtonIcon' instead of 'IconButton'

Tech Stack

• React
• Styled Components
• React Testing Library
• Prettier

To Do:

• [x] Configure with React Testing Library
• [x] Figure out simple development workflow for local visual during-development testing (currently have both Storybook and a demo CRA to choose from)
• [x] Figure out how to elegantly deal with theming
• [ ] Refine Readme
• [ ] figure out Sparkgeo npm install path for component library
• [x] Configure linter
• [x] install Storybook
• [x] figure out how to automatically deploy storybook on push (using Netlify)
• [x] configure addonn for documentaiton (pulls from props and docgen comments)
• [ ] figure out and articulate when to hardcode CSS and when to use a token. (Try not to over-engineer. This just makes the code harder to maintain. Limit tokens to properties that are anticipated to be used in simple re-theming because users can always use styled components to override component styles in a project. ????)

Initial library stucture partially inspired by 'Create Library of React Component'