documentation-update

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:
  - input: "Execute documentation-update skill after adding new tokens"
    output: "Updates both docs with new token definitions, usage examples, contrast annotations, validates markdown, confirms accuracy"

  - input: "Execute documentation-update skill to sync component examples"
    output: "Reads current component implementations, updates all code examples in docs, verifies syntax, confirms examples work"

  - input: "Execute documentation-update skill after workflow changes"
    output: "Updates theme-mapping.md build pipeline section, corrects all commands, removes deprecated steps, adds new validation methods"

model: claude-sonnet-4-5-20250929