auth0 / cosmos

🔭 Auth0 Design System

Project Status

Cosmos is a legacy project, that has now been deprecated. Consider using Quantum Design System as an alternative.

Thank you.

 

Cosmos

A Design System For Auth0 Products.

What is a design system?

“A set of shared and integrated principles and patterns that define the overall design of a product.” — Karri Saarinen @ Airbnb

The aim of Cosmos is to help Auth0 designers and developers deliver work faster and better. It provides teams with a common language and encourages adherence to design guidelines with compliant components right out of the box.

We are currently building our roadmap and initial components inventory to estimate the v1 release date. We are in active development and testing with selected teams, so the components API may change frequently. However, you can play with the alpha version today! Your feedback will help us shape Cosmos.

See the documentation at https://auth0-cosmos.now.sh/

   

Quicklinks:

• Getting started
• How to use Cosmos
• Components Overview
• Playground
• Sandbox - Storybook
• Contribution Guide

   

Installation

Ensure you have Yarn installed.

To add Cosmos to your React application, run:

$ yarn add @auth0/cosmos

If you prefer npm, run this command instead:

$ npm install --save @auth0/cosmos

That's all you need to do: no config changes required!

   

Using Cosmos components in your application

1. Cosmos provides a CssBaseline component to setup some of the base styles required (fonts, etc). It also fixes some inconsistencies across browsers and devices while providing slightly more opinionated resets to common HTML elements. Import and render the CssBaseline component once at the top of your application.

import { CssBaseline } from '@auth0/cosmos';

const App = () => {
  return (
    <>
      <CssBaseline />
      {/* The rest of your application */}
    </>
  )
};

2. Include and render them alongside your React components:

import { Button } from '@auth0/cosmos'

const Actions = () => (
  <div>
    <h1>Hello Word!</h1>
    <Button size="default" appearance="cta" onClick>
      Cosmos Documentation
    </Button>
  </div>
)

To learn more about the components and the props they offer, check the Cosmos documentation. Pick a component from the sidebar to find examples and configuration options.

   

Contribute

There's a lot to write here, we maintain it in our docs: Contribution guidelines

   

Feedback

Issues or feature requests can be created on our GitHub page or on Slack (internal). You can use the playground to test and share code, report bugs and ask for feedback.

Thanks

Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions.

Thanks to BrowserStack for providing the infrastructure that allows us to test in real browsers.

Thanks to Circle CI for providing the infrastructure for our Continuous Integration needs.

cosmos's Issues

Clicking the switch in the docs page throws an error

Process for component support

Leaving this here as a placeholder for better thoughts 😀

We need to come up with a process where teams can request components or come and contribute to the component system without the core team becoming a bottleneck. This will be crucial to the success of the design system.

Packaging + versioning strategy

This can be divided into 5 closely related questions. Feel free to nitpick/give your ideas on any of them.

1. What all do we ship? (packaging)

We have 2 code entities to ship:

1. component library
2. tokens

As tokens are a part of the cosmos system, we can ship them as a namespace in the same npm package: auth0-cosmos/tokens

import { spacing } from 'auth0-cosmos/tokens'

@import "node_modules/auth0-cosmos/tokens/colors.sass";

This can be the first incremental step of adopting cosmos into a codebase

---

2. What's our versioning model (versioning)

Once Cosmos comes out of it's alpha status, It will follow semver which means we will introduce breaking changes only in major versions (= major redesign, so not anytime soon).

If you use a component from Cosmos, you can be sure that it will not break when you update Cosmos version.

---

3. When do we freeze the API? (versioning)

As a team not directly working on the product, we are also aware that we will not always know the needs of product. For this reason, some components will be released in an experimental mode first before they make it into stable.

The way we can do this is by having a explicit namespace: cosmos/next or cosmos/beta.

Certain components can start in the next namespace and then make it to stable root import, after which their API can not change.

import { Button, Form } from 'auth0-cosmos'
import { Stack } from 'auth0-cosmos/next'

