The design system

Mixel is built with one design system, and so is every app's page and every form Mixel draws for an app. This page is that system for app authors: the principles, the component rules and the words reviewers read your page against. Design is the short version, Design tokens has every colour, size and timing, and the components reference lists every component with its props.

A page gets all of it from one package: the theme once in its CSS (@import "@0x1audio/design-system/theme.css"), and components from @0x1audio/design-system. A custom page shows the setup. An app without a page needs none of this: the form Mixel draws already follows every rule here.

PrinciplesCopy Anchor Link

1. Greys, and one colour of your own. The interface is greys. Your app's accent lives in its hero and its icon, nowhere else. Mixel's own lit colour means "sound is playing" or "this needs you" everywhere in Mixel, so apps leave it alone.
2. Facts, not taglines. A page opens with what's true: "3 songs · 12:40 in all". No greetings, and no marketing sentence where a number fits.
3. Every state is designed. Default, hover, pressed, focus, disabled, working, empty, error, and long or overflowing text. Empty on first use and empty after a filter are different states.
4. Nothing is dead. Every visible control does something. No placeholders and no "coming soon". Something empty is hidden, not shown greyed out.
5. Remove before adding. If a border, label, icon or card can go without losing meaning, it goes. Space and alignment do the work borders would.
6. Both themes, always. Never a hex colour in a page. Look at every screen in light and in dark, and at the window's smallest size.
7. Motion explains. Short and eased, and only to show where something came from or went.
8. Instant. A press gets an answer within 100 ms. The screen changes first; slow work follows, with progress and a way to stop it.

ComponentsCopy Anchor Link

The components reference lists each one with its props. Use the component rather than drawing your own: no raw <input>, <hr> or <kbd>, no role="dialog" of your own, no dashed empty boxes, no home-made badges. The rules that matter most:

• Button: one filled button per view, for the main thing to do. Everything else is secondary, outline or ghost. Labels are specific verbs: "Make the loop", "Choose a song", never "Submit", "OK" or "Get started".
• PageHeader: a title, a description made of facts, and actions on the right, with at most one filled button.
• Card: a raised surface for a group of related things. Never a card inside a card; if the page is already the container, you don't need one.
• EmptyState: what will appear here and the first step, with at most two actions. After a filter it says "Nothing matches…" and offers "Clear filters".
• Callout: a message inside the page, with a tone of neutral, danger, warning or success. It says what happened, then what to do.
• Skeleton while anything with a layout loads, in the shape of that layout. Spinner only inside a button that's working, or in a one-line status; never alone on a page.
• Progress: value when the size of the job is known, indeterminate when it isn't. The label says what's happening, with the percentage in tabular-nums on the right. A first 0 isn't a percentage: show none until a value above 0 arrives.
• Waiting with a way out. Anything that waits on the network, like a model download, says how much when it knows, and offers Stop or Cancel.
• Toaster and toast: bottom right, one line, and at most one action (usually Undo or Try again), drawn as an outline button.
• Tooltip: an icon button's name, on hover and focus. The button keeps its own aria-label.
• Badge: a short status in a row or card. Not for counts, which are plain text-caption tabular-nums.
• Switch saves on change. Never pair one with a Save button.
• ActionForm and AppHero: the form Mixel draws for an action, and your app's hero. After Stop, the form lists what the action had already finished.

WordsCopy Anchor Link

• Say what it does for the person, in their words: song, sound, file, folder, Library. Not repository, worker, manifest, runtime or SDK.
• Sentence case. Buttons are verbs, and short. No exclamation marks, no "Oops", no emoji.
• An error says what happened, then what to do: "That file is too large to open. Try one under 80 MB."
• The product is Mixel, and the account is "your Mixel account". Apps live in Mixel's Apps section, never an "App Store".
• Never compare your app with another product, or criticise one.

Yours, and sharedCopy Anchor Link

An app may declare accent and icon in app.json, and open with a hero band at most 160 px tall with its own art: <AppHero wordmark="Loop Maker" accent="#20b4c4" art={…} />.

Below the hero, an app must use these components, tokens, type and spacing; work in light and dark; design its empty, working, done and error states; keep to one filled button; and follow the words above. Reviewers read your page and its source against this.

Before you publishCopy Anchor Link

• Built from these components and tokens: no hex colours, no fixed sizes, nothing off the type scale.
• Looked at in light and in dark, and at the window's smallest size.
• Real content: a long file name, no files, one file, many files.
• Every state: hover, pressed, focus, disabled, working, empty, error, and after Stop.
• Every word read aloud once. Would a musician say it?