Brand the sign-in pages

Your sign-in pages can wear your app's colours, fonts and logo, so they feel like your own. You also choose the corner shape, button style, layout, background and spacing, and you set separate colours for light and dark mode.

Your branding applies all the way through sign-in: the opening page, the email and phone codes, account setup, required details, the what's-shared screen, and the buttons in an iframe or the snippet. It is saved as part of your sign-in setup, so every change gets a version number.

printf '%s' "$APP_SECRET" | silicon-accounts app use waveform --secret-stdin
silicon-accounts app config set branding.json --expected-version 8

with branding.json:

{
  "branding": {
    "theme": "auto",
    "logo_url": "https://cdn.example.com/waveform/logo.svg",
    "logo_dark_url": "https://cdn.example.com/waveform/logo-dark.svg",
    "logo_height": 40,
    "show_app_name": false,
    "font_family": "Inter",
    "heading_font_family": "Fraunces",
    "corner_style": "rounded",
    "radius": 12,
    "button_style": "solid",
    "layout": "split",
    "background_style": "dots",
    "density": "comfortable",
    "light": {"primary": "#0B6E4F", "primary_foreground": "#FFFFFF"},
    "dark": {"primary": "#0B6E4F", "primary_foreground": "#FFFFFF", "background": "#101412", "surface": "#18201C"}
  }
}

Updated waveform (branding); the sign-in setup is now version 9.

Everything you leave out keeps its current value, and for an app that never set any branding, that's the Silicon Accounts look. A palette you never set takes its colours from the same theme's defaults, so your dark palette never inherits light colours. Over HTTP, it's the same patch:

curl -s -X PATCH -u "$APP_ID:$APP_SECRET" \
  -H 'Content-Type: application/json' \
  --data-binary @branding.json \
  "$ACCOUNTS_URL/v1/apps/$APP_ID/signin-config"

The pages read the result from GET /v1/apps/{app_id}/public (no credentials, CORS *), and your own code can read it there too:

curl -s "$ACCOUNTS_URL/v1/apps/waveform/public"

{
  "app_id": "waveform",
  "name": "Waveform",
  "methods": ["apple", "google", "email"],
  "branding": {
    "background_image_url": null,
    "background_style": "dots",
    "button_style": "solid",
    "corner_style": "rounded",
    "dark": {"background": "#101412", "border": "#4A4845", "danger": "#FF8A80", "foreground": "#FFFDF9", "muted": "#B5B0A8", "primary": "#0B6E4F", "primary_foreground": "#FFFFFF", "surface": "#18201C"},
    "density": "comfortable",
    "font_family": "Inter",
    "heading_font_family": "Fraunces",
    "layout": "split",
    "light": {"background": "#FFFDF9", "border": "#E8E3DA", "danger": "#B42318", "foreground": "#353432", "muted": "#6F6B66", "primary": "#0B6E4F", "primary_foreground": "#FFFFFF", "surface": "#FFFFFF"},
    "logo_dark_url": "https://cdn.example.com/waveform/logo-dark.svg",
    "logo_height": 40,
    "logo_url": "https://cdn.example.com/waveform/logo.svg",
    "radius": 12,
    "show_app_name": false,
    "theme": "auto"
  },
  "copy": {"title": "Sign in to Waveform", "subtitle": null, "terms_url": "…", "privacy_url": "…", "support_email": "…"},
  "logo_url": "…",
  "logo_dark_url": "…",
  "homepage_url": "…",
  "allowed_origins": ["…"]
}

You can make the same changes in your app's Pages tab (/apps/{app_id}/pages) on developers.teamofsilicons.com, where you can edit the wording too.

Its live preview shows every step: sign-in and sign-up, opening Google or Apple, entering a code, account setup, your custom flow, the what's-shared screen and the embedded buttons. Switch between light and dark, or desktop and phone, to check each layout.

Branding can be changed with the app's credentials, or by one of its authors through their own session. See who can change the setup.

The variables#

Values are exact: "Inter", not "inter"; "split", not "Split". Numbers are whole numbers.

The palettes#

Each theme has the same eight colours, written #RRGGBB (any letter case; we store them uppercase):

With theme: "auto", set both palettes, because a visitor whose device is dark sees dark. With a forced theme, only that palette is used.

Contrast: at least 4.5:1#

