@5voltfx/design-system 0.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@5voltfx/design-system",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./styles.css": "./src/tokens/index.css",
+    "./components/*": "./src/components/*/index.js",
+    "./vite-plugin": "./vite-plugin.js"
+  },
+  "files": [
+    "src",
+    "vite-plugin.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.0.0"
+  }
+}

package/src/components/Button/Button.css

@@ -0,0 +1,77 @@
+.ds-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--ds-space-2);
+  border: 1px solid transparent;
+  border-radius: var(--ds-radius-pill);
+  font-family: var(--ds-font-body);
+  font-weight: var(--ds-font-weight-semibold);
+  font-size: var(--ds-font-size-200);
+  line-height: var(--ds-line-height-tight);
+  text-decoration: none;
+  cursor: pointer;
+  transition:
+    background-color var(--ds-motion-duration-base) var(--ds-motion-ease-standard),
+    border-color var(--ds-motion-duration-base) var(--ds-motion-ease-standard),
+    color var(--ds-motion-duration-base) var(--ds-motion-ease-standard),
+    transform var(--ds-motion-duration-fast) var(--ds-motion-ease-standard),
+    box-shadow var(--ds-motion-duration-base) var(--ds-motion-ease-standard);
+}
+
+.ds-button--md {
+  padding: var(--ds-space-3) var(--ds-space-5);
+}
+
+.ds-button--sm {
+  padding: var(--ds-space-2) var(--ds-space-4);
+  font-size: var(--ds-font-size-100);
+}
+
+.ds-button--lg {
+  padding: var(--ds-space-4) var(--ds-space-6);
+  font-size: var(--ds-font-size-300);
+}
+
+.ds-button--primary {
+  background-color: var(--ds-color-bg-2);
+  color: var(--ds-color-font-0);
+  box-shadow: var(--ds-shadow-sm);
+}
+
+.ds-button--primary:hover {
+  transform: translateY(-1px);
+  box-shadow: var(--ds-shadow-md);
+}
+
+.ds-button--secondary {
+  background-color: transparent;
+  color: var(--ds-color-font-0);
+  border-color: var(--ds-color-bw-3);
+}
+
+.ds-button--secondary:hover {
+  background-color: var(--ds-color-bw-1);
+}
+
+.ds-button--ghost {
+  background: transparent;
+  color: var(--ds-color-font-1);
+  padding-inline: var(--ds-space-3);
+}
+
+.ds-button--ghost:hover {
+  color: var(--ds-color-font-0);
+}
+
+.ds-button:focus-visible {
+  outline: 2px solid var(--ds-color-bg-2);
+  outline-offset: 2px;
+}
+
+.ds-button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  transform: none;
+  box-shadow: none;
+}

package/src/components/Button/Button.jsx

@@ -0,0 +1,20 @@
+import "./Button.css";
+
+export function Button({
+  as: Component = "button",
+  variant = "primary",
+  size = "md",
+  className = "",
+  ...rest
+}) {
+  const classes = [
+    "ds-button",
+    `ds-button--${variant}`,
+    `ds-button--${size}`,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return <Component className={classes} {...rest} />;
+}

package/src/components/Button/index.js

@@ -0,0 +1 @@
+export { Button } from "./Button.jsx";

package/src/components/Card/Card.css

@@ -0,0 +1,11 @@
+.ds-card {
+  background-color: var(--ds-color-bg-1);
+  color: var(--ds-color-font-0);
+  border: 1px solid var(--ds-color-bw-1);
+  border-radius: var(--ds-radius-lg);
+  padding: var(--ds-space-5);
+  box-shadow: var(--ds-shadow-sm);
+  transition:
+    box-shadow var(--ds-motion-duration-base) var(--ds-motion-ease-standard),
+    transform var(--ds-motion-duration-base) var(--ds-motion-ease-standard);
+}

package/src/components/Card/Card.jsx

@@ -0,0 +1,6 @@
+import "./Card.css";
+
+export function Card({ as: Component = "div", className = "", ...rest }) {
+  const classes = ["ds-card", className].filter(Boolean).join(" ");
+  return <Component className={classes} {...rest} />;
+}

package/src/components/Card/index.js

@@ -0,0 +1 @@
+export { Card } from "./Card.jsx";

package/src/components/Footer/Footer.css

@@ -0,0 +1,48 @@
+.ds-footer {
+  background-color: var(--ds-color-bg-1);
+  color: var(--ds-color-font-1);
+  border-top: 1px solid var(--ds-color-bw-1);
+  font-family: var(--ds-font-body);
+}
+
+.ds-footer__inner {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: var(--ds-space-4) var(--ds-space-6);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ds-space-4);
+}
+
+.ds-footer__left,
+.ds-footer__right {
+  flex: 1;
+  display: flex;
+  align-items: center;
+}
+
+.ds-footer__right {
+  justify-content: flex-end;
+}
+
+.ds-footer__center {
+  display: flex;
+  justify-content: center;
+}
+
+.ds-footer__copyright {
+  font-size: var(--ds-font-size-100);
+}
+
+@media (width <= 660px) {
+  .ds-footer__inner {
+    flex-direction: column;
+    padding: var(--ds-space-4);
+  }
+
+  .ds-footer__left,
+  .ds-footer__right {
+    justify-content: center;
+  }
+}

