Add a product
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.
Before you start
Section titled “Before you start”- The logo color, as
#RRGGBB. It becomesprimaryin 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 thedata-brandvalue, the theme file names and the Flutter enum value, so pick it once.
1. Generate the themes
Section titled “1. Generate the themes”In the design system repository:
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. |
How the colors are made
Section titled “How the colors are made”| 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.
When the check reports a pair
Section titled “When the check reports a pair”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.
2. Add the logos
Section titled “2. Add the logos”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.
3. Load a new display font
Section titled “3. Load a new display font”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.
4. Add the product to the docs
Section titled “4. Add the product to the docs”- 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 thedata-brandlist.
Write each change in English and in Indonesian, under id/.
5. Check and commit
Section titled “5. Check and commit”Run pnpm check. It rebuilds everything that reads the list:
sosialoka.csswith[data-brand="lokaticket"]for light and dark mode- the registry themes
theme-lokaticket.jsonfor React and Vue - the Flutter enum value
SosialokaBrand.lokaticketintokens.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:
npx shadcn@latest add https://design.sosialoka.tech/r/react/theme-lokaticket.jsonShadApp(theme: SosialokaTheme.shad(SosialokaBrand.lokaticket, Brightness.light));Neutral theme
Section titled “Neutral theme”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">npx shadcn@latest add https://design.sosialoka.tech/r/react/theme-neutral.jsonShadApp(theme: SosialokaTheme.shad(SosialokaBrand.neutral, Brightness.light));