03 · Theme and brand

A theme isn't a color — it's a system of chained decisions. In Fayz you declare three decisions in app.manifest.json and the shell's theme engine derives the entire palette from them. The shell stays the same; only the look changes, and it changes coherently.

Step 1 · Think in systems

Before editing, pick three things — each one cascades through dozens of tokens:

• Brand color → becomes primary, the focus ring, a derived accent and (optionally) the colored sidebar.
• Corner personality (the radius) → sets buttons, cards, inputs and modals all at once.
• Mode strategy → light, dark, or follow the operating system.

Three decisions, not thirty colors. That's the whole point of a Design System.

Step 2 · Apply it in the manifest

Freshly created, the app ships with "theme": { "brand": "violet" }. The block accepts three keys:

{
  "theme": {
    "brand": "teal",
    "radius": "lg",
    "mode": "system"
  }
}

Looks like very little — and that's on purpose. Each key is the root of a chain. Here's what it unfolds into.

Gallery of the 7 brands

Choosing brand means choosing a whole family. The engine takes the brand's hue, applies it to primary/ring and rotates the hue −50° to generate a harmonic accent automatically. The table below shows, per brand, the base hue, the derived accent and where each one shines:

What each key cascades into

Notice that radius doesn't change "the button": it changes buttons, cards, inputs and modals together, in the same proportion. That's what keeps the app coherent when you change one end of it.

3 ready-made recipes

Copy, paste into app.manifest.json and adjust the name. Each is a tested combination of brand + radius + mode for a type of business:

Clinic / health

{
  "theme": { "brand": "green", "radius": "md", "mode": "light" }
}

Green communicates care and trust; md balances formal and approachable; light suits a reception desk and daytime service.

Food / evening orders

{
  "theme": { "brand": "orange", "radius": "lg", "mode": "dark" }
}

Orange is appetite and hospitality; lg makes the targets tactile for quick taps; dark rests the eyes on the floor at night.

Sober B2B SaaS

{
  "theme": { "brand": "blue", "radius": "sm", "mode": "system" }
}

Institutional blue reads as safe; sm keeps the professional density; system respects the operator's OS throughout the day.

The name at the top of the manifest is the display name — change it along with the color so the rebrand is complete:

{
  "name": "My Clinic",
  "theme": { "brand": "green", "radius": "md", "mode": "light" }
}

Step 3 · Validate

Edit the block, save, and run doctor:

npx @fayz-ai/cli doctor

⚠ plugins referenced by manifest are resolved by the platform bundle, not public npm packages: dashboard

0 error(s), 1 warning(s)

Under the hood

Those three keys are the condensed expression of a larger system. Starting from your brand color, the theme engine (createTheme / applyTheme, in @fayz-ai/saas) derives the chain — verified in the code:

applyTheme then writes every value as a CSS variable on the document (--primary, --ring, --accent, --sidebar, --button-radius, --font-family, --shadow-sm/md/lg). Your brand is one input into an already consistent token system.

Want the whole chain — the eight token families, the contrast reasoning and the flow of designing the system before configuring it? It's in the Design System and theming chapter.

See also: the full token reference — a quick lookup of the families and the CSS variables the engine writes.

Beyond the 3 keys Experimental

The manifest exposes three decisions today, but the engine underneath is far richer. Already sitting behind the platform runtime: free-form HSL color (not just the 7 names), 11 font families (from inter and geist to outfit and manrope), shadow levels (none → subtle → medium → bold), the sidebar in brand or neutral mode, and entire base presets. Exposing those families in the manifest — without bloating it — is the next step for the theme contract; the direction is evolutionary, not finished.

← Previous: 02 · Explore the anatomy · Next: 04 · Add a plugin →