arkui-api-design_skill

Overview

This skill provides hands-on guidance for designing, reviewing, and maintaining ArkUI component APIs that follow OpenHarmony TypeScript/JavaScript coding guidelines. It enforces synchronization between static (.static.d.ets) and dynamic (.d.ts) interfaces, resource typing rules, JSDOC requirements, and SDK build/verification steps. Use it to produce consistent, versioned, and testable ArkUI API changes.

How this skill works

The skill inspects proposed API changes and checks required updates across static API files (interface/sdk-js/api/arkui/component/*.static.d.ets) and dynamic Attribute interfaces (@internal/component/ets/*.d.ts). It validates naming, types, Resource type usage boundaries (API 13+), undefined/null semantics, unit defaults (vp), JSDOC constraints, and cross-component impact. Finally, it outlines SDK build and verification commands to confirm the changes appear in generated outputs.

When to use it

• Design a new ArkUI component property or method
• Add or modify a Modifier/Attribute method in dynamic API
• Review or audit ArkUI API changes for OpenHarmony compliance
• Deprecate an existing API and produce migration guidance
• Write or update JSDOC for ArkUI public APIs

Best practices

• Always update both static (.static.d.ets) and dynamic (@internal/*.d.ts) definitions together and keep signatures synchronized
• Follow camelCase for properties/methods and PascalCase for types; include @since tags with static/dynamic suffix
• Support Resource types only for themeable properties; use ResourceStr only for NEW APIs (API 13+)
• Document undefined vs null behavior explicitly in JSDOC and declare valid ranges, units (vp), and clamping rules
• Use chainable return types correctly: this for static declarations, concrete Attribute type for dynamic methods
• Run the SDK build and verify generated files under out/ohos-sdk/interfaces/sdk-js/api after changes

Example use cases

• Add a themeable fontSize property: update Text.static.d.ets and Text.d.ts, document units, ranges, and ResourceStr use for API 13+
• Deprecate a property: mark @deprecated in both static and dynamic files and provide migration notes and @obsoleted version
• Introduce a boolean runtime flag: keep it runtime-only (no Resource support) and document undefined/null handling
• Review API signatures in a PR: confirm return types, @since tags, JSDOC constraints, and cross-component compatibility