Bridging CSS Differences: How Taro Adapts Styles for HarmonyOS ArkUI

HarmonyOS uses the proprietary ArkUI framework for native UI, which diverges from W3C CSS standards, causing compatibility issues for Taro developers who aim for cross‑platform consistency.

To bridge the gap, Taro processes CSS through a Rust plugin built on LightningCSS that traverses the CSS abstract syntax tree (AST) and converts styles into ArkUI‑compatible data structures, handling unit conversion (e.g., converting all sizes to vp and colors to 0xAARRGGBB ).

Because runtime conversion of every style would hurt performance, static CSS is transformed at compile time, while inline style attributes are parsed at runtime using lightweight CSS parsers written in C++.

Layout differences are also addressed: ArkUI lacks several web layout features (e.g., calc() , percentage support). Taro therefore integrates the Yoga layout engine, an open‑source FlexBox implementation, to map CSS layout properties to Yoga nodes, compute widths, heights, and positions, and then apply the results back to ArkUI nodes.

The overall style workflow consists of initialization, class‑name matching, style application, and updates. After project startup, compiled style files are loaded, generating StyleRule objects for each selector. During React reconciliation, class names and inline styles are matched against these rules, merged according to specificity, and combined with any pseudo‑element or keyframe rules.

When a node’s style changes, Taro marks it as "dirty" and queues it for the next frame. Yoga then recalculates the layout for all affected nodes, and the updated geometry ( width , height , x , y ) is written back to the corresponding HarmonyOS nodes.

For class‑name updates, Taro identifies all selectors containing the new class, determines the scope of affected elements (direct, descendant, etc.), and performs a two‑step process (remove old class, add new class) to re‑match styles.

Performance optimizations include batching dirty nodes and processing them in a single frame to avoid redundant calculations.

In summary, Taro’s CSS adaptation pipeline—comprising compile‑time conversion, runtime style parsing, Yoga‑based layout handling, and efficient update queuing—enables developers to write standard React/CSS code that runs smoothly on HarmonyOS ArkUI while preserving cross‑platform compatibility.

Key visual references:

Example CSS selector snippet used in Taro’s matching logic:

.E .G {}
.E .H {}
.I > .J {}
.I {}

These examples illustrate how class‑name changes propagate to affected nodes (e.g., nodes F, G, H, I, J) and how Taro batches updates for optimal performance.