Add brand kit: logo, favicon, social preview, guidelines

Author: MHWing

brand/INSTALL.md

@@ -0,0 +1,157 @@
+# The Foundation : Brand Kit, Install and Usage
+
+Everything you need to put the brand live. Read top to bottom the first time. Each terminal block is meant to be run one block at a time; after each one, glance at the output before moving on.
+
+If you only do two things, do these: upload `avatar/avatar-512.png` as the org avatar, and upload `social/social-preview.png` under repository Settings, Social preview. Everything else is polish.
+
+---
+
+## A. What is in this kit
+
+```
+brand/
+  README.md                  The brand spec (colour tokens, fonts, voice). Lives in the repo.
+  INSTALL.md                 This file.
+  brand-guidelines.html      Open in a browser for the full visual reference.
+  logo/
+    the-foundation-logo.svg            Horizontal lockup, light backgrounds
+    the-foundation-logo-reversed.svg   Horizontal lockup, dark backgrounds
+    the-foundation-mark.svg            Mark only, light backgrounds
+    the-foundation-mark-reversed.svg   Mark only, dark backgrounds
+  avatar/
+    avatar-512.png             Upload this as the GitHub org or repo avatar
+    mark-512-transparent.png   Mark only, transparent, for slides or docs
+  favicon/
+    favicon.ico                16, 32, 48 in one file
+    favicon.svg                Scalable source
+    favicon-16/32/48.png       Individual sizes
+    apple-touch-icon.png       180 x 180
+  social/
+    social-preview.png         1280 x 640, GitHub social preview and Open Graph
+    social-preview.svg         Editable source
+```
+
+The wordmark in every logo and social file is converted to vector outlines, so the files look identical on any machine with no font installed.
+
+---
+
+## B. Preview the guidelines (30 seconds, no terminal)
+
+1. Double-click `the-foundation-brand.zip` to unzip it. You get a folder called `brand`.
+2. Open the `brand` folder and double-click `brand-guidelines.html`.
+3. It opens in your browser. You will see the logo, colour palette, fonts, icon set, and tone of voice. You need an internet connection the first time so the fonts can load.
+
+---
+
+## C. Add the brand folder to the repo (terminal)
+
+Your repo is the monorepo that already contains `open-charity-api`. From your earlier work that is:
+
+```
+/Users/mohamedhhussain/Projects/The-Foundation/Foundation/Foundation
+```
+
+### Block 1 : confirm you are in the right place
+
+```bash
+cd /Users/mohamedhhussain/Projects/The-Foundation/Foundation/Foundation
+ls
+```
+
+You should see `open-charity-api` in the list (along with README.md, LICENSE, and so on). If you do, you are in the repo root. If you do not see `open-charity-api`, stop and tell me what `ls` shows, because the path has moved.
+
+### Block 2 : pull the latest, then copy the brand folder in
+
+```bash
+# make sure local is in sync with GitHub first
+git pull
+
+# copy the unzipped brand folder from Downloads into the repo root
+cp -R ~/Downloads/brand .
+
+# check it landed
+ls brand
+```
+
+`ls brand` should show `README.md`, `brand-guidelines.html`, `logo`, `avatar`, `favicon`, `social`, and this `INSTALL.md`.
+
+If `cp` reports that `~/Downloads/brand` does not exist, it means the zip unzipped somewhere else. Run `ls ~/Downloads | grep -i brand` to find it, then adjust the path in the `cp` command.
+
+### Block 3 : commit and push
+
+```bash
+git add brand
+git commit -m "Add brand kit: logo, favicon, social preview, guidelines"
+git push
+```
+
+That is the brand folder live in the repo. Confirm by visiting:
+`https://github.com/the-foundation-stack/Foundation/tree/main/brand`
+
+---
+
+## D. Set the GitHub avatar (browser, cannot be done from git)
+
+GitHub avatars must be a PNG or JPG, which is why `avatar-512.png` exists.
+
+For the organisation avatar:
+1. Go to `https://github.com/organizations/the-foundation-stack/settings/profile`
+2. Under **Profile picture**, click **Upload a photo**
+3. Choose `brand/avatar/avatar-512.png`
+4. GitHub will let you crop. Leave it centred, then save.
+
+(If you would rather set it on the repo itself rather than the org, GitHub does not support per-repo avatars; the org avatar is what shows.)
+
+---
+
+## E. Set the social preview (browser)
+
+This is the image people see when the repo is shared on Slack, X, LinkedIn, and so on.
+
+1. Go to `https://github.com/the-foundation-stack/Foundation/settings`
+2. Scroll to **Social preview**
+3. Click **Edit**, then **Upload an image**
+4. Choose `brand/social/social-preview.png`
+
+Done. Share the repo link anywhere to see it.
+
+---
+
+## F. Wire the favicon and preview into the docs site (optional)
+
+This applies to the published docs landing page (the `docs-site/index.html` that deploys to `the-foundation-stack.github.io/Foundation/`). It makes the browser tab show the keystone icon and makes link previews use the social card.
+
+Open `docs-site/index.html` and paste these lines inside the `<head>` section:
+
+```html
+<link rel="icon" href="/Foundation/brand/favicon/favicon.ico" sizes="any">
+<link rel="icon" href="/Foundation/brand/favicon/favicon.svg" type="image/svg+xml">
+<link rel="apple-touch-icon" href="/Foundation/brand/favicon/apple-touch-icon.png">
+<meta property="og:title" content="The Foundation">
+<meta property="og:description" content="Open standards for charitable giving.">
+<meta property="og:image" content="https://the-foundation-stack.github.io/Foundation/brand/social/social-preview.png">
+```
+
+Note the `/Foundation/` prefix in the paths. GitHub Pages for a project repo serves the site under that subpath, so the leading `/Foundation/` is needed. If you ever move to a custom domain at the root, drop the `/Foundation` prefix.
+
+Commit and push the same way as Block 3, wait two or three minutes for the deploy, then hard-refresh the page (Cmd + Shift + R) to see the new tab icon.
+
+---
+
+## G. Where each file goes, at a glance
+
+| File | Goes where |
+|------|------------|
+| `avatar/avatar-512.png` | Org settings, Profile picture |
+| `social/social-preview.png` | Repo Settings, Social preview |
+| `favicon/*` | Referenced from `docs-site/index.html` head |
+| `logo/*.svg` | README badges, slides, the docs site header |
+| `brand-guidelines.html` and `README.md` | Stay in the repo `brand` folder as the reference |
+
+---
+
+## Need a raster version of the lockup?
+
+The lockups are SVG. If a tool needs a PNG (for example a slide deck), open the SVG in any browser, or tell me the size you need and I will export it.
+
+If you want the colour palette changed, or the wordmark set in a different display face, say so and I will regenerate the entire kit in one pass so everything stays consistent.