Two pairs must be readable in both themes, or the patch is refused:

The minimum is 4.5:1, the WCAG AA level for normal-size text. Our defaults are well above it (button text 6.10:1, page text 12.24:1 light and 14.30:1 dark). A refusal tells you the measured ratio, rounded down to two decimals:

curl -s -X PATCH -u "$APP_ID:$APP_SECRET" -H 'Content-Type: application/json' \
  -d '{"branding": {"light": {"primary": "#22C55E", "primary_foreground": "#FFFFFF"}}}' \
  "$ACCOUNTS_URL/v1/apps/$APP_ID/signin-config"

{
  "error": {
    "code": "validation_failed",
    "details": {
      "fields": {
        "branding.light.primary_foreground": "contrast between branding.light.primary_foreground (#FFFFFF) and branding.light.primary (#22C55E) is 2.27:1; it must be at least 4.5:1 (WCAG AA for text) because button text must stay readable"
      }
    },
    "hint": "Fix the fields listed in details.fields and send the request again.",
    "message": "Invalid fields: branding.light.primary_foreground: contrast between …"
  }
}

There are two ways to fix it: keep the colour and flip the text (#22C55E under #0A0A0A is well above 4.5:1), or darken the colour (#15803D under #FFFFFF is 5.01:1). The check runs on the whole result of the patch, so changing primary alone can break a pair you set earlier.

We don't refuse other colours, but check them the same way: text sits on surface in the card, so keep foreground and muted at 4.5:1 there too. Error text is the one case the pages handle for you. When danger reads below 4.5:1 on your surface or background, the pages move it toward your foreground just far enough to pass, and keep every other colour exactly as you chose it.

Logos#

{"branding": {"logo_url": "https://cdn.example.com/waveform/logo.svg", "logo_dark_url": "https://cdn.example.com/waveform/logo-dark.svg", "logo_height": 40}}

• Use an https URL, or an inline data:image/png, jpeg, webp, gif or svg+xml URI up to 128 KB. Plain http is refused ('http://…' must use https), and a larger inline logo is refused with "inline data URIs must be at most 128 KB; host the logo and use an https URL".
• The pages load your logo from your URL as it is, without sending the page address as a referrer. Serve it from a host that stays up, because a logo that fails to load is replaced by your app's name.
• Without logo_url, the logo your app has in Silicon Apps is used, so many apps never set one here.
• The whole PATCH body may be at most 512 KB, which leaves room for two inline logos.

Fonts#

Only these. We serve them ourselves and load each one only when a page uses it, so your sign-in never waits on a third-party font host or reports your visitors to one. The usual pairing is a body font with a heading font: "font_family": "Inter", "heading_font_family": "Fraunces".

"Powered by Silicon Accounts"#

Every page ends with "Powered by Silicon Accounts", with "Silicon Accounts" linking to https://accounts.teamofsilicons.com. It isn't a variable: you can't remove, hide, recolour or restyle it. We draw it outside the branded part of the page, in our own colours (light or dark, following the visitor), so no branding reaches it. The iframe and the snippet show it too, on an opaque pill of their own so it reads on any page. Why.

The iframe and the snippet#

The buttons in the iframe and the snippet use the same palette, radius, corner style, button style, density and font. Which palette they paint is decided in this order:

• iframe: the embed URL's theme=light or theme=dark (it describes your page around the frame); otherwise a branding theme of light or dark; otherwise the device's theme when the URL says theme=auto; otherwise light.
• snippet: data-theme="light" or "dark"; otherwise a branding theme of light or dark; otherwise your page decides: the first opaque background behind the buttons, or the page's color scheme.

How to set them up is in Add sign-in to your app.

Reset and undo#

• null resets one variable to its default: {"branding": {"radius": null}}.
• {"branding": {"light": null}} resets the whole light palette.
• {"branding": null} resets all branding to the Silicon Accounts look.
• Every change is a new version in the history, with the before and after of each variable. To undo, patch the before values back.

Errors#

All of these are 422 validation_failed, with every problem in details.fields. We only check colour contrast once all eight colours of a palette are valid.

Related#

• Why branding works this way: what is and isn't configurable, and why.
• Configure sign-in: versions, history and the other settings.
• Add sign-in to your app: the hosted pages, the iframe and the snippet.