Cross Platform Tauri UI
Designcross-platform-tauri-uiCross Platform Tauri UI is an Agent Skill for design published in the ifer47/markeron repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Cross-platform UI styling for MarkerOn Tauri app (macOS WKWebView vs Windows WebView2). Use when styling Vue/CSS, fixing Mac/Windows visual differences, working on settings window, overlay panels, or Tailwind opacity issues on WebKit.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/ifer47/markeron/blob/HEAD/.cursor/skills/cross-platform-tauri-ui/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cross-platform-tauri-ui, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Cross-Platform Tauri UI (MarkerOn)
Why Mac and Windows look different
1. Different web engines (main cause)
| Platform | Engine | Used by |
|---|---|---|
| macOS | WKWebView (WebKit) | Tauri WRY |
| Windows | WebView2 (Chromium) | Tauri WRY |
Same Tailwind class can produce different pixels. This is not a "Mac bug" in app logic — it is compositing / alpha blending behavior in WebKit vs Chromium.
2. Tailwind opacity modifiers are the trigger
Tailwind v4 generates classes like text-white/45 → color: rgb(255 255 255 / 45%).
On macOS WebKit these often fail in predictable ways:
- Borders (
border-white/5,/8): render as harsh white outlines - Text (
text-white/20–/70): render paler than intended; low contrast on#1e1e20 - Backgrounds (
bg-white/4,/10): nearly transparent; active states disappear - Semantic colors with alpha (
text-green-400/70,bg-accent/30): hue/saturation lost; green looks grey
Safe: solid colors — text-white, text-accent, bg-[#1e1e20], hex/rgb in inline styles.
3. Transparent overlay windows (macOS-only extra issues)
The drawing overlay is a transparent Tauri window. WKWebView additionally needs:
overlay-panel-surface(isolation, backface-visibility, contain:paint)- Explicit panel background on
.overlay-panel(not relying on semi-transparent Tailwind bg) - Tauri:
set_background_colorfor overlay; settings window usesmacos.rsdark background + transparent title bar - Do not call Objective-C on WryWebView inner handle (crashes)
Project convention: semantic rgba classes
All cross-platform UI colors live in src/style.css as named classes with explicit rgba().
Settings window
| Class | Purpose |
|---|---|
settings-text-brand/title/heading/label/value/muted/subtle/faint/dim/footer/body | Typography |
settings-text-accent, settings-text-accent-link | Links, accent text |
settings-status-success | Green "up to date" |
settings-msg-success, settings-msg-error | Toast messages |
settings-nav-item, settings-nav-item--active | Sidebar tabs |
settings-toggle-on, settings-toggle-off | Switches |
settings-card, settings-card-row, settings-card-desc, settings-card--active | Cards |
settings-card--popover-host | Card that hosts a dropdown/tooltip — overrides card overflow |
settings-btn-accent-outline, settings-btn-accent-primary | About page buttons |
settings-row-hover, settings-row-hover-strong | List row hover |
settings-locale-item, settings-locale-item--active | Language dropdown |
settings-app-icon | About logo container |
settings-progress-track, settings-progress-fill | Update progress |
Overlay panels (space panel, quick colors)
| Class | Purpose |
|---|---|
overlay-panel, overlay-panel--compact | Panel shell |
overlay-panel-surface | WebKit corner bleed fix |
overlay-text-section/hint/label/body/secondary/separator/caption/key* | Text |
overlay-tool-btn, overlay-tool-btn--active | Tool buttons |
overlay-width-btn, overlay-width-btn--active, overlay-width-line* | Stroke width |
ui-divider-h/v/b, ui-kbd, ui-select, ui-popover, ui-segment* | Shared controls |
color-swatch-ring*, color-picker-ring, color-dot-ring | Color UI |
All platforms use the same rgba() values — do not add Mac-only text opacity overrides.
Settings cards and popovers (overflow)
.settings-card uses overflow: hidden in style.css so rounded borders clip
cleanly on macOS WebKit. That clips any child with position: absolute or
fixed (dropdowns, tooltips) and sibling cards below can paint over the
overflow.
Rules:
- Any card that contains a dropdown, tooltip, or popover must also use
settings-card--popover-host(overflow: visible). - While the popover is open, raise the host card above siblings (e.g.
relative z-20when open) so the menu is not covered by the next card. - Prefer
Teleporttobodyfor new floating UI if it must survive scroll containers (overflow-y-autoon tab content) — seeGeneralTab.vuelanguage select for the card-host pattern; Teleport is the more robust default for new work.
Before changing a shared container class (.settings-card, .overlay-panel,
scroll wrappers), grep for floating children:
rg "absolute|fixed|ui-popover|ui-tooltip|Teleport" src/components/settings/
Container CSS checklist — these on a parent often break popovers; re-test open state after adding any of them:
| Property | Risk |
|---|---|
overflow: hidden / auto | Clips absolute/fixed descendants |
transform | New stacking context; z-index surprises |
contain: paint | Clips overflow |
isolation: isolate | Stacking context; siblings may cover popover |
Manual QA after card/style refactors (both platforms, ~2 min):
- Settings → 常规: language dropdown fully visible, can switch locale
- Settings → 快捷键: info tooltip visible on hover
- Scroll the tab if applicable; popover still usable
Development workflow
Adding new UI
- Check if an existing semantic class fits.
- If not, add one class (or modifier) in
style.csswithrgba(). - Use the class in Vue — no
text-white/XXorborder-white/XXin templates. - For Help-tab-style scoped CSS, prefer
rgba()in<style scoped>(already done inSettingsView.vuehelp section).
Fixing Mac-only reports
- Confirm the component uses Tailwind opacity → migrate to semantic class.
- If borders: use
ui-divider-*orsettings-cardpatterns. - Use explicit
rgba()at the same values on all platforms — do not add Mac-only opacity bumps. - Verify Windows unchanged (rgba values match original Tailwind intent).
Pre-commit grep
rg "border-white/|text-white/|bg-white/|from-accent/|to-accent/|bg-accent/|text-accent/|border-accent/|text-green-|bg-emerald-|text-red-.*/|bg-red-.*/" src/components
Zero hits in src/components is the target for new work.
Manual test matrix
| Surface | macOS | Windows |
|---|---|---|
| Settings → 常规 | Toggles, language dropdown open, labels | Same |
| Settings → 关于 | Green status, nav highlight, card borders | Same |
| Space → settings panel | Text, borders, tool active state | Same |
| Right-click color panel | Caption text, swatch rings | Same |
Anti-patterns
<!-- BAD: WebKit opacity issues -->
<span class="text-white/45">Label</span>
<div class="border border-white/8 bg-white/4">
<!-- GOOD -->
<span class="settings-text-muted">Label</span>
<div class="settings-card">
<!-- BAD: dropdown inside .settings-card without popover-host -->
<div class="settings-card">
<div class="relative">
<div class="absolute ...">...</div>
</div>
</div>
<!-- GOOD: allow popover to escape card; raise z-index when open -->
<div class="settings-card settings-card--popover-host" :class="{ 'relative z-20': open }">
...
</div>
<!-- BAD: status color with alpha -->
<span class="text-green-400/70">Up to date</span>
<!-- GOOD -->
<span class="settings-status-success">Up to date</span>
/* GOOD: new semantic token */
.settings-text-new-role {
color: rgba(255, 255, 255, 0.55);
}
Related files
src/style.css— all semantic UI classessrc-tauri/src/macos.rs— settings window background & title barindex.html—html.settingsfor settings route