Design-System Charter

2025-06-05

Zoe Rackley Design-System Charter (v1)

Purpose
Establish a single source of truth that drives every design, accessibility, and engineering decision for my portfolio & blog.
All future artifacts must trace back to — and stay within — this charter.

0 · Discovery & Scope

| Category | Decisions & Rationale | Open Items | | -------- | -------------------- | ---------- | | Initial scope | Surfaces: Portfolio (home, about, featured work) and Blog (MDX posts & tag pages).
Audience: recruiters, peers, friends, tech-curious visitors.
Ownership: solo-maintained (Zoe); collaborators possible later. | — | | Future scope | Interactive AI/Data demos (client-side; long-lived public APIs).
Spin-off microsites re-using the same design system. | Identify the first demo so primitives anticipate required interactivity. | | Success criteria | 1. Functional – portfolio + blog shipped.
2. Maintainable – zero-config GitHub Pages deploy; Dependabot/Renovate keep deps green; tokens drive all theming.
3. Accessible – WCAG 2.2 AA baseline; full keyboard support; prefers-reduced-motion handled.
4. Aesthetic – Dracula-inspired dark mode + modern-poster blocking; deliberate geometry; animations ≤ 80 ms main-thread.
5. Playground-ready – flexible enough for ADHD-fuelled experiments.
De-prioritised: aggressive SEO. | • Choose two automated health checks → Lighthouse ≥ 90 Accessibility, JS bundle < 300 kB gz. | | Guiding principles | • Form follows function, then delights.
• Geometric clarity over ornament.
• Dark-mode first; light optional.
• Animation enhances comprehension or delight—never slows UX.
• Every component documented in Storybook. | Draft one-pager elaborating these principles (Layer 1). | | Governance & workflow | Git flow: main (live) ← design-system/* feature branches.
PR checklist: token diff, a11y scan (axe-linter), Lighthouse CI, optional Percy visual diff.
Roles: Designer / Dev / PM / QA = Zoe. | Decide whether Storybook deploys per-PR or only on release tags. |

Immediate Next Steps (v1 roadmap)

Commit this charter as docs/charter.mdx (done).
Draft the Guiding Principles & Ethos one-pager (Layer 1).
Define and automate the two health-check metrics (Lighthouse & bundle budget) in CI.
Generate design tokens (colour, spacing, typography) with Style-Dictionary → Tailwind theme.
Ship Button, Link, and Heading/Text primitives in Storybook; verify a11y + focus order.
Replace ad-hoc CSS with token-driven Tailwind classes on existing pages.
Schedule weekly 30-min design-system “office hours” for continuous refinement.

Change-log Process

| Change type | SemVer bump | Release notes | | ----------- | ----------- | ------------- | | Token or visual-only tweak (no breaking prop changes) | patch | Changelog + screenshot diff | | New component or additive prop | minor | Usage example in Storybook | | Breaking API change | major | Migration doc + codemod script |

Glossary

| Term | Definition | | ---- | ---------- | | Token | Atomic design decision (e.g., --color-primary, --space-2). | | Primitive | Lowest-level UI element (Button, Link, Heading). | | Composite | Component composed of primitives (Card, Navbar). | | Pattern | Page-level layout (Hero, Blog Index). |