Appearance
- Code: SET-APR
- Module: Settings
- Type: Configuration
1. Overview
Appearance is the interface theme setting that applies to the whole tenant: font, primary color, base color, corner radius, and text scale. There is a single setting per tenant, and changes are visible across the entire dashboard as soon as they are saved.
Expected outcome: every tenant can adapt the dashboard’s look to their brand identity without help from a developer.
2. Problem
Without per-tenant appearance settings, every business uses exactly the same theme, even though each tenant’s visual and readability needs differ. As a result:
- All tenants look identical, so the dashboard does not feel like it belongs to their business.
- Some users need larger or smaller text to use it comfortably on store devices.
- Changing the theme through code for each tenant does not scale.
3. Goals & Non-goals
3.1 Goals
- The dashboard’s look can be adapted to each tenant’s brand identity.
- Text and element sizes can be adjusted for comfortable use on store devices.
- Adjustments are made by admins themselves, without involving the technical team.
- The result of an adjustment can be previewed before it is actually saved.
3.2 Non-goals
- A different theme per user; the theme applies to the whole tenant.
- Free colors outside the provided list of options.
- Uploading custom fonts.
- Setting light and dark mode; both follow the user’s device preference.
4. Business Rules
Business rules are the set of provisions and constraints that apply to Appearance throughout the application, on every screen and action that involves it, whoever performs it. These rules are the single source of truth: if another part of this PRD appears to differ, the rules here prevail.
- BR-01 Each tenant has only one appearance setting, and that setting applies to all of its users.
- BR-02 Every choice must come from the provided list of options; values outside the list are not accepted.
- BR-03 The preview is only visible to the user who is making the change. Other users only see the change after it is saved.
- BR-04 A saved theme applies to every user session in that tenant.
- BR-05 Every appearance change is recorded along with its actor and time.
5. Flow
5.1 Main Flowchart
- View Appearance — The current theme setting is shown along with the options in use.
- Edit Appearance — An authorized admin opens the setting to adjust it.
- Choose Options — Every choice is immediately applied as a preview across the entire dashboard, so the result is visible before saving.
- Validation — Choices are checked before saving, and only available options are accepted.
- Appearance Saved — The new theme applies to all users of the tenant.
- Cancel Without Saving — If the admin leaves the page without saving, the look reverts to the previously saved theme.
6. Document Structure
6.1 General
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| Font | Enum | No | App default | Geist, Roboto, Open Sans, Lato, Montserrat, Inter, Poppins, Raleway, Manrope, or DM Sans (BR-02) |
| Primary Color | Enum | No | App default | Neutral, Red, Orange, Amber, Yellow, Lime, Green, Emerald, Teal, Cyan, Sky, Blue, Indigo, Violet, Purple, Fuchsia, Pink, or Rose (BR-02) |
| Base Color | Enum | No | App default | Neutral, Slate, Gray, Zinc, Stone, Taupe, Mauve, Mist, or Olive (BR-02) |
| Radius | Enum | No | App default | Sharp, Medium, or Full (BR-02) |
| Scale | Enum | No | App default | Small, Medium, or Large (BR-02) |
7. UI Structure
This section defines how Appearance is displayed and operated: form controls along with their option sources. This section only governs display and interaction; content and value rules still follow Document Structure.
7.1 Form & Details
A single page with view and edit modes. View mode marks the currently active option and dims the others. Edit mode applies each choice as a live preview across the entire dashboard before saving. Actions: Edit Data (view), Save (edit), Activity Logs.
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Font | Option cards | 10 font choices | Selected → preview applied immediately |
| Primary Color | Round swatches | 18 color choices | Selected → preview applied immediately |
| Base Color | Square swatches | 9 color choices | Selected → preview applied immediately |
| Radius | Corner radius preview cards | Sharp, Medium, Full | Selected → preview applied immediately |
| Scale | Text size preview cards | Small, Medium, Large | Selected → preview applied immediately |
8. User Stories
US-01 - View appearance settings
As an admin, I want to see the active theme, so that I know the tenant’s current configuration.
| ID | Acceptance criteria |
|---|---|
| AC-01.1 | Users with the view permission see 5 settings: Font, Primary Color, Base Color, Radius, Scale, each with a label and description. |
| AC-01.2 | The active option is marked; other options appear dimmed and cannot be clicked. |
| AC-01.3 | A skeleton appears while the data is loading. |
| AC-01.4 | The tenant has never set an appearance — all fields are empty; the interface uses the app’s default theme. |
US-02 - Edit appearance with preview
As an admin, I want to try theme options and see the result immediately, so that I am confident before saving.
| ID | Acceptance criteria |
|---|---|
| AC-02.1 | The Edit Data button only appears for users with the update permission. |
| AC-02.2 | In edit mode, selecting an option immediately applies the theme to the entire interface. |
| AC-02.3 | The Update button is disabled until there is a change. |
| AC-02.4 | After saving successfully, a success toast appears and the user returns to view mode with the new theme. |
| AC-02.5 | When leaving edit mode without saving, a confirmation appears; if the user still leaves, the theme reverts to the saved values. |
| AC-02.6 | The theme is saved, then the page is reloaded — it must use the new theme. Currently, saving Appearance does not yet refresh the tenant initialization data cache (unlike Company), so the old theme may reappear until the cache expires (BR-04). |
| AC-02.7 | Two admins edit the appearance at the same time — the last save wins. |
US-03 - Change history
As an owner, I want to see the appearance activity log, so that I know who changed the theme.
| ID | Acceptance criteria |
|---|---|
| AC-03.1 | The Activity Logs button in view mode opens the log panel with event, actor, and date range filters. |
9. User Scenarios
| Role | Scenario |
|---|---|
| Owner | Matches the dashboard’s primary color with the store’s brand color |
| Owner | Increases the text scale so older cashiers can read comfortably |
| Admin | Tries several color combinations, then cancels because the result does not fit |
| Auditor | Views the history of who changed the appearance and when |
10. Permissions & Actions
10.1 Permission by Action
| Action | Permission | Condition |
|---|---|---|
| View Appearance | settings:appearance:view:any | — |
| View Activity Logs | settings:appearance:view:any | — |
| Edit Appearance | settings:appearance:update:any | — |
11. Notifications
This feature does not trigger any notifications.
12. Dependencies
Related PRDs
- Company — shares the same tenant initialization data (
/public/init). - Activity Logs — the source of the activity log.
Effects on other modules
- The theme is applied throughout the tenant-dashboard app, including auth pages.