package/src/components/Footer/Footer.jsx

@@ -0,0 +1,37 @@
+import { ThemeSwitcher } from "../ThemeSwitcher/ThemeSwitcher.jsx";
+import "./Footer.css";
+
+/**
+ * Generalizes the 3 existing footers: 5voltfx.com's simple centered
+ * copyright, song-chart's minimal bar, and mattwelker.com's 3-column
+ * layout (auth links / theme swatches / copyright). `left` and `right`
+ * default to nothing and a copyright string respectively, so a single
+ * centered ThemeSwitcher is the only thing rendered out of the box.
+ */
+export function Footer({
+  brand = "5VoltFX/Matt Welker",
+  showThemeSwitcher = true,
+  left,
+  right,
+  className = "",
+}) {
+  const year = new Date().getFullYear();
+
+  return (
+    <footer className={["ds-footer", className].filter(Boolean).join(" ")}>
+      <div className="ds-footer__inner">
+        <div className="ds-footer__left">{left}</div>
+        <div className="ds-footer__center">
+          {showThemeSwitcher && <ThemeSwitcher />}
+        </div>
+        <div className="ds-footer__right">
+          {right ?? (
+            <span className="ds-footer__copyright">
+              © {year} {brand}
+            </span>
+          )}
+        </div>
+      </div>
+    </footer>
+  );
+}

package/src/components/Footer/index.js

@@ -0,0 +1 @@
+export { Footer } from "./Footer.jsx";

package/src/components/Header/Header.css

@@ -0,0 +1,47 @@
+.ds-header {
+  background-color: var(--ds-color-bg-0);
+  color: var(--ds-color-font-0);
+  border-bottom: 1px solid var(--ds-color-bw-1);
+  font-family: var(--ds-font-body);
+}
+
+.ds-header__inner {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: var(--ds-space-4) var(--ds-space-6);
+  display: flex;
+  align-items: center;
+  gap: var(--ds-space-6);
+}
+
+.ds-header__brand {
+  display: flex;
+  align-items: center;
+  color: var(--ds-color-font-0);
+  text-decoration: none;
+  font-weight: var(--ds-font-weight-bold);
+  font-size: var(--ds-font-size-300);
+  letter-spacing: 0.02em;
+}
+
+.ds-header__nav {
+  flex: 1;
+}
+
+.ds-header__actions {
+  display: flex;
+  align-items: center;
+  gap: var(--ds-space-3);
+  margin-left: auto;
+}
+
+@media (width <= 480px) {
+  .ds-header__inner {
+    padding: var(--ds-space-3) var(--ds-space-4);
+    gap: var(--ds-space-4);
+  }
+
+  .ds-header__brand {
+    font-size: var(--ds-font-size-200);
+  }
+}

package/src/components/Header/Header.jsx

@@ -0,0 +1,30 @@
+import { Link } from "react-router-dom";
+import { Nav } from "../Nav/Nav.jsx";
+import "./Header.css";
+
+/**
+ * Generic header shell with brand/nav/actions slots, so each site's
+ * bespoke chrome (song-chart's auth-aware menu + fullscreen toggle,
+ * mattwelker.com's audio-loop toggle + Venmo link, 5voltfx.com's plain
+ * logo-with-text-fallback) stays app-specific and is passed in rather
+ * than encoded into this component.
+ */
+export function Header({
+  brand,
+  brandHref = "/",
+  links = [],
+  actions,
+  className = "",
+}) {
+  return (
+    <header className={["ds-header", className].filter(Boolean).join(" ")}>
+      <div className="ds-header__inner">
+        <Link to={brandHref} className="ds-header__brand">
+          {brand}
+        </Link>
+        {links.length > 0 && <Nav links={links} className="ds-header__nav" />}
+        {actions && <div className="ds-header__actions">{actions}</div>}
+      </div>
+    </header>
+  );
+}

