# Styling and Theming

UXP provides a theme system with CSS variables for styling your v5 apps.

***

## Theme System

Access the current theme in your components:

```typescript
import { useUXPContext } from "uxp/components";

const MyComponent = () => {
    const uxpContext = useUXPContext();
    const theme = uxpContext.theme;

    return (
        <div style={{
            backgroundColor: theme.backgroundColor,
            color: theme.primaryTextColor
        }}>
            Content
        </div>
    );
};
```

***

## CSS Variables

Use CSS variables in your stylesheets for automatic theme support:

```scss
.my-component {
    // Background colors
    background-color: var(--primaryBGColor);
    background-color: var(--secondaryBGColor);

    // Text colors
    color: var(--primaryTextColor);
    color: var(--secondaryTextColor);

    // UI
    border: 1px solid: var(--borderColor);

    // Buttons
    .primary-btn {
        background-color: var(--primaryButtonBGColor);
        color: var(--primaryButtonTextColor);

        &:active {
            background-color: var(--primaryButtonActiveBGColor);
            color: var(--primaryButtonActiveTextColor);
        }
    }

    // Toast notifications
    &.success { background-color: var(--toastSuccessBGColor); }
    &.error { background-color: var(--toastErrorBGColor); }
    &.warning { background-color: var(--toastWarningBGColor); }
}
```

### Available Theme Variables

```scss
// Portal
--portalBGColor
--portalSidebarBGColor
--portalSidebarTextColor
--portalHeaderBGColor

// Backgrounds
--primaryBGColor
--secondaryBGColor
--secondaryRowColor

// Text
--primaryTextColor
--secondaryTextColor

// UI
--borderColor
--boxShadowColor

// Buttons
--primaryButtonBGColor
--primaryButtonTextColor
--primaryButtonActiveBGColor
--primaryButtonActiveTextColor
--secondaryButtonBGColor
--secondaryButtonTextColor
--secondaryButtonActiveBGColor
--secondaryButtonActiveTextColor

// Toast Notifications
--toastSuccessBGColor
--toastSuccessTextColor
--toastErrorBGColor
--toastErrorTextColor
--toastWarningBGColor
--toastWarningTextColor
--toastInfoBGColor
--toastInfoTextColor

// Status
--pendingStatusColor
--onGoingStatusColor
--completedStatusColor
--approvedStatusColor
--rejectedStatusColor
--onHoldStatusColor
--parkedStatusColor

// Priority
--lowPriorityColor
--mediumPriorityColor
--highPriorityColor
--urgentPriorityColor

// Charts
--chartColor1 through --chartColor15
```

***

## SCSS Organization

V5 apps use a simple, component-based SCSS structure:

```
src/
├── global.scss                              # Shared mixins, variables, utilities
├── index.tsx                                # Imports global.scss
├── views/
│   ├── portfolio/
│   │   ├── PortfolioView.tsx
│   │   └── PortfolioView.scss              # Component-specific styles
│   └── details/
│       ├── DetailsView.tsx
│       └── DetailsView.scss
└── components/
    ├── location-card/
    │   ├── LocationCard.tsx
    │   └── LocationCard.scss
    └── site-summary/
        ├── SiteSummary.tsx
        └── SiteSummary.scss
```

**Key Points:**

* **global.scss** - Shared mixins, variables, and utility classes used across components
* **Component SCSS** - Co-located with component files, imported directly
* **App Prefix** - Use your app prefix (e.g., `ilocapp_` for Location app) to avoid conflicts
* **BEM Naming** - Follow BEM convention: `prefix_component__element--modifier`

**Note:** CSS scoping will be added in future versions. For now, use app-specific prefixes to prevent style conflicts.

***

### global.scss

Define shared mixins, variables, and utilities in `src/global.scss`:

```scss
// src/global.scss

// Shared mixins
@mixin card-hover {
    transition: background-color 0.2s ease;
    &:hover {
        background-color: var(--secondaryBGColor);
    }
}

@mixin flex-center {
    display: flex;
    align-items: center;
    justify-content: center;
}

```

