# How to customize the theme

This guide shows how to change the visual appearance of Croupier to match your brand.

## Prerequisites

- A Croupier instance already working (see the [tutorial](../tutorials/getting-started.md))
- Basic knowledge of CSS custom properties

## Override design tokens

All visual properties are controlled by CSS custom properties prefixed with `--cr-`. Override them in your page's `:root` or in a container element:

```css
:root {
  /* Surface colors */
  --cr-bg-base:        #0A0A0F;   /* page background */
  --cr-bg-surface:     #12121A;   /* card background */
  --cr-bg-elevated:    #1A1A26;   /* elevated surfaces */

  /* Text colors */
  --cr-text-primary:   #E2E8F0;
  --cr-text-secondary: #94A3B8;

  /* Accent */
  --cr-accent:         #A78BFA;   /* violet accent */

  /* Action colors */
  --cr-action-reject:  #EF4444;   /* red */
  --cr-action-accept:  #22D3EE;   /* cyan */
  --cr-action-save:    #FBBF24;   /* amber */
  --cr-action-undo:    #F472B6;   /* pink */
}
```

This creates a dark theme. No `!important` needed — Croupier uses CSS `@layer` so your unlayered styles always win.

> **Important:** Croupier's CSS is organized in `@layer croupier.reset, croupier.tokens, croupier.component`. Per CSS spec, **unlayered** styles (like the `:root` overrides above) always win over **layered** styles. This means your overrides work without `!important` **as long as they are not inside a `@layer` block**. If you wrap your overrides in `@layer`, they'll be at the same priority as Croupier's own styles and may not override correctly. Keep overrides in plain CSS, not inside `@layer`.

## Override via the `theme` config

You can also pass theme overrides directly in the config object:

```js
const deck = Croupier.create('#deck', {
  items: myItems,
  renderCard: myRenderFn,
  theme: {
    '--cr-accent': '#7C5CFF',
    '--cr-action-accept': '#4ADE80',
    '--cr-action-reject': '#EF4444',
  },
});
```

## Hide UI elements

Hide any built-in UI element with CSS:

```css
.cr-stats-bar { display: none; }
.cr-kbd-hint  { display: none; }
```

## Replace the brand mark

The brand mark ("cⁱ · swipe deck") is in the HTML. Override it by targeting the header:

```css
.cr-brand-mark { display: none; }
.cr-brand-name { display: none; }
```

Then add your own branding inside the `#deck` container.

## See also

- [Design tokens reference](../reference/design-tokens.md)
- [How to embed Croupier](embed.md)