@myxplor/stardust

Stardust is a single source of truth for user interface (UI) standards at Xplor.

Intent

A consistent user experience, regardless of platform ... builds trust with customers

~Nielsen Norman Group

The primary goal of Stardust is to create a consistenly great user experience (UX) across Mobile, the Mobile Web and the Desktop Web.

🏃‍♀️ Getting Started

• Install dependencies: yarn install
• Install peer dependencies: yarn install react styled-components --peer
• Start watching for changes: yarn run watch

Development

• Playroom: yarn run playroom
• Storybook: yarn run storybook

Note: because React is a peer dependency, you may sometimes run into an error where react or styled-components is missing. You can run yarn run install:peers to add it.

Linking

You can run this repo locally and have other projects use it as their version of Stardust. From the root run yarn link, then in the project where you want to use it run yarn link @myxplor/stardust.

Note that the files the other repo will see are the ones that get published via yarn run build.

Once you're done developing, make sure you run yarn unlink @myxplor/stardust in the project you were testing against and then run yarn install --force.

You may run into errors around hooks doing this, this is caused by duplicate React versions (as this one might use its own). The easy fix for this is to delete react and react-dom from the node_modules in Stardust (better fix TBD).

Versioning

This project uses semver.

• Major: Breaking changes to existing components, removal of components
• Minor: New components, adding props to existing components
• Patch: Fixes to existing components

Release Versions

Stardust V2 was originally built alongside a series of components the design team use in Figma: https://www.figma.com/file/OooqFlQLoogScfMaaWRuIY/(Legacy---Use-Space-Design-Components)Stardust-Design-System-v2?node-id=0%3A2

Since then the design team have been putting together a Stardust V3. It is based on Stardust V2 and has general improvements, new components, and meets design requirements and ethos set by Xplor Technologies: https://www.figma.com/file/CBsAVV2b5VwRSO06PGFalB/Space-design-components?node-id=0%3A1

There is no immediate desire to move everything over to V3, but it is recommended new work be built against and use V3 where feasilble.

To manage this, we will be splitting Stardust into two maintained versions:

• V2: is now officially the "old" version of Stardust and lives on the branch v2. No major changes should happen on this branch, it is maintained only for minor and patch fixes.
• V3: is the offical "new" version of Stardust and lives in master. It will start as just a version bump of V2, and will slowly have new design and components added to it.

Updating

• Keep track of changes you make in CHANGELOG.md, so any consumers will know the impact
• Record the intended version in the CHANGELOG.md, so that during review it can be confirmed that he correct versioning is applied

Usage

import React from 'react'
import { DarkTheme, LightTheme, Heading, StardustProvider } from '@myxplor/stardust'

const themes = {
  dark: DarkTheme,
  light: LightTheme,
}

const App = () => (
  <StardustProvider activeTheme="light" themes={themes}>
    <Heading level={1}>Now you're using Stardust!</Heading>
  </StardustProvider>
)

Release

• To release a new version of stardust you need to add a changeset with the changes you made with yarn changeset
  • Select the type of change (Major, Minor or Patch) following the semver versioning rules.
  • A new file will be created inside of .changeset directory, you can commit this file alongside your other changes, and open your PR.
• After you have merged your PR, a new PR will be created for the next version of stardust.
  • The changeset will be deleted and the changelog file updated.
  • Version in package.json will be bumped following the type of change.
  • Stardust will automatically publish your changes to NPM.

Other stuff

📩 Slack

If you would like to contribute, provide feeback or chat design systems, join the #design-system Slack channel in the Xplor workspace.

Legacy notes

Stardust has seen some stuff. It went through a long development cycle where semver wasn't used, so it was very easy to have incompatible packages. Documentation was also rough.

At some point, there were some major rewrites and updates which did not maintain compatability, which meant they were never adopted. Stardust spent a long time with what was effectively a broken master, so all projects were using an old version (0.0.0-alpha24).

This release was actually pretty solid, so in the spirit of continued progress, master was rebased with this version, effectively set aside all of the work that came since. The version was bumped to 1.0.0, with the goal being to make sure that Stardust can continue to be improved and ensure that updates don't break existing projects.