Import global.scss **once** in `src/index.tsx`:

```typescript
// src/index.tsx
import './global.scss';
import { enableLocalization } from './uxp';
import PortfolioView from './views/portfolio/PortfolioView';

window.registerUI({
    id: "portfolio-view",
    component: PortfolioView
});

enableLocalization();
```

***

### Component SCSS

Co-locate SCSS files with components and import directly:

```typescript
// src/views/portfolio/PortfolioView.tsx
import './PortfolioView.scss';
import { ObjectSearchComponent } from "uxp/components";

const PortfolioView = () => {
    return (
        <div className="ilocapp_portfolioview__container">
            <ObjectSearchComponent {...props} />
        </div>
    );
};

export default PortfolioView;
```

```scss
// src/views/portfolio/PortfolioView.scss

// Local mixin (only used in this component)
@mixin site-image($width, $height) {
    &__site-image-container {
        width: $width;
        height: $height;
        border-radius: 50%;
        border: 1px solid var(--borderColor);
        display: flex;
        align-items: center;
        justify-content: center;

        svg {
            width: 60%;
            height: 60%;
        }
    }

    &__site-image {
        width: 100%;
        height: 100%;
        background-position: center;
        background-repeat: no-repeat;
        background-size: cover;
        border-radius: inherit;
    }
}

// Component styles with app prefix
.ilocapp_portfolioview {
    &__container {
        width: 100%;
        height: 100%;
        border: 1px solid var(--borderColor);
    }

    &__collapsed {
        width: 100%;
        height: auto;
        padding: 0.3rem;

        &__top {
            display: flex;
            align-items: center;
            justify-content: space-between;
        }

        &__left {
            flex-grow: 1;
            min-width: 0;
        }

        &__right {
            width: 3rem;
            flex-shrink: 0;
        }

        @include site-image(2.5rem, 2.5rem);

        &__name {
            padding: 0.1rem 0.5rem;
        }

        &__code {
            display: flex;
            align-items: center;
            font-size: 0.9rem;
            color: var(--accentColor);
        }
    }

    &__locationname {
        display: flex;
        align-items: center;
        gap: 0.5rem;

        @include site-image(3rem, 3rem);
    }
}
```

***

### Naming Convention

Use BEM with your app prefix:

```scss
// Format: appprefix_component__element--modifier

.ilocapp_locationcard {                    // Block
    &__header {                             // Element
        &--highlighted {                    // Modifier
            background-color: var(--accentColor);
        }
    }

    &__body { }                             // Element
    &__footer { }                           // Element
}
```

**Choosing your prefix:**

* Use app name abbreviation
* Keep it short (4-8 characters)
* Examples: `ilocapp_` (Location), `iuserapp_` (User)

***

## RTL Support

Use logical CSS properties for RTL support:

```scss
.header {
    // Instead of margin-left
    margin-inline-start: 16px;

    // Instead of text-align: left
    text-align: start;
}
```

***

## Quick Tips

**DO:**

* ✅ Use CSS variables for **all** theme colors (backgrounds, text, borders, etc.)
* ✅ Define shared mixins/variables in `global.scss`
* ✅ Co-locate component SCSS with component files
* ✅ Use app prefix with BEM: `ilocapp_component__element`
* ✅ Import `global.scss` once in `index.tsx`
* ✅ Import component SCSS in each component file
* ✅ Use logical properties (margin-inline-start, text-align: start) for RTL support
* ✅ Use SCSS variables for non-theme values (spacing, border-radius, breakpoints)

**DON'T:**

* ❌ Hardcode colors - **always** use CSS variables
* ❌ Use inline styles for theming
* ❌ Override UXP core component styles directly
* ❌ Forget app prefix - prevents conflicts with other apps
* ❌ Import `global.scss` in multiple files - only once in `index.tsx`

***

**See Location 5.0 app** (`/Location/5.0/Resources/views/src/`) for complete styling examples and patterns.

***

## Next Steps

* [Step 13: Localization](https://help.iviva.com/uxp/v5/styling-and-localization/13-localization) - Multi-language support