| name | docs-sync |
| description | Keep user-facing docs and DESIGN specification aligned with behavior and API changes. |
Docs Synchronization Workflow
Use this skill whenever a change touches user-visible behavior, APIs, or contracts.
When to update docs
| What changed | Update |
|---|
| CLI flags or commands | docs/guide/cli/index.md + docs/ai/SKILL.md (Build and run section) |
| Template syntax or directives | docs/guide/concepts/directives/ + docs/ai/SKILL.md |
| Component authoring model | docs/guide/concepts/interactivity.md + docs/ai/SKILL.md |
| Hydration markers or mechanism | docs/guide/concepts/hydration.md + DESIGN.md (WebUI Framework Plugin) |
| Routing behavior | docs/guide/concepts/routing.md + docs/ai/SKILL.md |
| State management or path resolution | docs/guide/concepts/state-management/index.md |
| Handler API (Rust, Node, FFI) | docs/guide/concepts/handlers/ + docs/guide/integrations.md |
| Protocol fields or fragment types | DESIGN.md (Protocol Specification) |
| Plugin system (parser or handler) | docs/guide/concepts/plugins/index.md + DESIGN.md |
| Performance characteristics | docs/guide/concepts/performance.md |
| Public API (Rust crate, npm package) | DESIGN.md + relevant handler/integration docs |
| Error variants or error messages | DESIGN.md |
@microsoft/webui-framework decorators or API | docs/guide/concepts/interactivity.md + docs/ai/SKILL.md + packages/webui-framework/README.md |
@microsoft/webui-router behavior | docs/guide/concepts/routing.md + packages/webui-router/README.md |
DESIGN.md rules
DESIGN.md is the living technical specification. Update it in the same commit when modifying:
- Public APIs or type signatures
- Protocol fields or fragment types
- Behavioral contracts (matching semantics, expression evaluation, state resolution)
- Error variants
- SSR marker formats
- Metadata object format
If DESIGN.md and the code disagree, that is a bug - fix both.
docs/ rules
Update docs/ in the same commit when the change is user-visible:
- CLI usage or flags changed
- Template syntax or rendering output changed
- Integration behavior that external developers depend on
- New features or removed features
Public API boundary
Developer documentation (docs/, crate/package READMEs, and
docs/ai/SKILL.md) documents only supported public APIs and externally
observable contracts. Every addition must map to at least one public entry
point:
- an exported Rust, Node, WASM, FFI, or package API;
- a CLI command, flag, configuration field, or supported identifier;
- supported template/component authoring syntax;
- a documented protocol or integration contract.
Do not document private or pub(crate) items, internal callbacks, intermediate
representations, cache algorithms, implementation sequencing, regression-test
details, or dependency-specific workarounds in developer docs. Put architecture
and implementation invariants in DESIGN.md; keep local rationale in succinct
ordinary source comments.
Rust /// documentation comments are for exported public APIs only. Use //
sparingly for non-public implementation rationale. Before finishing, audit the
documentation diff against the public exports and remove text that has no public
entry point.
Do not update user-facing docs for internal implementation details, regression
tests, refactors, or bug fixes that only restore already-documented behavior.
Every addition must help developers author, configure, debug, or integrate a
WebUI application. Do not add release-note-style implementation observations
to reference docs.
Keep protocol internals out of general user docs. The docs/ai/SKILL.md file is the single-page AI reference and should be kept in sync with all other docs.
docs/ai/SKILL.md is authoring-first by design. Keep deep reference material (full CLI flag tables, error-code lists, per-language integration snippets) in its canonical page and link to it from docs/ai/SKILL.md rather than duplicating it there.
Validation
cd docs && pnpm build
This catches broken links, VitePress syntax errors (unescaped {{ outside code blocks), and missing pages. Run it when docs are changed.
Style rules for docs
- No emdashes (
-). Use hyphens (-).
- Escape
{{ outside fenced code blocks with <code v-pre>{{expr}}</code>.
- Use correct CLI flag names (check
crates/webui-cli/src/commands/).
- Verify SSR markers match source code (
crates/webui-handler/src/plugin/webui.rs).
