🌈 Skittles UI - v1.3.4

Live Storybook from latest Skittles build! 📖

Go to

Getting Started

Contribution

Introduction - What is Skittles UI? 🤔

Skittles UI is ACG's Mobile design system..

Skittles handles Theming for you, not just for colours, but also spacing, typography & more!

The idea is to give designers & devs the same toolbox that is constraint-based so both parties can focus on what matters most: delivering a world-class user experience; and not nit-picking the margin sizes required for a container etc.

Through the power of react-native-web we are able to showcase Skittles UI on the web.

Getting Started 🏃

In order to start using Skittles UI quickly in your React Native project, it's as simple as:

yarn add @a-cloud-guru/skittles-ui

You will also need to have the following libraries configured and installed iny our project:

• react-native-svg
• react-native-vector-icons

Usage

Once you've setup Skittles UI, you can use like so...

// MyComponent.tsx
import {
  Layout,
  Text,
  Button,
  SkittlesThemeProvider,
} from '@a-cloud-guru/skittles-ui';

export const MyComponent = () => (
  <SkittlesThemeProvider>
    <Layout>
      <Text variant={'h2'}>My Styled Heading 2</Text>
      <Button>Click Me!</Button>
    </Layout>
  </SkittlesThemeProvider>
);

If you're wondering how we just set bg to danger & it knows the value, see Styling.

Theming & Styling 🎨 💅

Styled System

Skittles UI uses styled-system which allows us to provide you components w/ 'theme-aware' props..

This means you can do cool things like:

<Layout mb="small" bg="danger">
  ...
</Layout>

Which will give our Layout the right margin bottom & background color according to our theme!

Check out the official Styled System site/docs for more info. Don't worry about the setup parts though, focus on consumption & usage of the props.

Theming 🎨

When you setup your ConfigProvider, you will to pass it a theme as a prop (otherwise falls back to default).

This theme object you provide can be one you import directly from the Rainbow package.. OR it can be entirely yours (or an override on top of an existing one)

Icons

Skittles uses SVGR to generate React components out of the SVG icons used. To add a new Icon add the SVG to assets/icons and run yarn generateIcons.

Contribution 🏗

If you'd like to setup Skittles UI for local development, please follow the steps below!

And thank you in advance 🙇‍♀️

Setup

1. Clone the ACG packages monorepo: git clone [email protected]:ACloudGuru/a-cloud-guru.git

2. Navigate to the repo: cd a-cloud-guru

3. Add a .envrc w/ contents: export NPM_TOKEN=x; this is to keep the .npmrc file happy 🙄, you don't actually need a valid token!

4. Make sure you have Direnv installed & setup correctly for your Shell environment: https://direnv.net/#getting-started

5. Run direnv allow, you should see a few logs, one setting NPM_TOKEN if successfull.

6. Navigate to Skittles: cd packages/skittles-ui

7. Install dependencies: yarn

8. Run storybook: yarn storybook

9. 🌈

Making changes

If you're just making an update to an existing Component, theme or token, you should look at the relevant stories to make sure everything looks/behaves as expected.

If you're adding a new variant of a Component (eg. new Button type), please ensure you update the relevant story for it to reflect this enhancement. Eg. for Button, you'd update the Variants story & add your new type/variant there!

Adding entirely new components will require you to setup brand new stories for them.

Please follow the same pattern for setting up stories as per existing ones (folder structure, grouping, naming, ..).

Stories 📚

Story files demo a single or set of components, with sub items for different states or alternate implementations. e.g.

Decorators can (optionally) wrap stories, providing layout and/or context for components using themes.

Our Storybook utilises DocsPage w/ the new CSF syntax!

Read more here.

import React from 'react';

import { MyComponent } from '../src/components';
import { ContainerDecorator, ContextDecorator } from './decorators';

export default {
  title: 'MyComponent',
  component: MyComponent,
  decorators: [ContextDecorator, ContainerDecorator],
};

export const first = () => <MyComponent />;
export const withProp = () => <MyComponent prop={true} />;

Releases

Everytime you make a change to any code (not docs), you MUST increment the version number field in the package.json.

We are adhering to the SemVer (semantic versioning) guidelines for our releases.

It goes like this: MAJOR.MINOR.PATCH

• Patch: increment for bug fixes & small patches
• Minor: increment for new features, enhancements & the like that are NOT breaking changes.
• Major: increment for breaking changes that require migration work by the end user etc..

Once a PR is merged w/ a bumped version, release will be automated via the acg-packages Buildkite pipeline!

Majors

As explained above, major releases equals breaking changes.

A great way to avoid small breaking changes (eg. renaming a token, theme key or component), is to create a NEW one & put a @DEPRECATED comment on the old one.

This allows users to update to the latest version w/o breaking the existing code.

However, on every major release you must do 2 things:

1. Document all migration steps necessary in Migration Guides

2. Ensure that any code w/ comment @DEPRECATED is deleted