docs: establish approved Phase 1 design + Phase 2 spec as project foundation
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
cesnimda
@@ -0,0 +1,69 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user