===============================================================================
 BRANDING GUIDE  -  SHRDBMS React backoffice
 How to re-skin the app for a broker without rebuilding it.
===============================================================================

You edit ONE file:  branding-config.json   (in this same folder, next to
index.html), and you drop in TWO image files. That's the whole job.

IN branding-config.json:
   - theme       the colour palette          (one word, section 1)
   - typography  the font pairing            (one word, section 2)
   - text        re-word the sign-in screen  (section 3 - optional)

IMAGE FILES (section 4 - nothing to type in the JSON):
   - logos/logo.svg  (or logos/logo.png)   the logo on the sign-in screen
   - favicon.ico  (in THIS same folder)     the browser-tab icon

Advanced / rarely needed, also in the JSON:
   - colors   override individual colours on top of the theme    (section 5)
   - fonts    override individual font roles on top of typography (section 6)

The client's NAME and ADDRESS are NOT set here - the app fetches them from the
backend (GET /api/branding.swc) at start-up, so they live in the database and are
changed centrally. If that call fails the screen shows the neutral "SHRDBMS"
wordmark with no address; that is the expected fallback. (The sign-in wording,
by contrast, IS in this file - section 3.)


-------------------------------------------------------------------------------
 THE WORKFLOW
-------------------------------------------------------------------------------
 1. Open  branding-config.json  in any text editor (Notepad is fine).
 2. Change the values you want (see below).
 3. Save.
 4. In the browser, hard-refresh:  Ctrl + Shift + R.
 5. The new look loads immediately - no rebuild, no Windows service restart.
    (IIS is set to never cache this file, so the change is picked up at once.)

 If something you set did NOT take effect:
   - Press F12 in the browser, open the "Console" tab, reload.
   - A line starting with  [branding]  tells you what was ignored and why
     (usually a typo, a missing quote, or a colour in a format the app
     doesn't accept).
   - A broken file never breaks the app - it just falls back to the built-in
     "SHRDBMS" house style.


-------------------------------------------------------------------------------
 FILE FORMAT RULES
-------------------------------------------------------------------------------
 - It is a JSON file. Keep the { } braces and the commas between items.
 - Text values go in "double quotes":   "theme": "theme-07"
 - No comma after the LAST item in a { } block.
 - You MAY add notes with  //  ... the app ignores them. Example:
       "theme": "theme-07",   // ABC brand blue
   (Your editor might underline the // in yellow - that is only the editor
    being strict; the app is fine with it.)


-------------------------------------------------------------------------------
 1. theme      - the base colour palette
-------------------------------------------------------------------------------
 Pick ONE. This sets every accent colour in the app in one go.

   "theme": "theme-07"

   VALUE      NAME       PRIMARY    FEEL
   theme-01   Indigo     #1d4ed8    all-purpose blue
   theme-02   Emerald    #047857    growth / positive
   theme-03   Graphite   #334155    minimal, understated
   theme-04   Crimson    #9f1239    bold, high-energy
   theme-05   Violet     #6d28d9    premium, modern
   theme-06   Teal       #0f766e    calm fintech
   theme-07   Azure      #0369a1    clean corporate blue
   theme-08   Sapphire   #3730a3    deep formal blue
   theme-09   Forest     #15803d    solid, traditional
   theme-10   Amber      #92400e    warm, distinctive
   theme-11   Rose       #be123c    approachable, retail
   theme-12   Cyan       #0e7490    bright, tech-forward
   theme-13   Plum       #86198f    rich, boutique
   theme-14   Navy       #1e3a8a    conservative, institutional
   theme-15   Olive      #4d7c0f    earthy, muted
   theme-16   Burgundy   #991b1b    heritage, private-client
   theme-17   Ocean      #155e75    deep teal-blue
   theme-18   Zinc       #52525b    true-neutral grey
   theme-19   Magenta    #a21caf    vivid, challenger brand
   theme-20   Copper     #9a3412    warm bronze, premium
   theme-21   Pewter     #45454c    white + grey monochrome (DEFAULT)

 The neutral background/surface/text colours and the red/green figures stay
 the same on every theme, on purpose - so ledgers and reports always read the
 same way for every broker. The whole sign-in screen (both panels, the
 buttons, the field icons, the dashed seam) follows the theme automatically.


-------------------------------------------------------------------------------
 2. typography  - the font pairing (one word swaps every font)
-------------------------------------------------------------------------------
 Like "theme" for colours: one value changes headings, body text, figures AND
 the sign-in heading together.

   "typography": "serif"

   VALUE         HEADINGS       BODY    SIGN-IN HEADING   NEEDS INTERNET?
   ""  (blank)   Space Grotesk  Inter   Spectral (serif)  no  - house default
   "sans"        Space Grotesk  Inter   Space Grotesk     no  - no serif anywhere
   "serif"       Spectral       Inter   Spectral          no  - serif headings
   "minimal"     Inter          Inter   Inter             no  - one face, quietest
   "editorial"   Fraunces       Inter   Fraunces          YES - loads Fraunces

 - Figures / codes stay "IBM Plex Mono" in every preset.
 - An unknown value behaves like ""  (house default).
 - "editorial" pulls the Fraunces face from Google Fonts at run time; on a
   network with no internet it falls back to a system serif - not broken, just
   plainer. The other presets use only built-in faces and always work offline.
 - Need a pairing that isn't here? Use section 6 ("fonts") to name the exact
   families yourself.


-------------------------------------------------------------------------------
 3. text       - re-word the sign-in screen   (OPTIONAL)
-------------------------------------------------------------------------------
 The sign-in screen ships with neutral wording. To put the broker's own words
 there, fill in the "text" block. Every line is optional - leave it "" and the
 built-in wording is used (and the description line simply stays hidden).

   "text": {
     "loginWelcome":     "One console for clients, DP, ledgers and KYC.",
     "loginDescription": "Ledgers and holdings, trade register and net position, fund transfers and KYC - opened in your role, scoped to one year.",
     "authHeading":      "Sign in to your backoffice"
   }

   KEY               WHERE IT SHOWS                             DEFAULT
   loginWelcome      big line on the left sign-in panel         "One console for clients, DP,
                                                                 ledgers, positions and KYC."
   loginDescription  one grey sentence under that big line      (empty - line hidden until
                                                                 you write one)
   authHeading       heading above the ID / password fields     "Sign in to your backoffice"

 - Plain text only. One line each - line breaks and repeated spaces are pulled
   back to single spaces so the panel can't be knocked out of shape.
 - Length caps: loginWelcome ~160 chars, loginDescription ~240, authHeading ~80.
   Anything longer is trimmed.
 - This is the WORDING only. The FONT of the "authHeading" line is a separate
   knob - "fonts": { "authDisplay": ... } in section 6.
 - The client's NAME and ADDRESS are still NOT here (see the top of this file) -
   only the wording above.


-------------------------------------------------------------------------------
 4. logo + favicon  - just drop the files in
-------------------------------------------------------------------------------
 There is NOTHING to type in branding-config.json for these. Copy the files
 in using these EXACT names and locations:

     logos/logo.svg   your logo for the sign-in screen   (or  logos/logo.png )
     favicon.ico      the browser-tab icon  (goes directly in THIS folder,
                       the one with index.html - NOT inside logos/)

 The app looks for them on start-up and uses whatever it finds.

 LOGO
 - Inside THIS folder there is a subfolder named  logos . Put your file there,
   named exactly  logo.svg  (preferred) or  logo.png . SVG or a transparent
   PNG; it is shown about 30 px tall, width scales to fit.
 - This subfolder is for YOUR logo only - do not touch any other folder here
   (a separate one holds the app's own "Powered by" mark and is not yours to
   edit).
 - No logo.svg / logo.png in  logos/  ->  the sign-in screen shows a text
   monogram from the client name instead ("ABC Securities Ltd." -> "AB").

 FAVICON
 - Name it exactly  favicon.ico , placed directly in THIS folder (same level
   as branding-config.json, not inside logos/). A 32x32 / 48x48 .ico is
   safest across browsers.
 - No favicon.ico  ->  the bundled default icon (favicon.ico) is kept. If you
   prefer, you can instead just OVERWRITE the existing favicon.ico with your
   own SVG - same effect, no extra file.

 AFTER A NEW BUILD is deployed, the  logos/  folder is empty again and
 favicon.ico is back to the default - copy your logo.svg + favicon.ico back in.


-------------------------------------------------------------------------------
 5. colors     - fine-tune individual colours   (OPTIONAL - advanced)
-------------------------------------------------------------------------------
 Most installs never need this - just pick a "theme" (section 1).
 Use "colors" only to override specific colours on top of the chosen theme.

   "colors": {
     "primary":         "#1e6f5c",
     "primaryHover":    "#17594a",
     "primaryContrast": "#ffffff"
   }

 - Keep  "colors": {}  to change nothing.
 - Add only the keys you want to change; the rest come from the theme.
 - Accepted value formats:
       "#1d4ed8"              (3, 4, 6 or 8 hex digits)
       "rgb(29,78,216)"       "rgba(29,78,216,0.9)"
       "hsl(221,83%,48%)"     "hsla(221,83%,48%,0.9)"
   Anything else is ignored (a typo cannot break the page).

   KEY                WHAT IT COLOURS
   primary            main buttons, links, active menu item, focus ring, KPI
                      accents, the avatar, the dark sidebar + the dark sign-in
                      panel, sign-in field icons
   primaryHover       those same things while the mouse is over them
   primaryContrast    the TEXT / ICON that sits on top of a primary button
                      (set this if you choose a light "primary")
   secondary          a secondary accent (used sparingly)
   info               neutral information banners            (default blue)

   (The page background, cards/panels, text and hairlines - "bg" / "surface" /
   "border" / "text" / "textMuted" - are NOT overridable here: they belong to
   the light/dark switch every user controls themselves (the sun/moon toggle),
   not to the broker's colour scheme. An override here would fight that
   switch and could leave dark mode permanently broken for this install.)

   (Gain / loss / caution colours - green, red, amber - are fixed by the app and
   cannot be changed here: they carry meaning, so they must look the same on
   every install. Any "success" / "danger" / "warning" key is ignored.)

 NOTE ON CONTRAST: if you set a light "primary" and do NOT set
 "primaryContrast", the app auto-picks black or white text so the button
 label stays readable.


-------------------------------------------------------------------------------
 6. fonts      - override individual font roles   (OPTIONAL - advanced)
-------------------------------------------------------------------------------
 Only needed if no "typography" preset (section 2) fits. Each role you fill in
 overrides that one role; the rest still come from the chosen "typography".

   "fonts": {
     "heading": "Poppins",
     "body": "",
     "mono": "",
     "authDisplay": "",
     "googleFonts": ["Poppins:wght@500;600;700"]
   }

   KEY          AFFECTS                              DEFAULT
   heading      page titles and headings             "Space Grotesk"
   body         ALL body text, tables, form fields   "Inter"
   mono         codes, references, figures           "IBM Plex Mono"
   authDisplay  the sign-in heading line only        "Spectral" (a serif)

 - Leave a value ""  to keep whatever "typography" set for that role.
 - CARE with "body": a narrow or low-legibility font makes dense data tables
   hard to read. Test a full ledger screen before shipping it to a broker.

 WHICH FONT NAMES WORK
 - These four are always available, no extra step:
       "Inter"   "Space Grotesk"   "Spectral"   "IBM Plex Mono"
 - To use ANY other font, you must also list it under "googleFonts" so the
   app can load it. Each entry is a Google Fonts "family" spec:

       "googleFonts": [
         "Poppins:wght@400;600;700",
         "Roboto Mono:wght@400;500"
       ]

   Then you can use  "heading": "Poppins"  and  "mono": "Roboto Mono".

 - Loading Google Fonts needs the browser to reach fonts.googleapis.com.
   On a locked-down broker network where that is blocked, the app simply
   falls back to a standard system font - it does not break.
 - If a broker network has no internet at all, stick to the four built-in
   fonts.


-------------------------------------------------------------------------------
 WORKED EXAMPLES
-------------------------------------------------------------------------------
 Typical install - two words in the JSON:
 {
   "theme": "theme-06",
   "typography": "serif"
 }
 ...plus  logos/logo.svg  and  favicon.ico  copied in.

 Same, with the broker's own sign-in wording:
 {
   "theme": "theme-06",
   "typography": "serif",
   "text": {
     "loginWelcome": "Your ABC Securities backoffice, in one place.",
     "loginDescription": "Clients and DP, ledgers and holdings, trade register and net position - opened in your role, scoped to one year."
   }
 }

 With advanced tweaks - a custom heading font + one recoloured token:
 {
   "theme": "theme-06",
   "typography": "sans",
   "colors": { "primary": "#0e7c66", "primaryHover": "#0b6353" },
   "fonts": { "heading": "Manrope", "googleFonts": ["Manrope:wght@500;700"] }
 }

 The client's NAME and ADDRESS are NOT in this file - the backend's
 /api/branding.swc returns them for that install.


-------------------------------------------------------------------------------
 AFTER A NEW BUILD IS DEPLOYED
-------------------------------------------------------------------------------
 Every fresh "dist" ships with the default branding-config.json, an empty
 "logos" folder and the default favicon.ico. After replacing the files:
   1. put your edited branding-config.json back
   2. copy your logo into  logos/logo.svg  (or  logos/logo.png )
   3. copy favicon.ico back into this same folder
 Keep a copy of all three somewhere safe.
===============================================================================
