Skip to content

Commit e0da74d

Browse files
DerGooglerkanaodnd
DerGoogler
and
kanaodnd
committed
Add WebUI X CSS setup docs and sidebar link
Add a new documentation page docs/en/guide/webuix/css-setup.md that describes the WebUI X CSS APIs (Insets and Colors), import instructions, usage examples, best practices, FAQs, and credits. Also update docs/.vitepress/config/en.ts to include a "CSS Setup" entry in the WebUI X guide sidebar so the new page is discoverable. Co-Authored-By: Kanao <kanaokiddo@gmail.com>
1 parent 6f6006d commit e0da74d

2 files changed

Lines changed: 307 additions & 0 deletions

File tree

‎docs/.vitepress/config/en.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,7 @@ function sidebarGuide() {
112112
},
113113
{ text: "Why WebUI X", link: "/guide/webuix/" },
114114
{ text: "Index Setup", link: "/guide/webuix/index-setup" },
115+
{ text: "CSS Setup", link: "/guide/webuix/css-setup" },
115116
{ text: "Application Info Flags", link: "/guide/webuix/application-info-flags" },
116117
{ text: "Patching", link: "/guide/webuix/patching" },
117118
{ text: "Config", link: "/guide/webuix/config" },

‎docs/en/guide/webuix/css-setup.md‎

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
# WebUI X CSS Setup
2+
3+
## Overview
4+
5+
WebUI X: Portable 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.
6+
7+
Table Content:
8+
9+
- API Insets (Safe Area)
10+
- API Colors (Material You)
11+
12+
## Import
13+
14+
```css
15+
@import "https://mui.kernelsu.org/internal/insets.css";
16+
@import "https://mui.kernelsu.org/internal/colors.css";
17+
18+
/* @deprecated */
19+
@import "https://mui.kernelsu.org/mmrl/insets.css";
20+
/* @deprecated */
21+
@import "https://mui.kernelsu.org/mmrl/colors.css";
22+
```
23+
24+
There is necessary import, you should put this import at top in your <code>style.css</code> You can definitely use one of import.
25+
26+
# Insets API (insets.css)
27+
28+
```css
29+
--window-inset-top: Status bar safe area --window-inset-bottom: Navigation bar safe area;
30+
```
31+
32+
Usage guidelines:
33+
34+
- Use only for elements with position: fixed or position: absolute
35+
- Apply to elements at screen edges
36+
- Do not use for general containers or scrolling content
37+
38+
Example Usage Top insets:
39+
40+
```css
41+
/* Safe area usage */
42+
.top-navigation {
43+
padding-top: var(--window-inset-top);
44+
}
45+
```
46+
47+
Example Usage Bottom Insets:
48+
49+
```css
50+
.bottom-navigation {
51+
padding-bottom: var(--window-inset-bottom);
52+
}
53+
```
54+
55+
> [Framework7](https://framework7.io/) is support be default and no future actions are required.
56+
57+
# Keyboard Height <Badge type="warning" text="Since v398"/>
58+
59+
You can get the keyboard height in CSS with `var(--window-keyboard-height)`
60+
61+
Always use the variable with a fallback as it get's removed when the keyboard is closed!
62+
63+
```css
64+
/* Extra keys bar */
65+
#extra-keys {
66+
background: #1a1a1a;
67+
border-top: 1px solid #333;
68+
padding: 8px;
69+
padding-bottom: calc(var(--window-keyboard-height, var(--window-inset-bottom, 0px)) + 8px) !important;
70+
display: flex;
71+
flex-wrap: wrap;
72+
gap: 4px;
73+
justify-content: space-around;
74+
min-height: 44px;
75+
box-sizing: border-box;
76+
flex-shrink: 0;
77+
transition:
78+
transform 0.3s ease,
79+
opacity 0.3s ease;
80+
}
81+
```
82+
83+
Also make sure to disable [`windowResize`](config#windowRezie) in the config file
84+
85+
# Colors API (colors.css)
86+
87+
Color Variable Groups:
88+
89+
Primary Colors (Main Brand)
90+
91+
```css
92+
--primary /* Primary brand color */
93+
--onPrimary /* Content on primary background */
94+
--primaryContainer /* Container for primary elements */
95+
--onPrimaryContainer /* Content on primary container */
96+
```
97+
98+
Secondary Colors (Supporting)
99+
100+
```css
101+
--secondary /*Secondary brand color */
102+
--onSecondary /* Content on secondary background */
103+
--secondaryContainer /* Container for secondary elements */
104+
--on-secondaryContainer /* Content on secondary container */
105+
```
106+
107+
Tertiary Colors (Accent)
108+
109+
```css
110+
--tertiary /* Tertiary accent color */
111+
--onTertiary /* Content on tertiary background */
112+
--tertiaryContainer /* Container for tertiary elements */
113+
--onTertiaryContainer /* Content on tertiary container */
114+
```
115+
116+
Error Colors (Error States)
117+
118+
```css
119+
--error /* Error state color */
120+
--onError /* Content on error background */
121+
--errorContainer /* Container for error states */
122+
--onErrorContainer /* Content on error container */
123+
```
124+
125+
Surface Colors (Background & Layout)
126+
127+
```css
128+
--background /* Main app background */
129+
--onBackground /* Content on background */
130+
--surface /* Surface/card background */
131+
--onSurface /* Content on surface */
132+
--surfaceVariant /* Variant surface color */
133+
--onSurfaceVariant /* Content on surface variant */
134+
```
135+
136+
Surface Container Hierarchy (Elevation Levels)
137+
138+
```css
139+
--surfaceContainerLowest /* Closest to background */
140+
--surfaceContainerLow /* Low elevation */
141+
--surfaceContainer /* Default elevation */
142+
--surfaceContainerHigh /* High elevation */
143+
--surfaceContainerHighest /* Closest to foreground */
144+
```
145+
146+
Outline Colors (Borders & Separators)
147+
148+
```css
149+
--outline /* Default outline/border */
150+
--outlineVariant /* Subtle separator outline */
151+
```
152+
153+
Special Colors (Utility)
154+
155+
```css
156+
--shadow /* Shadow color */
157+
--inverseSurface /* Inverse surface for contrast */
158+
--inverseOnSurface /* Content on inverse surface */
159+
--inversePrimary /* Inverse primary color */
160+
--surfaceBright /* Bright surface variant */
161+
--surfaceDim /* Dim surface variant */
162+
```
163+
164+
# Example Implement
165+
166+
Safe Area Usage
167+
168+
```css
169+
/* Correct: For fixed elements at edges */
170+
.top-bar {
171+
position: fixed;
172+
top: 0;
173+
padding-top: var(--window-inset-top);
174+
}
175+
176+
/* Incorrect: For general content */
177+
.main-content {
178+
padding-top: var(--window-inset-top); /* Avoid */
179+
}
180+
```
181+
182+
Color Usage
183+
184+
```css
185+
/* Correct: Use semantic variables */
186+
.card {
187+
background-color: var(--surfaceContainer);
188+
color: var(--onSurface);
189+
}
190+
191+
/* Incorrect: Hardcoded colors */
192+
.card {
193+
background-color: #f5f5f5; /* Avoid */
194+
}
195+
```
196+
197+
Examples
198+
199+
Top Navigation Bar
200+
201+
```css
202+
.android-top-nav {
203+
position: fixed;
204+
top: 0;
205+
left: 0;
206+
right: 0;
207+
height: calc(56px + var(--window-inset-top));
208+
padding-top: var(--window-inset-top);
209+
background-color: var(--surface);
210+
color: var(--onSurface);
211+
z-index: 1000;
212+
}
213+
```
214+
215+
Bottom Navigation Bar
216+
217+
```css
218+
.android-bottom-nav {
219+
position: fixed;
220+
bottom: 0;
221+
left: 0;
222+
right: 0;
223+
height: calc(56px + var(--window-inset-bottom));
224+
padding-bottom: var(--window-inset-bottom);
225+
background-color: var(--surface);
226+
color: var(--onSurface);
227+
z-index: 1000;
228+
}
229+
```
230+
231+
Complete App Structure
232+
233+
```css
234+
@import "https://mui.kernelsu.org/internal/insets.css";
235+
@import "https://mui.kernelsu.org/internal/colors.css";
236+
237+
body {
238+
background-color: var(--background);
239+
color: var(--onBackground);
240+
margin: 0;
241+
padding: 0;
242+
}
243+
244+
.app-bar {
245+
position: fixed;
246+
top: 0;
247+
left: 0;
248+
right: 0;
249+
height: 64px;
250+
padding-top: var(--window-inset-top);
251+
background-color: var(--surface);
252+
color: var(--onSurface);
253+
z-index: 1000;
254+
}
255+
256+
.main-content {
257+
margin-top: calc(64px + var(--window-inset-top));
258+
margin-bottom: calc(56px + var(--window-inset-bottom));
259+
padding: 16px;
260+
}
261+
```
262+
263+
# FAQ & Troubleshooting
264+
265+
<details>
266+
<summary>Do I need to handle light/dark themes manually?</summary>
267+
No. WebUI X automatically manages theme switching. Colors dynamically update based on system settings without any manual CSS media queries.
268+
</details>
269+
270+
<details>
271+
<summary>When should I use <code>var(--window-inset-top)</code> and <code>var(--window-inset-bottom)</code>?</summary>
272+
Only use these variables for elements that:
273+
274+
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)
275+
</details>
276+
277+
<details>
278+
<summary>Can I override the color variables?</summary>
279+
Yes, you can define custom values before the imports, but it's recommended to let WebUI X manage colors for consistent theming across the app.
280+
</details>
281+
282+
<details>
283+
<summary>What happens if I don't use the safe area variables?</summary>
284+
Your fixed-positioned elements may be partially hidden behind the status bar or navigation bar on some Android devices.
285+
</details>
286+
287+
<details>
288+
<summary>How do I debug color issues?</summary>
289+
Check that you're using the correct semantic variable names. All colors should update automatically when the system theme changes.
290+
</details>
291+
292+
<details>
293+
<summary>Color not updating</summary>
294+
Verify you're using WebUI X variables (not hardcoded colors) and Check that both CSS files are imported correctly
295+
</details>
296+
297+
<details>
298+
<summary>Safe area not working</summary>
299+
300+
Ensure elements have `position: fixed` or `position: absolute` or Verify variables are applied to the correct elements (top/bottom only)
301+
302+
</details>
303+
304+
### Credits
305+
306+
This documentaion have been sourced from [kanaodnd/WebUIX-API-Color-Docs](https://github.com/kanaodnd/WebUIX-API-Color-Docs/blob/core/README.md).

0 commit comments

Comments
 (0)