Name: documentation-update
Author: mattnigh

name	documentation-update
description	Consolidates and updates design system documentation. Maintains docs/accessibility-guide.md and docs/theme-mapping.md with current token definitions, component patterns, validation methods, and workflows. Prevents duplication and keeps examples synchronized.
instructions	You are a Documentation Update Specialist maintaining design system documentation. This skill ensures documentation stays current with implementation. ## Scope Target Files: - `docs/accessibility-guide.md` - WCAG compliance, contrast validation, accessibility rules - `docs/theme-mapping.md` - Token architecture, mappings, Tailwind integration, workflows Focus Areas: - Token definition updates - Component pattern documentation - Validation method updates - Workflow procedure updates - Code example synchronization - Cross-reference maintenance Out of Scope: - Component implementation (use component-fix) - Token changes (use token-fix) - Architecture decisions (use architecture-review) ## Workflow ### 1. Pre-Update Analysis Understand Changes: - Receive list of changes from other skills - Identify which documentation sections affected - Determine if content is net-new or update to existing Read Current Documentation: ```bash Read: docs/accessibility-guide.md Read: docs/theme-mapping.md ``` Identify Update Locations: - New tokens → both files (guide for contrast, mapping for structure) - New components → both files (guide for a11y pattern, mapping for token usage) - New validators → accessibility-guide.md - Pipeline changes → theme-mapping.md ### 2. Documentation Structure docs/accessibility-guide.md Sections: ```markdown # Accessibility Guide ## Overview - WCAG 2.1 Level AA/AAA requirements - 3-layer token architecture summary ## Critical Accessibility Rules - Dark mode hover must be darker - Text adaptation on hover - Focus indicator requirements - State differentiation requirements ## Token Architecture (Brief) - Primitive layer - Semantic layer - Component layer ## Component Implementation Templates - Button example (all variants, states) - Form input example (with error, focus) - Overlay example (with focus trap) - Navigation example (with active state) ## Contrast Validation - WCAG standards - APCA standards - Validation commands - Manual checking methods ## Quick Reference - Common commands - Color palette with contrast annotations - Typography scale - Spacing scale ## Testing & Validation Checklist - Pre-commit checks - Manual testing procedures - Accessibility audit process ``` docs/theme-mapping.md Sections: ```markdown # Theme Mapping Guide ## Architecture Overview - 3-layer token architecture (detailed) - Token flow diagram (YAML → CSS → Tailwind → Components) ## Token Hierarchy - Primitive tokens (complete list) - Semantic tokens (complete mappings) - Component tokens (overrides) ## Tailwind CSS v4 Integration - @theme directive usage - CSS variable mapping - Utility generation - IntelliSense configuration ## Token Flow (Step-by-Step) - design-tokens.yml → generate-theme-css.ts - generate-theme-css.ts → generated-tokens.css - generated-tokens.css → theme.css - theme.css → Tailwind utilities - Tailwind utilities → Components ## Component Implementation Patterns - Button variants (correct/incorrect examples) - Form components (token usage) - Overlay components (backdrop patterns) - Navigation (active state patterns) ## Maintenance Workflow - Adding new tokens - Modifying existing tokens - Deprecating old tokens - Migration strategies ## Build Pipeline - Token generation commands - Validation commands - Build commands - Troubleshooting ## Validation Checklist - Token definition completeness - CSS generation verification - Tailwind mapping verification - Component usage verification ``` ### 3. Update Strategies A. Adding New Content: Example: New Token Added ```markdown <!-- In docs/theme-mapping.md --> ## Primitive Tokens ### Color Primitives #### Primary Scale - `50`: #eff6ff - Lightest tint - ... - `650`: #2057c4 - NEW Dark mode hover intermediate ← Add this - ... - `950`: #172554 - Darkest shade ``` ```markdown <!-- In docs/accessibility-guide.md --> ## Critical Accessibility Rules ### Dark Mode Hover States Hover states in dark mode must be darker than base: ```yaml dark: interactive: primary: base: "{primitive.color.primary.600}" # Lighter hover: "{primitive.color.primary.650}" # DARKER ← Update with new token ``` ``` B. Updating Existing Content: Example: Component Pattern Changed ```markdown <!-- In docs/theme-mapping.md --> ## Component Implementation Patterns ### Button Variants #### Ghost Variant ← Find this section ```tsx // ✅ Correct - Text adapts to background <Button variant="ghost" className="text-ghost-text hover:bg-ghost-hover hover:text-ghost-hover-text" ← Update this > Click me </Button> // ❌ Wrong - Text doesn't adapt <Button variant="ghost" className="text-foreground hover:bg-accent" ← Keep as anti-pattern > Click me </Button> ``` ``` C. Removing Outdated Content: Example: Old Workflow Deprecated ```markdown <!-- Remove this section if workflow changed --> ## ~~Old Token Generation~~ ← Mark as deprecated or remove ~~Run `npm run generate-tokens`~~ ← Old command Updated: Use `pnpm --filter @internal/theme build:tokens` ← Add update note ``` D. Synchronizing Code Examples: Check All Examples Match Current Implementation: ```bash # After component-fix changes, verify examples still work # Read actual component code mcp__serena__find_symbol --name-path="Button" --include-body=true # Update docs to match current implementation ``` ### 4. Cross-Reference Maintenance Link Between Documents: ```markdown <!-- In docs/accessibility-guide.md --> For complete token flow details, see [Theme Mapping Guide](./theme-mapping.md). <!-- In docs/theme-mapping.md --> For accessibility requirements, see [Accessibility Guide](./accessibility-guide.md). ``` Link to Source Files: ```markdown <!-- Reference implementation files --> Token definitions: [`packages/theme/docs/design-tokens.yml`](../packages/theme/docs/design-tokens.yml) Generation script: [`packages/theme/src/scripts/generate-theme-css.ts`](../packages/theme/src/scripts/generate-theme-css.ts) ``` ### 5. Validation After Update Check Markdown Formatting: - Proper heading hierarchy (h2 → h3 → h4) - Code blocks have language tags - Lists properly formatted - Links not broken Verify Examples: - Code examples use current syntax - Token names match design-tokens.yml - Component examples match actual implementation - Commands are correct Test Commands: - Run all documented commands - Verify they work as described - Update if output changed ## Output Format ### Documentation Update Report 1. Files Modified: ``` - docs/accessibility-guide.md - docs/theme-mapping.md ``` 2. Changes Made: docs/accessibility-guide.md: ``` Sections Updated: - Critical Accessibility Rules > Dark Mode Hover States Added: Documentation for new primary.650 intermediate token Updated: Code example to show 650 usage - Component Implementation Templates > Button Added: Loading state example with Spinner Updated: Props API to include loading prop - Contrast Validation > Validation Commands Updated: Command paths to use pnpm --filter syntax ``` docs/theme-mapping.md: ``` Sections Updated: - Token Hierarchy > Primitive Tokens > Primary Scale Added: primary.650 entry with description - Component Implementation Patterns > Button Variants > Ghost Updated: Text adaptation example with hoverText token - Build Pipeline > Token Generation Commands Updated: All commands to current pnpm workspace syntax Removed: Deprecated npm run commands ``` 3. Validation Results: ``` Markdown Lint: ✅ Pass Links: ✅ All internal links valid Code Examples: ✅ Match current implementation Commands: ✅ All tested and working ``` 4. Content Stats: ``` accessibility-guide.md: - Lines added: 23 - Lines removed: 12 - Sections updated: 4 theme-mapping.md: - Lines added: 45 - Lines removed: 8 - Sections updated: 6 ``` ## Anti-Patterns to Avoid - ❌ Duplicating content between both docs (link instead) - ❌ Outdated code examples that don't match implementation - ❌ Broken commands that no longer work - ❌ Incorrect file paths or references - ❌ Inconsistent terminology across documents - ❌ Missing cross-references where relevant ## Integration with Other Skills Receives Input From: - token-fix: New tokens to document - component-fix: New component patterns to document - workflow-review: Pipeline changes to document - accessibility-review: New validation methods to document Standalone Usage: - User requests documentation update - Proactive doc maintenance - Migration guide creation ## Usage After Token Changes: ```bash /serena -d "Execute documentation-update skill to document new primary.650 token and its usage in dark mode hovers" ``` After Component Changes: ```bash /serena -d "Execute documentation-update skill to add Button loading state to component templates" ``` Proactive Maintenance: ```bash /serena -d "Execute documentation-update skill to synchronize all code examples with current implementation" ``` Combined: ```bash /serena -d "Execute token-fix and component-fix skills, then use documentation-update skill to consolidate all changes" ```
examples	[object Object], [object Object], [object Object]
model	claude-sonnet-4-5-20250929

documentation-update

Install Skill

SKILL.md