ResumeSite/docs/spec/COMPONENT_ARCHITECTURE.md

COMPONENT_ARCHITECTURE.md

1. Principles

1. Server components by default (Astro components, zero client JS). Client behaviour only via the five behaviour modules bound by data-* attributes.
2. Components receive typed props from content + locale; they never fetch or read files. Layouts do the data plumbing.
3. One component, both themes, both locales — no HeroNo.astro, no CardDark.astro. Locale comes in as a prop bundle; theme is pure CSS.
4. Naming and states follow the Phase 1 component inventory (DESIGN_SYSTEM §5) 1:1 — design system and component tree share vocabulary.

2. Component tree

layouts/
  Base            html/head/meta, Seo, ThemeScript(inline), fonts preload, SkipLink,
                  Header, <slot/>, Footer, behaviour-module script tags (deferred)
  Page            Base + page-title block + prose container (about/contact/cv/colophon)
  Home            Base + section scaffolding with reveal data-attributes
  CaseStudy       Base + case-study scaffold (header block, MiniToc, section renderer)

components/core/
  Header          nav links (slug-map-driven), LangSwitch, ThemeToggle, SplitCvButton;
                  states: default/scrolled via data-scrolled (observer module)
  MobileNav       overlay panel (template in DOM, hidden; nav.ts toggles, traps focus)
  Footer          channels, CV links, language repeat, colophon link
  Seo             per-page meta, hreflang pairs (slug map), OG, JSON-LD builders
  ThemeScript     inline no-flash theme init (the one permitted inline script, CSP-hashed)
  SkipLink        first focusable element

components/ui/    (design-system atoms — dumb, prop-driven)
  Chip(kind: fact|status|stack, status?)     Button(variant: primary|secondary|ghost)
  SplitCvButton(locale, cvMeta)              LangSwitch(currentPageId, locale)
  ThemeToggle                                Card(interactive?)
  SectionLabel(number, text)                 TraceMotif(animated?)
  FramedImage(media, loading)                Tooltip(delay 600ms)

components/home/
  Hero(profile)                    ProofStrip(4 tiles from profile/skills data)
  SkillsGrid(skillGroups)          ProjectCards(featured projects, homelab slim card)
  ExperienceTimeline(entries)      AboutTeaser(profile)         ContactBand(profile)

components/case-study/
  CsHeader(project)                TldrBox(project.tldr)
  MiniToc(sections, sticky ≥1200)  SectionRenderer(section) — markdown → prose
  DecisionList(decisions)          ArchDiagram(diagram, locale labels)
  Gallery(media) + Lightbox host   NextPrev(project order)

3. Behaviour modules (the entire client JS surface)

Module	Binds to	Responsibility	Budget
theme.ts	ThemeToggle + inline init	read/persist preference, data-theme swap, icon morph class	~1 kB
nav.ts	Header/MobileNav	overlay open/close, focus trap, scroll lock, Esc; header data-scrolled flag	~2 kB
observer.ts	[data-reveal], [data-spy]	shared IntersectionObserver: reveal-once classes, scroll-spy for nav/MiniToc, timeline draw trigger	~2 kB
lightbox.ts	Gallery	open/close/navigate, focus trap, key handling, swipe	~3 kB
form.ts	Contact form	client validation, honeypot timing, POST to relay, A9 success/error panels, copy-to-clipboard buttons	~3 kB

Rules: modules are independent (no shared state beyond localStorage keys), fail-silent (feature simply absent if errored), loaded defer, total ≤ 15 kB gzip — well under the 40 kB budget with margin for the language-hint logic (~1 kB, lives in nav.ts).

4. Contracts between design tokens and components

• Components use Tailwind utilities mapped to tokens; no raw hex/px in component code (lint-guarded where feasible).
• State styling via data-attributes (data-scrolled, data-open, data-revealed, data-status="active") so behaviour modules never touch inline styles — CSS owns all appearance.
• Motion classes come exclusively from motion.css (token durations + reduced-motion layer) — a component never declares its own transition values.

5. Reuse & variant policy

• Case-study template is one component set; JobTrack vs InboxIntel differ only in content. Homelab's capability template reuses CsHeader/SectionRenderer, omits TldrBox/MiniToc/DecisionList.
• The 404, hint bar, and colophon reuse existing atoms only — no bespoke components for one-offs unless an atom can't express it (guard against component sprawl in a one-person codebase).