Skip to content

Add missing user guides for core framework systems #47

@PAMulligan

Description

@PAMulligan

Summary

Several core framework systems lack user-facing documentation. Users (and contributors) have no way to understand how these systems work beyond reading source code.

Missing Guides

P0 — Core Pipeline Systems

  1. Design Token System Guide — token structure, lockfile format, validation, sync strategy, drift detection
  2. Visual QA Deep Dive — how visual-diff.js works, sub-pixel detection, typography analysis, region grids, threshold tuning
  3. Pipeline Caching & Performance — how incremental builds work, cache invalidation, profiling, when to use --force

P1 — Development Guides

  1. Hook System Guide — how hooks fire, execution order, creating custom hooks (pairs with Add JSON schema validation for pipeline.config.json #45)
  2. Error Recovery Guide — what to do when a pipeline phase fails, how to resume, common failure modes
  3. Agent Creation Guide — how to create a custom agent, required YAML frontmatter, tool declarations

P2 — Framework-Specific

  1. Vue Converter Workflow — Vue 3 pipeline specifics, Composition API patterns
  2. Svelte Converter Workflow — SvelteKit pipeline specifics, store patterns
  3. React Native Converter Workflow — Expo pipeline specifics, NativeWind setup
  4. Chrome Extension Pipeline — manifest v3, service worker testing, extension E2E
  5. PWA Pipeline — service worker lifecycle, offline testing, manifest validation

Suggested Location

docs/guides/ directory with clear naming (e.g., design-tokens.md, visual-qa.md, caching.md)

Acceptance Criteria

  • P0 guides written and linked from CLAUDE.md
  • P1 guides written
  • P2 guides written (can be shorter, reference existing pipeline docs)
  • Onboarding quickstart updated to reference new guides

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or requesthelp wantedExtra attention is needed

Projects

Status

Done

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions