Plate Docs
Own Plate's public documentation experience: house style, page composition,
example coverage, setup, API teaching, MDX and navigation. Use
pstack:technical-writing for prose, voice and document modes. Its general
rules serve this project's house style. A docs edit keeps code, commands,
identifiers, frontmatter and link targets unchanged unless the change covers
them, and keeps numbers, versions and names tied to their source. It also keeps obligation words (must, may, never), uncertainty and meaningful scope limits as strong as the source says; never turn a possibility into a guarantee, whatever technical-writing says about hedging. Code snippets
follow the repository formatter's two-space indentation, not technical-writing's
tab rule.
Handle the requested page, feature or documentation audit. An audit reports
source-backed gaps; edits stay within the requested scope. General prose in
plans, reports, READMEs and PR descriptions goes directly to pstack:technical-writing.
For a tiny copy edit, read the text and resolve changed links without loading
unrelated docs mechanics; it still runs the verify table's docs audits.
Read the target page, its nearest useful sibling, and the source that owns each
changed claim. Start from the current source and public exports. Docs describe
the current API; unresolved API design belongs to Best API before teaching it.
House style: shadcn
This house style takes precedence over the generic presentation defaults of
pstack:technical-writing. Use shadcn for density and page composition; Plate source owns API
behavior, imports, requirements and examples.
- Start fast. Frontmatter supplies the title and description. Add a short lead
only when it clarifies the task, owner or an easily confused sibling.
- Put the first useful preview or working path before deeper explanation.
Recommend the kit/CLI path first when it is the actual supported default;
put manual or headless alternatives after it.
- Keep component pages together: installation, usage, visible examples and
compact API reference can serve one reader goal. Each section does one job.
- Show imports and the smallest real working example. Add context when the
code needs it; obvious usage does not need a ceremonial lead-in sentence.
- Prefer a real preview and one useful line to paragraphs describing a visual
variant. Use MDX components for real structure or choices, not decoration.
- Keep reference compact: exact names, types, options and short caveats.
Preserve established headings and anchors across comparable pages.
- Explain a non-obvious choice briefly. Runtime concepts can need more context
than a UI component; density must not hide ownership or lifecycle behavior.
- Document only the latest state. Never write changelog-style language ("has
been removed", "new feature", "previously", "now supports"), migration notes
or "what changed"; write as if no prior version exists.
For a substantial style or page-shape decision, compare the nearest Plate
sibling with a relevant page in
../shadcn/apps/v4/content/docs/. Component
examples include components/base/button.mdx, chart.mdx and sidebar.mdx;
installation and registry pages cover their own shapes. Read the applicable
page, not the whole corpus. This comparison does not require an upstream sync.
Cover the feature's actual use
Choose examples by reader need. Identify the page's important reader tasks,
claims and likely misunderstandings, and give each a clear home in an example,
a precise reference section or a linked guide. Choose each example for
something distinct it helps the reader do or understand, keep it small enough
to understand and complete enough to use, and name its prerequisites. Reuse or
link an existing example when it already serves the reader. Label a mock
service or local snapshot at the example, and state unsupported or unverified
behavior as a limitation instead of inventing it. An audit reports missing
coverage; implementation stays within the requested scope. For feature and
component pages:
- Lead with a focused example of the named feature. Use its kit and required
dependencies in setup; a full application
EditorKit belongs in an example
whose purpose is that composition. Preserve explicit feature configuration
under Plate UI's teaching/install rules.
- Give important tasks and materially different states a clear home in an
example, snippet, reference section or linked guide. Consider creation and
editing, boundaries and history, persistence and recovery, and rendering or
access modes only where they affect this feature. Do not require every
category, a demo per API method or a fixed number of previews.
- Let each additional example teach a distinct task, behavior or useful visual
variant. Reuse registered demos and link composition to its owning page
instead of reproducing the same mixed-feature preview across sibling pages.
- Keep integration requirements next to the example that needs them. Show
minimum prerequisites in setup; put detailed ownership and lifecycle
explanations after working examples or in a linked concept guide.
- Keep example claims within their proof. An in-memory save/reload demonstrates
a local round trip; label simulated failures. A read-only editor setting
does not establish application authorization. Preserve established fixtures
and meaningful interactions when revising examples.
For a coverage audit, account for the important in-scope tasks and states and
their homes or gaps. Use the existing report or plan when one is needed; do
not create a second inventory or expand a wording-only edit into an audit.
Verify changed examples through the existing proof owners below.
Select the needed mechanics
| Changed contract |
Read |
| New page, substantial rewrite or a docs gap/topology decision |
Page shapes; select only the matching lane |
| MDX components, navigation, installation requirements or release routes |
MDX and routes |
| Public schema, identity, migration, decoration or renderer examples |
Public API examples |
| Plugin setup, kit/manual paths, format mappings, events or API examples |
Plugin documentation |
For a gap review, compare the nearest concept guide, public reference and
feature page before adding a page. Put exact signatures in their reference,
setup in the feature page, and cross-package explanations in a concept guide.
Merge duplicated concepts and link to one owner. Read content/docs/meta.json
only when adding, moving, merging or deleting routes or changing navigation.
Verify the changed claims
| Change |
Required evidence |
| Prose or link only |
Read the edited text and resolve changed links; preserve code and metadata |
| MDX structure or examples |
pnpm --filter www build:source; verify symbols, imports and fence content against source |
| Docs source parity or generated docs |
pnpm --filter www check:docs |
Any content/docs edit |
node tooling/scripts/check-plite-docs.mjs and node tooling/scripts/check-plate-doc-code-contracts.mjs, the docs audits that pnpm check runs in its plite-docs and core-audits steps, which otherwise first run at landing |
| New/moved route or navigation |
Parse changed metadata and request the exact route; inspect pager/sidebar when they changed |
| Preview or visible component behavior |
Resolve the real demo and use verify on that exact route/state |
| Registry source |
Plate UI and the branch's registry-generation rule |
Run applicable checks once after the final prose pass. New source changes or a
failure can require another pass. An MDX parse does not prove a route, runtime
API behavior or browser input. Report the exact proof limit.
1---2description: Use before any edit under content/docs, including a one-line fix to existing advice, a Chinese twin or an embedded demo, and to write or audit Plate public documentation, page design, examples, installation, MDX and navigation.3name: plate-docs4metadata:5 skiller:6 source: https://skillmd.com/skills/udecode/plate-docs7 upstream: .agents/rules/plate-docs.mdc8---910# Plate Docs1112Own Plate's public documentation experience: house style, page composition,13example coverage, setup, API teaching, MDX and navigation. Use14`pstack:technical-writing` for prose, voice and document modes. Its general15rules serve this project's house style. A docs edit keeps code, commands,16identifiers, frontmatter and link targets unchanged unless the change covers17them, and keeps numbers, versions and names tied to their source. It also keeps obligation words (must, may, never), uncertainty and meaningful scope limits as strong as the source says; never turn a possibility into a guarantee, whatever `technical-writing` says about hedging. Code snippets18follow the repository formatter's two-space indentation, not technical-writing's19tab rule.2021Handle the requested page, feature or documentation audit. An audit reports22source-backed gaps; edits stay within the requested scope. General prose in23plans, reports, READMEs and PR descriptions goes directly to `pstack:technical-writing`.24For a tiny copy edit, read the text and resolve changed links without loading25unrelated docs mechanics; it still runs the verify table's docs audits.2627Read the target page, its nearest useful sibling, and the source that owns each28changed claim. Start from the current source and public exports. Docs describe29the current API; unresolved API design belongs to Best API before teaching it.30## House style: shadcn3132This house style takes precedence over the generic presentation defaults of33`pstack:technical-writing`. Use shadcn for density and page composition; Plate source owns API34behavior, imports, requirements and examples.3536- Start fast. Frontmatter supplies the title and description. Add a short lead37 only when it clarifies the task, owner or an easily confused sibling.38- Put the first useful preview or working path before deeper explanation.39 Recommend the kit/CLI path first when it is the actual supported default;40 put manual or headless alternatives after it.41- Keep component pages together: installation, usage, visible examples and42 compact API reference can serve one reader goal. Each section does one job.43- Show imports and the smallest real working example. Add context when the44 code needs it; obvious usage does not need a ceremonial lead-in sentence.45- Prefer a real preview and one useful line to paragraphs describing a visual46 variant. Use MDX components for real structure or choices, not decoration.47- Keep reference compact: exact names, types, options and short caveats.48 Preserve established headings and anchors across comparable pages.49- Explain a non-obvious choice briefly. Runtime concepts can need more context50 than a UI component; density must not hide ownership or lifecycle behavior.51- Document only the latest state. Never write changelog-style language ("has52 been removed", "new feature", "previously", "now supports"), migration notes53 or "what changed"; write as if no prior version exists.54For a substantial style or page-shape decision, compare the nearest Plate55sibling with a relevant page in `../shadcn/apps/v4/content/docs/`. Component56examples include `components/base/button.mdx`, `chart.mdx` and `sidebar.mdx`;57installation and registry pages cover their own shapes. Read the applicable58page, not the whole corpus. This comparison does not require an upstream sync.5960## Cover the feature's actual use6162Choose examples by reader need. Identify the page's important reader tasks,63claims and likely misunderstandings, and give each a clear home in an example,64a precise reference section or a linked guide. Choose each example for65something distinct it helps the reader do or understand, keep it small enough66to understand and complete enough to use, and name its prerequisites. Reuse or67link an existing example when it already serves the reader. Label a mock68service or local snapshot at the example, and state unsupported or unverified69behavior as a limitation instead of inventing it. An audit reports missing70coverage; implementation stays within the requested scope. For feature and71component pages:7273- Lead with a focused example of the named feature. Use its kit and required74 dependencies in setup; a full application `EditorKit` belongs in an example75 whose purpose is that composition. Preserve explicit feature configuration76 under Plate UI's teaching/install rules.77- Give important tasks and materially different states a clear home in an78 example, snippet, reference section or linked guide. Consider creation and79 editing, boundaries and history, persistence and recovery, and rendering or80 access modes only where they affect this feature. Do not require every81 category, a demo per API method or a fixed number of previews.82- Let each additional example teach a distinct task, behavior or useful visual83 variant. Reuse registered demos and link composition to its owning page84 instead of reproducing the same mixed-feature preview across sibling pages.85- Keep integration requirements next to the example that needs them. Show86 minimum prerequisites in setup; put detailed ownership and lifecycle87 explanations after working examples or in a linked concept guide.88- Keep example claims within their proof. An in-memory save/reload demonstrates89 a local round trip; label simulated failures. A read-only editor setting90 does not establish application authorization. Preserve established fixtures91 and meaningful interactions when revising examples.9293For a coverage audit, account for the important in-scope tasks and states and94their homes or gaps. Use the existing report or plan when one is needed; do95not create a second inventory or expand a wording-only edit into an audit.96Verify changed examples through the existing proof owners below.9798## Select the needed mechanics99100| Changed contract | Read |101| --- | --- |102| New page, substantial rewrite or a docs gap/topology decision | [Page shapes](./references/lanes.md); select only the matching lane |103| MDX components, navigation, installation requirements or release routes | [MDX and routes](./references/mdx.md) |104| Public schema, identity, migration, decoration or renderer examples | [Public API examples](./references/api-examples.md) |105| Plugin setup, kit/manual paths, format mappings, events or API examples | [Plugin documentation](./references/plugin.md) |106107For a gap review, compare the nearest concept guide, public reference and108feature page before adding a page. Put exact signatures in their reference,109setup in the feature page, and cross-package explanations in a concept guide.110Merge duplicated concepts and link to one owner. Read `content/docs/meta.json`111only when adding, moving, merging or deleting routes or changing navigation.112113## Verify the changed claims114115| Change | Required evidence |116| --- | --- |117| Prose or link only | Read the edited text and resolve changed links; preserve code and metadata |118| MDX structure or examples | `pnpm --filter www build:source`; verify symbols, imports and fence content against source |119| Docs source parity or generated docs | `pnpm --filter www check:docs` |120| Any `content/docs` edit | `node tooling/scripts/check-plite-docs.mjs` and `node tooling/scripts/check-plate-doc-code-contracts.mjs`, the docs audits that `pnpm check` runs in its plite-docs and core-audits steps, which otherwise first run at landing |121| New/moved route or navigation | Parse changed metadata and request the exact route; inspect pager/sidebar when they changed |122| Preview or visible component behavior | Resolve the real demo and use [`verify`](../verify/SKILL.md) on that exact route/state |123| Registry source | [Plate UI](../plate-ui/SKILL.md) and the branch's registry-generation rule |124125Run applicable checks once after the final prose pass. New source changes or a126failure can require another pass. An MDX parse does not prove a route, runtime127API behavior or browser input. Report the exact proof limit.