# What TrueUp needs from a design package (a new skin)

Hand this to whoever (or whatever, e.g. Claude Design) builds the package. It is written so that what comes back can be
installed as `skins/<id>/` with no guessing. A skin changes **appearance only**; it never changes data, numbers or what a
person may see. Anything not supplied falls back to the default TrueUp look, so a partial package is safe but looks mixed.

Contract and checks: `docs/design-skin-selection.md`, `docs/audit-skin-readiness.md`, `npm run lint:skin-contract`.

## 0. Identity (text)

| Need | Example (TrueUp today) |
|---|---|
| Skin id, lowercase letters/digits/hyphen, ≤ 32 | `ib` |
| Label shown in the admin switcher | `Intelligent Buildings` |
| Brand name printed on tenant statements, lease abstracts, findings reports | `Stiles Property Management` |
| Product name shown in the app | `TrueUp` (say if it must change) |
| Tagline on the sign-in screen and Home | Nothing to supply: fixed product copy under every skin (sign-in: "CAM reconciliation, backed by lease evidence."; Home: "Backed by lease evidence. Reviewed by people.") |
| Browser/PWA chrome colour (one hex) | `#2B2D6E` |
| Who approves the finished skin | a name |

## 1. Colour (light mode only; there is no dark theme)

Give every value as a hex (or `rgba()` where an alpha is stated). Use these **exact role names**; they are the skin's
palette. Names such as "crimson" and "slate" are historical: *crimson = the accent colour*, *slate = the dark surface*.

| Role (primitive) | What it paints |
|---|---|
| `crimson` | the accent: primary buttons, links, active tab underline, focus ring |
| `crimson-hover` | accent when hovered/pressed |
| `crimson-light` | accent **on a dark band** (must read on `slate`) |
| `crimson-06/12/26/50` | the accent at 6 / 12 / 26 / 50 % alpha (tints, borders) |
| `slate` | the dark surface: dark bands, inverse cards, the print heading colour |
| `slate-mid`, `slate-light` | two steps lighter than `slate` |
| `slate-12` | `slate` at 12 % (soft shadow) |
| `scrim` | the dimmed backdrop behind a modal (with alpha) |
| `ink` | body text and headings |
| `ink-72`, `ink-55` | secondary and muted text (**must hold contrast, see below**) |
| `paper` | page background |
| `cloud` | quiet panels and table stripes |
| `mist` | hairlines and borders |
| `white` | cards and inputs |
| `green`, `green-12`, `green-30` | success text, success tint, success border |
| `on-dark-75`, `on-dark-22` | text and hairlines on a dark band (white at 75 % / 22 %) |

**Contrast the app checks automatically (WCAG AA, 4.5 : 1):** `ink`, `ink-72` and `ink-55` on `white` and on `paper`;
`crimson` on `white` and `paper` (it is also the error/danger colour, so it must read as text); white on `crimson` and on
`crimson-hover`; `green` and `slate` (credit amounts) on `white`; `crimson-light` and `on-dark-75` on `slate`. For the printed
documents: `print-ink`, `print-navy`, `print-dim`, `print-owes` on `print-surface`; `print-navy` on `print-tint`; `print-dim`
on `print-page`; `print-green` on `print-ok-bg`; `print-warn-fg` on `print-warn-bg`. If a brand colour fails, supply the nearest
darker/lighter value that passes and say which brand value it replaces. A package whose pairs fail will be sent back.

## 2. Printed documents (tenant statement, lease abstract, findings, estimate letters)