brand/README.md

@@ -0,0 +1,120 @@
+# The Foundation : Brand
+
+Open standards for charitable giving, built once and adopted everywhere. From Gift Aid to Zakat, treated as equals.
+
+This folder is the single source of truth for The Foundation's visual identity. Start with `brand-guidelines.html` (open it in any browser) for the full living reference; everything in it is summarised below for quick use.
+
+## Contents
+
+```
+brand/
+  brand-guidelines.html          Full interactive guidelines (logo, colour, type, icons, voice)
+  logo/
+    the-foundation-logo.svg          Horizontal lockup, for light backgrounds
+    the-foundation-logo-reversed.svg Horizontal lockup, for dark backgrounds
+    the-foundation-mark.svg          Mark only, for light backgrounds
+    the-foundation-mark-reversed.svg Mark only, for dark backgrounds
+  favicon/
+    favicon.ico                  Multi-resolution (16/32/48)
+    favicon.svg                  Scalable source
+    favicon-16/32/48.png         Individual sizes
+    apple-touch-icon.png         180x180
+  social/
+    social-preview.png           1280x640, GitHub social preview / Open Graph
+    social-preview.svg           Editable source
+```
+
+Wordmark text in the logo and social files is converted to outlines, so the files render identically anywhere with no font installed.
+
+## The logo
+
+The mark is a foundation in three courses: a broad base, a bearing course, and a clay keystone. Read it as a stable plinth, as a *stack* of standards, or as an upward lift. The keystone always carries the warm accent, the single piece that holds the structure together.
+
+Do:
+* Keep the keystone in Clay; set the base courses in Bedrock, or reverse them to Sand on dark surfaces.
+* Give the mark clearspace of at least one keystone height on every side.
+* Use the mark alone as an avatar, favicon, or social tile.
+* Set the wordmark in Fraunces, capitalised as "The Foundation".
+
+Don't:
+* Recolour the keystone or apply gradients to the courses.
+* Rotate, skew, stretch, or drop-shadow the mark.
+* Re-typeset the wordmark in another font or in all-caps.
+* Place the mark on a busy photo without a solid containing tile.
+
+## Colour
+
+Earth and stone carry the human work of giving; one deep blue carries the trust of a technical standard. Warmth dominates; the blue and ochre punctuate, they are never the field. A rough balance is Sand 60, Bedrock 22, Clay 10, Lapis 5, Ochre 3.
+
+| Token     | Hex       | Use |
+|-----------|-----------|-----|
+| Bedrock   | `#1A1A17` | Primary ink, logo, dark surfaces, body text |
+| Clay      | `#C75B39` | The keystone. Primary accent, links, highlights |
+| Clay Deep | `#A4452A` | Link hover, pressed states, depth |
+| Lapis     | `#1F4A57` | Trust accent: code, positive states, charts |
+| Ochre     | `#D9A441` | Sparing highlight: generosity, callouts |
+| Sand      | `#F4EFE6` | Default background |
+| Paper     | `#FBF9F4` | Raised cards and surfaces on Sand |
+| Stone     | `#8A8170` | Muted captions, metadata, dividers |
+
+```css
+:root{
+  --bedrock:#1A1A17; --clay:#C75B39; --clay-deep:#A4452A;
+  --lapis:#1F4A57; --ochre:#D9A441;
+  --sand:#F4EFE6; --paper:#FBF9F4; --stone:#8A8170;
+}
+```
+
+## Typography
+
+Three voices, all available on Google Fonts under the SIL Open Font License.
+
+* **Fraunces** : display serif, for headlines and pull-quotes. Weights 600, 700, 900.
+* **Hanken Grotesk** : humanist sans, for body copy, labels, and UI. Weights 400 to 700.
+* **IBM Plex Mono** : monospace, for the thing we actually make: endpoints, fields, and tokens. Weights 400, 500, 600.
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,700;9..144,900&family=Hanken+Grotesk:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+```
+
+## Iconography
+
+One line system: 24px grid, 1.8px stroke, rounded joins, geometric and quiet. Icons explain, they never decorate. Draw in Bedrock and reserve Clay for the single icon you want noticed. The full set lives in `brand-guidelines.html`.
+
+## Tone of voice
+
+We write the way a good standard reads: plainly, precisely, and without taking a side.
+
+* **Clear before clever.** A volunteer running a one-person charity must understand us as easily as a platform engineer. Short sentences, concrete nouns, every acronym expanded on first use.
+* **Even-handed, always.** Gift Aid and Zakat get the same care and the same word count. We never rank traditions, platforms, or causes. Respect is non-negotiable; warmth is welcome.
+* **Precise, not rigid.** Specs live or die on precision. We use "must", "should", and "may" in their RFC sense, and we would rather be exact than impressive.
+* **Confident, open to being wrong.** A standard is an invitation, not a decree. We state our reasoning, welcome critique, and change our minds in public when the evidence is good.
+
+We say:
+* "OCAS describes how a charity exposes donations and tax-relief declarations."
+* "Zakat is modelled with all eight Asnaf categories as first-class fields."
+* "This is a draft. Tell us where it is wrong."
+
+We don't say:
+* "Our revolutionary, best-in-class platform disrupts the giving space."
+* "We also support some religious donation types."
+* "The specification is final and authoritative."
+
+## Wiring it into the repo
+
+For the org avatar and social preview, in your repository settings:
+* Upload `logo/the-foundation-mark.svg` (or a PNG export) as the organisation or repository avatar.
+* Under Settings, Social preview, upload `social/social-preview.png`.
+
+For the published docs site, add to the page `<head>`:
+
+```html
+<link rel="icon" href="/brand/favicon/favicon.ico" sizes="any">
+<link rel="icon" href="/brand/favicon/favicon.svg" type="image/svg+xml">
+<link rel="apple-touch-icon" href="/brand/favicon/apple-touch-icon.png">
+<meta property="og:image" content="/brand/social/social-preview.png">
+```
+
+## Licence
+
+Brand assets in this folder are released under CC BY 4.0. Fraunces, Hanken Grotesk, and IBM Plex Mono are licensed separately under the SIL Open Font License.