atomui-control-documentation

name	atomui-control-documentation
description	Use when creating, completing, splitting, reviewing, or synchronizing AtomUI control documentation under docs/controls, including overview.md, implementation.md, token.md, changelog.md, topic design documents, LLMS source coverage, Gallery API/Token/ShowCase alignment, or documentation impact from control API, theme, behavior, and architecture changes.

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:

Document	Owns	Must not become
overview.md	Current design positioning, public contract, state/behavior model, visual/theme model, compatibility, navigation, LLMS source map	Implementation walkthrough or API dump
implementation.md	Current source ownership, composition, data/state flow, lifecycle, algorithms, resource/performance/AOT boundaries, maintenance invariants	User guide, design history, or private-method catalog
<topic>-design.md	One stable cross-cutting design spanning model/API, strategy, architecture, Template, algorithm, compatibility, and verification	Issue analysis, ADR, option comparison, or implementation plan
token.md	Control-specific Token semantics, categories, family impact, compatibility, validation	Generated Token table or runtime state model
changelog.md	Dated design/API/theme/Token/implementation-structure changes	Current design explanation or release changelog

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

4. Synchronize the Documentation Set

• Keep overview.md and implementation.md as the primary entry points.
• Add bidirectional links for each topic design document.
• Keep enough API and semantic summary in the main documents for LLMS generation.
• Update changelog.md for actual design, API, theme, Token, or implementation-structure changes.
• Update the category index when adding a new control directory.
• Check Gallery API/Token tables and ShowCase examples when public usage changes.
• Do not hand-edit generated files under docs/AI/generated/llms; update their source documents or generator input.

5. Review

Read the result as a maintainer who has not seen the task:

• Can they identify the contract without reading history?
• Can they find the owner for every state, metric, resource, and lifecycle?
• Do API, Template, Gallery, tests, and docs use the same names and defaults?
• Are platform and mode differences complete rather than scattered exceptions?
• Does every specialized section belong in this control rather than a global guideline?
• Are all links valid and all required main-document sections present?

Fix contradictions and vague language before reporting completion.

Red Flags

Stop and reshape the document when any of these appear:

• The opening starts with an Issue, screenshot, reproduction, or pixel analysis.
• overview.md or implementation.md contains “target files,” “planned API,” implementation status, or a task checklist.
• A topic design document contains adopted/rejected option comparison or historical root-cause analysis.
• Public API is listed only in a topic document and absent from the overview summary.
• Template/composition claims are not grounded in actual Themes or an approved design contract.
• Internal types are presented as user APIs.
• Generated LLMS output is edited directly.
• A control-level document repeats global AOT, Token, Gallery, or documentation rules.
• A new helper document has no independent audience, lifecycle, or ownership boundary.
• A Mobile Control directory is created before Public API source, Theme, Contract/Headless tests, and Gallery API/Token/ShowCase evidence exist.

Verification

Always run:

git diff --check

Then verify according to impact:

• Documentation only: inspect relative links, required sections, stale names, and git status.
• Public API or behavior: run the targeted control tests and verify Gallery API/example synchronization.
• Theme/Template: run theme contract tests and inspect Light/Dark plus affected platform hosts.
• Gallery source changes: run tests/AtomUIGallery.Tests.
• LLMS source changes: run the repository LLMS verification command when available; never claim generated output is current without it.
• AOT-sensitive changes: run the required NativeAOT publish validation.

Completion Report

Report:

Documents created/updated:
Contract or design represented:
Source/Theme/Gallery evidence:
LLMS impact:
Validation performed:
Known mismatch or residual platform validation:
Commit created: No unless explicitly requested