This page is a WIP.
Below, you can find all of the latest design tokens that we use. This file should be treated as the source of truth. If you see mismatches in the codebase, it is likely a mistake. We aim to match this file 1:1 in our codebase.
All these tokens should be defined in a single file here:
https://github.com/maybe-finance/maybe/blob/main/app/assets/tailwind/maybe-design-system.css
Conventions
In the Maybe app, we define everything centrally. We do NOT use dark:custom-style throughout the views, but instead, define our functional "tokens" with all the necessary themes:
// Functional "utility" class (this is what we use in our views)
@utility text-primary {
@apply text-gray-900; // Primitive Tailwind class
@variant theme-dark {
@apply text-white; // Primitive Tailwind class
}
}
Then, throughout the codebase, we attempt to exclusively use these Tailwind functional utility classes so we automatically get the benefit of dark/light mode without duplicate effort:
Correct:
<p class="text-primary">This works in both dark / light mode automatically</p>
Incorrect usage
<p class="text-gray-900 dark:text-white">INCORRECT USAGE</p>
Component conventions
Tokens for "components" (i.e. buttons, checkbox, tooltip, switch, etc.) should generally NOT be defined in our global CSS file. Instead, they should be referenced and encapsulated in a partial that represents that component.
NOTE: The current codebase does not yet reflect this and has scattered usage of classes like btn btn--primary throughout. We plan to migrate towards ViewComponent in the future and will be extracting these usages into a centralized component.
Form conventions
The majority of our forms are styled through a custom Form Builder, which is invoked via styled_form_with helper:
<%= styled_form_with model: @some_model do |f| %>
<%# All form elements are automatically styled %>
<% end %>
All styles should be consolidated here unless the form is a "one-off" form_with not utilizing these global builder styles.
Design tokens
- Usage Class - this represents the "functional token" that we use throughout the views
- Light - the primitive Tailwind class this token is an alias to
- Dark - the primitive Tailwind class this token is an alias to
Background tokens
| Usage Class | Light | Dark |
|---|---|---|
| bg-surface | bg-gray-50 | bg-black |
| bg-surface-hover | bg-gray-100 | bg-gray-800 |
| bg-surface-inset | bg-gray-100 | bg-gray-900 |
| bg-surface-inset-hover | bg-gray-200 | bg-gray-800 |
| bg-container | bg-white | bg-gray-900 |
| bg-container-hover | bg-gray-50 | bg-gray-800 |
| bg-container-inset | bg-gray-50 | bg-gray-800 |
| bg-container-inset-hover | bg-gray-100 | bg-gray-700 |
| bg-inverse | bg-gray-800 | bg-white |
| bg-inverse-hover | bg-gray-700 | bg-gray-100 |
| bg-overlay | bg-gray-100/50 | bg-black/90 |
| chat-bg-default | bg-gray-100 | bg-gray-900 |
| tab-bg-group | bg-gray-50 | bg-black/70 |
| tab-item-active | bg-white | bg-gray-700 |
| tab-item-hover | bg-gray-200 | bg-gray-800 |
| menu-item-item-active | bg-white | bg-gray-800 |
| menu-item-item-hover | bg-gray-100 | bg-gray-800 |
Foreground tokens
| Usage Class | Light | Dark |
|---|---|---|
| fg-primary | text-gray-900 | text-white |
| fg-primary-variant | text-gray-800 | text-gray-50 |
| fg-secondary | text-gray-50 | text-gray-700 |
| fg-secondary-variant | text-gray-100 | text-gray-600 |
| fg-gray | text-gray-500 | text-gray-400 |
| fg-subdued | text-gray-400 | text-gray-500 |
| fg-contrast | text-gray-400 | text-gray-500 |
| fg-inverse | text-white | text-gray-900 |
| text-primary | text-gray-900 | text-white |
| text-secondary | text-gray-500 | text-gray-400 |
| text-subdued | text-gray-400 | text-gray-600 |
| text-link | text-blue-600 | text-blue-500 |
Semantic tokens
| Usage Class | Light | Dark |
|---|---|---|
| success | text-green-600 | text-green-500 |
| warning | text-yellow-600 | text-yellow-400 |
| destructive | text-red-600 | text-red-400 |
Border tokens
| Usage Class | Light | Dark |
|---|---|---|
| border-primary | border-black/30 | border-white/40 |
| border-secondary | border-black/20 | border-white/30 |
| border-tertiary | border-black/10 | border-white/20 |
| border-subdued | border-black/5 | border-white/10 |
| border-solid | border-black | border-white |
| border-destructive | border-red-500 | border-red-400 |
Utility tokens
| Usage Class | Light | Dark |
|---|---|---|
| progress-ring-fill | fill-gray-200 | fill-gray-700 |
| shadow | shadow | shadow |
Component tokens
Buttons
| Usage Class | Light | Dark |
|---|---|---|
| button-bg-primary | bg-gray-900 | bg-white |
| button-bg-primary-hover | bg-gray-800 | bg-gray-50 |
| button-bg-secondary | bg-gray-50 | bg-gray-700 |
| button-bg-secondary-hover | bg-gray-100 | bg-gray-600 |
| button-bg-ghost-hover | bg-gray-50 | bg-gray-800 |
| button-bg-outline-hover | bg-gray-100 | bg-gray-700 |
| button-bg-disabled | bg-gray-50 | bg-gray-700 |
| button-bg-destructive | bg-red-500 | bg-red-400 |
| button-bg-destructive-hover | bg-red-600 | bg-red-500 |
Inputs
| Usage Class | Light | Dark |
|---|---|---|
| input-bg-default | bg-white | bg-black/70 |
| input-bg-variant | bg-white | bg-gray-900 |
| input-bg-disabled | bg-gray-50 | bg-black/50 |
| input-border-default | border-black/10 | border-white/20 |
| input-border-hover | border-black/20 | border-white/30 |
| input-border-focus | border-black | border-white |
Switches
| Usage Class | Light | Dark |
|---|---|---|
| switch-bg-default | bg-gray-100 | bg-gray-700 |
| switch-bg-hover | bg-gray-200 | bg-gray-800 |
| switch-bg-active | bg-green-600 | bg-green-500 |
| switch-bg-active-hover | bg-green-700 | bg-green-600 |
| switch-bg-disabled | bg-gray-100 | bg-gray-800 |
| switch-indicator-fill | bg-white | bg-gray-500 |
| switch-indicator-fill-active | bg-white | bg-gray-500 |
| switch-indicator-fill-disabled | bg-gray-50 | bg-gray-700 |
Checkboxes
| Usage Class | Light | Dark |
|---|---|---|
| checkbox-bg-default | bg-white | bg-gray-800 |
| checkbox-bg-active | bg-gray-900 | bg-white |
| checkbox-bg-disabled | bg-gray-50 | bg-gray-900 |
| checkbox-border | border-black/20 | border-white/30 |
| checkbox-border-disabled | border-black/10 | border-white/20 |
Tooltips
| Usage Class | Light | Dark |
|---|---|---|
| tooltip-bg-on-chart | bg-white | bg-gray-800 |
| tooltip-bg-default | bg-gray-700 | bg-gray-800 |
WIP Sidebar
WIP Footer