Theme a site with a brand DNA

A brand DNA is one JSON file, brand/brand.dna.json. It holds the identity, the colours, the type, the logos and the voice of a brand. The site engine reads only this file for these facts, so a change to the brand is a change to one file.

The filesCopy Anchor Link

Do not format brand.dna.json with a code formatter. A change to the bytes changes the hash of the brand.

What the site takes from the DNACopy Anchor Link

The engine text is in seven languages: English, German, French, Spanish, Dutch, Portuguese and Turkish. A locale with no table stops the build.

Compile the brandCopy Anchor Link

ship-site theme compiles the brand DNA. ship-site build and ship-site dev also do this step first.

npx ship-site theme

The command writes the theme to .ship-site/theme/ and the served brand files to public/_brand/. Both folders are generated, so keep them out of git. The served files are the favicon, the app icons, the logos and the default social card.

If the logo mark has no permission to sit on the page surface, the favicon puts the mark on a tile. The tile has the colour that the DNA allows under the mark. A white mark thus stays visible in a browser tab.

Dark modeCopy Anchor Link

The site has a dark mode only when the DNA has dark colour roles, in tokens.color.role-dark. Then the site follows the system setting, and the header has a theme switch. Without dark roles, the site stays light and has no theme switch.

Check the brandCopy Anchor Link

The dna command of @lets-ship/brand-dna checks and changes a DNA file.

npx dna lint brand/brand.dna.json --assets brand/assets
npx dna derive brand/brand.dna.json --write

dna lint checks the file against the schema and the brand rules. dna derive computes the tonal steps and the contrast pairs from the source colours. Run dna derive after you change a source colour, because the lint fails on old derived values.

The white-label checkCopy Anchor Link

After each build, ship-site build reads every file in out/. A colour that is not in the DNA stops the build, and so does a font family that is not a brand font. Each page must also have a social card. This check keeps a theme of another brand, or a default palette, out of your site.

To start a new brand, write a DNA from a preset: harbor, fern, ember, slate, plum or sand.

npx dna preset harbor --id acme --name "Acme" --out brand

Get a brand in the first missionCopy Anchor Link

The form of the first site mission asks where the brand comes from. Pick one of three brand sources:

• Use my website: the agents take the colors, the fonts and the logo from a website that you own.
• Use my logo: the agents make the brand from your logo file and your brand name. The file is a PNG, JPEG or WebP image of up to 2 MB.
• Pick a look: the site starts from one of six preset looks, with your brand name.

The brand name has 2 to 60 characters. The form does not take an SVG logo. A preset look keeps its own mark, and the agents set your brand name in the DNA.

The brand rights boxCopy Anchor Link

Before you start, confirm that you own the brand or have the right to use it. SHIP records the confirmation with your user, the time and the version of the text. Without it, SHIP refuses the start.

The text of the box is "I own this brand or have the right to use it". The record also holds the brand source and its detail: the website address, the hash of the logo file, or the id of the preset. With a logo or a preset, it holds the brand name too. If the text changes after you open the form, SHIP refuses the start. Reload the form and confirm the new text.