Skip to content

Add a product

Download .md

Every brand is listed once, in tokens/brands.json. The token build, the registry, the Flutter package and this site all read that list, so a new product takes one command, its logos and a few lines of docs.

  • The logo color, as #RRGGBB. It becomes primary in light mode as it is: a product’s primary is always its logo color.
  • The logo files, one for light grounds and one for dark grounds, in SVG or PNG.
  • An id: lowercase letters and digits, such as lokaticket. It becomes the data-brand value, the theme file names and the Flutter enum value, so pick it once.

In the design system repository:

Terminal window
pnpm new-brand lokaticket --name "Loka Ticket" --logo "#B83A0B" --summary "Ticketing for music events."

The command writes tokens/themes/lokaticket-light.tokens.json and lokaticket-dark.tokens.json, adds the product to tokens/brands.json, and runs the contrast check on the two new themes.

Option Use it for
--name The product name as people read it. Required.
--logo The logo color. Required.
--summary One line, in English, on what the product does. Required.
--secondary A second logo color, for gradients and the login hero.
--dark-primary primary in dark mode, when the derived one doesn’t suit the logo.
--font The display font for brand moments. Defaults to Plus Jakarta Sans.
--fallback sans-serif or serif, after the display font.
--sample A line set in the display font on the Brand page. Write it the way the login hero would say it.
Tokens Light Dark
primary The logo color The logo color, lightened until dark text reads on it
primary-foreground White or dark ink, whichever reads on the logo color and on its hover Dark ink
background, card, muted, border Near white, with a trace of the logo hue Near black, with a trace of the logo hue
foreground, muted-foreground, input Stepped until they reach 4.5:1, or 3:1 for input Same
primary-soft, primary-text A pale tint, and the logo color darkened until it reads as text A deep tint, and a light version of the logo color
chart-1 The logo color, darkened only if it needs to reach 3:1 The logo color, lightened only if needed
brand-* The logo colors, the same in both modes Same

A gray logo gives gray neutrals, because the tint never carries more color than the logo has. The result is a starting point: open the theme files, tune what doesn’t feel like the product, and run pnpm check, which holds every pair to the contrast it needs.

Some logo colors, such as a bright pink or orange, can’t carry white or dark text at 4.5:1. The command keeps the logo color and lists those pairs. Don’t swap in a different primary on your own: ask the design system owner. They either accept the pair as an exception in packages/tokens/src/contrast.ts, as they did for the Cover Clearance orange, or choose another primary.

Put the files in site/public/brand/ and list them in the product’s entry in tokens/brands.json:

"logos": [
{ "variant": "light-ground", "file": "lokaticket.svg", "alt": "Loka Ticket logo, for light grounds" },
{ "variant": "dark-ground", "file": "lokaticket-white.svg", "alt": "Loka Ticket logo, white, for dark grounds" }
]

The Brand page shows them in its logo grid, and the font specimen picks up the display font and the sample line.

If the display font isn’t one the site already loads, add its @fontsource-variable package to site/ and import it in FontSpecimen.astro and block-preview.css. Products load their own fonts.

  • On the Brand page, a section with the product’s brand tokens: <TokenTable group="brand" theme="lokaticket-light" />.
  • On the home page, a line in the product list.
  • In site/public/AGENTS.md, the id in the data-brand list.

Write each change in English and in Indonesian, under id/.

Run pnpm check. It rebuilds everything that reads the list:

  • sosialoka.css with [data-brand="lokaticket"] for light and dark mode
  • the registry themes theme-lokaticket.json for React and Vue
  • the Flutter enum value SosialokaBrand.lokaticket in tokens.g.dart
  • the brand selector on this site and the theme list of the MCP server

Commit the theme files, tokens/brands.json, the logos and flutter/lib/src/generated/tokens.g.dart. The product then installs its theme like any other:

Terminal window
npx shadcn@latest add https://design.sosialoka.tech/r/react/theme-lokaticket.json
ShadApp(theme: SosialokaTheme.shad(SosialokaBrand.lokaticket, Brightness.light));

neutral is a graphite theme: gray surfaces, a near-black primary in light mode and a light gray one in dark mode. It belongs to no product. Use it for:

  • work a vendor or partner starts before the product’s brand is set
  • internal tools and prototypes
  • screens that serve several products at once

A product with its own logo gets its own theme instead. The neutral theme installs and switches like the others:

<html data-brand="neutral" data-theme="dark">
Terminal window
npx shadcn@latest add https://design.sosialoka.tech/r/react/theme-neutral.json
ShadApp(theme: SosialokaTheme.shad(SosialokaBrand.neutral, Brightness.light));