design_system

Yamato Zhen's personal design system for Next.js App Router projects: the Nav navigation system, shared layout components, theme palettes, and the globals.css/layout.tsx overrides that make them work.

See USAGE.md in the source site for the full architecture writeup (which files are critical, how Nav.* is composed, known open items). This README only covers installing and wiring the package into a new project.

Install

npm install yamatozhen/design_system

Note: npm's GitHub-shorthand installer (owner/repo) does not support an @latest suffix the way registry packages do — owner/repo@latest is silently not recognized as a git spec and npm will instead try (and fail) to resolve it against the public registry. The bare form above always installs the current default-branch HEAD, which is the closest equivalent. To pin/update to a specific tagged version instead, use npm install yamatozhen/design_system#v1.0.0 or a range like npm install yamatozhen/design_system#semver:^1.0.0 (matches git tags). If you want real @latest dist-tag semantics, publish this package to the npm registry under a scope (e.g. @yamatozhen/design_system) instead of installing straight from GitHub.

This installs straight from the GitHub repo (no npm registry publish required) and its postinstall script automatically copies the package contents into your project:

| Copied to | Behavior on install | | ----------------------------- | ------------------------------------------------------ | | app/components/ (top-level) | Merged in — existing files of the same name are kept, never overwritten. | | app/themes/ | Merged in the same way. | | public/fonts/material-symbols/ | Merged in the same way (icon font used by globals.css). | | app/globals.css | Replaced. Your previous file is saved as globals.css.bak. | | app/layout.tsx | Replaced. Your previous file is saved as layout.tsx.bak. | | app/ClientNav.tsx | Replaced. Your previous file is saved as ClientNav.tsx.bak. |

(If your project uses src/app instead of app, the script detects that and copies there instead.)

Prerequisites

• Next.js App Router (v15+), React 19+.
• Tailwind CSS v4 — globals.css starts with @import "tailwindcss";.
• A @/* path alias pointing at the project root in tsconfig.json:

  { "compilerOptions": { "paths": { "@/*": ["./*"] } } }

  The copied components import each other via @/components/..., so without this alias they won't resolve.
• Peer dependencies (declared in package.json, install if missing): framer-motion, @fontsource/outfit, colorthief (used by the hero slideshow and useImageColor), flubber (used by ShapeMorph — note it has no bundled types, so a hand-written components/tools/flubber.d.ts ships alongside it, don't delete that file).

After installing

1. Run npm install again if npm reports missing peer deps (framer-motion, @fontsource/outfit, tailwindcss).
2. Open app/layout.tsx and replace the site-specific bits that were copied verbatim:
   • <title> / metadata / Open Graph & Twitter meta tags.
   • Favicon links (/favicon.png, /apple-touch-icon.png) — supply your own files in public/.
3. Open app/ClientNav.tsx and replace the logo images (HeaderLogo, referencing /Yamato.svg and /Zhen C.svg) and the NAV_ITEMS list with your own site's nav entries.
4. If you don't like the generated theme palettes in app/themes/, you can hand-author replacements — keep the file names identical (theme.css, light.css, dark.css, light-mc.css, dark-mc.css), since globals.css imports them by literal path.
5. npm run dev and confirm the nav renders (Nav.Rail/Nav.Bar/Nav.Header depending on viewport) and the accessibility modal opens.

What's inside template/

This mirrors what actually gets copied — it's not itself a runnable app:

template/
├─ components/          # full components/layout + components/tools tree
├─ app/
│  ├─ themes/            # theme.css, light.css, dark.css, light-mc.css, dark-mc.css
│  ├─ globals.css
│  ├─ layout.tsx
│  └─ ClientNav.tsx
└─ public/fonts/material-symbols/   # icon font referenced by globals.css

Updating the package

This repo is meant to be re-synced from yamatozhen.com whenever the source components change — there's no build step, template/ is a straight copy. Bump the version in package.json and tag a release so npm install yamatozhen/design_system@latest picks up the new commit.