// Evaluates grammar, spelling, and formatting in design systems' documentation. Use when checking mechanics like spelling, punctuation, heading hierarchy, and list formatting.
| name | copy-editing-evaluation |
| description | Evaluates grammar, spelling, and formatting in design systems' documentation. Use when checking mechanics like spelling, punctuation, heading hierarchy, and list formatting. |
Hard technique for evaluating grammar, spelling, and formatting in design systems documentation.
copy-editing script to get objective findingsThe deterministic pass catches spelling errors, flagged words, heading issues, and formatting problems. The qualitative pass covers everything else: list structure, link quality, terminology consistency, and punctuation style.
Run copy-editing.js from the same directory as this skill file. Pass the path to a markdown file as the only argument.
node <skill-directory>/copy-editing.js <file.md>
The script:
Multi-word phrases in @.agents/dockit/references/flagged-words.txt (e.g. "in order to", "end user") are not detected by the script. Flag those during the qualitative pass.
The script outputs a JSON object with five keys:
{
"spelling": [
{
"word": "componnet",
"line": 5,
"offset": 4
}
],
"forbiddenWords": [
{
"word": "ensure",
"line": 9,
"lineText": "Please ensure that you use the correct variant.",
"suggestion": "make sure"
},
{
"word": "simply",
"line": 5,
"lineText": "Simply add the component to your page."
}
],
"headings": [
{
"type": "skipped-level",
"line": 7,
"text": "Skipped heading",
"message": "Heading level skipped: H2 → H4. Expected H3."
},
{
"type": "multiple-h1",
"line": 17,
"text": "Second title",
"message": "Multiple H1 headings found. ..."
},
{
"type": "not-sentence-case",
"line": 21,
"text": "This Is Title Case",
"message": "Heading is not in sentence case: \"This Is Title Case\"."
}
],
"formatting": [
{
"type": "em-dash",
"line": 5,
"lineText": "The button component — one of the most common — is used for actions.",
"message": "Em-dash (—) found. Use an alternative phrasing or punctuation."
}
],
"summary": {
"spelling": 1,
"forbiddenWords": 2,
"headings": 3,
"formatting": 1,
"total": 7
}
}
spelling — misspelled words detected by cspell. Each entry has the word, the line number (1-indexed), and the character offset from the start of the file.
forbiddenWords — words from @.agents/dockit/references/flagged-words.txt found in the document. Entries with a suggestion field are words that have a preferred replacement. Entries without suggestion are strictly forbidden and should be removed or the sentence restructured.
headings — heading hierarchy and capitalisation issues. The type field is one of skipped-level, multiple-h1, or not-sentence-case. The message field provides a human-readable description.
formatting — punctuation issues. Currently detects em-dashes (—).
summary — counts of issues by category and a total across all categories.
The copy editor checks mechanics: grammar, spelling, punctuation, formatting, and structural consistency. It does not evaluate:
If a sentence is grammatically correct but does not match the style guide's tone, do not flag it. If a section is thin, do not flag it. Stay in your lane.
The following checks are performed by the LLM during the qualitative pass. The script does not cover these.
The script only flags single words. During the qualitative pass, also check for multi-word phrases from @.agents/dockit/references/flagged-words.txt such as "in order to", "for the purpose of", "end user", and "in conjunction with".
Common terms and their preferred spellings. Flag deviations.
| Preferred | Common variants to flag |
|---|---|
| dropdown | drop-down, drop down, DropDown |
| checkbox | check box, check-box, CheckBox |
| tooltip | tool tip, tool-tip, ToolTip |
| popover | pop over, pop-over, PopOver |
| dialog | dialogue (in UI context), Dialog |
| modal | Modal (when not a proper noun) |
| open source | open-source |
| sidebar | side bar, side-bar |
| navbar | nav bar, nav-bar, navigation bar |
| login (noun/adj) | log in (noun/adj) |
| log in (verb) | login (verb) |
| setup (noun/adj) | set up (noun/adj) |
| set up (verb) | setup (verb) |
| frontend | front-end, front end |
| backend | back-end, back end |
| webpage | web page |
The style guide at @.agents/dockit/references/style-guide.md has its own terminology section. If it specifies a different preference, the style guide wins.
All items in a list should follow the same grammatical structure.
Good (all imperative):
Bad (mixed structures):
Use the explore-existing-design-systems-documentation skill to check:
... not . . .<output_format>
Each finding:
[severity] Section: {section name} (line ~{number})
Issue: {description}
Current: "{the current text}"
Suggested: "{the corrected text}"
Rule: {which rule this falls under}
<severity_levels>
[critical] — Spelling error in a heading, broken code example, skipped heading level[suggestion] — Inconsistent formatting, parallel structure issue[nitpick] — Minor punctuation, optional style preference</severity_levels>
Group findings by section, then by severity within each section.
End with a summary:
Copy Editing Summary:
Spelling: {count} findings
Headings: {count} findings
Lists: {count} findings
Links: {count} findings
Terminology: {count} findings
Punctuation: {count} findings
Formatting: {count} findings
Total: {count} findings ({critical} critical, {suggestions} suggestions, {nitpicks} nitpicks)
</output_format>
Evaluates documentation against the team's brand guidelines. Use when reviewing docs for tone, terminology, sentence structure, and phrasing consistency.
Evaluates whether documentation sections have substantive content. Use when checking whether planned sections are complete, thin, placeholders, or missing.
Scores and evaluates documentation readability using Flesch-Kincaid metrics and qualitative analysis. Use when reviewing docs for sentence length, passive voice, jargon, and reading level.
Evaluates documentation against the team's brand guidelines. Use when reviewing docs for tone, terminology, sentence structure, and phrasing consistency.
Evaluates whether documentation sections have substantive content. Use when checking whether planned sections are complete, thin, placeholders, or missing.
Evaluates grammar, spelling, and formatting in design systems' documentation. Use when checking mechanics like spelling, punctuation, heading hierarchy, and list formatting.