portfolio-template (Nuu-maan) — Next.js 作品集模板

SHA-256: d0ecd6c01362289c292f026ac8ba8075c841409cf296c366affc6e695206823e

2026-10-14T17:10:48.737Z

<div align="center">

<img src="assets/banner.svg" alt="Portfolio Template — y2k cute animated banner" width="100%"/>

# ⌘ portfolio-template

**A loud, cute, Y2K-flavored personal-portfolio template.**
Five full-viewport sections, original SVG mascots, scroll-linked parallax — and one config file you edit to make it yours.

[![License: MIT](https://img.shields.io/badge/license-MIT-ffd24c?style=flat-square&labelColor=1a1a2e)](LICENSE)
[![Next.js](https://img.shields.io/badge/next.js-16-1a1a2e?style=flat-square&labelColor=ff6f9c)](https://nextjs.org)
[![React](https://img.shields.io/badge/react-19-1a1a2e?style=flat-square&labelColor=b9d8ff)](https://react.dev)
[![Tailwind](https://img.shields.io/badge/tailwind-v4-1a1a2e?style=flat-square&labelColor=cdb6ff)](https://tailwindcss.com)
[![Motion](https://img.shields.io/badge/motion-11-1a1a2e?style=flat-square&labelColor=fff6e3)](https://motion.dev)

</div>

---

## ✨ what's inside

- 🎨 **5 dense, full-viewport sections** — Hero, Stack, Principles, Featured Work, Contact
- 🐣 **Original SVG mascots** drawn from scratch — no clipart, no Lottie payloads
- 🌊 **Scroll-linked parallax** + reveal animations powered by [`motion`](https://motion.dev)
- 🌈 **Stripe-shadow chunky text**, halftone & checker patterns, sticker drop-shadows
- 🪟 **Retro browser-window chrome** for project tiles
- 📱 **Responsive** — `clamp()` titles, mobile-first character counts, `prefers-reduced-motion` honored
- 📦 **One config file** holds every piece of editable copy & data (`portfolio.config.ts`)
- 🚀 Built on **Next.js 16 App Router**, **React 19**, **Tailwind v4**, **TypeScript strict**

---

## 🚀 getting started

```bash
git clone https://github.com/Nuu-maan/portfolio-template.git my-portfolio
cd my-portfolio
npm install
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) — refresh on save, no rebuild needed.

```bash
npm run build   # production build
npm run start   # serve the build
npm run lint    # lint with eslint
```

---

## 🎀 make it yours

**Open [`portfolio.config.ts`](portfolio.config.ts) at the repo root.** Everything the site shows lives there:

```ts
export const config: PortfolioConfig = {
  identity: {
    name: "NUMAN",              // huge hero wordmark
    fullName: "Numan Khan",     // metadata + footer
    role: "Full Stack Developer",
    tagline: "FULL STACK × SHIPS FAST",
    bio: "Self-taught full-stack developer...",
    location: "New Delhi, India",
    timezone: "IST · UTC+5:30",
    availability: "OPEN TO WORK",
  },

  social: {
    email: "[email protected]",
    githubHandle: "yourhandle",
    githubUrl: "https://github.com/yourhandle",
    // ...
  },

  stack: {
    languages: ["Python", "TypeScript", "Rust", "C++", "SQL · Bash"],
    chips: {
      Frontend: ["React", "Next.js", "Tailwind"],
      Backend:  ["Node", "FastAPI"],
      // ...
    },
  },

  principles: [ /* sticker cards on "How I Work" */ ],
  services:   [ /* what you build */ ],
  projects:   [ /* the 6 tiles on Featured Work */ ],
  marquees:   { stack: [...], work: [...], contact: [...] },
  copy:       { /* every section heading + blurb */ },
};
```

Save the file → the dev server hot-reloads → the whole site re-skins.

### swap colors

Brand colors are CSS custom properties in [`src/app/globals.css`](src/app/globals.css):

```css
:root {
  --pink-hero: #ff6f9c;
  --blue-sky:  #b9d8ff;
  --lavender:  #cdb6ff;
  --yellow-sun:#ffd24c;
  --ink:       #1a1a2e;
  --cream:     #fff6e3;
  /* ... */
}
```

Change a value, every section that uses that token shifts together.

### swap mascots

The mascots are plain SVG components in [`src/app/_components/`](src/app/_components/):

| File | What it draws |
| --- | --- |
| `Mascot.tsx`   | Round bean creature + `Star` / `Sparkle` / `Flower` |
| `Stickers.tsx` | `Cloud`, `Daisy`, `GlobeBuddy`, `HandSticker`, `SpeechBubble`, `BadgeCorner`, `BrowserWindow` |

Each accepts color props — replace the SVG paths to drop in your own art.

---

## 🏗 tech stack

| Layer | Choice | Why |
| --- | --- | --- |
| Framework | **Next.js 16** (App Router, Turbopack) | RSC by default, fast HMR |
| UI runtime | **React 19** + react-compiler | Auto-memoization, less manual `useMemo` |
| Styling | **Tailwind CSS v4** | `@theme inline` design tokens, zero config files |
| Type display | **Lilita One** via `next/font` | Chunky rounded display |
| Body | **Sora** via `next/font` | Clean modern UI text |
| Motion | **`motion`** (Framer Motion v11+) | `whileInView`, `useScroll` parallax |
| Type safety | **TypeScript strict** | Config + props are fully typed |

No external icon libraries. No clipart. No tracking.

---

## 📁 project structure

```
.
├─ assets/
│  └─ banner.svg                 ← animated README banner (SMIL)
├─ portfolio.config.ts           ← ✦ edit me ✦
├─ src/
│  └─ app/
│     ├─ layout.tsx              ← fonts + metadata (reads config)
│     ├─ page.tsx                ← stacks the 5 sections
│     ├─ globals.css             ← tokens, patterns, keyframes
│     └─ _components/
│        ├─ Mascot.tsx           ← base SVG primitives
│        ├─ Stickers.tsx         ← cloud, daisy, hand, browser-window, ...
│        ├─ Reveal.tsx           ← scroll-in reveal wrapper
│        ├─ Parallax.tsx         ← scroll-linked drift wrapper
│        ├─ Marquee.tsx          ← looping ticker
│        └─ sections/
│           ├─ Hero.tsx          ← NUMAN
│           ├─ Stack.tsx         ← MY STACK
│           ├─ Principles.tsx    ← HOW I WORK
│           ├─ Work.tsx          ← FEATURED WORK
│           └─ Contact.tsx       ← SAY HELLO
├─ LICENSE                       ← MIT
└─ tsconfig.json                 ← @config alias → portfolio.config.ts
```

---

## 🐞 known UI bugs

Honest list — these are real, you may hit them. PRs welcome.

| # | Bug | Where | Notes |
| - | --- | ----- | ----- |
| 1 | **FOUT layout shift on hero title** — `text-stripe`'s shadow ladder is sized to the rendered text height, so when `Lilita One` swaps in, the title height jumps a few px and pulls the rest of the hero with it | `Hero.tsx`, `globals.css` `.text-stripe` | `next/font` reserves layout, but the stripe-shadow ladder still shifts. Acceptable but visible on slow connections. |
| 2 | **Floor characters can overlap in the 480–639px window** | `Hero.tsx`, `Contact.tsx` floor mascots | Absolute `left-[%]` positions are tuned for mobile and sm+, the in-between viewport sometimes packs two characters too close. |
| 3 | **No-JS users see blank sections** | every section (`Reveal.tsx`) | `motion`'s `initial: { opacity: 0 }` never resolves without JS. Fix: ship a `<noscript>` style override or fall back to CSS-only reveals. |
| 4 | **Project tile text wraps awkwardly on very narrow phones** | `Work.tsx` `<BrowserWindow>` tiles | The fixed `h-36`/`h-44` tile clips a 2-line `sub` line on widths < 360px. |
| 5 | **Pink floor band can eat >30% of viewport on very short screens** | `Hero.tsx`, `Contact.tsx` | Floor is `h-[22-26%]`. On <600px-tall screens (landscape phones) it crowds the title. |
| 6 | **Marquee shows a 1-frame seam on first paint** | `Marquee.tsx` | The looped track is duplicated `[items, ...items]`, but the animation starts after first commit — you may see the join briefly. |
| 7 | **Heavy drop-shadow filters can cause scroll jank on low-power devices** | `globals.css` `.sticker` | Every sticker has a `drop-shadow(...)` filter; on Hero/Contact there are 6–8 stacked. Consider `will-change: filter` selectively, or downgrade to `box-shadow` for static stickers. |
| 8 | **Stripe-shadow text extends ~38px below baseline** | `globals.css` `.text-stripe` | If you remove the `pb-12` / `pb-6` next to a `text-stripe` title, the shadow ladder clips the following element. |
| 9 | **Reduced-motion only kills CSS keyframes, not `motion` tweens** | `motion` components | `Reveal` checks `useReducedMotion()` and skips, but `whileInView` opacity reveals on motion.div elsewhere still run. Tighten in those components if you need full a11y. |
| 10 | **`bg-checker` uses `currentColor` + opacity** — color leakage between stacked overlays in Safari < 16 | every section | Modern Safari renders fine; old Safari can show a faint tint where overlays meet. |

If you fix one, open a PR with a 1-line repro. Issues with screenshots especially welcome.

---

## 💛 credits

- Type display: [**Lilita One**](https://fonts.google.com/specimen/Lilita+One) (OFL)
- Body type: [**Sora**](https://fonts.google.com/specimen/Sora) (OFL)
- Motion: [**Framer Motion / `motion`**](https://motion.dev) (MIT)
- All illustrations / SVGs in this repo are **original** to this project — feel free to redraw, remix, or replace.

Built by [**Numan Khan**](https://nuu-maan.com) · [@nuu-maan](https://github.com/nuu-maan) · [@Numankhannnnn](https://x.com/Numankhannnnn)

---

## 📦 license

[MIT](LICENSE) — do whatever, just keep the notice.

If you ship something with it, a star ★ on the repo makes my day.

<div align="center">

`★ NK-FS/DEV — NO.001  ·  built with attention, shipped with chaos  ·  ★`

</div>