# Custom Styles Guide 


## Overview

The Zid SDK allows you to customize the appearance of SDK components using custom CSS styles. This guide will help you write, test, and troubleshoot custom styles for your Zid store.

---

## Quick Start

Add your custom styles to the `custom-styles.js` file:

```javascript
window.zidCustomStyles = {
  // Component name: styles object
  auth_dialog: {
    '.MuiDialog-paper': {
      borderRadius: '24px',
      backgroundColor: '#ffffff',
      boxShadow: '0 25px 50px rgba(0, 0, 0, 0.25)',
    },

    '.MuiButton-containedPrimary': {
      background: 'linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%)',
      borderRadius: '16px',
    },
  },

  gift_dialog: {
    '.MuiDialog-paper': {
      borderRadius: '20px',
    },
  },
};
```

---

## How It Works

### Automatic Scoping

All your custom styles are **automatically scoped** to their specific component to prevent conflicts with other parts of your store.

**Example:**

```javascript
// You write:
gift_dialog: {
  '.MuiDialog-paper': {
    backgroundColor: 'red'
  }
}

// SDK applies it as:
.zid-kit-gift-dialog .MuiDialog-paper {
  background-color: red;
}
```

This ensures your styles only affect the gift dialog, not other dialogs in your application.

### Component Keys

Each component has a unique key that you can use in your window.zidCustomStyles object. You can easily find this key from the template component key shown in the Custom Styles section of the template documentation or configuration panel.

---

## Writing Custom Styles

### Rule 1: Use Flat Selectors Only

**Correct:**

```javascript
{
  '.button': { color: 'blue' },
  '.button:hover': { color: 'red' },
  '.button:focus': { outline: '2px solid blue' }
}
```

**Wrong:**

```javascript
{
  '.button': {
    color: 'blue',
    '&:hover': { color: 'red' }
  }
}
```

The SDK uses a flat CSS structure for performance and reliability. Nested selectors cause errors.

---

### Rule 2: Use camelCase for CSS Properties

**Correct:**

```javascript
{
  '.container': {
    backgroundColor: '#fff',
    fontSize: '16px',
    borderRadius: '8px'
  }
}
```

**Wrong:**

```javascript
{
  '.container': {
    'background-color': '#fff',
    'font-size': '16px'
  }
}
```

JavaScript object notation requires camelCase property names.

---

### Rule 3: Start Selectors with Valid CSS Prefixes

All selectors must start with one of these:

* `.` (class selector) → `.my-button`
* `#` (ID selector) → `#my-element`
* `@` (at-rule) → `@media`, `@keyframes`
* `:` (pseudo-class) → `:hover`, `:focus`

**Correct:**

```javascript
{
  '.MuiDialog-paper': { borderRadius: '16px' },
  '@media (max-width: 600px)': {
    '.MuiDialog-paper': { borderRadius: '8px' }
  }
}
```

**Wrong:**

```javascript
{
  'div': { color: 'red' },
  'button': { color: 'blue' }
}
```

---

### Rule 4: Don't Use Global Selectors

Avoid global selectors such as:

`body`, `html`, `:root`, `*`

Use specific class selectors instead:

```javascript
{
  '.my-custom-container': {
    backgroundColor: '#f0f0f0'
  }
}
```

---

## Using MUI Classes

When customizing MUI components, you can target classes using this pattern:

**Pattern:**

```
.Mui[ComponentName]-[slotName]
```

**Example:**

```javascript
{
  '.MuiButton-containedPrimary': {
    backgroundColor: '#3b82f6',
    borderRadius: '12px'
  },
  '.MuiDialogTitle-root': {
    fontSize: '20px',
    fontWeight: '600'
  }
}
```

**Important Note:**
Avoid targeting any dynamically generated MUI classes that contain hashes, such as:

```
.css-ae2u5c-MuiSlider-thumb
```

These classes are not stable and may change between builds. Always use the standardized MUI pattern instead.

---

## Common Errors & Solutions

### Forbidden Global Selector

```
[ZidError] Forbidden selector 'body' - Cannot scope global selectors
```

**Fix:** Replace global selectors with component-specific ones.

---

### Nested Selector with `&`

```
[ZidError] Nested '&' not allowed. Use flat selectors.
```

**Fix:** Flatten your selectors.

---

### Invalid CSS Structure

```
[ZidError] Invalid CSS structure at 'root'. Expected object, received string.
```

**Fix:** Make sure each component key contains an object of selectors.

---

## Examples

### Example 1: Modern Auth Dialog

```javascript
window.zidCustomStyles = {
  auth_dialog: {
    '.MuiBackdrop-root': {
      backgroundColor: 'rgba(15, 23, 42, 0.7)',
      backdropFilter: 'blur(8px)',
      WebkitBackdropFilter: 'blur(8px)',
    },

    '.MuiDialog-paper': {
      borderRadius: '24px',
      boxShadow: '0 25px 50px -12px rgba(0, 0, 0, 0.25)',
      maxWidth: '480px',
      background: 'linear-gradient(135deg, #ffffff 0%, #f8fafc 100%)',
    },

    '.MuiButton-containedPrimary': {
      borderRadius: '16px',
      padding: '14px 24px',
      background: 'linear-gradient(135deg, #3b82f6 0%, #8b5cf6 100%)',
      boxShadow: '0 4px 14px 0 rgba(59, 130, 246, 0.39)',
      transition: 'all 0.3s ease',
    },

    '.MuiButton-containedPrimary:hover': {
      background: 'linear-gradient(135deg, #2563eb 0%, #7c3aed 100%)',
      transform: 'translateY(-2px)',
    },

    '@media (max-width: 600px)': {
      '.MuiDialog-paper': {
        margin: '16px',
        borderRadius: '20px',
      },
    },
  },
};
```

### Example 2: Minimalist Gift Dialog

```javascript
window.zidCustomStyles = {
  gift_dialog: {
    '.MuiDialog-paper': {
      borderRadius: '16px',
      boxShadow: 'none',
      border: '1px solid #e2e8f0',
    },

    '.greeting-card': {
      borderRadius: '8px',
      border: '2px solid #e2e8f0',
      transition: 'all 0.2s ease',
    },

    '.greeting-card:hover': {
      borderColor: '#cbd5e1',
    },

    '.greeting-card.selected': {
      borderColor: '#3b82f6',
      backgroundColor: '#eff6ff',
    },
  },
};
```

---

## Testing Your Styles

1. Check the browser console for validation errors.
2. Inspect elements using DevTools to confirm applied scoping.
3. Test across devices, modes, and languages.

---

## Summary

**DO:**

* Use flat selectors
* Use camelCase properties
* Use valid MUI class names
* Support responsive design

**DON’T:**

* Use nested `&` selectors
* Use hashed MUI classes
* Use global selectors