Atomui Control Documentation

AtomUI Control Documentation

Core Rule

Treat docs/engineering/contributing/control-documentation-guidelines.md as the canonical documentation contract. Read it before editing. Do not copy its full rules into control documents or this skill.

Also read:

• docs/engineering/development/control-development-guidelines.md for API, theme, template, file-layout, and compatibility boundaries.
• docs/engineering/contributing/mobile-documentation-guidelines.md when the target is under docs/controls/mobile or the task concerns AtomUI.Mobile.Controls.
• The target control's existing overview.md, implementation.md, token.md, changelog.md, source, Themes, tests, and Gallery surface.
• docs/engineering/development/aot-programming-guidelines.md when the design involves reflection, dynamic discovery, binding paths, generators, or NativeAOT.

Classify the Document

Choose the document by responsibility before writing:

Create a topic design document only when the canonical guideline's creation conditions are met. Keep a short topic in overview.md or implementation.md.

Required Audit Gate

Before editing, establish this fact map from the repository:

Control:
Task: create / update / split / review / synchronize
Package and namespace:
Source and Themes directories:
Existing control docs:
Public API and defaults:
Template Parts / pseudo-classes / ControlTheme keys:
State, data, lifecycle, and owner model:
Token scope and consumers:
Gallery API / Token / ShowCase coverage:
Tests and platform/AOT validation:
Platform evidence status (iOS / Android / Release / publication):
Selected document type(s):
Contradictions or missing evidence:

Do not edit until the selected document type and evidence are clear. For a narrow change, keep the audit short; for a new or complex control, inspect the full control family and comparable controls.

Evidence Order

Use these sources in order and resolve conflicts explicitly:

1. Public/protected API registrations, CLR wrappers, events, interfaces, defaults, and control source.
2. Themes/ ControlTheme/ControlTemplate structure, Template Parts, selectors, resource keys, and runtime composition.
3. Tests proving behavior, lifecycle, platform, and theme contracts.
4. Gallery structured API/Token tables and stable ShowCase examples.
5. Existing control documents and changelog.

Issues, screenshots, commits, PRs, and investigation notes may explain why work started, but they are not design facts. Never use them as the narrative frame of a current control document.

When source, Gallery, tests, and docs disagree, report the contradiction and determine the intended contract. Do not silently pick the most convenient source.

Workflow

1. Inspect

• Read the canonical documentation and development guidelines.
• List the control docs, source files, Themes, tests, Gallery rows, and stable examples.
• Read git status and relevant diffs; preserve unrelated user changes.
• Identify comparable controls only when they clarify an established local pattern.

2. Select the Edit Shape

• Update existing documents before creating new ones.
• Create the standard control directory only when the control lacks it.
• Split a topic document only when it has a stable independent model and would overload both main documents.
• Keep pre-implementation reasoning, option comparison, and task planning outside control documents. A topic design document contains only the final design, without status or Issue narration.
• Do not create a second guideline when the rule belongs in control-documentation-guidelines.md.

3. Write the Current Design

• Start from the control capability, not from the bug, Issue, commit, or migration story.
• State API semantics and defaults precisely; do not mechanically copy every member.
• Describe actual Template and composition nodes from Themes, not imagined generic structure.
• Define state/data owners, direction of flow, lifecycle acquire/release pairs, and boundary behavior.
• For algorithms, define inputs, outputs, units, coordinate systems, main flow, invalidation, and degradation rules.
• For platform or mode variants, define shared invariants first, then use a complete matrix for differences and fallback.
• Record source file structure only when it expresses stable ownership, not a target-file checklist.
• Keep Token semantics in token.md; keep history in changelog.md.

Topic design documents follow this shape when each section applies:

Position -> Principles -> Model/API -> Variant strategy -> Architecture/ownership
-> Template/integration -> Algorithm/data flow/lifecycle -> Performance/AOT
-> Compatibility/customization -> Verification