# Brand & Theme Tools

> Resolve a workspace theme and load its complete storefront configuration

Canonical URL: https://fa7e86e3d553:3005/tools/brand-design

Use `lexsis_brand` to load brand identity, themes, navigation, and compiled
theme variables. Theme resolution is workspace-sensitive: resolve the target
workspace and store before generating or editing a page.

Merchants manage themes, brand direction, logos, fonts, colors, and visual
assets in the <AppLink to="designLibrary">Design Library</AppLink>. Public
documentation always links to the main library screen; select the intended
theme there before editing it.

## Actions

| Action | Purpose |
|---|---|
| `brand_kit` | Read brand tokens and voice constraints |
| `list_themes` | List theme IDs, names, and default status |
| `get_theme` | Load one complete theme, including navigation and `theme_css` |
| `navigation` | Read storefront navigation independently |
| `compile_theme` | Compile explicit theme inputs into `--lx-*` variables |

Theme writes use `lexsis_drafts` action `theme_update`.

## Required page-generation workflow

```text
1. lexsis_workspace → stores
2. Select the intended workspace and store
3. lexsis_brand → list_themes
4. lexsis_brand → get_theme
5. lexsis_design → guide
6. Generate and compile the page using that theme
```

Do not silently use a theme from another workspace. If the selected workspace
has no valid theme, stop page generation and report the missing configuration.

## List themes

```json
{
  "name": "lexsis_brand",
  "arguments": {
    "action": "list_themes",
    "args": {
      "workspace_id": "workspace-uuid"
    }
  }
}
```

```typescript
Array<{
  id: string;
  name: string;
  is_default: boolean;
}>
```

Select the explicit `theme_id` requested by the user. Otherwise select the
theme marked `is_default:true`.

The intended errors are:

- `theme_not_found` — an explicit theme ID does not exist in the selected
  workspace.
- `theme_unavailable` — the workspace has no usable default theme.
- `theme_workspace_mismatch` — the theme belongs to a different workspace.

These conditions do not fall back to a theme from another workspace.

## Get a complete theme

```json
{
  "name": "lexsis_brand",
  "arguments": {
    "action": "get_theme",
    "args": {
      "workspace_id": "workspace-uuid",
      "theme_id": "theme-uuid"
    }
  }
}
```

The complete response includes:

```typescript
{
  theme_id: string;
  name: string;
  is_default: boolean;
  logo: {
    url: string | null;
    favicon_url: string | null;
  };
  colors: {
    primary: string | null;
    secondary: string | null;
    accent: string | null;
    background: string | null;
    surface_alt: string | null;
    text: string | null;
    border: string | null;
  };
  typography: {
    heading: string | null;
    body: string | null;
    heading_weight: string | null;
    font_urls: string[];
  };
  radii: {
    default: string | null;
    card: string | null;
    image: string | null;
  };
  buttons: {
    background: string | null;
    text: string | null;
    padding: string | null;
    shadow: string | null;
  };
  navbar: {
    logo_url: string | null;
    links: unknown[];
  };
  footer: {
    links: unknown[];
    social_links: unknown[];
  };
  navigation: Record<string, unknown>;
  theme_json: Record<string, unknown> | null;
  theme_css: string;
  theme_css_issues: unknown[];
}
```

Use the returned `theme_css` as the page's brand-token layer. Tailwind remains
the layout and responsive styling system.

## Brand kit and design guide precedence

Call `brand_kit` for exact tokens and `lexsis_design` action `guide` for design
philosophy and explicit prohibitions.

When they differ:

- Brand-kit values win for exact colors, fonts, radii, and spacing tokens.
- The design guide wins for composition guidance, voice, component choices,
  and explicit “do not” rules.

## Update a theme

Theme updates are reversible writes:

For a merchant-reviewed visual update, open the
<AppLink to="designLibrary">Design Library</AppLink>. The MCP workflow below is
for agent-authored draft changes.

```json
{
  "name": "lexsis_drafts",
  "arguments": {
    "action": "theme_update",
    "args": {
      "workspace_id": "workspace-uuid",
      "theme_id": "theme-uuid",
      "primary_color": "#2d5016",
      "secondary_color": "#f5f0eb",
      "accent_color": "#b66a3c",
      "button_bg_color": "#2d5016",
      "button_text_color": "#ffffff",
      "font_heading": "Cormorant Garamond, serif",
      "font_heading_url": "https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@600;700&display=swap",
      "font_body": "Inter, sans-serif",
      "font_body_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap",
      "border_radius": "12px",
      "spacing_section": "5rem",
      "voice_md": "Warm, precise, and understated.",
      "banned_phrases": ["miracle", "guaranteed cure"]
    }
  }
}
```

Use the flat field names shown above. Do not wrap colors or fonts inside nested
objects.

If the requested button colors fail WCAG AA contrast, the service can adjust
the stored background and return `contrast_adjusted`.

## Theme changes and page CSS

Changing a workspace theme does not automatically refresh an already compiled
page. Use `lexsis_drafts` action `page_update_head` with the complete
`theme_css`. For source-backed pages, the MCP recompiles the complete stored
source and writes through the atomic replacement path so `compiled_page_css`
contains:

1. Updated page-authored theme rules
2. Every generated Tailwind utility
3. Section CSS in deterministic order

## Header and footer inheritance

New pages should normally use:

```json
{
  "theme_id": "theme-uuid",
  "inherit_header": true,
  "inherit_footer": true
}
```

Author custom `Navbar` or `Footer` islands only when intentionally overriding
the global storefront chrome.

## Related

- [Theming](/pages/theming)
- [Page Management](/tools/page-management)
- [Page Source Contract](/pages/schema)