Mobiz Theme Tokens: A Shadcn Admin Guide

by Admin 41 views
Mobiz Theme Tokens: A Shadcn Admin Guide

Hey guys! Let's dive into defining Mobiz theme tokens for Shadcn Admin. This guide will help you understand how to capture and utilize the shared color, typography, and spacing tokens from the existing Mobiz web application to ensure the new admin interface aligns perfectly with the Mobiz brand.

Summary

Our main goal here is to consolidate the design tokens currently scattered across apps/web/src/app/globals.css and apps/web/tailwind.config.ts. By extracting and centralizing these tokens, we can ensure that the new admin interface, built with Shadcn, maintains a consistent look and feel with the rest of the Mobiz ecosystem. This involves identifying key elements like color palettes, font stacks, spacing aliases, and heading styles, and making them readily available for use in the admin project.

Why This Matters

Maintaining brand consistency is crucial for user experience. When users navigate between different parts of the Mobiz platform, they should feel like they're still in the same environment. A unified design language helps build trust and familiarity. By ensuring the admin interface matches the Mobiz brand, we're creating a more cohesive and professional experience for our users.

The Current Challenge

Currently, design-related configurations are spread across multiple files. This makes it difficult to maintain consistency and update styles across the entire platform. By centralizing these tokens, we simplify the process of updating and maintaining our design language.

Long-Term Benefits

Centralizing design tokens provides numerous long-term benefits. It streamlines the design and development process, reduces the risk of inconsistencies, and makes it easier to onboard new team members. By establishing a single source of truth for design-related configurations, we can ensure that our platform remains visually consistent and professional.

Tasks

To achieve our goal, we need to perform the following tasks:

  • Extract Palette, Font Stack, Spacing Aliases, Heading Styles: This involves carefully examining the existing CSS and Tailwind configuration files to identify and extract all relevant design tokens.
  • Decide Where Those Tokens Will Live: We need to determine the best location for storing these tokens. Should they reside in a shared package, or should they be duplicated in the admin project's configuration?
  • Publish a Short Doc: We'll create a concise document that lists each token and provides guidance on how to use them in the admin project.

Detailed Breakdown of Tasks

Extract Palette, Font Stack, Spacing Aliases, Heading Styles

This is the most critical task. We need to meticulously go through apps/web/src/app/globals.css and apps/web/tailwind.config.ts and identify every color, font, spacing, and heading style that's being used. This includes:

  • Color Palette: Primary colors, secondary colors, accent colors, and the entire grayscale ramp.
  • Font Stack: The specific fonts being used (e.g., Libre Franklin), along with fallback fonts.
  • Spacing Aliases: Values for spacing like xs, sm, md, lg, xl, etc.
  • Heading Styles: Styles for h1, h2, h3, h4, h5, and h6 tags, including font size, font weight, and line height.

We should aim to create a comprehensive list of all these tokens, ensuring nothing is missed. Use comments and organize the extracted data.

Decide Where Those Tokens Will Live

There are two main options here:

  1. Shared Package: Create a separate package (e.g., @mobiz/design-tokens) that contains all the design tokens. This package can then be imported into both the web application and the admin project.
  2. Duplicated Config: Copy the design tokens into the admin project's configuration file (e.g., tailwind.config.js).

Each approach has its pros and cons. A shared package promotes consistency and simplifies updates, as changes only need to be made in one place. However, it adds complexity in terms of package management and versioning. Duplicating the config is simpler to set up but can lead to inconsistencies if the tokens are not kept in sync. The decision should be based on the project's specific needs and priorities. Consider future scalability and maintainability.

Publish a Short Doc

Once we've extracted the tokens and decided where they will live, we need to create a document that explains how to use them. This document should include:

  • A list of all available tokens, with clear descriptions of what they represent.
  • Examples of how to use the tokens in the admin project (e.g., in Shadcn components).
  • Guidance on how to update the tokens when necessary.

This document should be easily accessible to developers working on the admin project. Consider publishing it as a markdown file in the project's repository (e.g., /docs/admin-shadcn-theme.md).

Acceptance Criteria

To ensure we've successfully completed these tasks, we need to meet the following acceptance criteria:

  • Doc Lists All Tokens: The documentation must include a comprehensive list of all design tokens, including primary, secondary, and grayscale colors, the Libre Franklin font, spacing values like xs and lg, and heading styles.
  • Decision on Token Sharing Recorded: The decision on whether to use a shared package or duplicate the config must be clearly documented.

Detailed Examination of Acceptance Criteria

Doc Lists All Tokens

The documentation is the key to the successful adoption of the design tokens. If the documentation is incomplete or unclear, developers will struggle to use the tokens correctly. Therefore, it's crucial to ensure that the documentation is thorough and easy to understand. Each token should be clearly labeled and described, with examples of how to use it in the admin project.

Example of a well-documented token:

### Primary Color

**Token Name:** `primary-500`

**Description:** The primary color used for main actions and elements.

**Value:** `#007BFF`

**Usage:**

```jsx
<Button className="bg-primary-500 text-white">Click Me</Button>


#### Decision on Token Sharing Recorded

The decision on where to store the tokens is important for maintainability. Whether we choose a shared package or duplicated configuration, the rationale behind the decision needs to be documented. If we opt for a shared package, we should provide clear instructions on how to set up and use the package. If we choose to duplicate the configuration, we should outline a process for keeping the tokens in sync between the web application and the admin project. State the pros and cons of each solution.

**Example of a well-documented decision:**

```markdown
## Decision on Token Sharing

We have decided to use a shared package (`@mobiz/design-tokens`) for storing the design tokens. This approach offers the following advantages:

- **Consistency:** Ensures that all projects use the same set of tokens.
- **Maintainability:** Simplifies updates, as changes only need to be made in one place.

However, it also introduces some complexity:

- **Package Management:** Requires managing and versioning the shared package.

To use the shared package, follow these steps:

1.  Install the package: `npm install @mobiz/design-tokens`
2.  Import the tokens in your component: `import { colors } from '@mobiz/design-tokens'`

Dependencies

Fortunately, this task has no dependencies, meaning we can start working on it right away! Let's get this done, guys!

By following these steps and guidelines, we can ensure that the Mobiz admin interface aligns perfectly with the Mobiz brand, providing a seamless and consistent user experience. Good luck!