Brands and several surfaces

A product with several surfaces often needs more than one look. The website and the mobile app share most values, but the mobile app has its own accent colour. A partner portal uses the partner's brand. The brand library handles this.

How brands work

The brand library belongs to the workspace, so every project can use it. It holds two kinds of brand:

• A foundation holds what every brand shares: colours, type, spacing, corners.
• A brand inherits from a foundation (or from another brand) and changes only what differs.

A surface that uses a brand gets its values in this order. A later layer wins:

1. the foundation;
2. each brand below it, down to the surface's brand;
3. the surface's own changes.

Dark and other themes follow the same order, one theme at a time. A brand can change only the dark value of a colour and keep the light one.

A surface without a brand uses the project's own design system, plus its own changes.

Create a foundation and a brand

1. Open the brand library

   Go to Settings › Brand library.

2. Add a foundation

   Choose New brand. Leave Inherits from on Nothing: a new foundation. To copy an existing design system, pick a project under Start from a project.

3. Add a brand

   Choose New brand again. Under Inherits from, pick the foundation. The new brand starts with every value of the foundation.

4. Change what differs

   Select the brand, find a value and choose Edit. Each value shows where it comes from, such as From Acme or This brand. Choose Use inherited to go back to the parent's value.

Brands can be nested four levels deep. A brand that other brands inherit from can't be archived until they are archived.

Give a surface its brand

Open System and choose Surface brand. Pick the surface (the same one as in the switcher at the top of the project), then pick its Brand.

The list shows every value the surface ends up with and where each one comes from:

• From Acme: the foundation.
• From Acme Mobile: the surface's brand.
• This surface: a change made for this surface only.
• From the project system: the surface has no brand.

Change a value

Choose Edit next to a value, then:

• Save for this surface changes only this surface.
• Save to Acme Mobile changes the brand. Every surface that uses the brand, or a brand that inherits from it, changes too. M1rror tells you how many first, for example Used by 3 surfaces in 2 projects.

Every save is a new version. Nothing is overwritten, and a save based on an older version is refused. A save that would break a value, such as a link to a colour that no longer exists, is refused with the reason.

Brand versions

Every save of a brand is a version. In Settings › Brand library, select a brand and scroll to Versions:

• Each version shows its message, when it was saved, and how many values it sets.
• Choose Compare, or pick From and To, to see what changed: values set, changed, removed, or inherited again from the brand above.
• Where each version is used lists every surface on the brand. Surfaces always show the newest version while you work. Each line also says which version the surface's latest release used, or that no release recorded one.
• Restore saves an older version's values as a new version. Nothing in the history is lost. You need design access.

Send a release for one surface

When a project has surfaces, Send for review asks which surface the version is for. It starts with the surface chosen at the top of the project. Choose Whole project for a version that covers every surface.

The version records the surface and the brand versions it used. You can't change that later: send a new version instead.

Check consistency between surfaces

Open System and choose Consistency. It compares the surfaces of the project:

• Values that differ between surfaces, and where each value comes from, such as From Acme Mobile. Values some surfaces lack.
• Components some app surfaces lack, and components whose props differ between surfaces. M1rror uses the components the latest scan found in each surface's folder, and the components on each surface's screens.
• Brand versions: surfaces whose latest release used an older brand version are marked Behind the brand. A surface with no release, or a release from before versions were recorded, shows Not recorded.

M1rror compares only what it has. A surface with nothing to compare is listed under Nothing to compare yet, with the reason. For example, M1rror does not read Android code yet.

Export a surface's tokens

In Surface brand, choose Export CSS to download the surface's final values.

Every token export accepts a surface. Add surface_id to GET …/tokens/export, or pass surface_id to taste_export_tokens. To export a brand on its own, use GET /v1/workspaces/{ws}/brands/{brand}/export. Every format works: CSS, Tailwind, TypeScript, JSON, DTCG, Markdown, SwiftUI, Android and Jetpack Compose.

A DTCG export with layers=1 keeps the structure. Each token names its layer in $extensions["com.m1rror.layers"], and the file lists the layers in order.

For coding agents

Agents can read brands but not change them. These tools are read-only:

• taste_list_brands and taste_get_brand: the library, and one brand with its resolved values and where each comes from.
• taste_get_brand_impact: every surface, and its project, that a brand change reaches.
• taste_get_surface_tokens: a surface's final values with their layer.
• taste_export_tokens with surface_id: a surface's values in any format.
• taste_export_brand_tokens: a brand's values in any format.
• taste_list_brand_versions, taste_get_brand_version and taste_compare_brand_versions: a brand's versions, one version as saved, and what changed between two.
• taste_get_surface_consistency: how the surfaces of a project differ.

Changing brands and surface values needs a person with design access.