---

4. What code do we ship? (packaging)

We can transpile + bundle all the components (with tokens) into one file that we ship. We can also simply ship the source files.

I think it makes more sense to ship source files because there will always be a bundler in the application cosmos is used in either hidden inside create-react-app or a custom webpack setup. By shipping the source we give the application developers more power in terms of transpilation and tree-shaking.

(create-react-app doesn't transpile node_modules yet)

Example: If the application only supports only the last 2 versions of browsers (manage does that), they have the opportunity to have smaller bundles by shipping ES6 code. We cannot take that call for them.

On a similar note, if the application uses styled-components already, we don't want to package it with cosmos as well and end up with 2 versions of it.

Update
Here's what we do: Transpile all files in cosmos but don't bundle them into one file, ship libraries we depend on with cosmos

5. Should we ship each component in a different npm package or ship cosmos as one package (packaging)

It's important to state that this is not a performance problem, we can

1. make the imports more explicit: import Button from 'auth0/cosmos/button'
2. make sure our code is tree-shakable and promote that

This is more a question of adoption and the resulting maintenance for teams. Let me explain it with an example:

Manage and Support center both start using cosmos at 0.0.1

🔜 From the feedback of the support center team, we add more features to certain components say Button and List, we keep releasing new versions, support center keeps updating, we reach 0.0.4

🔜 Now, the team from manage comes up with a small request for Dialog, we reach 0.0.5. To upgrade, they not only have to test the Dialog, but also whatever happened since 0.0.1 which can be a lot of work. (even when we promise no breaking changes)

Maybe, they would like to only upgrade Dialog because that's what they need. Companies with multiple big teams (like atlassian) have to allow for that. So they publish each component as a different package enabling team to pick updates they like and ignore the rest.

If not done right, this can introduce design inconsistency between components in the same application.

So here's the adoption question:

Would we like teams to buy into cosmos as a whole and upgrade versions regularly? If yes, then we should not ship each package as a component. If we want to allow selective updates, we should. It's an open question at this point.

Make required props visible in docs

We could add an * next to the prop name to show that the prop is required

Expand the PoC to cover the Tickets page in Support Center

Button Component

Pending

• Render as a Link (anchor tag)
• Icons (like + Create item)
• Sizes: default | compressed | small | large

Possibility of exporting to HTML vs maintaining a CSS library for projects that are not React

Components inventory

The first step is to research Auth0 product(s) and list all components in use right now. It's like the 'State of Components'. This way we can:

• Give them an common name
• Check for similar (but slightly different components) to refactor
• List them so to keep track of what we need to build/prioritize

Basic

• Text
• Form @siddharthkp
• Field Group
• Input Field
• Form Actions
• Text Input
• Textarea Input
• Select
• Button
• Icon
• Switch
• Tooltip @beneliflo
• Tabs Navigation
• Page Header
• Breadcrumbs
• Client detail Page Header
• Badge
• Dropdown
• List/table
• List Filters
• Clients List/table
• Avatar
• Modal
• Spinner/loader
• List Pagination
• Headings
• 🚫 Switch Board -- on hold
• Empty State for tables/lists
• Form Helper text
• App Header
• App Navigation
• User Dropwdown
• Empty State

Packaging

Accessibility

cosmos should give people components that are accessible by default.

A lot of the work for accessibility is dependant on the product's flow, so we don't control that but the building blocks need to be correct first. (Example: Add for for labels by default)

Need more research here on the best way to test for accessibility and make it part of our process so that there are no regressions

Credit: @jennz0r for making me realise that our design system should have this from the start.

Decide which browsers Cosmos we want to target for support in 1.0

Decide which browser versions to support (specially IE) and if we'll need vendor prefixings for CSS. We'll use progressive enhancement.

Input: Are readonly and disabled redundant?

These seem very close in use cases.

From slack:

I think the one with different opacity comes from an use case I found where the input is not available until another event enables it. Like if a checkbox is checked that field will become full opacity and editable. Now that you pointed out, it's very edgy. Also, the label should have the same reduced opacity of the field to make more sense.
The read-only is widely used and we'll definitely keep it. I can track the "disabled" use case to see if it still makes sense to have it here.
-- @landitus

Pivot docs to start with markdown files instead of components

This will help us get the API right before creating the component itself.

Make propTypes warning visible in docs

Table Search/Filter Component

Why do we need to build our component library from scratch?

@fyockm and @auth0/crew-apollo asked some great questions, this issue tries to address one of them and serve as a place for discussion 🙂

Should we build cosmos from scratch or adopt an existing component library? (like blueprint or even a smaller bare bones library like skeleton)

It makes more sense to build out our component library from scratch because of the following reasons:

1. We can reach the same visual result by adopting a component library and customising it, but the underlying architecture would not be as good as we want it to be. This is not to say that we are smarter than the creators of these component libraries 😅, only that the end result will be an amalgam of the decisions taken by the original authors and the decisions taken by our team in the context of auth0.
   (This is different than adapting a library like hapi.js or react, because we use the public APIs that are made available by these libraries, we don't have to customise the inner parts)

2. Building it from scratch will give us a greater level of understanding and control to craft a better system. And we can implement smart optimisations for reducing bundle sizes/improving performance and improving developer experience because we control the core.

3. The component library is just one of the pieces of the component library, our brand's design philosophy and tokens are more significant - Read more on this. It will be very tricky to adopt a component library and make it work with our lower level of abstractions.

4. Because of the above reasons, It will be easier + faster to implement new components or modifications to existing components when a product team needs them. In the long run, we wish that product teams are able to contribute to the design system, and having an in-house expertise will help*

5. This isn't to say that we will develop our design systems in a cave. We will actively steal take inspiration from other design systems for patterns and architecture. In addition to that, we will adapt complex components from the community and build thin abstractions over them.

It's useful to state the cons of this approach, so that we make sure we are making a conscious decision:

1. It will take more time and humans to build out the design system in the short term. It's an investment which will reap its rewards over time.

2. Even though we'll try to do our best, our implementation will not be battle tested by the wider web community that same open source frameworks have access to.

3. This is a comment on reason number 4, even though we will have in-house expertise and support for teams wanting to contribute to the design system, the benefit of having blog posts and stack overflow questions for an established library are unmatched.

I hope the above points give a peak into the thought process.

Our aim is to help product teams in their work, feel free to continue the discussion raise any concerns that you have 😄

Change the layout of the FormField

The current layout of form field breaks when the text label is really long.

Fix deployment status

This has been bugging me on every commit.

The deployment is a fire and forget job right now (with now-travis) which means the travis job finishes before the deployment does, this leaves the deployment in pending state forever.

Fix would be to either:

• wait for deployment to finish and then finish travis job
• add a post deployment hook that completes the deployment status

Bonus: It doesn't delete the deployment instance which leaves some un-aliased orphans hanging around

Move common form TextInput styles to GenericInput component

TextInput, Select, TextArea should all extend from GenericInput component

ETA? and having a 'meanwhile' strategy for new products

Many teams have already showed interested in the DS! But we keep getting asked for an estimated ETA and also for a strategy for products being built right now, so that they can be more aligned to the DS and make a future migration easier.

We might not have a good answer for this, but It's something we should discuss

Naming cosmos 😓

cosmos and @cosmos are both taken on npm (Related: #3)

Also, @dschenkelman suggested that we make sure we are not infringing any copyrights

Wrap component-metadata watch mode in try/catch for syntax errors

Create second level of tokens

First layer = base, Values like colors, spacing, etc. go here

Second layer is what we consume, variables such as inputBorderColor live here

Component versioning for sketch libraries

It's easy to version and publish individual components in code. How does that play with our sketch library is something we'll have to figure out 🤔

Potential solution: create a new symbol for archiving components while pointing default to the latest version

[email protected]
[email protected]
[email protected]

button --> latest --> [email protected]

Shared components vs Manage specific components

Testing strategy

Putting this here, so that we don't forget 😅

Let me start from the other end, what do we want from our testing strategy? The answer for me is iterate with confidence, everything else is a byproduct.

The situations in which I feel under confident touching code right now are:

1. I don't know if this design change is intentional.
2. I don't know what else will change/break (components composed of this component and the places it is used in the application)
3. Adding props of a component might break another component
4. Changing logic in complex components should not break another component
5. Changing/improving prop type definitions might break cause validation errors elsewhere (in other components or the application using them)

Approach:

1. Visual testing

   1.1 Visual changes in components should be called out and approved
   1.2 Resulting changes in sample PoC should be called out and approved

2. API testing

   2.1 All combinations of props need to be laid out for error catching.

Groundwork needed:

1. We need a space where components with their variations are laid out (automated hopefully), this will be the space for catching + approving visual changes. Real snapshot testing?

2. We need more sample applications built with cosmos to catch issues in usage, this will help us experiment with our components before it reaches the product teams.

Global or common CSS declarations

Usually the font-family, line-height and other utilities like box-sizing and text-smoothing are declared only once in the <body> tag (or with *) for global inheritance. Where should we declare this global styles?

Umbrella: Manage PoC

This is an umbrella issue to track completion/progress of the PoC project:

The idea is to keep a checklist of issues here, feel free to add todos or link issues here
(we can also add these to a project to get a better feel of priorities).

⏲ Our deadline is 15 Feb.

💎 Screens:

(Sketch file)

• Client list
• Create client (modal)
• Client detail
• Addons tabs (removed from the PoC)
• Advanced tab (not in sketch) but easily mockable in code

Components:

• Have basic skeleton for each page and tabbed pages (#110)
• Here's the component inventory: #39

Documentation:

• Pivot docs to markdown files #107
• Add getting started guide
• Finish documentation of all the components (break down further)
• Add icon search

Packaging:

• Change the folder structure to a monorepo (yarn workspaces): #1
• Publish design tokens as a library [email protected]
• Publish [email protected]
• Publish [email protected]

Demo:

• Plan a live code example (#108)

Tests:

• Snapshot testing
• Automate visual snapshots, this is more of a manual testing approach #15
• Add linting for component structure. (Look for things like description, styledComponent, defaultProps, propTypes, can also be done manually for some time)
• Add warnings for hardcoded values that should be in tokens
• Add tracking for cosmos-preset size

Misc:

• Fix continuous deployment #44
• Accessibility story (need research here)

---

After the PoC:

• Do a partial implementation of Cosmos in a product
• Do a full components inventory
• Review our scope and goals for 1.0
• Estimate a date for 1.0 release
• Bonus: Account centre PoC (will consider after getting enough progress + confidence with manage.

Binary props vs enum

What makes a more intuitive API?

<Button primary large>Button</Button>

<Button transparent small>Button</Button>
<Button destructive small>Button</Button>

vs.

<Button type="primary" size="large">Button<Button>

<Button type="transparent" size="small">Button</Button>
<Button type="destructive" size="small">Button</Button>

The first approach has a simpler API, you write as you think, I need a large primary button, the conflicting props are not obvious, you need to rely on prop-type validation warnings to catch mistakes

The second approach does not have conflict problems at the cost of a longer/more explicit API.

Auth0 Styleguide roadmap

With the upcoming Design System, where's the Styleguide heading?

• Is it going to be deprecated?
• Will it be maintained as a non-react alternative?
• Will new components be added to SG?
• Will there be component parity between SG and the DS?
• Will it be recommended by the DS for a particular use case?

Ideal structure

• move into a multipackage repository (with lerna)
• tokens and components are standalone packages
• overview is an application that consumes these packages
• manage/client and styleguide documentation would be other application that does the same

Automate visual diff for pull requests 🔥

Sounds like a cool idea.

To be able to review visual diff along with code diff would be 💯

The Logo Page in the docs, just turns everything blank.

When I get to the Logo Page in docs, the docs go blank for some weird reason.

What's the criteria for a component to be in the design system

Here's Cory House's advice: At least 3 products should have this use case.

Example: it might be tempting to add a color-picker because it sounds generic enough, but only 1 app has it. However, we still need to actively take requests and keep an inventory to see when it is time.

Good to have: Lay down the coding structure of a component so that folks can build components in the same manner even if is outside the design system. However, it's optional, even if they don't want to pick up the extra work, we'll do it when the component needs to moved into the design system.

Define design tokens

There's a nice write-up in this PR: #176

[Page Header] Create Page Header component

Give this component, we can call it 'Page header':

Has an option to show additional help:

Or can show a video tutorial

• Should it be in the DS? Is it part of Manage's internal components? We've seen shopify has this kind of organisms (or bigger components).
• If we added to the system, should it be as 'open' or 'closed' component?
• Does this logic apply to all organisms?

Compound component syntax

There are 2 options for compound components, it's a experience choice rather than a technical one*

The first approach is more explicit, a parent component brings it's children with it.

import Tabs from 'cosmos/tabs'

const ClientScreen = (
  <Tabs>
    <Tabs.Link>Settings</Tabs.Link>
    <Tabs.Content>magic happens here</Tabs.Content>
  </Tabs>
)

or

import Tabs, { Link, Content } from 'cosmos/tabs'

const ClientScreen = (
  <Tabs>
    <Link>Settings</Link>
    <Content>magic happens here</Content>
  </Tabs>
)

The second one looks better (in my opinion) and works well when used in small files (good coding practice?) when there are no conflicts.

Even in situations where conflicts can happen, the user/developer has an easy workaround:

import { Link } from 'cosmos/navigation'
import Tabs, { Link as TabsLink, Content } from 'cosmos/tabs'
//                 ↑↑↑↑     this avoids any naming conflict

const SomethingElseWithALink = (
  <Link>Contact support</Link>
)

const ClientScreen = (
  <Tabs>
    <TabsLink>Settings</TabsLink>
    <Content>magic happens here</Content>
  </Tabs>
)

This approach requires the developer to think about conflicts but gives an option to opt-in into the longer/more explicit syntax only when needed.

--

• the technical implication here is that Tabs.Link syntax is difficult to tree shake, but it doesn't sound like a probably use case with compound components, they all get used together

How customisable should components be?

It's easy to add customisations to components but each prop adds complexity, they will be really hard to remove later on.

Opinion: We should pick consistency over flexibility.

Example: We have 2 kind of inputs that have similar behaviour: <Input disabled /> and <Input readonly />,

Rigid components will help make it easier to test and maintain components. This can feel limiting at first, but it will help us build consistent UIs and remove some of the decision fatigue while picking components. (Bonus: easier to test + maintain)

--

Another interesting way to look at this is:

• Build flexible atomic components
• Build molecules with strict props, which is essentially locking down props of underlying atoms to expose a simpler building block for others.

Best way to communicate icons in links/navigation?

To build this menu, folks should be able to pass a config to the <TopNav> component

import { TopNav } from 'cosmos'

const tenantOptions = {
  tenant: { ... },
  links: [
    { icon: 'dashboard',   label: 'Dashboard', url: '/tenants/switch' }, 
    { icon: 'settings', label: 'Settings', url: '/tenants' }, 
    { icon: 'add-user', label: 'Invite users to this tenant', url: '/tenant/admins' }, 
    { icon: 'plus',     label: 'Create tenant',  onClick: addTenant }
  ]
}

render () {
  return <TopNav tenantOptions={tenantOptions}/>
}

These icons are easy to write/predict because they mean generic things, but in some other cases, the icons are very specific.

import { SideNav } from 'cosmos'

const links = [
  { icon: 'dashboard', label: 'dashboard', url: '/dashboard' },
  { icon: 'windows': 'Clients', url: '/clients' },
  { icon: 'blocks??', label: 'APIs', url: '/apis' },
  { icon: 'cloud', label: 'SSO Integrations', url: '/externalapps' },
  { icon: 'nodes', label: 'Connections', url: '/connections' }
]

render () {
  return <SideNav links={links} />
}

As you can see, these are impossible to make sense of.

Possible solution: Create aliases/names for exact use cases.

const links = [
  { icon: 'dashboard', label: 'dashboard', url: '/dashboard' },
  { icon: 'clients', label: 'Clients', url: '/clients' },
  { icon: 'apis', label: 'APIs', url: '/apis' },
  { icon: 'sso-integrations', label: 'SSO Integrations', url: '/externalapps' },
  { icon: 'connections', label: 'Connections', url: '/connections' }
]

render () {
  return <SideNav links={links} />
}

This is easier to use and makes the icon prop redundant.

Instead we can use a higher level prop

const links = [
  { label: 'dashboard', url: '/dashboard' },
  { label: 'Clients', url: '/clients' },
  { label: 'APIs', url: '/apis' },
  { label: 'SSO Integrations', url: '/externalapps' },
  { label: 'Connections', url: '/connections' }
]

render () {
  return <SideNav links={links} withIcons={true} />
}

This sounds like a smart approach initially, but it has it's limitations when it comes to maintenance.
You can't rename things on the fly.

Also, when the team wants to add a new item in the navigation:

They will have to wait for the icon to be added and released to start using it. Ooor, they will have to do the cryptic dance of finding the right icon, criss-cross-thing, shuffle, crossing?

Responsive web design

Auth0 products are not responsive today, but's it's a good idea to bake in basic responsiveness to components so that they can adapt to any context and new responsive iterations are possible from the get go.

We should list what a basic responsive needs to comply with.

Autocomplete plugin for editors

An autocomplete plugin for code editors could be the most least frictional way of consuming cosmos

We've talked a lot about making the docs really good because that is where folks will find components and learn their usage.

The next step would be to start thinking about integrating the docs with people's workflow = IDEs, sketch, desktop app, etc are good places to explore

Should button be clickable while it's in loading state?

If not, there are 2 ways of doing it:

1. Override onClick prop when the loading prop is passed
2. You need to pass loading and disabled both to disable clicks.

Form helper text will need to support basic styling and components

Have the possibility to add , links and also code

Add generated metadata to gitignore

Table Pagination Component

@cristiandouce was telling me that we should factor in the pagination component in the Clients table. He also advised it could be used a wrapper to the elements so that they gain pagination.

Icons

Let's discuss how to better implement icons

Find the best way to load fonts

Options:

• Load from cdn
• Compile into the component library

Performance impacts of each are different: FOUC vs FOIC

Guiding principles of cosmos components to help make decisions

It's useful to keep all guiding principles in one place, these influence the smaller decisions we make 😄

The aim of cosmos is to help designers and developers deliver work faster and better.

 

• Common language for all teams.

  Code (components, tokens, etc.) and design assets (sketch files, icons, etc.) should always have the same naming convention/API and be kept in sync. The documentation is the tool to help bridge the gap between design, engineering and product.

• Encourage the best UX/UI practices.

  We should provide guidelines on when to use components and patterns (or not) to ensure consistency throughout our products (and within).

• Have meaningful defaults, bake convention in the components.

  Developers should be able to pick a component create the recommended design guideline out of the box. Optimise for ease of implementation. Bonus: Challenge conventions all the time.

• Provide powerful abstractions while exposing the inner components at the same time.

  It should be easy + fast to build entire pages with cosmos, but at no point should the developer feel limited by the system. If there's a need to go out of the recommended way, they should be able to compose it with the inner/base components.

• Be open about progress, direction, intentions.

Initial Documentation site design

The initial PoC will be our first take at the documentation for the design system (both for design/ux and the component library), but:

• How will it look like?
• What sections/pages are we going to have?
• What information are we going to display for each component?

Linting for hard coded values