# Design

> An app has its own personality at the top and Mixel's design system everywhere else, in light and dark.

People move between apps all day. They should feel like one place: each app with a face of its own, all of them read and used the same way.

## What's yours

- **`accent`** in `app.json`: the app's colour, like `"#20b4c4"`. Mixel uses it on the app's card, and it's yours for your hero and your sound visuals.
- **`icon`** in `app.json`: a square `.svg` or `.png`, shown on the app's card in Mixel.
- **A hero**, at most 160 px tall, with your own art behind your name: `<AppHero wordmark="Loop Maker" accent="#20b4c4" description="…" />`.

## What's shared

Everything below the hero uses the design system: its components, its colour tokens, its type and spacing. That's what makes a new app feel familiar on first use.

- **Components.** The [components reference](https://docs.0x1audio.com/reference/components.md) lists every one with its props and when to use it, [The design system](https://docs.0x1audio.com/design-system.md) has every rule, and [Design tokens](https://docs.0x1audio.com/design-tokens.md) every colour, size and timing. The MCP tool `ui_components` returns the same list to coding agents.
- **Colours** come from tokens (`bg-card`, `text-muted-foreground`, `border-border`), never hex values, so the page follows light and dark on its own. Call `followSystemTheme()` once, as [A custom page](https://docs.0x1audio.com/page.md) shows.
- **One filled button per view**, for the main thing to do. Everything else is `secondary`, `outline` or `ghost`.
- **Every state.** Design what the page looks like empty (`EmptyState`), working (`Progress`, `Skeleton`), done, and when something goes wrong (`Callout`).

## Words

- Say what it does for the person, in their words: song, sound, file, folder, Library. Leave out how it works inside.
- Sentence case. Buttons are specific verbs: "Make the loop", "Choose a song", not "Submit" or "OK".
- No exclamation marks, and no emoji.
- An error says what happened, then what to do: "That selection is too short to loop. Select at least 50 ms."

## Before you publish

Open the app with `mixel dev` and look at it in light and in dark, with a long file name, with no files yet, and after pressing Stop. Then read every word on it out loud once.