Running W3C Standard CSS on HarmonyOS with Taro: Bridging CSS and ArkUI

HarmonyOS uses the proprietary ArkUI framework for native UI, which differs from W3C CSS standards, causing compatibility issues when developers use Taro to write cross‑platform React code. The article outlines the challenges of reconciling ArkUI’s CAPI style system with standard CSS.

CSS vs. ArkUI CAPI Differences

Examples show that CSS units and color formats differ from ArkUI’s unified vp units and 0xAARRGGBB color representation, requiring conversion of sizes, colors, gradients, transforms, and matrix calculations.

To avoid runtime performance penalties, static CSS is transformed at compile time using a Rust LightningCSS plugin that traverses the CSS AST and generates ArkUI‑compatible data structures.

Dynamic style attributes are parsed at runtime with custom CSS parsers that handle string and object forms, enabling future support for CSS variables.

Layout Differences and Yoga Integration

ArkUI’s layout behavior (e.g., absolute positioning relative to parent, lack of right / bottom ) differs from web standards. To bridge this gap, the article adopts Facebook’s open‑source Yoga engine, which implements FlexBox based on web standards, providing broader CSS layout support.

During Taro node tree construction, a parallel Yoga node tree is built. Styles such as width, height, margin, padding, display, and position are applied to Yoga nodes, which compute layout and then propagate the results (width, height, x, y) back to the HarmonyOS nodes, ensuring consistent layout across platforms.

Style Workflow

After project compilation, the first loaded style file generates StyleRule objects for each selector. React’s reconciler maps component className and style to Taro nodes, where the following steps occur:

Identify all StyleRule objects matching the component’s class names.

Merge them according to selector specificity.

Combine the merged result with inline style rules to produce the final style configuration.

Pseudo‑elements and keyframe animations, which cannot be directly set on ArkUI, are transformed into additional nodes (for pseudo‑elements) or separate animation threads that compute per‑frame values and apply them with highest priority.

Applying Styles

For each node, the engine calls SetStyle , iterating over the StyleRule . Layout‑related properties are sent to the corresponding Yoga node and marked layout_dirty . Paint‑related properties are stored on the node and marked draw_dirty . These dirty nodes are processed in the next frame, where Yoga’s calcYGLayout computes new layouts, marks nodes with has_new_layout , and updates the HarmonyOS nodes with the calculated dimensions and positions.

After layout updates, paint properties are transferred to the HarmonyOS nodes, with special handling for properties that depend on layout (e.g., percentage‑based background-size ).

Style Updates

When a node’s style attribute changes, a new inline style is generated and merged with class‑based styles. When className changes, the engine:

Collects all selectors containing the new class.

Determines affected nodes (the element itself, direct children, or all descendants) based on selector type.

Marks affected nodes as dirty and queues them for batch processing in the next frame to avoid redundant recomputation.

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

Conclusion

The article provides a comprehensive walkthrough of how Taro bridges the gap between standard CSS and HarmonyOS ArkUI, covering unit conversion, layout handling with Yoga, style initialization, matching, application, and efficient update strategies, enabling developers to maintain cross‑platform compatibility while leveraging familiar web development practices.