WebUIX CSS API Documentation

Overview

WebUIX provides a CSS API system for integrating with Android system theming and safe area management. This allows webui interfaces to dynamically adapt to system colors and respect device-specific UI elements like status bars and navigation bars.

Table Content:

• API Insets (Safe Area)
• API Colors (Material You)

Import

@import "https://mui.kernelsu.org/internal/insets.css";
@import "https://mui.kernelsu.org/internal/colors.css";

There is necessary import, you should put this import at top in your style.css You can definitely use one of import.

Insets API (insets.css)

--window-inset-top: Status bar safe area
--window-inset-bottom: Navigation bar safe area

Usage guidelines:

• Use only for elements with position: fixed or position: absolute
• Apply to elements at screen edges
• Do not use for general containers or scrolling content

Example Usage Top insets:

/* Safe area usage */
.top-navigation {
  padding-top: var(--window-inset-top);
}

Example Usage Bottom Insets:

.bottom-navigation {
  padding-bottom: var(--window-inset-bottom);
}

Colors API (colors.css)

Color Variable Groups:

Primary Colors (Main Brand)

--primary           // Primary brand color
--onPrimary         // Content on primary background
--primaryContainer  // Container for primary elements
--onPrimaryContainer // Content on primary container

Secondary Colors (Supporting)

--secondary           // Secondary brand color
--onSecondary         // Content on secondary background
--secondaryContainer  // Container for secondary elements
--on-secondaryContainer // Content on secondary container

Tertiary Colors (Accent)

--tertiary           // Tertiary accent color
--onTertiary         // Content on tertiary background
--tertiaryContainer  // Container for tertiary elements
--onTertiaryContainer // Content on tertiary container

Error Colors (Error States)

--error           // Error state color
--onError         // Content on error background
--errorContainer  // Container for error states
--onErrorContainer // Content on error container

Surface Colors (Background & Layout)

--background      // Main app background
--onBackground    // Content on background
--surface         // Surface/card background
--onSurface       // Content on surface
--surfaceVariant  // Variant surface color
--onSurfaceVariant // Content on surface variant

Surface Container Hierarchy (Elevation Levels)

--surfaceContainerLowest   // Closest to background
--surfaceContainerLow      // Low elevation
--surfaceContainer         // Default elevation
--surfaceContainerHigh     // High elevation
--surfaceContainerHighest  // Closest to foreground

Outline Colors (Borders & Separators)

--outline        // Default outline/border
--outlineVariant // Subtle separator outline

Special Colors (Utility)

--shadow              // Shadow color
--inverseSurface      // Inverse surface for contrast
--inverseOnSurface    // Content on inverse surface
--inversePrimary      // Inverse primary color
--surfaceBright       // Bright surface variant
--surfaceDim          // Dim surface variant

Example Implement

Safe Area Usage

/* Correct: For fixed elements at edges */
.top-bar {
  position: fixed;
  top: 0;
  padding-top: var(--window-inset-top);
}

/* Incorrect: For general content */
.main-content {
  padding-top: var(--window-inset-top); /* Avoid */
}

Color Usage

/* Correct: Use semantic variables */
.card {
  background-color: var(--surfaceContainer);
  color: var(--onSurface);
}

/* Incorrect: Hardcoded colors */
.card {
  background-color: #f5f5f5; /* Avoid */
}

Examples

Top Navigation Bar

.android-top-nav {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  height: calc(56px + var(--window-inset-top));
  padding-top: var(--window-inset-top);
  background-color: var(--surface);
  color: var(--onSurface);
  z-index: 1000;
}

Bottom Navigation Bar

.android-bottom-nav {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  height: calc(56px + var(--window-inset-bottom));
  padding-bottom: var(--window-inset-bottom);
  background-color: var(--surface);
  color: var(--onSurface);
  z-index: 1000;
}

Complete App Structure

@import "https://mui.kernelsu.org/internal/insets.css";
@import "https://mui.kernelsu.org/internal/colors.css";

body {
  background-color: var(--background);
  color: var(--onBackground);
  margin: 0;
  padding: 0;
}

.app-bar {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  height: 64px;
  padding-top: var(--window-inset-top);
  background-color: var(--surface);
  color: var(--onSurface);
  z-index: 1000;
}

.main-content {
  margin-top: calc(64px + var(--window-inset-top));
  margin-bottom: calc(56px + var(--window-inset-bottom));
  padding: 16px;
}

FAQ & Troubleshooting

Do I need to handle light/dark themes manually?

No. WebUIX API automatically manages theme switching. Colors dynamically update based on system settings without any manual CSS media queries.

When should I use --window-inset-top and --window-inset-bottom?

Only use these variables for elements that:

Have position: fixed or position: absolute, Are positioned at the top or bottom of the screen, Need to avoid overlapping with system UI (status bar/navigation bar)

Can I override the color variables?

Yes, you can define custom values before the imports, but it's recommended to let WebUIX manage colors for consistent theming across the app.

What happens if I don't use the safe area variables?

Your fixed-positioned elements may be partially hidden behind the status bar or navigation bar on some Android devices.

How do I debug color issues?

Check that you're using the correct semantic variable names. All colors should update automatically when the system theme changes.

What support for WebUIX API?

AxManager- WebUIX

Color not updating

Verify you're using WebUIX variables (not hardcoded colors) and Check that both CSS files are imported correctly

Safe area not working

Ensure elements have position: fixed or position: absolute or Verify variables are applied to the correct elements (top/bottom only)

Documentation created 11 February 2026