hero-site-method

Hero Site Method

The proven architecture for a personal "hero" website: a fast, statically generated, editorial showcase that is a pure function of typed content. This skill is the source of truth for how a generated site is structured. The /hero command orchestrates the flow; this skill governs the build.

Non-negotiable stack

• Next.js 15 (App Router) + React 19, TypeScript, fully statically generated (SSG).
• No backend, no database, no CMS. All content lives in typed data files.
• Tailwind CSS v4, CSS-first config: @import "tailwindcss" + a @theme {} block in app/globals.css. No tailwind.config.js.
• Fonts via next/font/google, exposed as CSS variables (a display, a body, a mono).
• @/* path alias → project root (tsconfig.json).
• Vitest unit tests for the pure logic (filtering/sorting + any link helpers), not the UI.
• Minimal deps: next, react, react-dom; devDeps @tailwindcss/postcss, tailwindcss, types, typescript, vitest. Add nothing else unless strictly necessary.

Per the user's global rules: before writing code against Next.js / React / Tailwind APIs, pull current docs via Context7 (resolve-library-id → get-library-docs). Do not rely on memorized framework APIs — these versions move.

The core idea: content-as-typed-data

Every fact lives in /content/*.ts behind interfaces in content/types.ts. The UI is a pure function of that data. To reuse the site for a different person you swap the data, not the components. Never hard-code a person's facts into a component.

app/
  layout.tsx          # fonts, <Nav>, <Footer>, base metadata, Person JSON-LD, theme class
  page.tsx            # home: hero, stat band, section highlights
  <section>/page.tsx  # one route per selected section (publications, projects, etc.)
  globals.css         # @import tailwindcss + @theme tokens + base/components layers
  sitemap.ts robots.ts
components/            # presentational; *List components are "use client" (own filter state)
content/
  types.ts            # all interfaces + any closed enums (e.g. expertise AREAS)
  site.ts             # name, role, bio, bioLong[], contact, stats, etc.
  theme.ts            # the CHOSEN design tokens (written by the design selector)
  <collection>.ts     # publications/patents/projects/talks/awards/experience as data
lib/
  filter.ts           # pure filterAndSort + DEFAULT_FILTER + availableDecades + SortKey

See templates/ in this skill for concrete reference files to adapt (do not copy a person's data — copy the shapes and patterns).

Design system (theme-swappable)

A "look" is expressed entirely as CSS-variable tokens in @theme plus a font trio. This is what makes the live design selector cheap — switching looks is swapping variable values, never a structural change. The chosen theme is written to content/theme.ts and applied in layout.tsx.

Conventions that keep generated sites from looking generic:

• A restrained, cohesive palette (paper/ink/muted/line/card + one accent + accent-soft/deep).
• A display serif or characterful sans for headings, a clean body sans, a mono for small uppercase eyebrows/labels and index numbers.
• Optional signature treatments: subtle SVG grain overlay, .reveal entrance animation, underline-on-hover, accent ::selection and :focus-visible.
• Always include a prefers-reduced-motion reset and a sensible max content width.

Client-side filtering for large collections

When a section holds many items (publications, patents, projects), provide search + faceted filtering + sorting via a single pure filterAndSort over the static data. Include a "listed" sort that preserves source-file order (comparator returns 0) so order can be hand-curated in the data file. Unit-test this function.

SEO + anti-scraping (always)

• Per-page metadata (title, description from the bio, Open Graph, canonical from site.url).
• JSON-LD: a Person schema in the root layout; persona-appropriate ItemList (e.g. ScholarlyArticle for publications) where relevant.
• app/sitemap.ts and app/robots.ts.
• Email obfuscation: never emit the contact email as plaintext. Encode it base64 server-side, decode with atob in a useEffect on mount in a small client EmailLink component, and show a non-clickable fallback (e.g. " [at] " form) before hydration.

Honesty rules

• Never fabricate credentials, dates, links, or counts. Mark unknowns TBD and confirm before deploy.
• Where an exact count understates reality (patent families vs. total filings), prefer a literal headline stat (e.g. "100+") in site.ts over a misleading computed number.

Verification before "done"

npm run build AND npm run test (vitest) must pass — run them and show the output before claiming the site is ready. Evidence before assertions.

How this composes

• hero-content-intake skill → fills the content/*.ts files from the person's material.
• section-presets (in presets/) → decides which sections/collections exist.
• hero-design-system skill + the design selector → produce and lock content/theme.ts.
• /hero-deploy → ships it to Vercel + a Hover domain.