Custom CSS Styling in OutSystems: Beyond the Default Theme

In Service Studio, click the **Interface tab** in the right panel. Expand 'UI Flows' — you will see a 'Layouts' folder containing your app's Theme. Alternatively, look directly under the Interface tab root for 'Themes' folder. Double-click your application Theme (named after your app, e.g., 'TaskManagerTheme'). The Style Sheet Editor opens in the center area with two tabs: 1. **First tab (custom CSS)** — your writable CSS. This is where you add all custom styles. 2. **Second tab (base CSS)** — the compiled OutSystems UI base styles. Read-only. Use this to study existing class names. All CSS you add in the first tab applies application-wide — every screen that uses this theme inherits your styles. Click the first tab and start adding CSS in the editor. Click anywhere outside to save changes, then click 1-Click Publish to deploy.

1/* Add this to your Theme's first CSS tab */
2
3/* Custom primary button style */
4.btn-primary-custom {
5  background-color: #2C6ECB;
6  border-radius: 8px;
7  font-weight: 600;
8  padding: 10px 24px;
9  color: #ffffff;
10  border: none;
11  transition: background-color 0.2s ease;
12}
13
14.btn-primary-custom:hover {
15  background-color: #1a5ba8;
16}
17
18/* Custom card style */
19.card-elevated {
20  background: #ffffff;
21  border-radius: 12px;
22  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
23  padding: 24px;
24  margin-bottom: 16px;
25}

Every widget in Service Studio has a **Style Classes** property in the Properties panel. This field accepts space-separated CSS class names (quoted as a text expression). **Static class assignment:** 1. Select a Button widget on your screen canvas 2. In the Properties panel, find the 'Style Classes' field 3. Enter: `"btn-primary-custom"` (with quotes — it is a text expression) 4. To add multiple classes: `"btn-primary-custom margin-top-s"` OutSystems UI utility classes you can use alongside custom classes: - Layout: `margin-top-s`, `margin-top-m`, `margin-top-l`, `padding-s`, `padding-m` - Typography: `font-size-h1` through `font-size-h6`, `text-center`, `text-right`, `bold` - Visibility: `display-none`, `visible-desktop` (shows only on desktop), `visible-phone` - Colors: `background-primary`, `color-neutral-0` Check the OutSystems UI Documentation (forge.outsystems.com or outsystems.com/outsystems-ui) for the complete utility class list.

1/* Style Classes property value examples:
2
3   Static string:
4   "card-elevated"
5
6   Multiple classes:
7   "card-elevated margin-top-m"
8
9   OutSystems utility class + custom class:
10   "padding-m card-elevated"
11*/

The Style Classes field accepts any text expression, not just static strings. This enables conditional styling based on data or user state. In the Properties panel, click the **expression editor icon** (pencil) next to the Style Classes field and write an expression: **Pattern — conditional class based on a boolean:** `If(Task.IsComplete, "status-complete", "status-pending")` **Pattern — conditional class from a local variable:** `If(IsSelected, "item-selected card-elevated", "item-default")` **Pattern — class based on an integer value (status):** `If(Order.StatusId = Entities.OrderStatus.Approved, "status-approved", If(Order.StatusId = Entities.OrderStatus.Pending, "status-pending", "status-default"))` The expression is evaluated at runtime. When the underlying data changes (e.g., after a Server Action updates IsComplete), the style class updates automatically on the next screen refresh.

1/* Dynamic style class expressions */
2
3/* Toggle selected state */
4If(SelectedItemId = Task.Id, "list-item list-item-selected", "list-item")
5
6/* Overdue highlight */
7If(Task.DueDate < CurrDate() and not Task.IsComplete,
8   "card-elevated text-danger",
9   "card-elevated")
10
11/* Priority color coding */
12If(Task.Priority = 1, "priority-high",
13   If(Task.Priority = 2, "priority-medium", "priority-low"))

CSS custom properties (variables) let you define values once in the Theme and reference them everywhere. This is the correct way to implement a design system in OutSystems. In your Theme's Style Sheet Editor (first tab), define variables in the `:root` selector: Then reference them throughout your custom styles using `var()`: **OutSystems UI also exposes its own CSS variables** that you can override in your theme. Common ones: - `--color-primary` — primary brand color (used by buttons, links, etc.) - `--color-background-body` — page background - `--border-radius-soft` — default border radius - `--font-size-base` — base font size Overriding `--color-primary` in your theme automatically recolors all OutSystems UI components that use the primary color — without touching each component's individual CSS.

1/* In your Theme's Style Sheet Editor — first tab */
2
3:root {
4  /* Brand colors */
5  --color-brand-primary: #2C6ECB;
6  --color-brand-secondary: #1B4F8A;
7  --color-brand-accent: #F59E0B;
8
9  /* Override OutSystems UI variables */
10  --color-primary: var(--color-brand-primary);
11  --border-radius-soft: 8px;
12
13  /* Spacing scale */
14  --spacing-xs: 4px;
15  --spacing-s: 8px;
16  --spacing-m: 16px;
17  --spacing-l: 24px;
18  --spacing-xl: 40px;
19
20  /* Typography */
21  --font-heading: 'Inter', sans-serif;
22  --font-size-card-title: 18px;
23}
24
25/* Use variables in component styles */
26.dashboard-card {
27  background: #ffffff;
28  border-radius: var(--border-radius-soft);
29  padding: var(--spacing-l);
30  border-left: 4px solid var(--color-brand-primary);
31}
32
33.section-heading {
34  font-family: var(--font-heading);
35  font-size: var(--font-size-card-title);
36  color: var(--color-brand-secondary);
37  margin-bottom: var(--spacing-m);
38}

OutSystems UI components have their own CSS with high specificity. When your custom class is not taking effect, it is typically a specificity conflict. The solutions: **Method 1 — Use !important (quickest, use sparingly):** Add `!important` after the property value. This wins over framework specificity. **Method 2 — Match or exceed specificity:** Inspect the framework's selector in the browser DevTools. If OutSystems uses `.osui-accordion.is-open .osui-accordion__title`, match that specificity in your CSS. **Method 3 — Use the per-widget Styles Editor:** In the Properties panel with a widget selected, click the **Styles tab** (looks like a paintbrush icon). This opens a visual CSS editor for width, height, margin, padding, font, color, border, shadow. Styles set here apply as inline styles, which always override class-level CSS — use for one-off per-widget tweaks. **CSS naming conventions to know:** - OutSystems UI pattern classes: `.osui-<pattern>` (e.g., `.osui-accordion`, `.osui-tabs`) - State classes: `.is-open`, `.is-active`, `.is-selected`, `.is-disabled` - Utility classes: `.margin-top-s`, `.font-size-h3`

1/* Overriding OutSystems UI framework styles */
2
3/* Override accordion header background */
4.osui-accordion__header {
5  background-color: var(--color-brand-primary) !important;
6  color: #ffffff !important;
7}
8
9/* Override tab active indicator color */
10.osui-tabs__tab.is-active {
11  border-bottom-color: var(--color-brand-accent) !important;
12  color: var(--color-brand-accent) !important;
13}
14
15/* Override button default border-radius */
16.btn.btn-primary {
17  border-radius: 4px !important;
18}
19
20/* Target screen-specific widget without !important
21   by increasing specificity with screen wrapper class */
22.TaskDetail-screen .card-container {
23  padding: 32px;
24  max-width: 800px;
25  margin: 0 auto;
26}