Documentation

Everything you need to ship a brand repository

A practical guide to GitBrand — from creating your first repo to embedding it on another website.

Getting started

GitBrand requires no installation. Sign in with Google, GitHub or an email and password to create your account, then jump straight into the editor. Most users have a public repo online within five minutes.

Repositories live at gitbrand.com/your-slug. The slug is yours to pick and is part of how you share it.

Creating a repository

Head to your profile and click Create repository. You will be asked for a name, slug and visibility. You can change all of these later from the repo settings.

Name — the title shown at the top of your repo page.
Slug — the URL identifier, lowercase, hyphenated. Pick something memorable: short and clean wins.
Visibility — public for anyone to see, or private with a password.

Choose Continue to optionally add brand assets. Enter a public HTTPS website and choose Find website assets, or drop an SVG, PNG, JPG, or WebP logo (up to 2 MB). Website suggestions may include icons or social images; choose a candidate to review it. Sites that require JavaScript or block fetching may need a manual upload.

Raster logos are traced into an SVG. Compare the original and converted previews, then explicitly approve the result. Tracing can change lettering, gradients, and edges; upload the original SVG if the result is not accurate. Select any suggested colors you want to add. No colors are selected automatically. Your website, approved logo, and selected colors are saved when you choose Create repository. To start without assets, leave this step empty and create your repository.

Cloning a repository

Choose Clone on a repository in your profile, or Clone repositoryin the editor toolbar. Enter a new name and an unused URL, then choose Create private clone. You can clone repositories where you are a member, including private repositories.

The copy includes logos, color themes, fonts, resources, formatted FAQs, brand voice, description, and website. Uploaded files stored in the source repository get independent copies; external links, such as Google Fonts, remain linked. The original repository is unchanged.

The clone starts private with AI access off, no password, and you as its only member. Collaborators and view counts do not carry over. After cloning, the editor opens your new copy. You can change its visibility in repository settings when it is ready.

Editing & saving

Use the section navigation to jump between logos, colors, typography, resources, questions, and brand voice. Repository settings contains your name, description, website, and visibility. View repository opens the saved page.

Asset forms save when you confirm their Add, Upload, or Save action. Brand voice is saved separately: a save bar stays visible whenever you have unsaved changes. Choose Save brand voice to update the repository. If saving fails, your changes remain available and the bar offers a retry.

Unsaved brand voice drafts are kept in session storage for your account and repository. Return in the same browser tab to recover a draft after navigating away or reloading. Drafts are not shared with teammates or other devices, and closing the tab may remove them. If browser storage is unavailable, the save bar tells you to save before leaving.

Uploading logos

GitBrand prefers SVG as the source format. Vector files mean every export — PNG, JPG, retina, oversized — looks crisp.

Choose Upload logo, then select or drag in an SVG file.
Choose a category: wordmark, symbol, monogram, horizontal or stacked lockup, badge, social avatar, favicon, partner lockup, or an existing standard variant.
Add multiple variations to the same category. Give each a display name, or choose Custom category for a logo that needs its own name.
Set the background color (dark or light) so visitors can preview readability.
Visitors can download in SVG, PNG or JPG at the exact size they need.
Choose Download all logos to get every SVG in a single ZIP. Files are numbered in display order, so variations with the same name stay separate.

Tip: name your files semantically — "logo-horizontal-black.svg", not "v3-final-3.svg". Visitors see the file name when they download.

Color palettes

Define colors as #RRGGBB hex values. GitBrand automatically generates RGB, HSL and CMYK conversions so anyone using your brand can copy what they need.

Assign each color to Shared, Light theme, or Dark theme. Existing colors are Shared.
Add as many shades or variations as you need. Use the pencil button to edit a color, its name, type, or palette without deleting it.
Visitors can switch between light and dark palettes. Shared colors remain visible in both. Theme-specific values take precedence for a matching role.
Name each color (Primary, Accent, Surface…) for clarity.
Use the palette download menu on a published repo to export the full palette as CSS, SCSS, Tailwind, JSON, TXT or SVG. Theme-specific token names include a light or dark suffix; JSON also includes the theme and role.

Fonts

Upload font files (WOFF, WOFF2, TTF, OTF) or link to a Google Font or Adobe Fonts URL. GitBrand renders a live preview, including a size slider visitors can play with to see the type at different scales.

Resources & files

Anything that does not fit logos, colors or fonts goes in resources: PDF brand guidelines, illustrations, mockups, archives, presentations. Each resource gets its own download tile on your repo page.