package/src/components/Header/index.js

@@ -0,0 +1 @@
+export { Header } from "./Header.jsx";

package/src/components/Layout/Container.jsx

@@ -0,0 +1,10 @@
+import "./Layout.css";
+
+export function Container({ as: Component = "div", className = "", ...rest }) {
+  return (
+    <Component
+      className={["ds-container", className].filter(Boolean).join(" ")}
+      {...rest}
+    />
+  );
+}

package/src/components/Layout/Grid.jsx

@@ -0,0 +1,22 @@
+import "./Layout.css";
+
+export function Grid({
+  as: Component = "div",
+  columns = 2,
+  gap = "4",
+  className = "",
+  style,
+  ...rest
+}) {
+  return (
+    <Component
+      className={["ds-grid", className].filter(Boolean).join(" ")}
+      style={{
+        gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+        gap: `var(--ds-space-${gap})`,
+        ...style,
+      }}
+      {...rest}
+    />
+  );
+}

package/src/components/Layout/Layout.css

@@ -0,0 +1,26 @@
+.ds-container {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 0 var(--ds-space-6);
+}
+
+@media (width <= 660px) {
+  .ds-container {
+    padding: 0 var(--ds-space-4);
+  }
+}
+
+.ds-stack {
+  display: flex;
+  gap: var(--ds-stack-gap, var(--ds-space-4));
+}
+
+.ds-grid {
+  display: grid;
+}
+
+@media (width <= 660px) {
+  .ds-grid {
+    grid-template-columns: 1fr !important;
+  }
+}

package/src/components/Layout/Stack.jsx

@@ -0,0 +1,24 @@
+import "./Layout.css";
+
+export function Stack({
+  as: Component = "div",
+  gap = "4",
+  direction = "column",
+  align,
+  className = "",
+  style,
+  ...rest
+}) {
+  return (
+    <Component
+      className={["ds-stack", className].filter(Boolean).join(" ")}
+      style={{
+        "--ds-stack-gap": `var(--ds-space-${gap})`,
+        flexDirection: direction,
+        alignItems: align,
+        ...style,
+      }}
+      {...rest}
+    />
+  );
+}

package/src/components/Layout/index.js

@@ -0,0 +1,3 @@
+export { Container } from "./Container.jsx";
+export { Stack } from "./Stack.jsx";
+export { Grid } from "./Grid.jsx";

package/src/components/Nav/Nav.css

