Skip to Content

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

  1. View Appearance — The current theme setting is shown along with the options in use.
  2. Edit Appearance — An authorized admin opens the setting to adjust it.
  3. Choose Options — Every choice is immediately applied as a preview across the entire dashboard, so the result is visible before saving.
  4. Validation — Choices are checked before saving, and only available options are accepted.
  5. Appearance Saved — The new theme applies to all users of the tenant.
  6. 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

FieldTypeRequiredDefaultRules
FontEnumNoApp defaultGeist, Roboto, Open Sans, Lato, Montserrat, Inter, Poppins, Raleway, Manrope, or DM Sans (BR-02)
Primary ColorEnumNoApp defaultNeutral, Red, Orange, Amber, Yellow, Lime, Green, Emerald, Teal, Cyan, Sky, Blue, Indigo, Violet, Purple, Fuchsia, Pink, or Rose (BR-02)
Base ColorEnumNoApp defaultNeutral, Slate, Gray, Zinc, Stone, Taupe, Mauve, Mist, or Olive (BR-02)
RadiusEnumNoApp defaultSharp, Medium, or Full (BR-02)
ScaleEnumNoApp defaultSmall, 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.

FieldControlOptions SourceBehavior
FontOption cards10 font choicesSelected → preview applied immediately
Primary ColorRound swatches18 color choicesSelected → preview applied immediately
Base ColorSquare swatches9 color choicesSelected → preview applied immediately
RadiusCorner radius preview cardsSharp, Medium, FullSelected → preview applied immediately
ScaleText size preview cardsSmall, Medium, LargeSelected → 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.

IDAcceptance criteria
AC-01.1Users with the view permission see 5 settings: Font, Primary Color, Base Color, Radius, Scale, each with a label and description.
AC-01.2The active option is marked; other options appear dimmed and cannot be clicked.
AC-01.3A skeleton appears while the data is loading.
AC-01.4The 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.

IDAcceptance criteria
AC-02.1The Edit Data button only appears for users with the update permission.
AC-02.2In edit mode, selecting an option immediately applies the theme to the entire interface.
AC-02.3The Update button is disabled until there is a change.
AC-02.4After saving successfully, a success toast appears and the user returns to view mode with the new theme.
AC-02.5When leaving edit mode without saving, a confirmation appears; if the user still leaves, the theme reverts to the saved values.
AC-02.6The 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.7Two 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.

IDAcceptance criteria
AC-03.1The Activity Logs button in view mode opens the log panel with event, actor, and date range filters.

9. User Scenarios

RoleScenario
OwnerMatches the dashboard’s primary color with the store’s brand color
OwnerIncreases the text scale so older cashiers can read comfortably
AdminTries several color combinations, then cancels because the result does not fit
AuditorViews the history of who changed the appearance and when

10. Permissions & Actions

10.1 Permission by Action

ActionPermissionCondition
View Appearancesettings:appearance:view:any—
View Activity Logssettings:appearance:view:any—
Edit Appearancesettings: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.
Last updated on