Platforms

Colour

Shape, space and type

Themes

Platform default dark theme

One administrator setting, Default dark theme (Dark or Black), decides what System means on a dark device. It is the field defaultDarkTheme (dark or black) of the public Firestore document appConfig/public, next to the support contact; only super admins can write it (the existing rule), anyone can read it, and anything other than black means Dark.

Each app paints with the cached value first, then fetches and updates; offline it keeps the last known value. An explicit Light, Dark or Black choice ignores the setting.

In Black the surfaces are charcoal and surface-raised (white at 6%), and text on teal fills is charcoal. Adapters keep one palette per theme in a single token file; a widget asks the theme, not the mode name. The theme choice is stored per app: web cave-shops-theme (light, dark, black, auto), mobile theme_mode plus theme_black, POS theme_mode (light, dark, black, system).

Rules for adapters

• Bundle the fonts from fonts/ with each app; do not load them from a CDN at runtime (the POS works offline).
• Set Directionality or dir from the language, and use start/end (Flutter EdgeInsetsDirectional, CSS logical properties), never left/right.
• Do not add colours to an adapter that are not tokens. A new need goes in tokens.json first.
• Dark theme uses the dark values of the same tokens; do not derive it with lighten or darken.
• Each product keeps one shared widget per component here (button, field, badge, card, table, dialog, toast, banner, empty state), so a restyle is a one-file change.

Where the shared components live

cave_ui.dart is lib/presentation/widgets/cave_ui.dart in Shops mobile and lib/features/shared/cave_ui.dart in POS; the two files are kept identical apart from imports.

Shop colours

One function per platform turns a shop colour into the roles in the README ("Shop colours"): fill, text on fill, colour as text, graphic, tint, outline. All three are the same algorithm and are checked against the same 80 test vectors, so a shop looks the same everywhere.

• Storefront (web). createShopTheme (shop-template1/shopTheme.js) builds the page's theme from it. MUI primary.main is the text-safe colour; filled buttons, chips and badges use the fill and its label through component overrides; the roles are also exposed as --shop-fill, --shop-on-fill, --shop-text, --shop-graphic, --shop-tint and the ground variables for plain CSS (cart, product card, product page, QR poster). Nothing on those pages hardcodes a colour.
• App accent (mobile, POS). The shop's colour becomes primary (the fill), onPrimary (its label), onPrimaryContainer (the text-safe colour, used by text buttons, chips and the selected navigation item) and the graphic shade for progress, cursor and the focus line. Because the apps' surfaces are navy as well as charcoal, pass those surfaces as grounds: so the text and graphic shades read on them too. Cave's own colours already pass and are used as they are.
• Tests. A sweep over about 190 colours in Light, Dark and Black asserts 4.5:1 for button labels, coloured text and chip text on every surface of the theme, and 3:1 for graphics. Each repo carries the same vectors file in its tests.
• Picker. BrandColorSection (web) and ShopColorPicker (mobile) are the picker in the README. The web StorefrontPreview is the live preview frame.

Add-ons

One model, three clients. The catalog is addons/{id}, purchases are shopAddons/{paymentId_addonId}, and the server writes shopEntitlements/{shopId}: the shop's plan with its add-ons applied. Every client reads that copy through one rule: use it only while it matches the subscription and the plan's revision and has not passed validUntil; otherwise the plain plan applies, so a stale copy can never grant more.