# Add a product

> Give a new Sosialoka product its own light and dark theme from its logo color with one command, and use the neutral theme when a screen belongs to no 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

- **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.

## 1. Generate the themes

In the design system repository:

```bash
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

| 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

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

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

```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

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

- On the [Brand](https://design.sosialoka.tech/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/`.

## 5. Check and commit

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:

```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/theme-lokaticket.json
```

```dart
ShadApp(theme: SosialokaTheme.shad(SosialokaBrand.lokaticket, Brightness.light));
```

## 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
<html data-brand="neutral" data-theme="dark">
```

```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/theme-neutral.json
```

```dart
ShadApp(theme: SosialokaTheme.shad(SosialokaBrand.neutral, Brightness.light));
```
