# Design and slide tools

> Insert a brand’s logo in its colours, with the right file for the background.

Source: https://new.wasmenia.com/en/developers/use-cases/design

A slide or design tool where the user searches for a brand and inserts its logo: the original file (usually SVG), a file for dark backgrounds when there is one, the brand’s colours to tint around it, and a text colour that reads on them.

- `GET https://new.wasmenia.com/api/v1/search/suggest`
- `GET https://new.wasmenia.com/api/v1/brands/{slug}`

- **Products**: Search, logos, identity data
- **Pulls**: One per brand inserted
- **File**: The original with your key, usually SVG

## The problem, and the fix

The user searches the web for a logo and finds a cropped image on a white background, or an old logo, and guesses its colours with an eyedropper.

One record gives your tool the original logo, the right file for the slide’s background, and the brand’s colours with their source. `colorsSource` says: set by an editor, from the guidelines, or extracted from the file and approximate.

## Who it’s for

### Slide tools

The client’s logo on the cover in its identity’s colour.

### Design editors

Insert a logo with the brand’s palette.

### Document generators

Quotes and reports with the brand’s current logo.

## Build it

### Get a key

Open a developer account in the console and make a key. The free plan is enough to start, and the key stays on your server in an environment variable.

### Search inside the tool

Suggestions as you type, from a route on your server.

### Read the record on insert

One pull; keep it with the document.

### Pick the file for the background

A file whose `colorMode` matches the background, else the primary on a tile.

### Tint with the brand’s colour

The main colour as a background or band, with white or dark text by contrast.

## Picking the file for a background

`logo-for.js`

```javascript
/**
 * The file to show on a light or dark ground: one made for that ground if the
 * brand has it, else its primary logo, with whether that needs a tile behind it.
 */
export function logoFor(brand, ground /* 'light' | 'dark' */) {
  const version = brand.currentVersion;
  if (!version) return null;

  const files = version.variants.filter((v) => v.asset?.url);
  const forGround = files.find((v) => v.colorMode === ground);
  const primary = files.find((v) => v.role === 'primary');
  const asset = (forGround ?? primary)?.asset ?? version.logo;
  if (!asset) return null;

  return {
    src: asset.url,                 // the original, usually SVG
    small: asset.thumbnailUrl,      // WebP, 256 on its longer side
    width: asset.width,             // null for a vector without a size
    height: asset.height,
    // A primary drawn for dark grounds, shown on a light page, needs a dark tile.
    tile: !forGround && primary?.colorMode === 'dark' ? 'dark' : null,
  };
}
```

## The main colour and its text colour

`brand-swatch.js`

```javascript
/** The brand's main colour and a text colour that reads on it. */
export function brandSwatch(brand) {
  const main = brand.colors.find((c) => c.role === 'primary') ?? brand.colors[0];
  if (!main) return null; // no colours: keep your own
  return { background: main.hex, text: readableOn(main.hex), source: brand.colorsSource };
}

/** White or near-black, whichever contrasts more with `hex` (WCAG). */
function readableOn(hex) {
  const [r, g, b] = [1, 3, 5].map((i) => {
    const c = parseInt(hex.slice(i, i + 2), 16) / 255;
    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
  });
  const l = 0.2126 * r + 0.7152 * g + 0.0722 * b;
  return 1.05 / (l + 0.05) >= (l + 0.05) / 0.05 ? '#ffffff' : '#111111';
}
```

## How many pulls it costs

Search isn’t counted. Each brand a user inserts is one pull, and if you keep the record with the document it isn’t repeated when the document opens again.

> **Logo rights**
>
> The logo is inserted as it is, with no change to its shape or colours. Read [Use and rights](https://new.wasmenia.com/developers/docs/concepts/usage.md) (Arabic).

**Brand colours in your UI**

The main colour, a text colour that reads on it, and where colours come from.