Documentation

Architecture and implementation reference for danhenderson.dev, a motion-rich React + TypeScript portfolio application.

Audiences

These docs serve three groups:

Coding agents — safe extension guidance, architectural invariants, and ownership boundaries to prevent drift
Developers — precise documentation of motion systems, page composition, theme/styling patterns, and shared primitives
Reviewers / hiring managers — evidence of deliberate frontend engineering, system design, and implementation maturity

Repository instructions are layered. Use them in this order:

Resource	Owns	When to use
AGENTS.md	Repo-level workflow, guardrails, and instruction discovery	Before any cross-cutting or repo-wide task
Agent guide	Architecture invariants, intentional exceptions, and safe extension patterns	When making structural UI, motion, theme, styling, or route changes
Testing strategy	Validation matrix, build variants, and repo-standard command shapes	Whenever validating a change
PLANS.md	ExecPlan triggers, requirements, and template	When a task is non-trivial, cross-cutting, or otherwise meets a planning trigger
`src/**/AGENTS.md` and `public/resume/AGENTS.md`	Canonical local rules for the directory being edited	Before editing files in that scope
`.github/instructions/*.instructions.md`	Auto-applied shims that summarize the relevant scoped rules	When Copilot preloads file-matched instructions

If multiple documents overlap, prefer the canonical owner above and then the nearest scoped AGENTS.md for the files you are editing.

Document	Purpose
Project overview	What this site is, what makes it notable, and how the repo is organized

Document	Purpose
App architecture	Application shell, route structure, providers, and page composition model

Document	Purpose
Component architecture	Shared primitives, feature components, ownership boundaries, and safe extension points
Motion architecture	Motion token system, animation layers, choreography patterns, and intensity scaling
Theme and styling	MUI theme construction, appearance presets, style builders, and styling placement rules
Page choreography	Route-by-route page assembly, entrance sequencing, and orchestration patterns

Document	Purpose
Testing strategy	Test organization, harness patterns, motion-specific testing, and coverage priorities
Agent guide	Operational rules, common failure modes, and safe extension patterns for coding agents

Document	Purpose
Design system reference	Catalog of established UI patterns, shared surfaces, text primitives, and selection guide

Adding a new page? Start with app architecture, then page choreography.
Extending a component? Start with component architecture and the design system reference.
Working with animations? Start with motion architecture.
Changing theme or styling? Start with theme and styling.
Running or writing tests? Start with testing strategy.
AI agent implementing features? Start with the agent guide before touching code.