FAQs on your page

Most brands get asked the same handful of questions ("can I use the logo on a dark background?", "what's the correct typeface for body text?"). Add them to the FAQ section on your repo so visitors find answers without emailing you.

In the answer editor, select text and use Bold, Italic, Bullet list, Numbered list, or Link. The editor uses a small Markdown subset; choose Preview to see the formatted result before saving. Replace the example URL when inserting a link. Supported link schemes are https://, http://, and mailto:. Raw HTML is displayed as text.

Existing answers keep their plain-text appearance until you apply formatting. Editing a question does not change its position in the FAQ.

Private repositories

Set a repo to private from settings and add a password. Visitors will land on a lock screen and need to enter the password before any data is loaded.

Passwords are checked server-side — never exposed to the browser.
You can rotate the password at any time from settings.
Private repos still get a public URL — just locked behind the password.

Every repo has three URLs:

gitbrand.com/your-slug — the canonical public page.
gitbrand.com/embed/your-slug — the same content, without GitBrand's header and footer. Use this in an iframe on your own site.
gitbrand.com/r/your-slug — a permanent legacy alias if you ever change your slug.

Brand voice fields

Brand voice fields turn a static asset library into a living brand brief. They power the Markdown brief, brand.json and the prompts AI tools use to generate on-brand work. From the editor you can fill in:

Mission — one sentence about why your brand exists.
Tagline — the short-form expression of your brand.
Positioning — 1–2 sentences on who you serve and what makes you different.
Audience — the primary audience.
Voice — three to five voice anchors (e.g. confident, warm, plainspoken).
Tone — when and how the voice shifts.
Principles, Do, Don't — short lines an editor or AI can scan in seconds.
Pronunciation — useful for accessibility and read-aloud agents.

On colors, optionally tag a semantic role (primary, secondary, accent, neutral, success, warning, danger, background, text). AI tools rely on the role to pick the right color when generating UI.

Use with AI

Every public GitBrand is reachable as a structured record at well-known URLs. Hand any of them to an AI agent and it will generate on-brand work without guessing.

gitbrand.com/your-slug/brand.json — full structured record (schema versioned).
gitbrand.com/your-slug/llms.txt — a short llms.txt index.
gitbrand.com/your-slug/llms-full.txt — the verbose variant with full voice and FAQ.
gitbrand.com/your-slug.md — Markdown brief, perfect to paste as system context.
gitbrand.com/api/v1/repos/your-slug — REST endpoint with the same JSON record under data.

Each public repo page also embeds JSON-LD (schema.org/Organization) and <link rel="alternate"> tags pointing to the JSON, Markdown and llms.txt URLs — so AI crawlers and retrieval systems index the structured data, not just the rendered HTML.

From the public repo page, the Use with AI section gives you a one-click "Copy as prompt" button — it builds a system prompt from your voice, principles, palette and primary logo URL.

Privacy — private and password-protected repositories never appear on AI surfaces. Public repos can be opted out per-repo with the AI access toggle.

MCP server

GitBrand exposes a Model Context Protocol server at gitbrand.com/mcp/your-slug. Drop the snippet below into your agent's MCP config to make the brand a live tool.

{
  "mcpServers": {
    "your-brand": {
      "url": "https://gitbrand.com/mcp/your-brand"
    }
  }
}

For Cursor, that goes in ~/.cursor/mcp.json. For Claude Desktop, in the claude_desktop_config.json file. Once connected, your agent gains four tools:

get_brand — full JSON brand record.
get_brand_brief — Markdown brief.
get_palette — colors with semantic roles.
get_logos — logo URLs by type.

The MCP server is an HTTP-only JSON-RPC 2.0 transport (the latest streamable HTTP profile) — no installation, no SSE proxy. Calls run against the same Firestore document your team edits, so any change shows up the next time the agent fetches.

Asset API

Every published asset has a stable URL you can hot-link from a website, a design tool, a CMS or a script. Logos are rendered on demand in the size and format you ask for, so nobody has to export files by hand and nothing goes out of date.

/brand/{repository}/{link-name}/{version}
/brand/{repository}/{version}.json

repository — your slug, the same one used in gitbrand.com/your-slug.
link-name — the asset's link name, shown in the editor under each logo, color, font and file (for example logo-standard or color-primary). Link names are frozen inside each published version.
version — which published version to serve:
- main — The latest published version. Updates every time you publish.
- a version id — A specific published version, for example 8c5ofd. Never changes.

Parameters

