cesnimda
70 lines
4.4 KiB
Markdown
70 lines
4.4 KiB
Markdown
# 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).
|