@@ -0,0 +1,61 @@
+.ds-nav__list {
+  display: flex;
+  align-items: center;
+  gap: var(--ds-space-5);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.ds-nav__link {
+  position: relative;
+  display: inline-block;
+  padding: var(--ds-space-2) 0;
+  color: var(--ds-color-font-1);
+  font-family: var(--ds-font-body);
+  font-weight: var(--ds-font-weight-medium);
+  font-size: var(--ds-font-size-100);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  text-decoration: none;
+  transition: color var(--ds-motion-duration-base) var(--ds-motion-ease-standard);
+}
+
+.ds-nav__link::after {
+  content: "";
+  position: absolute;
+  left: 0;
+  bottom: -2px;
+  width: 100%;
+  height: 2px;
+  background-color: var(--ds-color-bg-2);
+  transform: scaleX(0);
+  transform-origin: left;
+  transition: transform var(--ds-motion-duration-base) var(--ds-motion-ease-standard);
+}
+
+.ds-nav__link:hover {
+  color: var(--ds-color-font-0);
+}
+
+.ds-nav__link:hover::after {
+  transform: scaleX(1);
+}
+
+.ds-nav__link--active {
+  color: var(--ds-color-font-0);
+}
+
+.ds-nav__link--active::after {
+  transform: scaleX(1);
+}
+
+@media (width <= 660px) {
+  .ds-nav__list {
+    gap: var(--ds-space-3);
+  }
+
+  .ds-nav__link {
+    font-size: 0.75rem;
+  }
+}

package/src/components/Nav/Nav.jsx

@@ -0,0 +1,29 @@
+import { NavLink } from "react-router-dom";
+import "./Nav.css";
+
+/**
+ * Generic nav-links list. Generalizes 5voltfx.com's Navbar.jsx (active
+ * underline via NavLink), song-chart's SiteHeader nav, and mattwelker.com's
+ * PageNav link list into one component driven by a `links` array.
+ */
+export function Nav({ links = [], className = "" }) {
+  return (
+    <nav className={["ds-nav", className].filter(Boolean).join(" ")}>
+      <ul className="ds-nav__list">
+        {links.map((link) => (
+          <li key={link.to}>
+            <NavLink
+              to={link.to}
+              end={link.end}
+              className={({ isActive }) =>
+                "ds-nav__link" + (isActive ? " ds-nav__link--active" : "")
+              }
+            >
+              {link.label}
+            </NavLink>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}

package/src/components/Nav/index.js

@@ -0,0 +1 @@
+export { Nav } from "./Nav.jsx";

package/src/components/ThemeSwitcher/ThemeSwitcher.css

@@ -0,0 +1,30 @@
+.ds-theme-switcher {
+  display: flex;
+  align-items: center;
+  gap: var(--ds-space-2);
+}
+
+.ds-theme-switcher__swatch {
+  width: 20px;
+  height: 20px;
+  border-radius: var(--ds-radius-pill);
+  border: 2px solid transparent;
+  cursor: pointer;
+  padding: 0;
+  transition:
+    transform var(--ds-motion-duration-fast) var(--ds-motion-ease-standard),
+    border-color var(--ds-motion-duration-base) var(--ds-motion-ease-standard);
+}
+
+.ds-theme-switcher__swatch:hover {
+  transform: scale(1.15);
+}
+
+.ds-theme-switcher__swatch--active {
+  border-color: var(--ds-color-font-0);
+}
+
+.ds-theme-switcher__swatch:focus-visible {
+  outline: 2px solid var(--ds-color-bg-2);
+  outline-offset: 2px;
+}

package/src/components/ThemeSwitcher/ThemeSwitcher.jsx

@@ -0,0 +1,26 @@
+import { useTheme } from "../../theme/useTheme.js";
+import "./ThemeSwitcher.css";
+
+export function ThemeSwitcher({ className = "" }) {
+  const { theme, setTheme, themes } = useTheme();
+
+  return (
+    <div className={["ds-theme-switcher", className].filter(Boolean).join(" ")}>
+      {themes.map((option) => (
+        <button
+          key={option.id}
+          type="button"
+          className={
+            "ds-theme-switcher__swatch" +
+            (option.id === theme ? " ds-theme-switcher__swatch--active" : "")
+          }
+          style={{ backgroundColor: option.swatch }}
+          aria-label={option.label}
+          aria-pressed={option.id === theme}
+          title={option.label}
+          onClick={() => setTheme(option.id)}
+        />
+      ))}
+    </div>
+  );
+}

package/src/components/ThemeSwitcher/index.js

@@ -0,0 +1 @@
+export { ThemeSwitcher } from "./ThemeSwitcher.jsx";

package/src/components/Typography/Heading.jsx

@@ -0,0 +1,29 @@
+import "./Typography.css";
+
+const SCALE_BY_LEVEL = { 1: "700", 2: "600", 3: "500", 4: "400", 5: "300", 6: "200" };
+
+export function Heading({
+  level = 1,
+  size,
+  decorative = false,
+  className = "",
+  children,
+  ...rest
+}) {
+  const Component = `h${level}`;
+  const scale = size ?? SCALE_BY_LEVEL[level] ?? "300";
+  const classes = [
+    "ds-heading",
+    `ds-heading--${scale}`,
+    decorative ? "ds-heading--decorative" : "",
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <Component className={classes} {...rest}>
+      {children}
+    </Component>
+  );
+}

package/src/components/Typography/Text.jsx

@@ -0,0 +1,20 @@
+import "./Typography.css";
+
+export function Text({
+  as: Component = "p",
+  size = "200",
+  tone = "default",
+  className = "",
+  children,
+  ...rest
+}) {
+  const classes = ["ds-text", `ds-text--${size}`, `ds-text--${tone}`, className]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <Component className={classes} {...rest}>
+      {children}
+    </Component>
+  );
+}

package/src/components/Typography/Typography.css

@@ -0,0 +1,35 @@
+.ds-heading {
+  margin: 0;
+  font-family: var(--ds-font-body);
+  font-weight: var(--ds-font-weight-bold);
+  line-height: var(--ds-line-height-tight);
+  color: var(--ds-color-font-0);
+}
+
+.ds-heading--decorative {
+  font-family: var(--ds-font-decorative);
+  font-weight: var(--ds-font-weight-regular);
+}
+
+.ds-heading--700 { font-size: var(--ds-font-size-700); }
+.ds-heading--600 { font-size: var(--ds-font-size-600); }
+.ds-heading--500 { font-size: var(--ds-font-size-500); }
+.ds-heading--400 { font-size: var(--ds-font-size-400); }
+.ds-heading--300 { font-size: var(--ds-font-size-300); }
+.ds-heading--200 { font-size: var(--ds-font-size-200); }
+
+.ds-text {
+  margin: 0;
+  font-family: var(--ds-font-body);
+  font-weight: var(--ds-font-weight-regular);
+  line-height: var(--ds-line-height-normal);
+  color: var(--ds-color-font-0);
+}
+
+.ds-text--100 { font-size: var(--ds-font-size-100); }
+.ds-text--200 { font-size: var(--ds-font-size-200); }
+.ds-text--300 { font-size: var(--ds-font-size-300); }
+
+.ds-text--muted {
+  color: var(--ds-color-font-1);
+}

package/src/components/Typography/index.js

@@ -0,0 +1,2 @@
+export { Heading } from "./Heading.jsx";
+export { Text } from "./Text.jsx";

package/src/index.js

@@ -0,0 +1,12 @@
+export { ThemeProvider } from "./theme/ThemeProvider.jsx";
+export { useTheme } from "./theme/useTheme.js";
+export { THEMES, THEME_IDS, DEFAULT_THEME } from "./theme/themeConstants.js";
+
+export { Button } from "./components/Button/index.js";
+export { Card } from "./components/Card/index.js";
+export { Header } from "./components/Header/index.js";
+export { Nav } from "./components/Nav/index.js";
+export { Footer } from "./components/Footer/index.js";
+export { ThemeSwitcher } from "./components/ThemeSwitcher/index.js";
+export { Heading, Text } from "./components/Typography/index.js";
+export { Container, Stack, Grid } from "./components/Layout/index.js";

package/src/theme/ThemeContext.js

@@ -0,0 +1,3 @@
+import { createContext } from "react";
+
+export const ThemeContext = createContext(null);

package/src/theme/ThemeProvider.jsx

@@ -0,0 +1,66 @@
+import { useCallback, useLayoutEffect, useMemo, useState } from "react";
+import { ThemeContext } from "./ThemeContext.js";
+import { THEMES, THEME_IDS, DEFAULT_THEME } from "./themeConstants.js";
+
+function readStoredTheme(storageKey, fallback) {
+  if (typeof window === "undefined") return fallback;
+  try {
+    const stored = window.localStorage.getItem(storageKey);
+    return THEME_IDS.includes(stored) ? stored : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * data-theme lives on <html> rather than a class or a wrapper div so every
+ * consuming site (song-chart used a class on <html>, mattwelker.com used a
+ * class on a wrapper div) lands on one shared convention.
+ */
+export function ThemeProvider({
+  children,
+  storageKey = "ds.theme",
+  defaultTheme = DEFAULT_THEME,
+  onThemeChange,
+}) {
+  const [theme, setThemeState] = useState(() =>
+    readStoredTheme(storageKey, defaultTheme)
+  );
+
+  useLayoutEffect(() => {
+    document.documentElement.setAttribute("data-theme", theme);
+    try {
+      window.localStorage.setItem(storageKey, theme);
+    } catch {
+      // localStorage unavailable (private browsing, etc.) — theme still applies for this session
+    }
+  }, [theme, storageKey]);
+
+  useLayoutEffect(() => {
+    function handleStorage(event) {
+      if (event.key === storageKey && THEME_IDS.includes(event.newValue)) {
+        setThemeState(event.newValue);
+      }
+    }
+    window.addEventListener("storage", handleStorage);
+    return () => window.removeEventListener("storage", handleStorage);
+  }, [storageKey]);
+
+  const setTheme = useCallback(
+    (id) => {
+      if (!THEME_IDS.includes(id)) return;
+      setThemeState(id);
+      onThemeChange?.(id);
+    },
+    [onThemeChange]
+  );
+
+  const value = useMemo(
+    () => ({ theme, setTheme, themes: THEMES }),
+    [theme, setTheme]
+  );
+
+  return (
+    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+  );
+}

package/src/theme/themeConstants.js

@@ -0,0 +1,12 @@
+export const THEMES = [
+  { id: "coral", label: "Coral — creative warm", swatch: "#ff6b6b" },
+  { id: "ink", label: "Ink — dark indigo", swatch: "#6366f1" },
+  { id: "sage", label: "Sage — muted olive", swatch: "#6b7568" },
+  { id: "midnight", label: "Midnight — high contrast", swatch: "#00d4ff" },
+  { id: "amber", label: "Amber — golden", swatch: "#b8652a" },
+  { id: "harvest", label: "Harvest — earthy warm", swatch: "#9f5508" },
+];
+
+export const THEME_IDS = THEMES.map((theme) => theme.id);
+
+export const DEFAULT_THEME = "coral";

package/src/theme/useTheme.js

@@ -0,0 +1,10 @@
+import { useContext } from "react";
+import { ThemeContext } from "./ThemeContext.js";
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return context;
+}

package/src/tokens/base.css

@@ -0,0 +1,21 @@
+/*
+  Every theme pairs bg-0 (page surface) with font-0 (on-surface text) —
+  without this, the page background stays the browser default (white) while
+  text/components assume a themed surface behind them, e.g. font-0 is
+  near-white in every theme because it's meant to sit on the dark bg-0.
+*/
+html,
+body {
+  background-color: var(--ds-color-bg-0);
+  color: var(--ds-color-font-0);
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  font-family: var(--ds-font-body);
+}
+
+* {
+  box-sizing: border-box;
+}

package/src/tokens/colors.css

@@ -0,0 +1,29 @@
+/*
+  Base color token shape. Every theme in themes.css overrides this full set
+  via [data-theme="<id>"]. These :root values are the default (coral) theme,
+  so components render sensibly even before ThemeProvider sets data-theme.
+*/
+:root {
+  --ds-color-url: #ff8787;
+  --ds-color-visited: #ffb4a2;
+
+  --ds-color-bg-0: #1a2f2f;
+  --ds-color-bg-1: #2d4a4a;
+  --ds-color-bg-2: #ff6b6b;
+  --ds-color-bg-3: #5c8a8a;
+  --ds-color-bg-4: #f7f0eb;
+
+  --ds-color-font-0: #fff5f0;
+  --ds-color-font-1: #ffb4a2;
+  --ds-color-font-2: #ff6b6b;
+  --ds-color-font-3: #2d4a4a;
+  --ds-color-font-4: #1a2f2f;
+
+  --ds-color-bw-0: #142424;
+  --ds-color-bw-1: #2d4a4a;
+  --ds-color-bw-2: #5c8a8a;
+  --ds-color-bw-3: #c5d5d5;
+  --ds-color-bw-4: #fff;
+
+  --ds-color-highlight: #7c3aed;
+}

package/src/tokens/elevation.css

@@ -0,0 +1,10 @@
+/*
+  Shadows are tinted with the active theme's accent (--ds-color-bg-2) at low
+  opacity rather than flat black, since none of the 3 sites uses any shadow
+  today and a flat-black shadow would read as generic rather than "on-brand".
+*/
+:root {
+  --ds-shadow-sm: 0 1px 3px color-mix(in srgb, var(--ds-color-bg-2) 18%, transparent);
+  --ds-shadow-md: 0 6px 16px color-mix(in srgb, var(--ds-color-bg-2) 20%, transparent);
+  --ds-shadow-lg: 0 16px 40px color-mix(in srgb, var(--ds-color-bg-2) 24%, transparent);
+}

package/src/tokens/index.css

@@ -0,0 +1,8 @@
+@import "./colors.css";
+@import "./themes.css";
+@import "./base.css";
+@import "./typography.css";
+@import "./spacing.css";
+@import "./radius.css";
+@import "./elevation.css";
+@import "./motion.css";

package/src/tokens/motion.css

@@ -0,0 +1,6 @@
+:root {
+  --ds-motion-duration-fast: 120ms;
+  --ds-motion-duration-base: 200ms;
+  --ds-motion-duration-slow: 320ms;
+  --ds-motion-ease-standard: cubic-bezier(0.2, 0, 0, 1);
+}

package/src/tokens/radius.css

@@ -0,0 +1,6 @@
+:root {
+  --ds-radius-sm: 6px;
+  --ds-radius-md: 10px;
+  --ds-radius-lg: 16px;
+  --ds-radius-pill: 999px;
+}

package/src/tokens/spacing.css

@@ -0,0 +1,10 @@
+:root {
+  --ds-space-1: 0.25rem;
+  --ds-space-2: 0.5rem;
+  --ds-space-3: 0.75rem;
+  --ds-space-4: 1rem;
+  --ds-space-5: 1.5rem;
+  --ds-space-6: 2rem;
+  --ds-space-7: 3rem;
+  --ds-space-8: 4rem;
+}

package/src/tokens/themes.css

@@ -0,0 +1,156 @@
+/*
+  Canonical theme set. Carries song-chart's 5 themes forward near-verbatim
+  (ink, sage, coral, midnight, amber) plus one new "harvest" theme
+  consolidating mattwelker.com's warm/retro/cirro family into a single palette.
+  Applied via ThemeProvider setting data-theme="<id>" on <html>.
+*/
+
+[data-theme="ink"] {
+  --ds-color-url: #818cf8;
+  --ds-color-visited: #a5b4fc;
+
+  --ds-color-bg-0: #0d0f14;
+  --ds-color-bg-1: #1a1f2e;
+  --ds-color-bg-2: #6366f1;
+  --ds-color-bg-3: #2d3348;
+  --ds-color-bg-4: #384260;
+
+  --ds-color-font-0: #ffffff;
+  --ds-color-font-1: #9aa8d4;
+  --ds-color-font-2: #818cf8;
+  --ds-color-font-3: #c5cce8;
+  --ds-color-font-4: #f0f2ff;
+
+  --ds-color-bw-0: #000;
+  --ds-color-bw-1: #1e2230;
+  --ds-color-bw-2: #4a5068;
+  --ds-color-bw-3: #5a6380;
+  --ds-color-bw-4: #fff;
+
+  --ds-color-highlight: #fbbf24;
+}
+
+[data-theme="sage"] {
+  --ds-color-url: #7a8578;
+  --ds-color-visited: #8a9388;
+
+  --ds-color-bg-0: #3a3f38;
+  --ds-color-bg-1: #4a5248;
+  --ds-color-bg-2: #6b7568;
+  --ds-color-bg-3: #9aa392;
+  --ds-color-bg-4: #d4d8d0;
+
+  --ds-color-font-0: #e8ebe6;
+  --ds-color-font-1: #c5cbc0;
+  --ds-color-font-2: #6b7568;
+  --ds-color-font-3: #5c6359;
+  --ds-color-font-4: #3a3f38;
+
+  --ds-color-bw-0: #323632;
+  --ds-color-bw-1: #4a5248;
+  --ds-color-bw-2: #6b7568;
+  --ds-color-bw-3: #9aa392;
+  --ds-color-bw-4: #e8ebe6;
+
+  --ds-color-highlight: #6b4c9a;
+}
+
+[data-theme="coral"] {
+  --ds-color-url: #ff8787;
+  --ds-color-visited: #ffb4a2;
+
+  --ds-color-bg-0: #1a2f2f;
+  --ds-color-bg-1: #2d4a4a;
+  --ds-color-bg-2: #ff6b6b;
+  --ds-color-bg-3: #5c8a8a;
+  --ds-color-bg-4: #f7f0eb;
+
+  --ds-color-font-0: #fff5f0;
+  --ds-color-font-1: #ffb4a2;
+  --ds-color-font-2: #ff6b6b;
+  --ds-color-font-3: #2d4a4a;
+  --ds-color-font-4: #1a2f2f;
+
+  --ds-color-bw-0: #142424;
+  --ds-color-bw-1: #2d4a4a;
+  --ds-color-bw-2: #5c8a8a;
+  --ds-color-bw-3: #c5d5d5;
+  --ds-color-bw-4: #fff;
+
+  --ds-color-highlight: #7c3aed;
+}
+
+[data-theme="midnight"] {
+  --ds-color-url: #0099cc;
+  --ds-color-visited: #007aa3;
+
+  --ds-color-bg-0: #000000;
+  --ds-color-bg-1: #111111;
+  --ds-color-bg-2: #00d4ff;
+  --ds-color-bg-3: #ececec;
+  --ds-color-bg-4: #ffffff;
+
+  --ds-color-font-0: #ffffff;
+  --ds-color-font-1: #555555;
+  --ds-color-font-2: #007799;
+  --ds-color-font-3: #333333;
+  --ds-color-font-4: #000000;
+
+  --ds-color-bw-0: #000;
+  --ds-color-bw-1: #222;
+  --ds-color-bw-2: #666;
+  --ds-color-bw-3: #bbb;
+  --ds-color-bw-4: #fff;
+
+  --ds-color-highlight: #ff6600;
+}
+
+[data-theme="amber"] {
+  --ds-color-url: #a0522d;
+  --ds-color-visited: #8b4513;
+
+  --ds-color-bg-0: #1a1510;
+  --ds-color-bg-1: #2c2218;
+  --ds-color-bg-2: #b8652a;
+  --ds-color-bg-3: #d9cbb0;
+  --ds-color-bg-4: #f5efe3;
+
+  --ds-color-font-0: #faf6ef;
+  --ds-color-font-1: #6b5344;
+  --ds-color-font-2: #8b6914;
+  --ds-color-font-3: #4a3d30;
+  --ds-color-font-4: #1a1510;
+
+  --ds-color-bw-0: #100c08;
+  --ds-color-bw-1: #3d2e1f;
+  --ds-color-bw-2: #6b5344;
+  --ds-color-bw-3: #b8a088;
+  --ds-color-bw-4: #fff;
+
+  --ds-color-highlight: #1d4ed8;
+}
+
+[data-theme="harvest"] {
+  --ds-color-url: #f4230c;
+  --ds-color-visited: #9bb4e2;
+
+  --ds-color-bg-0: #005558;
+  --ds-color-bg-1: #684022;
+  --ds-color-bg-2: #9f5508;
+  --ds-color-bg-3: #decebd;
+  --ds-color-bg-4: #fdf7e3;
+
+  --ds-color-font-0: #fdf7e3;
+  --ds-color-font-1: #decebd;
+  --ds-color-font-2: #9f5508;
+  --ds-color-font-3: #684022;
+  --ds-color-font-4: #005558;
+
+  --ds-color-bw-0: #000;
+  --ds-color-bw-1: #333;
+  --ds-color-bw-2: #666;
+  --ds-color-bw-3: #ccc;
+  --ds-color-bw-4: #fff;
+
+  --ds-color-highlight: #f4230c;
+}

package/src/tokens/typography.css

@@ -0,0 +1,29 @@
+/*
+  Shared type scale. Space Grotesk is already used by song-chart and
+  mattwelker.com; consuming apps must load the Google Fonts <link> themselves
+  (this package doesn't inject font-loading side effects). Pangolin is kept
+  as an optional decorative token for mattwelker.com's setlist page only.
+*/
+:root {
+  --ds-font-body: "Space Grotesk", system-ui, -apple-system, "Segoe UI", Roboto,
+    Helvetica, Arial, sans-serif;
+  --ds-font-decorative: "Pangolin", cursive;
+
+  --ds-font-weight-regular: 400;
+  --ds-font-weight-medium: 500;
+  --ds-font-weight-semibold: 600;
+  --ds-font-weight-bold: 700;
+
+  --ds-line-height-tight: 1.15;
+  --ds-line-height-normal: 1.5;
+  --ds-line-height-relaxed: 1.7;
+
+  /* modular scale, ~1.25 ratio, base 1rem */
+  --ds-font-size-100: 0.8rem;
+  --ds-font-size-200: 1rem;
+  --ds-font-size-300: 1.25rem;
+  --ds-font-size-400: 1.563rem;
+  --ds-font-size-500: 1.953rem;
+  --ds-font-size-600: 2.441rem;
+  --ds-font-size-700: 3.052rem;
+}

package/vite-plugin.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+const designSystemSrc = path.join(packageRoot, "src");
+
+/**
+ * Vite only watches files inside the consuming project's root by default, so
+ * edits made through the symlinked file: dependency (which lives outside
+ * that root) are invisible to HMR no matter what `server.watch.ignored`
+ * patterns say. This plugin explicitly adds the design system's real source
+ * directory to the watcher and forces a full reload when anything in it
+ * changes. Add it to every site's vite.config.js alongside the file:
+ * dependency on @5voltfx/design-system.
+ */
+export function watchDesignSystem() {
+  return {
+    name: "watch-design-system",
+    configureServer(server) {
+      server.watcher.add(designSystemSrc);
+      server.watcher.on("change", (file) => {
+        if (file.startsWith(designSystemSrc)) {
+          server.ws.send({ type: "full-reload" });
+        }
+      });
+    },
+  };
+}
+
+export const DESIGN_SYSTEM_SRC = designSystemSrc;