Parameter	Applies to	Values	Description
`format`	logos	svg · png · jpg · webp	Image format. Defaults to svg, the original file.
`width`	logos	16 – 4096	Width in pixels. The height follows unless you set it too.
`height`	logos	16 – 4096	Height in pixels.
`fit`	logos	contain · cover · fill · inside	How the logo fills the box when both width and height are set.
`background`	logos	a hex color, e.g. ffffff	Fills the transparent area. Required for jpg, optional otherwise.
`padding`	logos	0 – 512	Space around the logo, in pixels.
`quality`	logos	1 – 100	Compression for jpg and webp. Defaults to 90.
`format`	colors	json · hex · css · scss	How the color is returned. json includes hex, rgb, hsl and cmyk.
`format`	fonts	file · css	The font file itself, or a ready-to-use @font-face stylesheet.
`download`	every asset	1	Sends the file as a download instead of showing it in the browser.

Sizing parameters need a raster format (png, jpg or webp); an SVG is always returned exactly as uploaded. When only width or height is given the other side scales proportionally. Colors return JSON with hex, rgb, hsl and cmyk by default, or a single snippet with format=hex, css or scss. Fonts and files are served as stored; Google Fonts redirect to Google.

Examples

<!-- A 240px PNG of the latest logo -->
<img src="https://gitbrand.com/brand/acme/logo-standard/main?format=png&width=240" alt="Acme">

/* Pinned to one version, so the page never changes unexpectedly */
.hero { background-image: url("https://gitbrand.com/brand/acme/logo-standard/8c5ofd?format=webp&width=1200"); }

/* Colors as CSS variables */
@import url("https://gitbrand.com/brand/acme/color-primary/main?format=css");

// Everything that is published, as JSON
const brand = await fetch("https://gitbrand.com/brand/acme/main.json").then((r) => r.json());
brand.logos[0].formats.png; // → https://gitbrand.com/brand/acme/logo-standard/main?format=png

# Private repositories: send an API token
curl -H "Authorization: Bearer gb_…" "https://gitbrand.com/brand/acme/logo-standard/main?format=png&width=512"

Latest version, original file: https://gitbrand.com/brand/acme/logo-standard/main
Latest version as a 512px PNG: https://gitbrand.com/brand/acme/logo-standard/main?format=png&width=512
A specific version, JPG with a white background: https://gitbrand.com/brand/acme/logo-standard/8c5ofd?format=jpg&width=240&background=ffffff
Everything published, as JSON: https://gitbrand.com/brand/acme/main.json

Versions and caching

main always points at the latest published version and is revalidated every minute (Cache-Control: public, s-maxage=60, stale-while-revalidate=86400 with an ETag, so browsers and CDNs get a 304 when nothing changed). A version id never changes, so those URLs are cached for a year with immutable. Every response carries X-GitBrand-Version with the version id it was served from, X-GitBrand-Asset with the link name, and Access-Control-Allow-Origin: * so you can fetch from any origin.

Only GET, HEAD and OPTIONS are accepted. Errors are JSON: { "error": { "code": "not_found", "message": "…" } }.

Private repositories

Public repositories need nothing else. For private or password-protected repositories, create an API token in the repository settings (API access). The token is shown once; store it like a password and revoke it from the same place if it leaks. Send it as Authorization: Bearer <token>, or as ?token= where you cannot set headers. Signed-in members can also use their own session token. Authenticated responses are never cached (Cache-Control: private, no-store); requests without a valid token get a 401.

Public repositories need nothing else. Private repositories send a token in the Authorization header: Bearer <token>.
Responses are cached. main is checked again after a few minutes; version ids are cached for a long time.
Link names are frozen inside each published version, so old links keep working after a rename.

Tips & shortcuts

Click any color swatch on a repo page to copy the hex value to your clipboard.
Click a font name to copy the font family declaration.
Use the Share button at the bottom of every repo to copy the canonical URL.
Add a website link in repo settings so visitors can jump from your assets straight to your live brand.
Run curl gitbrand.com/your-slug.md in your terminal to grab the Markdown brief — pipe it straight into a chat or an agent.

Have a question we missed? Check the FAQ or contact us directly — we read every message.

Everything you need to ship a brand repository

Getting started

Creating a repository

Cloning a repository

Editing & saving

Uploading logos

Color palettes

Fonts

Resources & files

FAQs on your page

Private repositories

Sharing & embedding

Brand voice fields

Use with AI

MCP server

Asset API

Parameters

Examples

Versions and caching

Private repositories

Tips & shortcuts