These open in their own window and cannot see the app's stylesheet, so they take their own 17 values (same names, prefixed `print-`):
`navy` (headings and rules), `green`, `ink`, `line`, `dim`, `page` (background around the sheet), `surface` (the sheet),
`warn-bg`, `warn-fg`, `warn-line`, `ok-bg`, `ok-line`, `owes` (amount-due red), `tint`, `math`, `note`, `shadow`.
**`print-shadow` is ONE COLOUR** (the printed sheet's shadow on screen, for example `rgba(0, 0, 0, 0.08)`), not a full shadow. A full shadow is refused on upload until a person gives the colour.
If you only supply the app palette, say so and these will be derived from it; the documents will then need a visual check.

## 3. Shape

- **Corner radii**, in px: `xs, sm, md, lg, xl, 2xl, 3xl`, plus whether `pill` and `circle` are round or square. Controls
  (buttons, inputs), cards and overlays take `sm`/`md`/`lg`-class values; tell us which scale step you intend for each.
- **Shadows**: `sm`, `md`, `lg` (cards, menus, dialogs) and `raised` (a printed statement sheet). A flat hairline-ring style
  is fine; say so.
- **Borders**: `--p-border-hairline` (the line width, 1 px?) and `--p-border-bar` (the heavier emphasis rule, 4 px by default). Use these names; `border-width` and `emphasis-width` are not primitives.
- **Label casing**: are small section labels UPPERCASE or normal case? (`--p-case-label: uppercase | none`). Label letter-spacing is **not** skinnable (the app sets it); a `--p-tracking-label` line is ignored.

## 4. Type

| Need | Notes |
|---|---|
| Serif family (headings, statements) | name + fallbacks |
| Sans family (UI, tables) | name + fallbacks |
| Mono family (figures) | optional |
| Weights actually used | of 300 / 400 / 500 / 600 / 700 |
| **Where the font comes from** | a Google Fonts CSS URL, written as one line in `tokens.css`: `--p-font-url: "https://fonts.googleapis.com/css2?family=…"`. Self-hosted font files are **not supported yet**. |
| **Licence** | who licensed it and that web + app embedding is permitted. We will not ship a font without a stated licence. |

Tables and figures use tabular numerals; say if your sans has them. Check the sans at 13–14 px in dense tables.

## 5. Logos and brand assets

All **same-origin files** (no remote URLs). SVG preferred; PNG only if no vector exists.

| Asset | Where it shows | Spec |
|---|---|---|
| **nav logo** (`logo-nav`) | top bar, light background | horizontal; reads at 22–46 px tall; transparent background |
| **footer lockup** (`logo-footer`) | page footer | horizontal lockup on light background |
| **mark** | PWA install icon source only | the square/standalone symbol. NOTE: the animated TrueUp mark stays on Home, sign-in and waiting screens under every skin (it is the reminder that this is TrueUp software); it is drawn in the skin's accent and dark colours. Do not design a replacement. |
| **favicon** | browser tab | SVG, plus 32 × 32 and 16 × 16 PNG |
| **apple-touch icon** | iOS home screen | 180 × 180 PNG, opaque |
| **PWA icons** | installed app | 192 × 192 and 512 × 512 PNG, plus a maskable 512 |
| **alt text** for each | screen readers, printed documents | e.g. "Intelligent Buildings" |

## 6. Show us it working

Provide mock-ups (or a rendered page) of **three** screens in the new look so we can compare after install: the Portfolio
list, a property's Overview tab, and a printed tenant statement. Include a phone-width view (390 px) of the Portfolio.

## 7. How to deliver it

One folder, named for the skin id (a zip of it uploads in **Admin → Orgs & skins → Check a skin package**; a wrapper folder around it is fine):

```
<id>/
  brand.md            the identity table (section 0) first, then your open decisions; see below
  tokens.css          ONE rule, :root { --p-crimson: …; --p-print-navy: …; --p-radius-sm: …; --p-font-sans: …; --p-font-url: "…"; … }
  assets/             logo-nav.svg, logo-footer.svg, mark.svg, favicon.svg, favicon-32.png, favicon-16.png,
                      apple-touch-icon.png, icon-192.png, icon-512.png, icon-512-maskable.png
  previews/           portfolio.png, property-overview.png, statement.png, portfolio-phone.png   (looked at by people, never installed)
```

**`tokens.css`:** only `--p-*` custom properties inside one `:root { … }`, with the names in this brief. Anything else is refused by name. Colours are
hex or `rgb()`/`rgba()`; `--p-print-shadow` is one colour; `--p-font-url` is a quoted Google Fonts URL.

**`brand.md`:** start with the identity table, with these row labels, one value per row in backticks, so it can prefill the upload form:

| Need | Value |
|---|---|
| Skin id | `intellinet` |
| Admin switcher label | `IntelliNet` |
| Brand name on statements, abstracts, findings | `Name as it should print` |
| Browser / PWA chrome colour | `#122048` |
| Licence (in the Type table) | the licence for each font and that web and app embedding is permitted |

A value that is not known yet is written as `(placeholder, …)` next to it: the upload form leaves it empty and a person types it. It is never
treated as confirmed. List open decisions under a heading `## Open decisions`, as a numbered list with a bold title on each item; they are shown to the
admin and copied into the pull request for the reviewer.

If a decision is open (a brand value that fails contrast, a font without a licence, an asset not yet drawn), list it there rather than guessing.

**What happens on upload.** TrueUp converts the folder into the installed shape (`primitives.css` scoped to the skin, and `skin.json`), shows what it
made, asks an admin to confirm the identity values, runs the same contract as `npm run lint:skin-contract`, and (if switched on) opens a pull request.
It renames the two border names above if an older package used them, ignores `--p-tracking-label`, and reports each of those. It never installs
anything itself: a person reviews, merges and deploys the pull request.

---

### What is skinnable, and what is not
Skinnable today: colours, corners, type, browser colour, the nav logo, the footer lockup, the **browser-tab and apple-touch
icons**, and the printed documents including the brand name.
Fixed on purpose, under every skin: the **animated TrueUp mark** (Home, sign-in, waiting screens), and the footer, which shows
the TrueUp lockup only. No endorsement mark (including Intelligent Buildings) appears in any footer.
Not yet: the installed-app (PWA) manifest and its 192/512 icons (a manifest cannot be swapped per user without a server change,
so those follow the customer rollout, not the admin preview), the product name "TrueUp" in on-screen text, and notification emails.
