---
sourceDocument: Australia Build or modify applications
sourceDocumentLink: https://www.servicenow.com/docs/r/australia/application-development

 Release :

    - australia

ft:locale :

    - en-US

ft:publication_title :

    - Australia Build or modify applications

ft:clusterId :

    - cadev

bundleId :

    - cadev

workflow :

    - Development, Data, and Analytics


---

# Configure app-level theming

# Configure app-level theming {#ariaid-title1}

Release version: Australia  
Updated October 5, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read  
Configure app-level CSS for styles that belong to the app and must stay the same regardless of the tenant or user-resolved theme. Lux supports two optional files for this, tailwind.app.css and head.app.css.

## Before you begin

Role required: admin

## About this task

Both files sit at the app root, alongside aiux.json. The `aiux build` command discovers both files automatically, so they require no manifest entry or manual import.

The following table compares the two files.
{#configure-app-level-theming__table-app-level-css-files__entry__3}

| File | Scope | Use it for |
|-|-|-|
| tailwind.app.css | Every app component's shadow root | New or overriding utilities, dynamic-class safelists, and app-specific animations |
| head.app.css | The document `<head>` | CSS that must be registered once for the whole document, especially `@font-face` |
[Table 1. App-level CSS files]

{#configure-app-level-theming__table-app-level-css-files}

For colors, shape, or fonts that a tenant theme should be able to change, use theme.js instead. For instructions, see [Configure theme-level theming](https://www.servicenow.com/docs/3dytYzCtHCvBL4~ZT6KVxw "Configure brand colors, shape, theme-owned fonts, logos, favicons, and mobile color mappings in a theme.js module. Theme-level values can vary by tenant or user without a change to component code or an app rebuild.").

## Procedure

1. Extend component styles with tailwind.app.css  
   The app's Tailwind build compiles tailwind.app.css, and the compiled sheet is adopted into every app component's shadow root. Use this file when a rule must be available inside components.

   The file supports Tailwind directives and standard CSS, including the items in the following table.
   {#configure-app-level-theming__table-supported-directives-and-rules__entry__2}

   | Directive or rule | Use |
   |-|-|
   | `@source inline("...")` | Safelist class names that can't be discovered statically |
   | `@layer utilities { ... }` | Add or override utility classes |
   | `@keyframes ... { ... }` | Define app-specific animations |
   [Table 2. Supported directives and rules]

   {#configure-app-level-theming__table-supported-directives-and-rules}

   Declare overrides in a named layer so that their precedence doesn't depend only on stylesheet order:

       /* tailwind.app.css */
       @layer utilities, your-app;

       @layer your-app {
         .aiux-btn {
           border-radius: 50px;
         }
       }

   Important:  
   Leave the following two things out of tailwind.app.css:
   * Don't add `@import "tailwindcss"`. The build entry already imports Tailwind, and another import duplicates generated styles.
   * Don't add an `@theme { ... }` block. The app build removes the generated theme layer so that it can't replace the platform's customized tokens.
2. Register document-wide CSS with head.app.css  
   The head.app.css file isn't processed by Tailwind or PostCSS, and it's linked directly in the document `<head>`. Its content is preserved except for supported public/... URLs inside `@font-face` rules, which the build prefixes with the app basename.

   Use this file for CSS that must be registered once outside component shadow roots. The primary use case is `@font-face`:

       /* head.app.css */
       @font-face {
         font-family: 'Inter';
         font-style: normal;
         font-weight: 400 700;
         font-display: swap;
         src: url(https://cdn.example.com/fonts/inter.woff2) format('woff2');
       }

   Inside an `@font-face` rule, a path beginning with public/ is rewritten to /aiux/\<basename\>/public/.... Other URLs, URLs outside `@font-face`, and `@import` values are preserved as authored. For those references, use an `https:` URL, a `data:` URI, or an already-served root-relative path.

   The head.app.css pipeline doesn't copy local assets, so files under public/ must also be included by the app's static-content configuration.

## Verify {#configure-app-level-theming__configure-app-level-theming-verify}

* Build and deploy the app. No additional manifest configuration is required.
* Inspect the document `<head>` and confirm that head.app.css is linked after the platform's base `aiux-theme-variables` style block.
* Inspect an app component's shadow root and confirm that the compiled app Tailwind sheet is present.
* For a custom font, confirm that the font file loads once.

## What to do next

* [Configure app-level theming](https://www.servicenow.com/docs/StkRaVlFTjjN4z_rgIhpIg "Configure app-level CSS for styles that belong to the app and must stay the same regardless of the tenant or user-resolved theme. Lux supports two optional files for this, tailwind.app.css and head.app.css.") --- configure rebrandable colors, shape, and fonts.
* --- available tokens and their default values.